botmux 2.107.0 → 2.109.0-canary.0

package/README.en.md

@@ -15,14 +15,14 @@
   <a href="#design-philosophy">Design</a> &middot;
   <a href="#key-advantages">Advantages</a> &middot;
   <a href="#5-minute-setup">Quick Start</a> &middot;
-  <a href="https://github.com/deepcoldy/botmux/tree/master/docs-site/docs/en"><b>📖 Docs</b></a>
+  <a href="https://deepcoldy.github.io/botmux/en/"><b>📖 Docs</b></a>
 </p>
 
 [中文](README.md) | English
 
 **Plug any AI coding CLI into Feishu/Lark — every DM, group or topic gets its own CLI session, with live-streaming cards, a web terminal, and zero glue code.**
 
-> 📖 **Full docs** (commands / config / best practices / troubleshooting): **<https://github.com/deepcoldy/botmux/tree/master/docs-site/docs/en>** — this README only covers why and how to get started fast.
+> 📖 **Full docs** (commands / config / best practices / troubleshooting): **<https://deepcoldy.github.io/botmux/en/>** — this README only covers why and how to get started fast.
 
 | Lark Streaming Cards | Web Terminal | tmux Session Management | Multi-Bot Collaboration |
 |:-:|:-:|:-:|:-:|
@@ -40,7 +40,7 @@
 
 ### Design Philosophy
 
-Core philosophy: **Bridge CLIs, don't rebuild them**. botmux doesn't reimplement Agent capabilities — it bridges existing AI coding CLIs (Claude Code, Codex, Cursor, Gemini, OpenCode, Antigravity, GitHub Copilot, Kimi Code) directly. Memory, context management, tool use, permission systems — these capabilities are evolving rapidly within the CLIs themselves. botmux rides on top of that evolution rather than rebuilding in parallel. Every CLI upgrade benefits botmux automatically with zero adaptation.
+Core philosophy: **Bridge CLIs, don't rebuild them**. botmux doesn't reimplement Agent capabilities — it bridges existing AI coding CLIs (Claude Code, Codex, Cursor, Gemini, OpenCode, Antigravity, GitHub Copilot, Kimi Code, Grok Build, Kiro) directly. Memory, context management, tool use, permission systems — these capabilities are evolving rapidly within the CLIs themselves. botmux rides on top of that evolution rather than rebuilding in parallel. Every CLI upgrade benefits botmux automatically with zero adaptation.
 
 ### Key Advantages
 
@@ -52,7 +52,7 @@ Compared to OpenClaw-style approaches built on Agent SDKs:
 | CLI Capabilities | Full runtime (hooks, memory, plan mode, skills, `/` commands) | SDK API subset, missing features must be reimplemented |
 | CLI Upgrades | Zero-adaptation automatic benefit | Must track SDK version changes |
 | Memory / Context | Reuses CLI's built-in memory system, improves as the CLI evolves | Must build custom memory system, duplicating CLI-native capabilities |
-| Multi-CLI Support | 8 CLIs, switch with one config (Claude Code / Codex / Cursor / Gemini / OpenCode / Antigravity / GitHub Copilot / Kimi Code) | Tied to a single SDK, cannot switch CLIs |
+| Multi-CLI Support | Many CLIs, switch with one config (Claude Code / Codex / Cursor / Gemini / OpenCode / Antigravity / GitHub Copilot / Kimi Code / Grok Build / Kiro, …) | Tied to a single SDK, cannot switch CLIs |
 | Web Terminal | Interactive full terminal, mobile shortcut toolbar, phone/desktop/Lark tri-screen sync | Usually web chat UI or read-only output |
 | Multi-Bot Collaboration | Multiple bots in same group via @mention routing, isolated processes, different CLIs sparring | Usually single bot |
 | Multi-Topic Collaboration | A lead bot auto-splits the task, opens multiple topics, and dispatches several bots to work in parallel (coder + reviewer), with a Lark task list as the shared progress board | Usually manual one-by-one assignment, no unified progress board |
@@ -64,7 +64,7 @@ Compared to OpenClaw-style approaches built on Agent SDKs:
 ## Prerequisites
 
 - **Node.js** >= 22
-- **AI coding CLI / local agent app** installed and authenticated (`claude`, `codex`, `coco`, `cursor-agent`, `gemini`, `genius`, `opencode`, `hermes`, `seed` (Seed CLI, a Claude Code fork), `relay` (Relay CLI, the new release of Seed), `pi`, `omp` (oh-my-pi, a Pi fork), `copilot` (GitHub Copilot CLI), `traex` (TRAE CLI), `mircli` (Mir CLI), `agy` (Antigravity), or `kimi` (Kimi Code) in PATH)
+- **AI coding CLI / local agent app** installed and authenticated (`claude`, `codex`, `coco`, `cursor-agent`, `gemini`, `genius`, `opencode`, `hermes`, `seed` (Seed CLI, a Claude Code fork), `relay` (Relay CLI, the new release of Seed), `pi`, `omp` (oh-my-pi, a Pi fork), `copilot` (GitHub Copilot CLI), `traex` (TRAE CLI), `mircli` (Mir CLI), `agy` (Antigravity), `kimi` (Kimi Code), `grok` (Grok Build), or `kiro-cli` (Kiro) in PATH)
   - **CoCo requires `0.120.32+`**: type-ahead (sending a new message while a turn is still running, parked in CoCo's own message queue) relies on 0.120.32+ behavior; earlier versions may drop or serialize input while busy — upgrade before use
 - **tmux** >= 3.x (optional — auto-enabled when installed for persistent CLI sessions)
 - **CJK fonts** (only needed for screenshot rendering of Chinese text / emoji):
@@ -74,15 +74,18 @@ Compared to OpenClaw-style approaches built on Agent SDKs:
 
 ## 5-Minute Setup
 
-> 💡 **TL;DR**: `npm i -g botmux` → `botmux setup` and **scan two QR codes** to get a working bot → `botmux start`. The 1st scan creates the app and saves the AppID/AppSecret (event subscriptions + bot capability pre-configured); the 2nd scan lets botmux's built-in Feishu Web login **import permissions, configure the redirect URL, and create + submit a publish version automatically**. The entire Open Platform config (create app / permissions / redirect / publish) is handled by setup; pass `--no-open-platform-auto` to skip the second auto-config step and use the manual steps folded at the end.
+> 💡 **TL;DR**: `npm i -g botmux` → `botmux setup`; for Feishu tenants, **one QR scan** creates a working bot → `botmux start`. The same Web session names the app (`botmux-N` by default, customizable), creates it, reads AppID/AppSecret, imports permissions, configures the redirect URL, and creates + submits a publish version. Pass `--no-open-platform-auto` to skip permission/publish automation after app creation.
 
 ### 1. Install botmux
 
 ```bash
 npm install -g botmux
+# or: pnpm add -g botmux
 ```
 
-> Requires **Node.js ≥ 22**, with at least one AI coding CLI installed and authenticated (`claude` / `codex` / `cursor-agent` / `gemini` / `opencode` / `coco` / `agy` / `kimi` on your PATH). Installing **tmux** too is recommended (enables session persistence automatically).
+Manual and scheduled updates keep using the npm or pnpm global location that owns the running botmux install. Unknown install layouts are never silently updated with npm.
+
+> Requires **Node.js ≥ 22**, with at least one AI coding CLI installed and authenticated (`claude` / `codex` / `cursor-agent` / `gemini` / `opencode` / `coco` / `agy` / `kimi` / `grok` / `kiro-cli` on your PATH). Installing **tmux** too is recommended (enables session persistence automatically).
 
 ### 2. Create the App & Configure (`botmux setup`)
 
@@ -90,7 +93,7 @@ Run `botmux setup` — every choice is an interactive picker (↑/↓ to move, t
 
 1. **Action**: a fresh install goes straight into the create flow; with an existing config, first pick "add / reconfigure / edit / remove bot".
 2. **App source** — pick one of three:
-   - **Scan to create a new app (recommended)**: scan with the Lark mobile app and a PersonalAgent app is created with AppID/AppSecret persisted automatically, **with event subscriptions + bot capability pre-configured** — no manual browser navigation. Uses the official `@larksuiteoapi/node-sdk` device flow.
+   - **One-scan app creation (recommended)**: enter a bot name or leave it blank for `botmux-0`, `botmux-1`, etc. After Feishu Web QR login, botmux uploads its default icon, creates a custom app, reads AppID/AppSecret, then reuses that session for permissions and publishing. If Web creation is unavailable or the account is on Lark international, the user can explicitly choose the official `@larksuiteoapi/node-sdk` compatibility mode; it may require an additional scan and the platform chooses the app name.
    - **Pick an existing app**: reuse (or QR-login to get) a Feishu web session, list the apps you previously created on the Open Platform, and have the **AppID/AppSecret fetched automatically** — no digging through the console when re-configuring on a new machine (Feishu tenants only).
    - **Enter AppID/Secret manually** — see "Create the app manually" folded below.
 3. **Pick the CLI**: choose the CLI to bridge (searchable — type `cla` to filter Claude).
@@ -98,9 +101,9 @@ Run `botmux setup` — every choice is an interactive picker (↑/↓ to move, t
    - **Fixed default dir (recommended)**: new topics start straight in the given directory with **no card** (persisted as `defaultWorkingDir`; change later via `/config` or `botmux setup edit`). Pick this if you want the bot to just work in one directory.
    - **Repo-select card**: each new topic pops a card listing scanned git repos to choose from — good when you hop between repos. The follow-up question asks for the **repo scan root(s)** — usually the **parent directory** of your git projects (e.g. `~/projects`, comma-separated for multiple); the card scans **downward** for git repos (up to 3 levels). Avoid `~` (too many folders to traverse).
 
-Then comes the **2nd scan**: botmux's built-in Feishu Web login automatically imports permissions, configures the `http://127.0.0.1:9768/callback` redirect URL, and creates + submits a publish version. On failure it falls back and prints the manual steps (folded below) without affecting the config already written; importing only part of the permissions still counts as success — add the rest later on the Open Platform.
+After app creation, setup reuses the same Web session to import permissions, configure `http://127.0.0.1:9768/callback`, and create + submit a publish version, so the Feishu primary path **has no second QR code**. Another scan is possible only after the user explicitly selects SDK compatibility mode. Automation failures still print the manual steps without affecting the saved bot config.
 
-> ✅ **Both Feishu (feishu.cn) and Lark international (larksuite.com) tenants are supported.** Scan-to-create auto-detects the tenant brand (China / international) and remembers it — no manual choice needed; the manual paste path asks once. Each bot connects to its own brand's domain, so one machine can run Feishu and Lark bots side by side, with login credentials isolated per app.
+> ✅ **Both Feishu (feishu.cn) and Lark international (larksuite.com) tenants are supported.** Feishu uses the one-scan Web flow; explicitly selected SDK compatibility mode auto-detects and remembers Lark international tenants. The manual paste path asks once. Each bot connects to its own brand's domain, so one machine can run Feishu and Lark bots side by side, with login credentials isolated per app.
 
 At the end, setup validates credentials with a `tenant_access_token` call (only writing `bots.json` on success) and writes the full scope JSON to `~/.botmux/lark-scopes.json` for reference.
 
@@ -109,6 +112,11 @@ At the end, setup validates credentials with a `tenant_access_token` call (only
 
 ```bash
 botmux setup list --json                     # list bots (secret masked)
+botmux setup add --create-app \
+  --app-name "Engineering Assistant" \
+  --allowed-users alice@example.com          # first use scans once; later valid sessions skip it
+botmux setup add --create-app --switch-account \
+  --allowed-users alice@example.com          # explicitly rescan and replace the local session
 botmux setup add \
   --app-id cli_xxx --app-secret xxx \
   --allowed-users alice@example.com \
@@ -120,7 +128,8 @@ botmux setup help                            # full flag reference
 ```
 
 - `--working-dir` is the repo-select card's scan root; `--default-working-dir` is the fixed default dir (new topics start there directly, no card) — the same two modes as the TUI question.
-- `--json` prints machine-readable results (with `ok` / `error`); Open Platform auto-config is skipped by default — opt in with `--open-platform-auto` (requires QR scan).
+- `--create-app` reuses a valid session and reports the confirmed account/tenant on stderr; the first use scans once. `--switch-account` explicitly rescans and replaces the local session. `--json` never opens an unexpected QR when no valid cache exists unless `--switch-account` is passed. On success it returns the frozen `appName` and `appId`; a post-creation failure returns `partial`, `appId`, and an `--open-platform-auto` recovery command without creating another app.
+- Existing-credential mode skips Open Platform automation unless `--open-platform-auto` is passed. `--compatibility-mode` must be selected explicitly, may need another scan, and does not support `--app-name`.
 - If you previously scripted setup by piping numbered answers into the TUI, migrate to these subcommands: whenever the question sequence changes (this release adds the working-dir mode question), piped answers silently shift.
 
 </details>
@@ -150,7 +159,7 @@ botmux autostart enable
 ```
 
 <details>
-<summary><b>Manual Open Platform config: create app / permissions / redirect / publish (fallback)</b> —— handled automatically by botmux setup during the 2nd scan; expand only if auto-config failed or you want to verify manually</summary>
+<summary><b>Manual Open Platform config: create app / permissions / redirect / publish (fallback)</b> —— handled automatically by botmux setup with the same login session; expand only if auto-config failed or you want to verify manually</summary>
 
 <br>
 
@@ -188,7 +197,7 @@ base64 -w0 < ~/.botmux/lark-scopes.json | awk 'BEGIN{printf "\033]52;c;"}{printf
 
 <br>
 
-PersonalAgent apps come with event subscription + bot capability configured by default, so normally you don't touch this. If the bot **receives no messages at all** (not even DMs) after following the steps above, verify these two:
+botmux enables the bot capability, long-connection event mode, and baseline event subscriptions automatically, so normally you don't touch this. If the bot **receives no messages at all** (not even DMs) after following the steps above, verify these two:
 
 - **Event subscription**: Open Platform → your app → Events & Callbacks → should subscribe to `im.message.receive_v1` + `card.action.trigger` (subscribed by default; add manually if missing). The delivery method must be "Receive events via long connection" (WebSocket), with the botmux daemon running.
 - **Bot capability**: Open Platform → your app → Features → Bot should be enabled (on by default); name/avatar are editable.
@@ -223,7 +232,7 @@ On mobile/tablet, a floating shortcut toolbar provides Esc, Ctrl+C, Tab, arrow k
 
 ### Multi-Bot Collaboration
 
-Run multiple Lark bots on a single machine, each mapped to a different CLI. In the same group chat, messages are routed via @mention — each bot gets its own isolated CLI process. With a single bot in the group, it responds automatically without @. In a regular (non-topic) group, `@<bot1> @<bot2> /t xxx` spawns one independent thread per mentioned bot anchored at the same message. Send `@<bot1> @<bot2> /introduce` once so they register each other's open_id; afterwards each bot can explicitly @-mention the others from within its own session (commands: [📖 Docs · Slash Commands](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/en/slash-commands.md)).
+Run multiple Lark bots on a single machine, each mapped to a different CLI. In the same group chat, messages are routed via @mention — each bot gets its own isolated CLI process. With a single bot in the group, it responds automatically without @. In a regular (non-topic) group, `@<bot1> @<bot2> /t xxx` spawns one independent thread per mentioned bot anchored at the same message. Send `@<bot1> @<bot2> /introduce` once so they register each other's open_id; afterwards each bot can explicitly @-mention the others from within its own session (commands: [📖 Docs · Slash Commands](https://deepcoldy.github.io/botmux/en/slash-commands)).
 
 ### Multi-Topic Collaboration
 
@@ -311,7 +320,7 @@ ISO timestamp (`2026-05-01T10:00`).
 When a CLI spawns inside a botmux session it automatically gets
 `~/.botmux/bin` on PATH plus a set of ready-to-use Skills:
 
-- `botmux send` — send a message to the current thread (text, images, files, @mention)
+- `botmux send` — send a message to the current thread (text, images, files, interactive card JSON, @mention)
 - `botmux history` — fetch session history (topic groups → in-thread, regular groups → whole chat)
 - `botmux quoted <message_id>` — when the user @ed the bot via Lark's quote-reply UI, fetch the quoted message on demand
 - `botmux bots list` — discover bots + their `open_id`s
@@ -330,6 +339,7 @@ Gemini / OpenCode / Antigravity / GitHub Copilot), with no MCP protocol support
 > `botmux dashboard` issues a one-time-token URL — manage every daemon/bot from the browser.
 
 - One-click locate back to the Feishu thread / open Web Terminal / multi-select batch close
+- Add a bot with the same one-scan Feishu flow: optional stable name, AI CLI and working-directory choices, fail-closed administrator confirmation, and an explicit compatibility fallback
 - Create a new group with auto owner-transfer + @-mention notification
 - Disband or leave a chat (associated sessions auto-closed)
 - **Session Insights** (owner-only, read-only): parse each session's transcript to view action spans / work timeline / context curve / failure aggregates + diagnostic suggestions; send `/insight` in chat for the current session's summary card
@@ -387,16 +397,16 @@ Notes:
 
 The full reference — commands, config, best practices, troubleshooting — lives in the docs site; not duplicated here —
 
-### 👉 https://github.com/deepcoldy/botmux/tree/master/docs-site/docs/en
+### 👉 https://deepcoldy.github.io/botmux/en/
 
 | Topic | Docs |
 |-------|------|
-| Slash commands / CLI commands / agent-facing subcommands | [Commands](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/en/slash-commands.md) |
-| `bots.json` fields / env vars / file locations | [Configuration](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/en/bots-json.md) |
-| Multi-CLI adapters (incl. wrapper / gateway integration) | [Adapters](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/en/adapters.md) |
-| Scenario-based best practices (Oncall / alerting-ops / solo dev / team) | [Best Practices](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/en/best-practices.md) |
-| Common pitfalls / FAQ | [Pitfalls](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/en/pitfalls.md) · [FAQ](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/en/faq.md) |
-| Features: scheduled tasks / Oncall / Dashboard / multi-bot / session relay | [Schedule](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/en/schedule.md) · [Oncall](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/en/oncall.md) · [Dashboard](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/en/dashboard.md) · [Multi-bot](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/en/multi-bot.mdx) · [Relay](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/en/relay.md) |
+| Slash commands / CLI commands / agent-facing subcommands | [Commands](https://deepcoldy.github.io/botmux/en/slash-commands) |
+| `bots.json` fields / env vars / file locations | [Configuration](https://deepcoldy.github.io/botmux/en/bots-json) |
+| Multi-CLI adapters (incl. wrapper / gateway integration) | [Adapters](https://deepcoldy.github.io/botmux/en/adapters) |
+| Scenario-based best practices (Oncall / alerting-ops / solo dev / team) | [Best Practices](https://deepcoldy.github.io/botmux/en/best-practices) |
+| Common pitfalls / FAQ | [Pitfalls](https://deepcoldy.github.io/botmux/en/pitfalls) · [FAQ](https://deepcoldy.github.io/botmux/en/faq) |
+| Features: scheduled tasks / Oncall / Dashboard / multi-bot / session relay | [Schedule](https://deepcoldy.github.io/botmux/en/schedule) · [Oncall](https://deepcoldy.github.io/botmux/en/oncall) · [Dashboard](https://deepcoldy.github.io/botmux/en/dashboard) · [Multi-bot](https://deepcoldy.github.io/botmux/en/multi-bot) · [Relay](https://deepcoldy.github.io/botmux/en/relay) |
 
 ## Contributing
 

package/README.md

@@ -12,7 +12,7 @@
 </p>
 
 <p align="center">
-  <a href="#设计理念">设计理念</a> · <a href="#核心优势">核心优势</a> · <a href="#5-分钟快速接入">快速接入</a> · <a href="https://github.com/deepcoldy/botmux/tree/master/docs-site/docs/zh"><b>📖 文档</b></a>
+  <a href="#设计理念">设计理念</a> · <a href="#核心优势">核心优势</a> · <a href="#5-分钟快速接入">快速接入</a> · <a href="https://deepcoldy.github.io/botmux/"><b>📖 文档</b></a> · <a href="https://bytedance.larkoffice.com/wiki/UBOXwH01CixfxfkqxUpcKgvQnsg"><b>✨ 效果展示</b></a>
 </p>
 
 <p align="center">
@@ -21,9 +21,11 @@
 
 ---
 
-**飞书 + AI 编程 CLI——私聊 / 群聊 / 话题，每个会话一个独立 CLI 进程，实时流式回传。** Daemon 监听飞书消息，为每个新会话自动启动独立 CLI 进程（Claude Code / Codex / Cursor / Gemini / OpenCode / Antigravity / GitHub Copilot / Kimi Code），提供实时流式卡片和可交互 Web 终端。
+**飞书 + AI 编程 CLI——私聊 / 群聊 / 话题，每个会话一个独立 CLI 进程，实时流式回传。** Daemon 监听飞书消息，为每个新会话自动启动独立 CLI 进程（Claude Code / Codex / Cursor / Gemini / OpenCode / Antigravity / GitHub Copilot / Kimi Code / Grok Build / Kiro），提供实时流式卡片和可交互 Web 终端。
 
-> 📖 **完整文档**（命令 / 配置 / 最佳实践 / 排错）：**<https://github.com/deepcoldy/botmux/tree/master/docs-site/docs/zh>** ——本 README 只讲为什么用它和怎么快速上手。
+> ✨ **先看效果**：[**《5 分钟创建一个真正好用的飞书助理》**](https://bytedance.larkoffice.com/wiki/UBOXwH01CixfxfkqxUpcKgvQnsg) —— 飞书图文 + 视频演示：AI 消息提醒 / 多端同步跨端操作 / 多 Bot 协作 / 多话题并行编排 / 语音总结 + 飞书会议 / Oncall 与个人替身。
+
+> 📖 **完整文档**（命令 / 配置 / 最佳实践 / 排错）：**<https://deepcoldy.github.io/botmux/>** ——本 README 只讲为什么用它和怎么快速上手。
 
 ## 演示
 
@@ -45,7 +47,7 @@
 
 **不做 SDK wrapper，直接桥接 CLI。**
 
-botmux 不重新实现 Agent 能力，而是直接桥接已有的 AI 编程 CLI（Claude Code、Codex、Cursor、Gemini、OpenCode、Antigravity、GitHub Copilot）。记忆、上下文管理、工具调用、权限体系——这些能力 CLI 本身都在快速迭代，botmux 选择站在这个进化之上，而不是平行重造一套。CLI 的每次升级，botmux 零适配自动受益。
+botmux 不重新实现 Agent 能力，而是直接桥接已有的 AI 编程 CLI（Claude Code、Codex、Cursor、Gemini、OpenCode、Antigravity、GitHub Copilot、Kimi Code、Kiro）。记忆、上下文管理、工具调用、权限体系——这些能力 CLI 本身都在快速迭代，botmux 选择站在这个进化之上，而不是平行重造一套。CLI 的每次升级，botmux 零适配自动受益。
 
 ### 核心优势
 
@@ -57,7 +59,7 @@ botmux 不重新实现 Agent 能力，而是直接桥接已有的 AI 编程 CLI
 | CLI 能力 | 完整运行时（hooks、memory、plan mode、Skill、`/` 命令） | SDK API 子集，需手动实现缺失功能 |
 | CLI 升级 | 零适配自动受益 | 需要跟进 SDK 版本变更 |
 | 记忆 / 上下文 | 直接复用 CLI 内建的记忆系统，随 CLI 迭代自动增强 | 需自建记忆系统，与 CLI 原生能力重复 |
-| 多 CLI 支持 | 8 种 CLI 一键切换（Claude Code / Codex / Cursor / Gemini / OpenCode / Antigravity / GitHub Copilot / Kimi Code） | 绑定单一 SDK，无法切换 CLI |
+| 多 CLI 支持 | 多种 CLI 一键切换（Claude Code / Codex / Cursor / Gemini / OpenCode / Antigravity / GitHub Copilot / Kimi Code / Grok Build / Kiro 等） | 绑定单一 SDK，无法切换 CLI |
 | Web 终端 | 可交互的完整终端，移动端快捷键工具栏，手机/电脑/飞书三端同步 | 通常仅 Web 聊天界面或只读输出 |
 | 多机器人协作 | 多 bot 同群 @mention 路由，独立进程隔离，不同 CLI 赛博斗蛐蛐 | 通常单机器人 |
 | 多话题协作模式 | 主 bot 自动拆任务、开多话题、派多 bot 并行协作（coder+reviewer），飞书任务清单当共享进度板 | 通常需人工逐个分派、无统一进度板 |
@@ -92,7 +94,7 @@ botmux 可以管理 CLI 无关的自定义 Skill Registry，并按 bot 配置在
 
 ### 多机器人协作
 
-同一台机器上可运行多个飞书机器人，每个机器人可对应不同的 CLI。同一群聊中通过 @mention 路由消息，仅有一个机器人时无需 @ 自动响应；多机器人时 `@<bot1> @<bot2> /t xxx` 可让每个被 @ 的机器人在同一条消息上各自独立开新话题。先发一次 `@<bot1> @<bot2> /introduce` 让它们互相登记 open_id，之后各 bot 就能在自己的会话里显式 @mention 对方协作（命令详见 [📖 文档 · 斜杠命令](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/zh/slash-commands.md)）。
+同一台机器上可运行多个飞书机器人，每个机器人可对应不同的 CLI。同一群聊中通过 @mention 路由消息，仅有一个机器人时无需 @ 自动响应；多机器人时 `@<bot1> @<bot2> /t xxx` 可让每个被 @ 的机器人在同一条消息上各自独立开新话题。先发一次 `@<bot1> @<bot2> /introduce` 让它们互相登记 open_id，之后各 bot 就能在自己的会话里显式 @mention 对方协作（命令详见 [📖 文档 · 斜杠命令](https://deepcoldy.github.io/botmux/slash-commands)）。
 
 ### 多话题协作模式
 
@@ -176,7 +178,7 @@ BACKEND_TYPE=pty botmux start
 
 CLI 进入 botmux 会话时自动获得 `~/.botmux/bin` 在 PATH 中，以及一组开箱即用的 Skill：
 
-- `botmux send` — 向当前话题发消息（支持文本、图片、文件、@mention）
+- `botmux send` — 向当前话题发消息（支持文本、图片、文件、interactive 卡片 JSON、@mention）
 - `botmux history` — 读取当前会话历史消息（话题/thread 会话拉话题内，普通群 chat-scope 会话拉整群）
 - `botmux quoted <message_id>` — 用户用引用 UI @ 机器人时，按需读取被引用的那条消息
 - `botmux bots list` — 查询当前群聊的机器人及 open_id
@@ -189,6 +191,7 @@ CLI 进入 botmux 会话时自动获得 `~/.botmux/bin` 在 PATH 中，以及一
 > 命令行 `botmux dashboard` 出一次性 token URL，浏览器里跨所有 daemon/机器人管控
 
 - 一键定位回飞书话题 / 跳 Web 终端 / 多选批量关闭会话
+- 添加机器人对齐 Feishu 单次扫码主路径：名称可选且全程冻结，支持 AI CLI / 工作目录选择、管理员 fail-closed 补填与显式兼容模式
 - 拉新群、自动转让群主、@ 提醒
 - 解散群聊、bot 退群（关联会话自动清理）
 - **会话洞察**（owner-only，只读）：解析各会话 transcript，看动作 span / 工作时序 / 上下文曲线 / 失败聚合 + 诊断建议；聊天里发 `/insight` 可取当前会话摘要卡
@@ -205,7 +208,7 @@ CLI 进入 botmux 会话时自动获得 `~/.botmux/bin` 在 PATH 中，以及一
 ## 前置要求
 
 - **Node.js** >= 22
-- **AI 编程 CLI / 本地 Agent 应用** 已安装并完成认证（`claude`、`codex`、`coco`、`cursor-agent`、`gemini`、`genius`、`opencode`、`hermes`、`seed`（Seed CLI，Claude Code 衍生）、`relay`（Relay CLI，Seed 新版）、`pi`、`omp`（oh-my-pi，Pi 衍生）、`copilot`（GitHub Copilot CLI）、`traex`（TRAE CLI）、`mircli`（Mir CLI）、`agy`（Antigravity）或 `kimi`（Kimi Code）在 PATH 中）
+- **AI 编程 CLI / 本地 Agent 应用** 已安装并完成认证（`claude`、`codex`、`coco`、`cursor-agent`、`gemini`、`genius`、`opencode`、`hermes`、`seed`（Seed CLI，Claude Code 衍生）、`relay`（Relay CLI，Seed 新版）、`pi`、`omp`（oh-my-pi，Pi 衍生）、`copilot`（GitHub Copilot CLI）、`traex`（TRAE CLI）、`mircli`（Mir CLI）、`agy`（Antigravity）、`kimi`（Kimi Code）、`grok`（Grok Build）或 `kiro-cli`（Kiro）在 PATH 中）
   - **CoCo 最低版本 `0.120.32`**：type-ahead（会话忙时即可发新消息，由 CoCo 自己的消息队列接住）依赖 0.120.32+ 的行为；更早版本忙时输入可能丢失或串行，请升级后再用
 - **tmux** >= 3.x（可选，安装后自动启用会话常驻）
 - **CJK 字体**（用于截图渲染中文/emoji）：
@@ -215,15 +218,18 @@ CLI 进入 botmux 会话时自动获得 `~/.botmux/bin` 在 PATH 中，以及一
 
 ## 5 分钟快速接入
 
-> 💡 **TL;DR**：`npm i -g botmux` → `botmux setup`，**扫两次码**就能建好一个可用机器人 → `botmux start`。第 1 次扫码建应用、拿到 AppID/AppSecret（事件订阅 + bot 能力默认已配好）；第 2 次扫码让 botmux 内置的飞书 Web 登录**自动导入权限、配置重定向 URL、创建并提交发布版本**。整个开放平台配置（建应用 / 权限 / 重定向 / 发版）都已由 setup 默认完成；加 `--no-open-platform-auto` 可跳过第二次自动配置、改走文末折叠的手动步骤。
+> 💡 **TL;DR**：`npm i -g botmux` → `botmux setup`，飞书租户**扫一次码**就能建好一个可用机器人 → `botmux start`。这次扫码拿到的 Web 登录态会连续完成：按 `botmux-N`（可自定义）命名并创建应用、读取 AppID/AppSecret、导入权限、配置重定向 URL、创建并提交发布版本。整个开放平台配置都由 setup 默认完成；加 `--no-open-platform-auto` 可跳过应用创建后的权限/发版自动配置。
 
 ### 1. 安装 botmux
 
 ```bash
 npm install -g botmux
+# 或：pnpm add -g botmux
 ```
 
-> 要求 **Node.js ≥ 22**，且本地已装好并登录至少一种 AI 编程 CLI（`claude` / `codex` / `cursor-agent` / `gemini` / `opencode` / `coco` / `agy` 等在 PATH 中）。推荐顺手装 **tmux**（装了自动启用会话常驻）。
+botmux 的手动/定时更新会识别当前全局安装归属，并继续使用同一个 npm 或 pnpm 安装位置；无法安全识别的安装方式不会自动回退到 npm。
+
+> 要求 **Node.js ≥ 22**，且本地已装好并登录至少一种 AI 编程 CLI（`claude` / `codex` / `cursor-agent` / `gemini` / `opencode` / `coco` / `agy` / `grok` / `kiro-cli` 等在 PATH 中）。推荐顺手装 **tmux**（装了自动启用会话常驻）。
 
 ### 2. 创建应用并配置（`botmux setup`）
 
@@ -231,7 +237,7 @@ npm install -g botmux
 
 1. **操作**：首次安装直接进入创建流程；已有配置时先选「添加新机器人 / 重新配置 / 编辑现有机器人 / 删除机器人」。
 2. **飞书应用来源**：三选一——
-   - **扫码创建新应用（推荐）**：飞书扫码后自动建出 PersonalAgent 应用并落盘 AppID/AppSecret，**事件订阅 + bot 能力默认已配好**，无需手动浏览器创建。底层走 `@larksuiteoapi/node-sdk` 官方 device flow。
+   - **一次扫码创建新应用（推荐）**：可填写机器人名称；留空自动使用 `botmux-0`、`botmux-1`……。首次扫码拿到 Web 登录态后，botmux 自动上传默认图标、创建企业自建应用、读取 AppID/AppSecret，并复用同一登录态继续配置权限与发版；后续添加会先显示当前账号与企业供确认，有效期内免扫码。Web 自动创建不可用或使用 Lark 国际版时，可由用户明确选择 `@larksuiteoapi/node-sdk` 兼容模式；兼容模式可能需要额外扫码，且应用名称由平台决定。
    - **选择已有应用**：复用（或扫码获取）飞书 Web 登录态，列出你在开放平台创建过的应用，选中后**自动读取 AppID/AppSecret**——换机器重配、复用旧应用不用再去后台翻 Secret（仅飞书租户）。
    - **手动输入 AppID/Secret**：见文末折叠的「手动创建应用」。
 3. **选择 CLI**：选本次要接入的 CLI（可搜索，如输入 `cla` 过滤出 Claude）。
@@ -239,9 +245,9 @@ npm install -g botmux
    - **固定默认目录（推荐）**：新话题直接在指定目录启动、**不弹卡片**（落 `defaultWorkingDir` 字段，之后可用 `/config` 或 `botmux setup edit` 修改）。想让机器人"直接进目录干活"选这个。
    - **仓库选择卡片**：新话题先弹卡片，从扫描到的 git 仓库里选一个再启动，适合经常在多个仓库间切换。下一问填**仓库扫描根目录**，通常是 git 项目的**父级目录**（如 `~/projects`，支持逗号分隔多个），卡片从该目录**向下**查找 git 仓库（最多 3 层）；尽量别填 `~`（要遍历太多文件夹）。
 
-接着进入**第 2 次扫码**：botmux 内置的飞书 Web 登录会自动导入权限、配置 `http://127.0.0.1:9768/callback` 重定向 URL、创建并提交发布版本。失败会自动回退并打印手动步骤（见文末折叠），不影响已写入的配置；权限只导入了一部分也算成功，缺的可事后到开放平台补。
+应用创建后会直接复用同一份 Web 登录态，自动导入权限、配置 `http://127.0.0.1:9768/callback` 重定向 URL、创建并提交发布版本。Feishu 主路径是**首次最多扫码一次、后续有效期内免扫**；缓存账号/企业会在创建前展示并用同一份 cookie 再次比对，登录态失效时先提示，不会静默弹码。只有用户主动「更换账号」或明确选择 SDK 兼容模式时才会重新扫码。
 
-> ✅ **飞书 (feishu.cn) 与 Lark 国际版 (larksuite.com) 均支持**。扫码创建时自动识别租户类型（国内 / 国际）并记住，无需手动选择；手动粘 AppID/Secret 时会让你选一次。每个机器人按所属版本独立连对应域名，同一台机器可同时跑飞书 + Lark 机器人，登录凭证按应用隔离、互不干扰。
+> ✅ **飞书 (feishu.cn) 与 Lark 国际版 (larksuite.com) 均支持**。飞书走单次 Web 扫码；用户明确选择 SDK 兼容模式后，会自动识别并记住 Lark 国际版租户。手动粘 AppID/Secret 时会让你选一次租户类型。每个机器人按所属版本独立连对应域名，同一台机器可同时跑飞书 + Lark 机器人，登录凭证按应用隔离、互不干扰。
 
 setup 末尾会用 `tenant_access_token` 校验凭证（通过才落盘 `bots.json`），并把完整权限 JSON 写到 `~/.botmux/lark-scopes.json` 备查。
 
@@ -250,6 +256,11 @@ setup 末尾会用 `tenant_access_token` 校验凭证（通过才落盘 `bots.js
 
 ```bash
 botmux setup list --json                     # 列出机器人（secret 脱敏）
+botmux setup add --create-app \
+  --app-name 研发助手 \
+  --allowed-users alice@example.com          # 首次扫码；后续有效登录态下免扫
+botmux setup add --create-app --switch-account \
+  --allowed-users alice@example.com          # 明确更换账号并覆盖本机登录态
 botmux setup add \
   --app-id cli_xxx --app-secret xxx \
   --allowed-users alice@example.com \
@@ -261,7 +272,8 @@ botmux setup help                            # 完整 flag 列表
 ```
 
 - `--working-dir` 是仓库选择卡片的扫描根；`--default-working-dir` 是固定默认目录（新话题直接启动、不弹卡），对应 TUI 里工作目录模式的两个选项。
-- `--json` 输出机器可读结果（含 `ok` / `error`）；开放平台自动配置默认跳过，需要时显式加 `--open-platform-auto`（要扫码）。
+- `--create-app` 默认先复用并在 stderr 显示已确认的账号/企业；无缓存时首次扫码。`--switch-account` 强制重新扫码并覆盖本机登录态。`--json` 不会在缺少有效缓存时自行弹码，需显式加 `--switch-account`；成功时返回冻结后的 `appName` 与 `appId`，应用已创建但后续失败时返回 `partial`、`appId` 和带 `--open-platform-auto` 的继续命令，不会重复建应用。
+- 已有凭证模式的开放平台自动配置默认跳过，需要时显式加 `--open-platform-auto`。`--compatibility-mode` 必须显式选择，可能需要额外扫码且不支持 `--app-name`。
 - 以前对交互问答「管道喂数字」的脚本请迁移到这些子命令：问答序列一变（本版本就新增了工作目录模式一问），喂数字会静默错位。
 
 </details>
@@ -291,7 +303,7 @@ botmux autostart enable
 ```
 
 <details>
-<summary><b>手动配置开放平台：建应用 / 权限 / 重定向 / 发版（备用）</b> —— 默认由 botmux setup 扫第二次码时自动完成，仅在自动配置失败、或想手动核对时展开</summary>
+<summary><b>手动配置开放平台：建应用 / 权限 / 重定向 / 发版（备用）</b> —— 默认由 botmux setup 使用同一次登录态自动完成，仅在自动配置失败、或想手动核对时展开</summary>
 
 <br>
 
@@ -329,7 +341,7 @@ base64 -w0 < ~/.botmux/lark-scopes.json | awk 'BEGIN{printf "\033]52;c;"}{printf
 
 <br>
 
-PersonalAgent 默认配好事件订阅 + bot 能力，正常情况下不用动。如果按上面步骤走完 bot **完全收不到任何消息**（连私聊都不回），分别确认这两项：
+botmux 会自动开启机器人能力、长连接事件模式并订阅基础事件，正常情况下不用动。如果按上面步骤走完 bot **完全收不到任何消息**（连私聊都不回），分别确认这两项：
 
 - **事件订阅**：开放平台 → 你的应用 → 事件与回调 → 应当订阅 `im.message.receive_v1` + `card.action.trigger`（默认已订阅，如缺失就手动添加）。订阅方式必须是「使用长连接接收事件」(WebSocket)，且 botmux daemon 已经在跑。
 - **机器人能力**：开放平台 → 你的应用 → 应用功能 → 机器人 应当已开通（默认开通），名字/头像可以改。
@@ -384,16 +396,16 @@ PersonalAgent 默认配好事件订阅 + bot 能力，正常情况下不用动
 
 命令、配置、最佳实践、排错的完整内容都在文档站，这里不再重复 ——
 
-### 👉 https://github.com/deepcoldy/botmux/tree/master/docs-site/docs/zh
+### 👉 https://deepcoldy.github.io/botmux/
 
 | 主题 | 文档 |
 |------|------|
-| 斜杠命令 / CLI 命令 / 会话内子命令 | [命令参考](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/zh/slash-commands.md) |
-| `bots.json` 字段 / 环境变量 / 文件位置 | [配置参考](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/zh/bots-json.md) |
-| 多 CLI 适配器（含 wrapper / 网关接入） | [适配器](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/zh/adapters.md) |
-| 按场景的最佳实践（Oncall / 报警运维 / 个人研发 / 多人协作） | [最佳实践](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/zh/best-practices.md) |
-| 常见踩坑 / FAQ 排错 | [踩坑](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/zh/pitfalls.md) · [FAQ](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/zh/faq.md) |
-| 功能详解：定时任务 / Oncall / Dashboard / 多机器人协作 / 会话接力 | [定时](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/zh/schedule.md) · [Oncall](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/zh/oncall.md) · [Dashboard](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/zh/dashboard.md) · [多 bot](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/zh/multi-bot.mdx) · [接力](https://github.com/deepcoldy/botmux/blob/master/docs-site/docs/zh/relay.md) |
+| 斜杠命令 / CLI 命令 / 会话内子命令 | [命令参考](https://deepcoldy.github.io/botmux/slash-commands) |
+| `bots.json` 字段 / 环境变量 / 文件位置 | [配置参考](https://deepcoldy.github.io/botmux/bots-json) |
+| 多 CLI 适配器（含 wrapper / 网关接入） | [适配器](https://deepcoldy.github.io/botmux/adapters) |
+| 按场景的最佳实践（Oncall / 报警运维 / 个人研发 / 多人协作） | [最佳实践](https://deepcoldy.github.io/botmux/best-practices) |
+| 常见踩坑 / FAQ 排错 | [踩坑](https://deepcoldy.github.io/botmux/pitfalls) · [FAQ](https://deepcoldy.github.io/botmux/faq) |
+| 功能详解：定时任务 / Oncall / Dashboard / 多机器人协作 / 会话接力 | [定时](https://deepcoldy.github.io/botmux/schedule) · [Oncall](https://deepcoldy.github.io/botmux/oncall) · [Dashboard](https://deepcoldy.github.io/botmux/dashboard) · [多 bot](https://deepcoldy.github.io/botmux/multi-bot) · [接力](https://deepcoldy.github.io/botmux/relay) |
 
 ## 贡献
 

package/dist/adapters/backend/sandbox.d.ts

@@ -228,6 +228,7 @@ export declare function attachSandboxOutbox(opts: {
 export declare function sweepOrphanSandboxes(dataDir: string, activeSessionIds: Set<string>): void;
 export interface RelayRequest {
     contentFile?: unknown;
+    cardFile?: unknown;
     attachments?: unknown;
     videos?: unknown;
     videoCovers?: unknown;
@@ -235,6 +236,7 @@ export interface RelayRequest {
 }
 export interface ValidatedRelay {
     contentName: string;
+    cardName?: string;
     attachmentNames: string[];
     videoNames: string[];
     videoCoverNames: string[];
@@ -243,7 +245,7 @@ export interface ValidatedRelay {
 /**
  * PURE validation of an outbox relay request (schema + flag allowlist only — no
  * filesystem access, so it's deterministically testable):
- *  - contentFile/attachments/videos/videoCovers must be plain basenames (no `/`, `\`, `..`).
+ *  - contentFile/cardFile/attachments/videos/videoCovers must be plain basenames (no `/`, `\`, `..`).
  *  - only allowlisted presentation flags pass; any other flag → reject (this
  *    rejects raw `--content-file`/`--session-id`/path flags etc.).
  * The TOCTOU-safe filesystem read is handled separately by materializeOutboxFile,

package/dist/adapters/backend/sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../src/adapters/backend/sandbox.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../src/adapters/backend/sandbox.ts"],"names":[],"mappings":"AAkCA;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAqB1G;AAED,mFAAmF;AACnF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED;gFACgF;AAChF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAQnD;AAqCD,MAAM,WAAW,WAAW;IAC1B;0FACsF;IACtF,YAAY,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,aAAa,EAAE,MAAM,CAAC;IACtB;2DACuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,+EAA+E;IAC/E,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC7C;;sEAEkE;IAClE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;sDAEkD;IAClD,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;;6DAEyD;IACzD,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,8EAA8E;IAC9E,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,EAAE,CA6B5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,GAAG,MAAM,EAAE,CAU7E;AAoCD;;;8DAG8D;AAC9D,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GACvE,MAAM,EAAE,CAaV;AAUD;+DAC+D;AAC/D,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,qFAAqF;IACrF,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB;;;mFAG+E;IAC/E,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;mDAWmD;AACnD,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAIrF;AAMD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC;;sFAEkF;IAClF,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;2EACuE;IACvE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB;+EAC2E;IAC3E,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B;;oEAEgE;IAChE,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;qEACiE;IACjE,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;iDAE6C;IAC7C,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,yEAAyE;IACzE,GAAG,CAAC,EAAE,OAAO,CAAC;CACf,GAAG,YAAY,GAAG,IAAI,CAqJtB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,GAAG,IAAI,CAsBjJ;AAiCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAoCzF;AAOD,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AASD,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,YAAY,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CA4C1H;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAiBzF;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,IAAI,CAgG5G"}

package/dist/adapters/backend/sandbox.js

@@ -651,7 +651,7 @@ const RELAY_FLAGS_VAL = new Set(['--mention', '--quote']);
 /**
  * PURE validation of an outbox relay request (schema + flag allowlist only — no
  * filesystem access, so it's deterministically testable):
- *  - contentFile/attachments/videos/videoCovers must be plain basenames (no `/`, `\`, `..`).
+ *  - contentFile/cardFile/attachments/videos/videoCovers must be plain basenames (no `/`, `\`, `..`).
  *  - only allowlisted presentation flags pass; any other flag → reject (this
  *    rejects raw `--content-file`/`--session-id`/path flags etc.).
  * The TOCTOU-safe filesystem read is handled separately by materializeOutboxFile,
@@ -661,6 +661,13 @@ export function validateRelayRequest(req) {
     const safeName = (n) => typeof n === 'string' && !!n && !n.includes('/') && !n.includes('\\') && !n.includes('..');
     if (!safeName(req.contentFile))
         return { ok: false, error: 'contentFile must be a plain outbox basename' };
+    const cardName = req.cardFile === undefined
+        ? undefined
+        : safeName(req.cardFile)
+            ? req.cardFile
+            : null;
+    if (cardName === null)
+        return { ok: false, error: 'cardFile must be a plain outbox basename' };
     const attachmentNames = [];
     for (const a of Array.isArray(req.attachments) ? req.attachments : []) {
         if (!safeName(a))
@@ -704,7 +711,7 @@ export function validateRelayRequest(req) {
         }
         return { ok: false, error: `flag not allowed: ${f}` };
     }
-    return { ok: true, value: { contentName: req.contentFile, attachmentNames, videoNames, videoCoverNames, flags } };
+    return { ok: true, value: { contentName: req.contentFile, cardName, attachmentNames, videoNames, videoCoverNames, flags } };
 }
 /**
  * TOCTOU-safe copy of an outbox file (`outbox/<name>`, name already validated as
@@ -822,6 +829,15 @@ export function startOutboxWatcher(outbox, baseEnv, sessionId) {
                 continue;
             }
             staged.push(contentDest);
+            let cardPath;
+            if (v.value.cardName) {
+                cardPath = join(staging, `${id}.card.json`);
+                if (!materializeOutboxFile(outbox, v.value.cardName, cardPath)) {
+                    finish(id, reqPath, name, staged, 1, '', 'relay rejected: card not a regular file in outbox');
+                    continue;
+                }
+                staged.push(cardPath);
+            }
             let attBad = false;
             const attPaths = [];
             v.value.attachmentNames.forEach((an, i) => {
@@ -875,7 +891,7 @@ export function startOutboxWatcher(outbox, baseEnv, sessionId) {
             }
             const hostArgs = [
                 ...v.value.flags,
-                '--content-file', contentDest,
+                ...(cardPath ? ['--card-file', cardPath] : ['--content-file', contentDest]),
                 ...attPaths.flatMap(a => ['--files', a]),
                 ...videoPaths.flatMap(a => ['--videos', a]),
                 ...videoCoverPaths.flatMap(a => ['--video-covers', a]),