botmux 3.10.0 → 3.23.1

package/README.en.md

@@ -6,7 +6,7 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/botmux"><img src="https://img.shields.io/npm/v/botmux.svg" alt="npm"></a>
-  <img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg" alt="Node >= 22">
+  <img src="https://img.shields.io/badge/binary-no%20Node%20required-brightgreen.svg" alt="self-contained binary, no Node required">
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
   <a href="https://github.com/deepcoldy/botmux"><img src="https://img.shields.io/github/stars/deepcoldy/botmux.svg?style=social" alt="Stars"></a>
 </p>
@@ -39,11 +39,32 @@ A daemon watches Lark messages and spawns an isolated session process for each n
 > About 5 minutes: a single Lark QR scan in `botmux setup` creates the app, configures all permissions, and publishes a version in one flow (add `--no-open-platform-auto` to only create the app and skip the permission + publish automation, which you then complete manually; creating the app manually / pasting credentials is a separate option inside setup).
 
 ```bash
-npm install -g botmux        # requires Node >= 22
+curl -fsSL https://raw.githubusercontent.com/deepcoldy/botmux/master/install.sh | sh
 botmux setup                 # one scan to create the app → pick a CLI → pick a working dir (permissions + publish auto-configured)
 botmux start                 # start the daemon (botmux autostart enable for auto-start on boot)
 ```
 
+> botmux ships as a **self-contained single-file binary** with its runtime embedded — **neither installing nor running it needs Node on the machine** (whatever the AI coding CLI you bridge needs is its own matter). It installs to `~/.botmux/bin/botmux` (override with `BOTMUX_INSTALL_DIR`), picks the right binary for your OS/arch, verifies its SHA-256, and adds `~/.botmux/bin` to the startup file your shell actually reads (zsh / bash / fish each get the correct one), so **a new terminal has the command**.
+>
+> Nothing native is compiled during install (no Python / node-gyp / compiler): the PTY is already inside the binary. Supported: linux / macOS × x64 / arm64, with musl builds selected automatically on Alpine and similar. **On Windows, install inside WSL2** — the daemon needs PTY / tmux / Unix signals and does not run on native Windows; WSL2 reports as linux and is a fully supported first-class environment. An unsupported platform, or a binary that cannot run on this host, **fails with an explicit error and leaves your existing install untouched** rather than leaving you with a command that won't start.
+>
+> Stable macOS CLI releases use a consistent Apple Developer ID signature. Replacing the binary during an upgrade therefore preserves the code identity used by macOS file and App Data permissions instead of appearing as a new program for every version. Canary, beta, and RC builds remain ad-hoc signed.
+>
+> To upgrade: `botmux upgrade` (replaces the binary in place), or just **re-run the curl command** — also an in-place upgrade, and it won't append a second PATH line.
+
+<details>
+<summary>Already living in the Node ecosystem? npm works too (same binary)</summary>
+
+```bash
+npm install -g botmux        # requires Node >= 22 to run the install itself
+```
+
+The npm package carries **the same self-contained binary** (only the one matching your os/arch is installed); its postinstall points `~/.botmux/bin/botmux` at it and writes PATH the same way. So you end up with exactly **one** botmux version — no more "two Node versions each carrying their own global botmux, fighting each other / no idea which one I just updated".
+
+The only difference is **who installs it and who upgrades it later**: the npm path needs Node ≥ 22 to run the install itself and hands upgrades back to `npm i -g botmux@latest`; the curl path never touches Node. Once running, the two are identical — same binary, same commands.
+
+</details>
+
 Then DM the bot, or run `botmux dashboard` to create a group, and start chatting. Full steps (Lark international, manual permission / publish setup after `--no-open-platform-auto`, troubleshooting) are in the **[5-Minute Quickstart](https://deepcoldy.github.io/botmux/en/quickstart)**.
 
 ## Core Scenarios
@@ -60,12 +81,44 @@ More: [Roles & teams](https://deepcoldy.github.io/botmux/en/roles) · [File sand
 
 ## Supported CLIs & Agents
 
-Switch with `cliId` in `bots.json`. **20+ adapters**, spanning local CLIs (process-isolated, reachable via `tmux attach`) and API / cloud agents (e.g. Mira, riff — reached over API / remote, not a local process). Representative ones:
+Switch with `cliId` in `bots.json`. **20+ adapters**, spanning local CLIs (process-isolated, reachable via `tmux attach`) and API / cloud agents (e.g. Mira, riff — reached over API / remote, not a local process; mojo is API-driven but executes tools on the bot host by default, set cloud: true for the remote sandbox). Representative ones:
+
+`claude-code` · `codex` · `gemini` · `cursor` · `opencode` · `opencode2` · `antigravity` · `copilot` · `grok` · `kimi` · `kiro-cli` · `reasonix` · `dsh` · `aiden` · `coco` (TRAE) · `hermes` · `ebsd` · `mira` · `riff` (cloud agent) … · `mojo` (API-driven, host execution by default) · `minimax` (MiniMax `mmx text repl`; region set by `mmx auth login --region cn|global`, isolate multiple regions on one host via per-bot `env` `MMX_CONFIG_DIR`) …
 
-`claude-code` · `codex` · `gemini` · `cursor` · `opencode` · `antigravity` · `copilot` · `grok` · `kimi` · `kiro-cli` · `reasonix` · `aiden` · `coco` (TRAE) · `hermes` · `mira` · `riff` (cloud agent) …
+The `ebsd` adapter uses a dedicated external service identity and native OMP session storage. Operators must provide the Diag Gateway token and ByteCloud service account through permission-restricted files, never through `bots.json`.
+
+Store only non-secret metadata and credential file paths in `bots.json`:
+
+```json
+{
+  "cliId": "ebsd",
+  "workingDir": "/var/lib/botmux/ebsd-work",
+  "sandbox": true,
+  "env": {
+    "EBSD_BOTMUX_DIAG_ENDPOINT": "https://ebsbot.example",
+    "EBSD_BOTMUX_DIAG_TOKEN_FILE": "/run/secrets/ebsd-botmux/diag-token",
+    "EBSD_BOTMUX_BYTECLOUD_ACCESS_KEY_FILE": "/run/secrets/ebsd-botmux/bytecloud-ak",
+    "EBSD_BOTMUX_BYTECLOUD_SECRET_KEY_FILE": "/run/secrets/ebsd-botmux/bytecloud-sk",
+    "EBSD_BOTMUX_SUBJECT": "botmux-ebsd@prod",
+    "EBSD_BOTMUX_REPOSITORY_ROOT": "/srv/repos"
+  }
+}
+```
+
+The three credential files must be owner-held `0600` regular files, not symlinks. Never put their contents, the AK/SK, or the Gateway token in `bots.json`. Use a dedicated empty `workingDir`; repositories are exposed separately through the read-only `EBSD_BOTMUX_REPOSITORY_ROOT`. Linux hosts need bubblewrap before enabling `sandbox`, and startup fails closed if isolation cannot be established. The Gateway may accept current and previous keys during rotation while the subject remains stable.
 
 The current full set of `cliId`s is authoritative in [`src/adapters/cli/registry.ts`](https://github.com/deepcoldy/botmux/blob/master/src/adapters/cli/registry.ts); per-CLI config and wrapper / gateway setups are in [CLI Adapters](https://deepcoldy.github.io/botmux/en/adapters).
 
+### Session-level CLI selection
+
+Before a session starts, select a registered CLI for that session with `/cli <cliId>`, for example:
+
+```text
+/cli codex
+```
+
+This switches only the bare CLI adapter. It does not inherit the bot's `wrapperCli`, `model`, or `startupCommands`. CLIs that require a `ttadk`, `aiden`, or other wrapper / gateway setup should therefore remain configured as the bot's default wrapper combination. Once the session starts, the CLI selection is frozen and is reused for later messages and restores.
+
 ## Design Philosophy: Bridge the CLI Directly, No SDK Wrapper
 
 botmux doesn't reimplement memory, context management, tool calls, or permission systems — **most native CLI capabilities don't need reimplementing, and CLI upgrades usually benefit botmux directly** (when interfaces / params / output formats / resume semantics change, an adapter may still need to catch up). You keep talking in plain language; the daemon wraps context into structured prompts behind the scenes before feeding the CLI. An Agent-SDK-based approach is the inverse: capabilities depend on what the SDK exposes and on your own integration.

package/README.md

@@ -6,7 +6,7 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/botmux"><img src="https://img.shields.io/npm/v/botmux.svg" alt="npm"></a>
-  <img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg" alt="Node >= 22">
+  <img src="https://img.shields.io/badge/binary-no%20Node%20required-brightgreen.svg" alt="self-contained binary, no Node required">
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
   <a href="https://github.com/deepcoldy/botmux"><img src="https://img.shields.io/github/stars/deepcoldy/botmux.svg?style=social" alt="Stars"></a>
 </p>
@@ -39,11 +39,32 @@ Daemon 监听飞书消息，为每个新会话自动 spawn 一个独立的会话
 > 约 5 分钟：`botmux setup` 一次飞书扫码就连续建好应用、配全权限、发版（加 `--no-open-platform-auto` 则只建应用、跳过权限与发版的自动配置，之后需手动完成；手动创建 / 粘贴凭证是 setup 里的另一个选项）。
 
 ```bash
-npm install -g botmux        # 需要 Node >= 22
+curl -fsSL https://raw.githubusercontent.com/deepcoldy/botmux/master/install.sh | sh
 botmux setup                 # 一次扫码建应用 → 选 CLI → 选工作目录（自动配权限 + 发版）
 botmux start                 # 启动 daemon（botmux autostart enable 设开机自启）
 ```
 
+> botmux 本体是一个**自包含单文件二进制**，运行时已嵌在里面——**装它和跑它都不需要机器上有 Node**（你要接的 AI 编程 CLI 自己需要什么另算）。装到 `~/.botmux/bin/botmux`（`BOTMUX_INSTALL_DIR` 可改），按 OS/arch 自动选对应二进制、校验 SHA-256，并把 `~/.botmux/bin` 写进你当前 shell 的启动文件（zsh / bash / fish 各写对的那个），**开个新终端就能用**。
+>
+> 安装过程**不编译任何原生模块**（不需要 Python / node-gyp / 编译器）：PTY 已经嵌在二进制里。支持 linux / macOS × x64 / arm64（Alpine 等 musl 环境自动选 musl 版）；**Windows 请在 WSL2 里安装**（daemon 依赖 PTY / tmux / Unix 信号，原生 Windows 跑不了；WSL2 报告为 linux，是完整支持的一等环境）。平台不在列表里、或下下来的二进制在本机跑不起来，安装会**明确报错并保留原有版本**，而不是装上一个起不来的命令。
+>
+> 正式版 macOS CLI 使用稳定的 Apple Developer ID 签名。升级替换二进制后，macOS 的文件与 App 数据访问授权仍绑定同一代码身份，不会因为版本哈希变化而把 botmux 当成一个新程序；canary / beta / rc 等预览版仍使用 ad-hoc 签名。
+>
+> 升级：`botmux upgrade`（原地换二进制），或**重跑一遍上面那条 curl 命令**——同样原地升级，不会重复往启动文件里追加 PATH。
+
+<details>
+<summary>已经在用 Node 生态？也可以走 npm（同一个二进制）</summary>
+
+```bash
+npm install -g botmux        # 需要 Node >= 22 装包本身
+```
+
+npm 包内带的是**同一个自包含二进制**（按 os/arch 只装匹配的那一个），postinstall 把 `~/.botmux/bin/botmux` 指向它并同样写 PATH。所以装完只有**一个** botmux 版本，不再出现「装了两个 Node 版本、各自带一份全局 botmux 互相打架 / 不知道更新了哪个」。
+
+区别只在**谁来装、以后谁来升**：npm 路径需要 Node ≥ 22 才能执行安装本身，升级交回 `npm i -g botmux@latest`；curl 路径全程不碰 Node。跑起来之后两者完全一致——同样的二进制、同样的命令。
+
+</details>
+
 然后私聊机器人、或 `botmux dashboard` 拉个群，直接开聊。完整步骤（含 Lark 国际版、`--no-open-platform-auto` 后手动配置权限 / 发版、排查）见 **[5 分钟快速接入](https://deepcoldy.github.io/botmux/quickstart)**。
 
 ## 核心场景
@@ -60,12 +81,72 @@ botmux start                 # 启动 daemon（botmux autostart enable 设开机
 
 ## 支持的 CLI / Agent
 
-`bots.json` 里用 `cliId` 一键切换。**20+ 适配器**，覆盖本地 CLI（进程隔离，`tmux attach` 可直连）和 API / 云 Agent（如 Mira、riff——通过 API / 远端接入，非本地进程）。代表项：
+`bots.json` 里用 `cliId` 一键切换。**20+ 适配器**，覆盖本地 CLI（进程隔离，`tmux attach` 可直连）和 API / 云 Agent（如 Mira、riff——通过 API / 远端接入，非本地进程；mojo 为 API 驱动、默认在宿主机执行工具，可配 cloud: true 走云沙箱）。代表项：
+
+`claude-code` · `codex` · `gemini` · `cursor` · `opencode` · `opencode2` · `antigravity` · `copilot` · `grok` · `kimi` · `kiro-cli` · `reasonix` · `dsh` · `aiden` · `coco`(TRAE) · `hermes` · `ebsd` · `mira` · `riff`(云 Agent) … · `mojo`(API 驱动,默认宿主机执行) · `minimax`(MiniMax `mmx text repl`；区域由 `mmx auth login --region cn|global` 决定，同机多区用 per-bot `env` 的 `MMX_CONFIG_DIR` 隔离) …
 
-`claude-code` · `codex` · `gemini` · `cursor` · `opencode` · `antigravity` · `copilot` · `grok` · `kimi` · `kiro-cli` · `reasonix` · `aiden` · `coco`(TRAE) · `hermes` · `mira` · `riff`(云 Agent) …
+`ebsd` 使用独立的外部服务身份和原生 OMP 会话目录；部署方必须通过受限权限文件配置 Diag Gateway token 与 ByteCloud service account，不能把密钥写入 `bots.json`。
+
+`bots.json` 里只放非敏感元数据和密钥文件路径，例如：
+
+```json
+{
+  "cliId": "ebsd",
+  "workingDir": "/var/lib/botmux/ebsd-work",
+  "sandbox": true,
+  "env": {
+    "EBSD_BOTMUX_DIAG_ENDPOINT": "https://ebsbot.example",
+    "EBSD_BOTMUX_DIAG_TOKEN_FILE": "/run/secrets/ebsd-botmux/diag-token",
+    "EBSD_BOTMUX_BYTECLOUD_ACCESS_KEY_FILE": "/run/secrets/ebsd-botmux/bytecloud-ak",
+    "EBSD_BOTMUX_BYTECLOUD_SECRET_KEY_FILE": "/run/secrets/ebsd-botmux/bytecloud-sk",
+    "EBSD_BOTMUX_SUBJECT": "botmux-ebsd@prod",
+    "EBSD_BOTMUX_REPOSITORY_ROOT": "/srv/repos"
+  }
+}
+```
+
+三个密钥文件必须是运行 BotMux 的账号持有的 `0600` 普通文件，不能是符号链接；文件内容、AK/SK 和 Gateway token 都不得写进 `bots.json`。`workingDir` 应是专用空目录，仓库通过只读的 `EBSD_BOTMUX_REPOSITORY_ROOT` 暴露。Linux 开启 `sandbox` 前需安装 bubblewrap，隔离建立失败时会拒绝启动。当前/上一把 Gateway key 可以在服务端并存完成轮换，subject 保持不变。
 
 当前完整 `cliId` 以 [`src/adapters/cli/registry.ts`](https://github.com/deepcoldy/botmux/blob/master/src/adapters/cli/registry.ts) 为准；各 CLI 的配置与套 wrapper / 网关方法见 [多 CLI 适配器](https://deepcoldy.github.io/botmux/adapters)。
 
+### 会话级 CLI 选择
+
+在会话尚未启动前，可以用 `/cli <cliId>` 为当前会话选择已注册的 CLI，例如：
+
+```text
+/cli codex
+```
+
+这个选择只切换裸 CLI 适配器，不继承当前 bot 配置中的 `wrapperCli`、`model` 或 `startupCommands`。因此依赖 `ttadk`、`aiden` 等 wrapper / 网关才能启动的 CLI，不适合用会话级选择切换；应直接把 bot 默认配置设为对应的 wrapper 组合。会话启动后 CLI 选择冻结，后续消息和恢复都会继续使用该 CLI。
+
+### 会话级 Codex 实例
+
+同一 Bot 的 Codex 多登录目录可使用 [会话级 Codex 实例](docs/codex-instances.md)：显式 `codexHome` 与默认实例、加权随机新会话分配，以及固定实例的恢复/fork。初始化和登录见该文档；不提供额度不足自动换号。
+
+### 最终回答反馈（按 bot、默认关闭）
+
+在单个 `bots.json` 条目中设置 `feedback.enabled: true`，可在最终回答卡片中收集固定三态语义 `positive / progress / negative` 的反馈；默认按钮为“结论可用 / 有效推进 / 结论有误”。按钮文案、样式、顺序、可见语义、负向原因、说明框与是否允许改选均可配置。默认关闭，`apiOnly` bot、进度卡、自定义卡、通知和语音不显示反馈控件。当前仅本次提问者可反馈，提交后原卡片原地更新，自由文本不会回显到群卡。
+
+```json
+{
+  "feedback": {
+    "enabled": true,
+    "visibleSemantics": ["positive", "progress", "negative"],
+    "buttons": [
+      { "key": "conclusive_usable", "label": "结论可用", "semantic": "positive", "style": "primary" },
+      { "key": "effective_progress", "label": "有效推进", "semantic": "progress", "style": "default" },
+      { "key": "incorrect", "label": "结论有误", "semantic": "negative", "style": "danger" }
+    ],
+    "negativeFollowup": {
+      "reasons": [{ "key": "wrong_result", "label": "结论或结果错误" }],
+      "comment": { "enabled": true, "required": false, "maxLength": 1000 }
+    }
+  }
+}
+```
+
+也可在 Dashboard 的「Bot 配置 → 卡片 → 最终回答反馈」编辑，或用 `/botconfig set feedback '<json>'` 热更新。策略支持本地团队 → bot → bot-scoped chat 分层，优先级为 chat > bot > team；Dashboard 可预览最终生效策略。策略修改只影响之后交付的新卡；已发送卡片继续使用发送时快照。Agent 主动发送可声明 `botmux send --response-kind progress ...` 或 `botmux send --response-kind final ...`；未声明时默认按 progress/非 final 发送，只有显式 final 才挂反馈。数据仅落在本机 `botmux-feedback.sqlite`；可选 webhook 通过 durable outbox 投递 `turn.completed` 与 `feedback.revised` 事件。完整实现和边界见 [`docs/feedback-capability-current-implementation.md`](docs/feedback-capability-current-implementation.md)。
+
 严格兼容 Codex 参数、交互与会话存储的独立发行版无需新增适配器：保留 `cliId: "codex"`，通过 `cliRuntime` 声明自己的 executable、展示名和更新源。BotMux 会按发行版隔离版本与会话身份，未知更新源不会回落到官方 Codex。详见 [Codex 兼容发行版](https://deepcoldy.github.io/botmux/adapters#codex-兼容发行版)。
 
 ## 设计理念：直接桥接 CLI，不做 SDK wrapper
@@ -83,6 +164,10 @@ botmux 不重新实现记忆、上下文管理、工具调用、权限体系—
 | 多机器人 | 同群多 bot @mention 路由 | 取决于实现 |
 | 终端直连 | 本地 CLI 可 `tmux attach` 进真进程 | 取决于实现 |
 
+## 可信建群服务的默认免 @
+
+自助建群服务可通过应用与群绑定的签名，为普通群声明默认 `ambient` 模式：无需 @ 即可对话，只 @ 其他成员时保持安静。功能默认关闭，群级显式设置优先，现有对话与操作权限仍然生效。配置、注册表协议和缓存限制见 [可信群默认模式](docs/signed-chat-defaults.md)。
+
 ## 文档 · 社区 · 贡献
 
 - 📖 **完整文档**（命令 / 配置 / 最佳实践 / 排错）：**<https://deepcoldy.github.io/botmux/>**

package/package.json

@@ -1,15 +1,11 @@
 {
   "name": "botmux",
-  "version": "3.10.0",
+  "version": "3.23.1",
   "description": "Bridge between IM platforms and AI coding CLIs — one topic, one CLI session with live streaming",
   "type": "module",
-  "main": "dist/index-daemon.js",
-  "bin": {
-    "botmux": "dist/cli.js"
-  },
   "files": [
-    "dist/",
-    "ecosystem.config.cjs",
+    "scripts/postinstall-bin.mjs",
+    "scripts/install-path-entry.mjs",
     "README.md",
     "README.en.md",
     "LICENSE"
@@ -19,25 +15,34 @@
     "access": "public"
   },
   "scripts": {
-    "build": "pnpm audit:domains && node scripts/clean-dist.mjs && tsc && node scripts/generate-runtime-build-id.mjs && cp src/setup/lark-scopes.json dist/setup/ && pnpm dashboard:bundle && chmod +x dist/cli.js && node scripts/audit-dist.mjs",
+    "build": "bun run audit:domains && node scripts/generate-app-icon-data.mjs && node scripts/clean-dist.mjs && tsc && bun run typecheck:scripts && bun run typecheck:test-mocks && node scripts/generate-runtime-build-id.mjs && cp src/setup/lark-scopes.json dist/setup/ && bun run dashboard:bundle && chmod +x dist/cli.js && node scripts/audit-dist.mjs && node scripts/audit-embedded-assets.mjs --require-dist",
+    "verify:binary": "bun scripts/verify-binary.mjs",
+    "typecheck:scripts": "tsc -p tsconfig.scripts.json",
+    "typecheck:test-mocks": "tsc -p tsconfig.test-mocks.json",
     "workflow-core:build": "node scripts/build-workflow-core-package.mjs",
-    "workflow-core:test": "pnpm workflow-core:build && node scripts/test-workflow-core-package.mjs",
-    "workflow-core:pack": "pnpm workflow-core:build && node scripts/pack-workflow-core-package.mjs",
+    "workflow-core:test": "bun run workflow-core:build && node scripts/test-workflow-core-package.mjs",
+    "workflow-core:pack": "bun run workflow-core:build && node scripts/pack-workflow-core-package.mjs",
+    "build:bun": "bun scripts/build-bun-binary.mjs",
     "audit:domains": "node scripts/audit-public-domains.mjs",
     "dashboard:bundle": "node scripts/build-dashboard.mjs",
     "dashboard:watch": "node scripts/build-dashboard.mjs --watch",
     "daemon": "tsx src/index-daemon.ts",
-    "daemon:start": "node dist/cli.js start",
-    "daemon:stop": "node dist/cli.js stop",
-    "daemon:restart": "node dist/cli.js restart",
-    "daemon:logs": "node dist/cli.js logs",
-    "daemon:status": "node dist/cli.js status",
-    "use:here": "node scripts/claim-botmux-bin.mjs",
-    "creds:sync": "node dist/cli.js suspend --isolated",
-    "switch:here": "pnpm build && pnpm use:here",
+    "daemon:bun": "bun src/index-daemon.ts",
+    "supervisor:bun": "bun src/index-supervisor.ts",
+    "dashboard:bun": "bun src/index-dashboard.ts",
+    "daemon:start": "bun dist/cli.js start",
+    "daemon:stop": "bun dist/cli.js stop",
+    "daemon:restart": "bun dist/cli.js restart",
+    "daemon:logs": "bun dist/cli.js logs",
+    "daemon:status": "bun dist/cli.js status",
+    "use:here": "bun scripts/claim-botmux-bin.mjs",
+    "creds:sync": "bun dist/cli.js suspend --isolated",
+    "switch:here": "bun run build && bun run use:here",
     "test": "vitest run --project unit",
     "test:all": "vitest run",
     "test:e2e": "vitest run --project e2e",
+    "test:bun": "node scripts/run-bun-tests.mjs",
+    "test:bun:self-check": "node scripts/run-bun-tests.mjs --self-check",
     "test:bench": "tsx scripts/bench-tests.ts",
     "test:codex": "vitest run --project e2e test/codex-input.e2e.ts",
     "test:gemini": "vitest run --project e2e test/gemini-input.e2e.ts",
@@ -50,30 +55,38 @@
     "desktop:runtime": "node scripts/prepare-desktop-runtime.mjs",
     "desktop:smoke": "tsx scripts/desktop-smoke.ts",
     "desktop:install:local": "bash src/desktop/install-local.sh",
-    "desktop:dev": "pnpm build && pnpm desktop:bundle && electron dist/desktop/main.cjs",
-    "desktop:pack": "pnpm desktop:pack:local",
+    "desktop:dev": "bun run build && bun run desktop:bundle && electron dist/desktop/main.cjs",
+    "desktop:pack": "bun run desktop:pack:local",
     "desktop:pack:local": "node scripts/desktop-pack-local.mjs",
     "prepublishOnly": "npm run build",
+    "postinstall": "node scripts/postinstall-bin.mjs",
     "prepare": "git config core.hooksPath scripts/git-hooks 2>/dev/null || true"
   },
   "dependencies": {
     "@larksuiteoapi/node-sdk": "^1.64.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@napi-rs/canvas": "^0.1.65",
     "@xterm/addon-unicode11": "^0.9.0",
     "@xterm/headless": "^6.0.0",
     "croner": "^10.0.1",
     "dotenv": "^17.3.1",
     "markdown-it": "^14.1.1",
-    "node-pty": "^1.1.0",
-    "pm2": "^6.0.0",
     "proxy-agent": "^6.5.0",
     "qrcode-terminal": "^0.12.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "ws": "^8.19.0",
+    "yaml": "^2.9.0",
     "zod": "^3.23.0"
   },
+  "optionalDependencies": {
+    "@napi-rs/canvas": "^0.1.65",
+    "botmux-darwin-arm64": "3.23.1",
+    "botmux-darwin-x64": "3.23.1",
+    "botmux-linux-arm64": "3.23.1",
+    "botmux-linux-arm64-musl": "3.23.1",
+    "botmux-linux-x64": "3.23.1",
+    "botmux-linux-x64-musl": "3.23.1"
+  },
   "devDependencies": {
     "@midscene/web": "^1.7.6",
     "@playwright/test": "^1.58.2",
@@ -88,21 +101,24 @@
     "electron-builder": "^26.0.0",
     "esbuild": "^0.28.0",
     "memfs": "^4.57.1",
+    "node-pty": "^1.1.0",
     "playwright": "^1.58.2",
     "react-test-renderer": "19.2.7",
     "tsx": "^4.20.5",
     "typescript": "^5.3.0",
     "vitest": "^4.0.18"
   },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "electron",
-      "node-pty"
-    ]
-  },
   "engines": {
     "node": ">=22"
   },
-  "packageManager": "pnpm@9.5.0",
-  "license": "MIT"
+  "packageManager": "bun@1.4.2",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepcoldy/botmux.git"
+  },
+  "license": "MIT",
+  "trustedDependencies": [
+    "electron",
+    "node-pty"
+  ]
 }

package/scripts/install-path-entry.mjs

@@ -0,0 +1,263 @@
+/**
+ * Put `~/.botmux/bin` on the user's PATH by writing their shell's startup file.
+ *
+ * WHY THIS EXISTS
+ * `npm i -g botmux` has no `bin` field (removed with the Node fallback — see
+ * postinstall-bin.mjs), so the ONLY `botmux` command is the launcher written to
+ * `~/.botmux/bin/botmux`. If that directory is not on PATH, a successful install
+ * still leaves the user with `botmux: command not found`.
+ *
+ * Both installers used to just PRINT a hint, and the hint was:
+ *
+ *     echo 'export PATH="…"' >> ~/.profile
+ *
+ * which is wrong for a large share of users, because **zsh never reads
+ * `~/.profile`** (measured: `zsh -lic` on a home dir containing `.profile` reads
+ * `.zshenv` + `.zprofile` + `.zshrc` and the `.profile` echo never fires). A zsh
+ * user who followed the hint verbatim got a file that is silently ignored — the
+ * command stayed missing with no indication why. That was the reported bug.
+ *
+ * ── WHICH FILE PER SHELL (all measured, not recalled) ─────────────────────────
+ * Startup files actually sourced, by shell and invocation mode:
+ *
+ *   zsh   -c  → .zshenv
+ *         -i  → .zshenv .zshrc
+ *         -li → .zshenv .zprofile .zshrc
+ *   bash  -c  → (none)
+ *         -i  → .bashrc
+ *         -li → the FIRST of .bash_profile → .bash_login → .profile
+ *   fish      → ~/.config/fish/conf.d/*.fish in all three modes
+ *
+ * So the target per shell is the file that covers the most modes:
+ *   • zsh  → ~/.zshenv                       (the only file read in all 3)
+ *   • bash → ~/.bashrc AND its login file    (login vs interactive are disjoint)
+ *   • fish → ~/.config/fish/conf.d/botmux.fish
+ *
+ * bash genuinely needs both: writing only `.bashrc` misses login shells, and
+ * writing only the login file misses ordinary interactive ones.
+ *
+ * ⚠️ bash's login file is "the first that EXISTS", not always `.bash_profile` —
+ * see bashLoginFile() below for why creating the wrong one destroys the user's
+ * existing login config.
+ *
+ * ── fish SYNTAX ──────────────────────────────────────────────────────────────
+ * fish is not POSIX; `export PATH="$INSTALL_DIR:$PATH"` is not its syntax. (fish
+ * 3.6 happens to tolerate `export` as a compatibility shim and even produces a
+ * correct PATH — measured — but `set -gx` is the real form and is what we write.)
+ */
+
+import { existsSync, readFileSync, appendFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { basename } from 'node:path';
+
+/** Marker so we can detect our own previous edit and never write twice. */
+export const PATH_ENTRY_MARKER = '# added by botmux installer';
+
+/**
+ * Which shell is the user actually on? `$SHELL` is the login shell recorded in
+ * passwd, which is what future terminals will start — the right question here,
+ * and better than `process.ppid` guessing (the parent of a postinstall is npm,
+ * not the user's shell).
+ */
+export function detectShell(env = process.env) {
+  const shell = env.SHELL ?? '';
+  const name = basename(shell);
+  if (name.includes('zsh')) return 'zsh';
+  if (name.includes('fish')) return 'fish';
+  if (name.includes('bash')) return 'bash';
+  // Unknown or unset (containers, cron, exotic shells): POSIX `.profile` is the
+  // most portable thing we can offer, and sh/ksh/dash all read it at login.
+  return name ? 'other' : 'unknown';
+}
+
+/**
+ * bash's LOGIN startup file, chosen without shadowing anything.
+ *
+ * ⚠️ bash reads only the FIRST of `.bash_profile` → `.bash_login` → `.profile`.
+ * So creating `.bash_profile` on a machine whose login config lives in
+ * `.profile` (or `.bash_login`) silently stops that file from ever being read.
+ * Measured — a sentinel exported from `.profile` is visible to `bash -lic`, and
+ * becomes MISSING the moment an unrelated `.bash_profile` appears; same for
+ * `.bash_login`. That is destroying the user's environment to fix a PATH entry,
+ * which is far worse than the bug being fixed.
+ *
+ * So: append to whichever of the three already exists (that is the file bash is
+ * actually reading), and only fall back to CREATING `.bash_profile` when none of
+ * them exists — in which case there is nothing to shadow.
+ */
+function bashLoginFile(home) {
+  for (const name of ['.bash_profile', '.bash_login', '.profile']) {
+    const file = join(home, name);
+    if (existsSync(file)) return file;
+  }
+  return join(home, '.bash_profile');
+}
+
+/**
+ * Quote a path for literal use inside a shell startup file.
+ *
+ * ⚠️ SECURITY, not cosmetics. The install dir is caller-controlled
+ * (`BOTMUX_INSTALL_DIR`, or just an unusual home), and the line we write is
+ * EXECUTED by the user's shell on every startup. Interpolating it into double
+ * quotes lets `$(…)`, backticks and `$VAR` run: measured — an install dir
+ * containing `$(touch /tmp/PWNED)` created that file the first time zsh started,
+ * and did so on every shell thereafter.
+ *
+ * Single quotes make the shell treat every byte literally; the only character
+ * needing care is `'` itself, closed and re-opened via `'\''`. This form is
+ * identical in POSIX shells and in fish.
+ */
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * The startup files to write for a shell, plus the line to write into each.
+ * Returns [] when we have nothing safe to say.
+ *
+ * `env` is read for the two relocation variables below; both are honoured
+ * because writing the un-relocated path produces a file the shell never reads —
+ * the same class of bug as writing `.profile` for zsh.
+ */
+export function pathEntryTargets(shell, installDir, home = homedir(), env = process.env) {
+  const q = shellQuote(installDir);
+  // ⚠️ The STATEMENT has to be idempotent too, not just the file write. An
+  // unconditional `export PATH=<dir>:$PATH` re-prepends on every shell startup, so
+  // a nested or re-sourced shell keeps growing PATH — measured: the same directory
+  // appeared twice at nesting depth 2, and `.bash_profile` files that source
+  // `.bashrc` hit it within a single login. `case` is POSIX and quote-safe (no
+  // subshell, no `grep`), and the `:` padding makes it an exact ELEMENT test, so a
+  // sibling like `<dir>-old` never satisfies it.
+  const posix = `case ":$PATH:" in *:${q}:*) ;; *) export PATH=${q}":$PATH" ;; esac  ${PATH_ENTRY_MARKER}`;
+  switch (shell) {
+    case 'zsh': {
+      // ⚠️ zsh reads its dotfiles from $ZDOTDIR when that is set, falling back to
+      // $HOME. Writing $HOME/.zshenv on a machine with ZDOTDIR set produces a file
+      // zsh never reads — measured: `zsh -c botmux` → "command not found".
+      const zdotdir = env.ZDOTDIR?.trim();
+      const base = zdotdir ? zdotdir : home;
+      return [{ file: join(base, '.zshenv'), line: posix }];
+    }
+    case 'bash': {
+      // Disjoint coverage — see header. Both, or one of the two common ways of
+      // opening a terminal is left broken. The login half must not shadow (above).
+      const login = bashLoginFile(home);
+      const targets = [{ file: join(home, '.bashrc'), line: posix }];
+      // When bash's login file IS .bashrc-adjacent there is nothing more to add;
+      // dedupe so we never append the same line to the same file twice.
+      if (login !== join(home, '.bashrc')) targets.push({ file: login, line: posix });
+      return targets;
+    }
+    case 'fish': {
+      // ⚠️ fish's config dir is $XDG_CONFIG_HOME/fish, defaulting to ~/.config/fish.
+      // Same failure as ZDOTDIR above — measured: with XDG_CONFIG_HOME set, a file
+      // under ~/.config/fish is ignored, while the same line under
+      // $XDG_CONFIG_HOME/fish/conf.d works (positive control).
+      const xdg = env.XDG_CONFIG_HOME?.trim();
+      const configHome = xdg ? xdg : join(home, '.config');
+      return [{
+        file: join(configHome, 'fish', 'conf.d', 'botmux.fish'),
+        // fish: `contains` is its own exact list-element test — PATH is a real list
+        // here, so no delimiter padding is needed.
+        line: `contains ${q} $PATH; or set -gx PATH ${q} $PATH  ${PATH_ENTRY_MARKER}`,
+      }];
+    }
+    case 'other':
+    case 'unknown':
+    default:
+      return [{ file: join(home, '.profile'), line: posix }];
+  }
+}
+
+/** Is `installDir` already handled by this file (ours or the user's own line)? */
+export function fileAlreadyHasEntry(file, installDir) {
+  if (!existsSync(file)) return false;
+  let text;
+  try { text = readFileSync(file, 'utf8'); } catch { return false; }
+
+  // ⚠️ TWO SEPARATE PREDICATES, deliberately not one clever one.
+  //
+  // Attempt #1 searched for the raw directory as a substring: `<installDir>-old`,
+  // `/backup<installDir>` and `<installDir>/other` all counted as configured, so
+  // the REAL directory was never written (measured, written=0 for each).
+  // Attempt #2 split the line into tokens and compared them — but the line we
+  // WRITE for a directory containing a quote is
+  //     export PATH='/x/q'\''bin'":$PATH"
+  // and ANY tokenizer that treats `'` as a separator shreds that into `/x/q`,
+  // `\`, `bin`, so the quoted spelling can never match a token (measured: marker
+  // count 1 → 2 on every re-install). Shell quoting cannot be undone by splitting
+  // on characters.
+  //
+  // So: recognise OUR line by its own known syntax (marker + the exact quoted
+  // form we would generate), and use conservative whole-token matching only for a
+  // line the USER wrote by hand.
+  const ourQuoted = shellQuote(installDir);
+  const lines = text.split('\n').filter(l => !/^\s*#/.test(l));
+
+  // (a) Our own line, byte-for-byte on the part that identifies the directory.
+  //     `PATH=` + the exact quoted dir is enough; the suffix may legitimately
+  //     differ (`":$PATH"` vs fish's ` $PATH`).
+  if (lines.some(l => l.includes(PATH_ENTRY_MARKER) && l.includes(ourQuoted))) return true;
+
+  // (b) A hand-written line. Compare whole PATH elements, and do NOT treat quotes
+  //     as element separators — strip the wrapping quotes first, then split on the
+  //     characters that actually delimit PATH elements.
+  const PATH_ASSIGNMENT = new RegExp(
+    [
+      'export\\s+PATH\\s*=',      // POSIX: export PATH="…"
+      '^\\s*PATH\\s*=',           // POSIX: PATH=…
+      'set\\s+(-\\w+\\s+)*PATH',  // fish:  set -gx PATH …
+      'fish_add_path',            // fish:  fish_add_path …
+      '\\bpath\\+=',              // zsh:   path+=(…)
+      '\\bpath=\\(',              // zsh:   path=(…)
+    ].join('|'),
+    'i',
+  );
+  const target = installDir.replace(/\/+$/, '');
+  return lines.some(l => {
+    if (!PATH_ASSIGNMENT.test(l)) return false;
+    // Quotes here are shell syntax around a plain path (the quote-containing case
+    // is handled by (a)); dropping them leaves the path bytes intact.
+    const bare = l.replace(/["']/g, '');
+    return bare
+      .split(/[:\s()=]+/)
+      .map(t => t.replace(/\/+$/, ''))
+      .some(t => t !== '' && t === target);
+  });
+}
+
+/**
+ * Append the PATH line to every startup file the user's shell reads.
+ *
+ * Returns `{ written: string[], skipped: string[], failed: [{file, error}] }`.
+ * Never throws: a PATH edit failing must not fail the install (the launcher is
+ * already in place and the caller prints a manual fallback).
+ */
+export function ensurePathEntry(opts) {
+  const installDir = opts.installDir;
+  const env = opts.env ?? process.env;
+  const home = opts.home ?? homedir();
+  const shell = opts.shell ?? detectShell(env);
+  const targets = pathEntryTargets(shell, installDir, home, env);
+
+  const written = [], skipped = [], failed = [];
+  for (const { file, line } of targets) {
+    if (fileAlreadyHasEntry(file, installDir)) { skipped.push(file); continue; }
+    try {
+      mkdirSync(dirname(file), { recursive: true });
+      if (existsSync(file)) {
+        // Keep the user's file intact; only append, and only with a leading
+        // newline so we never glue onto an unterminated last line.
+        const prev = readFileSync(file, 'utf8');
+        appendFileSync(file, `${prev.endsWith('\n') || prev === '' ? '' : '\n'}${line}\n`);
+      } else {
+        writeFileSync(file, `${line}\n`);
+      }
+      written.push(file);
+    } catch (err) {
+      failed.push({ file, error: err && err.message ? err.message : String(err) });
+    }
+  }
+  return { shell, written, skipped, failed };
+}