@mu-cabin/muc-cli 0.5.5 → 0.6.0

package/REFERENCE.md

@@ -1,781 +1,48 @@
-# muc-cli
+# MUC 命令契约
 
-Terminal client for 东航 MUC IM (the `com.meicloud.im.dh` desktop app, also
-called MUC.app). Drives the same REST surface the desktop talks to, plus the
-binary chat protocol on raw TCP 8101 for sending messages, withdrawing, and
-syncing sessions.
+本文件描述 0.6.0 的命令契约。旧的 `send/history/daemon-*` 命令已移除。
 
-REST commands always coexist with the running desktop and phone — the server
-allows concurrent `accessToken`s. Chat-channel commands share online slots
-with real devices; see [Coexistence](#coexistence) below before sending.
+## 命令结构
 
-## What it is
+全局参数放在命令之前：`muc [--config-root <绝对路径>] [--output json|jsonl|text] <命令>`。默认 JSON。配置根也可由 `MUC_CONFIG_DIR` 提供。
 
-A single command (`muc`) packaging:
+| 命令 | 用途 |
+| --- | --- |
+| `init` | 从受保护 stdin 配置租户与初始 profile |
+| `login [--account <账号>] [--profile-id <id>]` | 隐藏提示或 JSON stdin 登录 |
+| `login --account <账号> --password-stdin` | stdin 仅提供密码 |
+| `login --remember` / `login --no-remember` | 保存或移除该账号记住密码的选择 |
+| `login --qr` | 在真实终端扫码登录 |
+| `whoami [--profile-id <id>]` | 核验当前用户 |
+| `profile list/create/update/login/logout` | 管理账号配置；修改输入来自 stdin |
+| `daemon start/stop/status/logs` | 管理同包后台进程 |
+| `runtime status/ensure/start/resume/stop` | 管理明确 profile 的连接状态 |
+| `manifest` | 查询当前操作契约 |
+| `exec <operation-id> --profile-id <id>` | 按 schema 执行业务操作 |
 
-- **Send** — 1:1 and group text, files, images, and voice clips. Add and
-  remove emoticon reactions on existing messages.
-- **Read** — server-side chat history, profile lookups, group lists, sticker
-  packs, directory search (people, departments, apps, service numbers), and
-  long-lived `listen` tail of inbound messages with sender/keyword filters.
-- **Manage** — login / token refresh, withdraw a message, clear a session,
-  download a chat-attached file, wait for a human emoticon reaction before
-  proceeding (`wait-react`).
-- **Personal daemon** — foreground `daemon-start` process for the user's own
-  account. It owns one chat socket, records raw `daemon-events`, and lets
-  ordinary chat-channel commands share that socket instead of opening a second
-  TCP login.
-- **Auto-reply** — long-running `assistantd` daemon plus named `assistant`s
-  with their own backend (Claude Code / Codex / Gemini / Cursor / Antigravity), persona prompt,
-  scope rules, optional slash-command claims, and a memory log. A
-  structural signature tail on every outbound stops bot-vs-bot reply loops.
-  This is separate from the personal daemon; ordinary commands do not borrow
-  a dedicated assistant account's socket.
-- **Self-describe** — every command has a `--json` mode emitting a stable
-  envelope; `muc manifest --json` returns the full command graph + per-command
-  output JSON Schema for agent / script consumers.
+操作 ID 与输入结构以 `src/ipc/v2/operations.ts` 和实际 `muc manifest` 为准，不在文档维护另一份静态覆盖矩阵。
 
-## Install
+## 输出与恢复
 
-```bash
-npm i -g @mu-cabin/muc-cli
-muc --version
-```
+成功输出包含 `ok`、`command`、`data`。错误输出到 stderr，包含 `ok:false` 与 `error.code`，不反射密码、token 或租户配置。
 
-Requirements: **Node ≥ 18**. macOS, Linux, and Windows are all supported.
-DES-CBC password encryption is `crypto-js` (pure JS) — no
-`--openssl-legacy-provider` flag needed.
+`events.watch` 使用 JSONL：先输出订阅 metadata，再输出事件。保留 `startedAtCursor`、`highWatermark` 和每条已处理事件的游标。消费进程退出不停止 daemon。
 
-`~/.muc/credentials.json` and `~/.muc/config.json` are written with mode
-`600` and the parent dir with mode `700`. POSIX honors that; on Windows the
-modes are silently ignored — protect the files with NTFS ACLs if you're on a
-shared host.
+写操作使用稳定 idempotency key；dry-run 与真正提交使用不同 key。提交结果不明时使用原 key 或 deliveryId 查询 `deliveries.get`，不新建 key 重发。
 
-## First-time setup
+认证恢复由 daemon 负责。明确认证失效后才进入下一种凭据，网络失败不触发密码兜底；恢复耗尽后由用户重新登录指定 profile。
 
-Before you can `login`, run `muc init` to seed the tenant configuration. The
-CLI is generic across MUC deployments — your MUC admin provides the
-tenant-specific values.
+## 初始配置
 
-```bash
-muc init       # interactive: walks through APP_KEY, APP_ID, signing secrets, hosts
-```
+`init` 输入为 `{ "profileId": "default", "tenant": {...}, "endpoints": {...} }`。
 
-What `muc init` collects:
+- `tenant`：`schemaVersion:2`、8 位十六进制 `appKey`、24 位十六进制 `appId`、`signSecretRest`、`signSecretSecure`、毫秒时间 `savedAtMs`，可选 `passwordKey`。
+- `endpoints`：`restOrigin`、`imHost`、`imPort`、`fileHost`、`filePort`。端点可以通过 `profile update` 显式修改。
 
-| Field | Source | Notes |
-|---|---|---|
-| `appKey` | admin | 8 hex chars |
-| `appId` | admin | 24 hex chars |
-| `signSecretRest` | admin | secret for the regular-API signing scheme |
-| `signSecretSecure` | admin | secret for the `/contacts/secure/...` signing scheme |
-| `pwdDesKey` | admin (optional) | DES-CBC key for password encryption; defaults to `appKey` |
-| `restHost` | default `https://muc.ceair.com/` | press enter to accept |
-| `ssoHost` | default `https://store.ceair.com/` | reserved (advanced) |
-| `imHost` / `imPort` | default `muc.ceair.com` / `8101` | TCP chat channel |
-| `fileHost` / `filePort` | default `muc.ceair.com` / `6101` | TCP file channel |
+这些值由管理员提供，只经受保护 stdin 输入；不要把真实配置写进仓库、命令行参数或聊天。
 
-Built-in defaults are provided **for hosts and ports only** — never for
-`appKey`, `appId`, or signing secrets.
+新私聊先用 `directory.search` 取得准确用户 ID，再调用 `chats.get`，输入 `{"conversationId":"dm:UPPERCASE_USER_ID"}`。发送时使用返回的正式 `conversationId`，不能直接向别名发送。
 
-### Non-interactive (CI, scripts)
+认证错误退出码为 3，禁止访问为 8，配置缺失为 6、配置无效为 7，输入错误为 2；提交结果不明为 75，并带 `automaticReplay:false`。错误的 `hint` 提供可执行的恢复路径。
 
-You can supply values via flags or env vars:
-
-Get the four secrets from your MUC admin first; the snippets below use
-placeholder names — substitute the real values your admin gives you.
-
-```bash
-# Flag form
-muc init --no-interactive \
-  --app-key            "$APP_KEY" \
-  --app-id             "$APP_ID" \
-  --sign-secret-rest   "$SIGN_SECRET_REST" \
-  --sign-secret-secure "$SIGN_SECRET_SECURE" \
-  --json
-
-# Env-var form
-MUC_APP_KEY="$APP_KEY" \
-MUC_APP_ID="$APP_ID" \
-MUC_SIGN_SECRET_REST="$SIGN_SECRET_REST" \
-MUC_SIGN_SECRET_SECURE="$SIGN_SECRET_SECURE" \
-muc init --no-interactive
-```
-
-Environment variables: `MUC_APP_KEY`, `MUC_APP_ID`, `MUC_SIGN_SECRET_REST`,
-`MUC_SIGN_SECRET_SECURE`, `MUC_PWD_DES_KEY`, `MUC_REST_HOST`, `MUC_SSO_HOST`,
-`MUC_IM_HOST`, `MUC_IM_PORT`, `MUC_FILE_HOST`, `MUC_FILE_PORT`.
-
-> **Env-var leakage warning.** Values exported into the environment are
-> visible to other processes on the same machine via `/proc/<pid>/environ`
-> on Linux, and they land in shell history if you don't prefix the command
-> with a space (and `HISTCONTROL=ignorespace` is set). For production setups
-> prefer the **interactive** prompt or **flag-based** invocation — you can
-> protect the flag values with secret-manager retrieval that never touches
-> the env.
-
-### Inspect, repair, reset
-
-```bash
-muc init --check          # validate; exit 0 ok, 6 missing, 7 invalid
-muc init --check --json   # same, machine-readable
-muc init --show           # print config (secrets always redacted)
-muc init --show --json    # JSON envelope — secrets are also redacted here
-                          # (read ~/.muc/config.json directly for raw values)
-muc init --reset --yes    # delete ~/.muc/config.json
-```
-
-Resolution order per field: CLI flag → env var → existing saved value → built-in
-default (hosts/ports only) → interactive prompt (TTY) → fail.
-
-## Login
-
-`muc login` is **non-interactive on the credential side** — it never prompts
-for a password. Pass it via flag, stdin, env var, or `--token-pwd` (reuse
-the saved tokenPwd).
-
-```bash
-# Plaintext flag (avoid; lands in shell history)
-muc login --account WANGLULU8 --password '…'
-
-# Safer: read password from stdin, no flag value
-printf '%s' "$MY_PWD" | muc login --account WANGLULU8 --password-stdin
-
-# Reuse saved tokenPwd (no password needed; ~30 day TTL)
-muc login --token-pwd
-
-# Env-var form
-MUC_ACCOUNT=WANGLULU8 MUC_PASSWORD='…' muc login
-```
-
-- `account` is your MUC uid (uppercase ASCII, e.g. `WANGLULU8`); falls back
-  to `$MUC_ACCOUNT` or the previously-saved uid if `--account` is omitted.
-- One of `--password` / `--password-stdin` / `--token-pwd` / `$MUC_PASSWORD`
-  is required — running `muc login` with no creds fails fast with
-  `AUTH_REQUIRED` (exit 3).
-- The password is encrypted client-side (DES-CBC) before being sent — same
-  scheme the desktop client uses.
-- A successful login saves to `~/.muc/credentials.json` (mode `600`):
-  `accessToken` (short-lived; the server doesn't publish a fixed TTL —
-  expect anywhere from hours to days) and `tokenPwd` (a longer-lived
-  refresh token used for silent re-login with `--token-pwd`).
-- On any `61004` (access token expired/invalid), the CLI mirrors the
-  desktop's `mucReLogin` recovery: it first probes `/emp/get` (which
-  rotates `accessToken` server-side without burning the `tokenPwd`); only
-  if that probe also fails does it fall back to the `tokenPwd → /emp/login`
-  refresh.
-- If a command fails with `code: AUTH_EXPIRED` and `tokenPwd rejected`
-  (server `61018`), the saved `tokenPwd` is gone — re-run
-  `muc login --account <UID>` with your real password to mint fresh
-  credentials.
-- A stable per-CLI device id is generated at `~/.muc/device-id` on first
-  run. It is intentionally **different** from the desktop's machine-id so
-  REST sessions stay independent.
-
-## Output contract
-
-- **Default:** human-readable plain text on stdout, errors on stderr in the
-  form `error: <msg>` / `hint: <hint>` / `code: <code> (exit <n>)`.
-- **`--json`** (anywhere on the command line): every command emits a single
-  stable JSON envelope on stdout — `{ok:true, schema_version:1, data}` or
-  `{ok:false, schema_version:1, code, msg, hint?}` — and stderr stays
-  silent. Agents and scripts should always pass `--json`.
-- **Exit codes** are typed and identical in both modes: `0` success, `1`
-  internal bug, `2` usage, `3` auth required / expired, `4` not found, `5`
-  remote / network error, `6` config missing, `7` config invalid.
-- `--help` / `--version` are human escape hatches and bypass the JSON
-  envelope by design. The canonical agent surface is `muc manifest --json`.
-
-## Commands
-
-### Setup
-
-| Command | What it does |
-|---|---|
-| `muc init` | Seed / inspect / reset tenant config (`~/.muc/config.json`). Run before `login`. See [First-time setup](#first-time-setup). |
-| `muc login` | Authenticate; persists `accessToken` + `tokenPwd` to `~/.muc/credentials.json`. See [Login](#login). |
-| `muc assistant-init` / `muc assistant-login` | Same as `init` / `login` but for the assistant daemon's **dedicated account** at `~/.muc/assistant/` — see [Dedicated account for the daemon](#dedicated-account-for-the-daemon). |
-| `muc whoami [--assistant]` | Show the saved account + token freshness. `--assistant` inspects `~/.muc/assistant/` instead. |
-
-### REST commands (no impact on the desktop app)
-
-| Command | What it does |
-|---|---|
-| `muc login` | Authenticate, persist `accessToken` + `tokenPwd`. |
-| `muc whoami` | Show the saved profile + token freshness. Local only — does not read tenant config. |
-| `muc search <keyword>` | Org / employee directory search (12 results max, server-side). |
-| `muc search-dept <keyword>` | Department directory search (with employee count + path). |
-| `muc search-app <keyword>` | Search the user's MUC widgets/apps drawer. |
-| `muc search-sno <keyword>` | Search service-numbers (服务号); shows `★` for already-subscribed. |
-| `muc whois <UID>` | Employee info + ext info (`secureApi`). Renders `cn / id / mail / departmentName / positionName / empStatusText`. `--no-ext` skips the slower `getExtInfo` call. |
-| `muc set-signature [text]` | Update your personal signature (个人签名). ≤50 chars; pass `""` or `--clear` to clear. Read back via `muc whois <self-uid> --json` at `data.ext.sign` (the value lives on `getExtInfo`, not `empInfo`). Other personal-info fields (name / empId / dept / mobile / email) are HR-sourced and have no client-side write API. |
-| `muc groups` | Starred groups (flat list keyed by `team_id`) + department groups (keyed by `groupId / deptName`). |
-| `muc default-emojis` | Built-in default emoji names bundled by the desktop client. These can be used in text messages; `data.reactions` is the supported message-reaction subset. |
-| `muc history --peer UID \| --team TEAM_ID \| --to-self` | Server-side chat history via the roaming-messages endpoint. Stateless: each call fetches from the server. Default window: 30 days, 50 messages newest-first. |
-| `muc download --file-key <key> [--out <path>]` | Download a chat-attached file from the V5 file server (TCP 6101). **Read-only** — opens a fresh per-request session, no chat login, doesn't kick anyone. Pass `--mid <mid>` instead of `--file-key` plus `--peer/--team/--to-self` to look the file up via roaming history. Verifies md5 on completion. |
-| `muc react --mid <MID> [--emoji <name>] [target]` | Add a default message reaction emoji to an existing message. **Visible.** Defaults to `[点赞]` and `--to-self`; non-self chats need `--yes-not-self`. By default assumes the original message was sent by the current user; pass `--src-sender-id <UID>` (and `--src-sender-app <appkey>`) to react to someone else's message. |
-| `muc reactions --mid <MID>` | List all emoticon reactions on a single message. Read-only. |
-| `muc unreact --emoticon-id <id> [target]` | Revoke one of your own reactions (id from `muc react` or `muc reactions`). |
-| `muc manifest` | Print the full command graph + per-command output JSON Schema. Pair with `--json` for agents. |
-
-`history` flags: scope with one of `--peer UID`, `--team TEAM_ID`,
-`--sid <UID1|UID2 or teamId>`, or `--to-self`. `--limit N` (default 50),
-`--days N` (window from now, default 30), `--before <ts|ISO>` to fetch
-older than a moment, `--sub-type N` to filter to one type (e.g. `1` text,
-`7` file, `8` image), `--desc` for newest-first (default: oldest at top).
-The fetched `timestamp` is normalized to ms.
-
-```bash
-muc history --peer YANWENYU --limit 100
-muc history --to-self --days 7
-muc history --team 9009876543210000 --before 2026-04-20 --json | jq .
-```
-
-### Chat-channel commands (TCP 8101) — see [Coexistence](#coexistence)
-
-| Command | What it does |
-|---|---|
-| `muc tcp-ping [--wait N] [--debug]` | TCP connect + NEGOTIATE only. Smoke test, no login frame, **zero** kick risk. |
-| `muc sync [--os OS]` | After chat-login, run `syncDone` / `syncSession` / `syncWithdraws`. Read-only. |
-| `muc search-team <keyword> [--enrich]` | Search groups you belong to via the chat channel; `--enrich` follows up with `team/get_team` per id to print names + member counts. |
-| `muc team-members <TEAM_ID> [--profiles]` | List members of a joined group via `team/get_team_members`; `--profiles` enriches each UID with org directory fields. |
-| `muc send (--to-self \| --peer UID \| --team TEAM_ID) <text> [--yes-not-self]` | Send a plain-text message. **Visible to the recipient.** |
-| `muc send-file <file> [target] [--yes-not-self]` | Upload a file (TCP 6101) and broadcast as `MESSAGE_CHAT_FILE` (subType=7). Returns persistent `fileKey` + `mid`. **Visible.** Uses both 6101 (upload) and 8101 (broadcast) — costs the chosen `--os` slot for the broadcast. |
-| `muc send-image <file> [target] [--width N --height N]` | Same as `send-file` but as `MESSAGE_CHAT_IMAGE` (subType=8). Width/height auto-probed from PNG/JPEG/GIF/BMP headers; pass `--width/--height` to override. |
-| `muc send-voice <file> --duration <ms> [target]` | Same as `send-file` but as `MESSAGE_CHAT_AUDIO` (subType=9). `--duration <ms>` is required (the desktop renders the bubble's clip length from this metadata, not from the file). |
-| `muc withdraw --mid <MID> [target]` | Recall a sent message. Original gets replaced server-side with "您撤回了一条消息". Target flag must match the original message's chat. |
-| `muc clear-session [target]` | Delete a session from your client-side history (syncs to all your devices). **Doesn't delete server-side history** — `history` still returns the messages. |
-| `muc pin (--to-self \| --peer UID \| --team TEAM_ID \| --sid sId)` | Pin a session to the top of the chat list (`user/setCacheField` → `sticky_on_top_id`). Multi-device. **Not** the same as starred groups (`muc groups`). |
-| `muc unpin [target]` | Unpin a session (same targets as `pin`). |
-| `muc pinned` | List currently pinned session sIds (and best-effort kind: team / p2p / self). |
-| `muc wait-react --mid <MID> [--from-uid UID] [--emoji <name>] [--timeout 300]` | Block until someone reacts with a default reaction emoji to `--mid`, then exit. Useful as a "human-in-the-loop approval" gate after `muc send`. Exits with `TIMEOUT` (exit 5) if no matching reaction arrives within `--timeout` seconds. |
-| `muc listen [--from-uid UID] [--team TEAM] [--peer UID] [--contains TEXT] [--regex …] [--at-me] [--max N]` | Long-lived TCP tap that emits one **NDJSON line per matching inbound message** (in `--json` mode each line is the standard envelope; in human mode it's a one-line summary). Supports repeatable filters (OR semantics within each kind, AND across kinds), `--at-me` to restrict to group messages where another user @-mentions you (implies excluding self), `--include-self` to include your own sends, `--include-reactions` to also surface type=3 sub=300/301 frames, `--max N` to exit after N matches. Stop with `^C`. |
-
-`--os` resolves as **per-call `--os` → `defaultChatOs` in `~/.muc/config.json`
-→ built-in `iPad`**. Valid values: `Windows`, `OS X`, `Mac`, `iOS`, `Android`,
-and `iPad`. The existing option name is retained for compatibility: logical
-`iPad` serializes as `os:"iOS", browser:"iPad"` and selects the third slot.
-Set an override with `muc init --default-os <os>` or `MUC_DEFAULT_OS`.
-
-Sending to anyone other than yourself requires the explicit `--yes-not-self`
-flag — a guard against accidentally messaging real humans during testing.
-
-**Personal daemon routing.** When `muc daemon-start` is running for the same
-uid, every ordinary chat-channel command above (`send`, `send-file`,
-`send-image`, `send-voice`, `withdraw`, `clear-session`, `pin`, `unpin`,
-`pinned`, `sync`,
-`search-team`, `team-members`, `wait-react`, `listen`) routes its TCP work
-through the personal daemon's already-open socket. Dedicated `assistantd`
-is not borrowed by ordinary commands; it is only probed to avoid stealing a
-same-uid shared-profile assistant slot.
-
-Behavioural consequences while a daemon is running:
-
-- `--os` is **ignored** by these commands; the slot is fixed by whatever
-  `--os` the daemon was started with. Passing an `--os` value that disagrees
-  with the daemon's slot is rejected up front with `code:"USAGE"` (so the
-  user can't ask the CLI to do something that would kick the daemon).
-- `muc listen --include-offline` is rejected with `code:"USAGE"` — the
-  daemon already drained the offline batch at its own startup, so there
-  are no offMsg frames left for `listen` to surface. Use `muc daemon-events`
-  for raw replay, or stop the daemon and rerun without it if you need a
-  direct offline flush.
-- `--json` output now carries a `route` field: `"daemon"` when the call was
-  forwarded through the daemon's IPC socket, `"direct"` when the CLI opened
-  its own TCP login. Routed ordinary commands also include
-  `daemon_kind:"personal"` for compatibility-friendly disambiguation.
-- If the daemon is up but **not connected** (kicked, auth-expired, or
-  network-error parked), commands fail fast with `code:"DAEMON_UNAVAILABLE"`
-  (exit 5) rather than silently taking the slot the daemon is trying to
-  reclaim. Inspect with `muc daemon-status --json`; resolve the pause or stop
-  the daemon (`muc daemon-stop`) before sending directly.
-- If `assistantd` is explicitly running on the personal shared profile,
-  direct ordinary TCP is blocked with `code:"DAEMON_CONFLICT"` so it cannot
-  steal the assistant's slot. Stop `assistantd` or run the personal daemon.
-
-### Personal daemon
-
-Foreground-only v1 daemon for the user's own `~/.muc` account. It records raw
-chat-channel events for 90 days by default (`MUC_DAEMON_HISTORY_DAYS`
-overrides retention) and exposes replay/tail by stable cursor.
-
-| Command | What it does |
-|---|---|
-| `muc daemon-start [--os OS] [--on-kicked POLICY] [--debug]` | Start the personal daemon in the foreground. Holds one chat socket for ordinary commands. `POLICY` is `pause`, `immediate`, or a duration such as `5m`; default `3m`. |
-| `muc daemon-status` | Show `kind:"personal"`, running status, uid, os, pid, socket, and retained history window. |
-| `muc daemon-stop` | Send `SIGTERM` to the personal daemon pid, or clean stale socket state. |
-| `muc daemon-events [--since CURSOR_OR_TIME] [--tail] [--if-missing error|earliest|latest]` | Replay raw daemon events and optionally continue live. `--since` accepts a cursor id, ISO timestamp, epoch milliseconds, or `now`. |
-
-`daemon-events` emits one envelope per NDJSON line. Event ids are ordered as
-`<epoch_ms>-<sequence>`; delivery is at-least-once, so consumers should
-deduplicate by event `id` and, for messages, by MUC `mid`.
-
-### Assistant daemon (auto-reply)
-
-A long-lived daemon (`assistantd`) plus a registry of named **assistants**
-that auto-reply to inbound DMs and group `@me` mentions. The assistant daemon
-owns one TCP-8101 slot for assistant replies only. Ordinary commands route
-through `muc daemon-start`, not through a dedicated assistant account.
-
-#### Daemon lifecycle
-
-| Command | What it does |
-|---|---|
-| `muc assistantd-start [--os OS] [--on-kicked POLICY] [--debug]` | Start the assistant daemon in the foreground. Holds the chosen slot (priority: `--os` → active profile `defaultChatOs` → built-in `iPad`). Personal and dedicated-assistant behavior share this default. `POLICY` defaults to `3m`. Without a dedicated profile it fails unless `muc init --allow-assistant-shared-profile` explicitly opted into shared-profile mode. |
-| `muc assistantd-status` | Probe the daemon: running? slot? attached assistants? last paused-state message? |
-| `muc assistantd-stop` | Send `SIGTERM` to the daemon (graceful shutdown). |
-| `muc assistantd-resume` | Manual resume for `--on-kicked pause`, auth expiry, or exhausted network retries is reserved for v1.1. Today: `assistantd-stop` then `assistantd-start` again. |
-
-For both daemon types, `--on-kicked` accepts `pause`, `immediate`, a plain
-number of seconds, or a duration ending in `s`, `m`, `h`, or `d` (maximum
-`7d`). The default is `3m`. Immediate and delayed recovery open a new login
-after the selected delay, so they may kick the other device if it is still
-online. `daemon-status` / `assistantd-status` expose the resolved policy as
-`on_kicked`.
-
-If the daemon parks itself (`paused_kicked` with policy `pause`,
-`paused_auth` when `accessToken` / `tokenPwd` are stale, or
-`paused_network` after a dropped link), the process keeps running but stops
-handling events. The corresponding status command shows the `status` and
-`message`; chat-channel CLI calls fail fast with `code:"DAEMON_UNAVAILABLE"`
-(exit 5) until the daemon recovers or you stop it.
-
-#### Dedicated account for the daemon
-
-By default `assistantd` requires a dedicated profile under `~/.muc/assistant/`.
-Shared-profile assistant mode is an explicit advanced opt-in:
-`muc init --allow-assistant-shared-profile`. In shared mode it authenticates
-as the personal `~/.muc` account and is mutually exclusive with
-`muc daemon-start` for that uid.
-
-- **Chat slot.** A daemon and a real device on the **same** slot kick each
-  other (`auth/kicked`, "same account login"). The built-in default is the
-  separate iPad slot, so desktop and phone coexist; a real iPad may conflict.
-- **REST `tokenPwd`.** A fresh `muc login` rotates the account's refresh
-  token; other devices on that account get logged out when their token
-  next refreshes. Remembered-password daemon recovery is different: it uses
-  `createTokenPwd=false`, refreshing only accessToken and preserving the
-  phone's auto-login credential.
-
-The fix is to give the daemon its **own account**, stored under
-`~/.muc/assistant/` (next to its pid / socket / logs) and completely
-separate from your personal `~/.muc/`:
-
-```bash
-muc assistant-init        # tenant config → ~/.muc/assistant/config.json
-                          # (tenant secrets/hosts default to whatever your
-                          #  personal `muc init` saved; defaultChatOs → iPad)
-muc assistant-login --account <BOT_UID>   # → ~/.muc/assistant/credentials.json
-                                          # (--platform defaults to mac)
-muc assistantd-start                      # picks up the dedicated profile
-muc whoami --assistant                    # confirm which account it's on
-```
-
-Once provisioned, `muc assistantd-start` reads the dedicated profile
-automatically (every REST call the daemon makes follows it too). The
-daemon defaults to the **iPad slot**, so the account's desktop and phone
-slots remain independent. A real iPad logged into that same assistant
-account may be kicked. Remove the profile (`rm -rf ~/.muc/assistant/config.json
-~/.muc/assistant/credentials.json`) only if you intend to use the explicit
-shared-profile mode.
-
-#### Assistant CRUD
-
-| Command | What it does |
-|---|---|
-| `muc assistant-new <name> [--template <id>] [--backend claude-code\|codex\|gemini\|cursor\|antigravity] [--model <id>] [--reasoning-effort <level>] [--commands /a,/b] [--description TEXT]` | Scaffold `~/.muc/assistants/<name>/` with `config.json`, a persona `system-prompt.md` (template substitutes `<SCOPE_DESCRIPTION>` from `--description`), and an empty `memory.jsonl`. **`--template <id>`** seeds the scaffold from a starter template (run `muc assistant-templates` to list); supplies the persona prompt, default `backend` / `model` / `reasoning_effort` / `commands`, and copies any `bin/` helpers into `~/.muc/assistants/<name>/bin/`. Explicit `--backend` / `--model` / `--reasoning-effort` / `--commands` flags still override the template's defaults. **`--reasoning-effort <level>`** is codex-only (`minimal` \| `low` \| `medium` \| `high` \| `xhigh`) and forwards to `codex -c model_reasoning_effort=<level>`; `xhigh` is model-dependent (codex falls back to `high` on models that don't support it). Other backends ignore the field. Omit the flag (and don't set `reasoning_effort` in the template) to let codex use its built-in default. After a template-based create the JSON output includes `setup_notes` (host-side prereqs the template can't auto-do, e.g. `glab auth login`) and `bin_files`. Backend defaults to `claude-code`; `codex` requires the `codex` CLI on PATH (logged in via `codex login` or `OPENAI_API_KEY`); `gemini` requires the `gemini` CLI on PATH (logged in via `gemini` interactive first-run, or `GEMINI_API_KEY` / `GOOGLE_API_KEY`); `cursor` requires the `cursor-agent` CLI on PATH (logged in via `cursor-agent login` OAuth, or `CURSOR_API_KEY`); `antigravity` requires the `agy` CLI on PATH (logged in via `agy` interactive Google-OAuth first-run) — its `--model` is advisory only (the active model is whatever you select in agy's own picker; defaults to `"Gemini 3.5 Flash (High)"`). `--commands` claims a comma-separated set of slash-commands (e.g. `--commands /img,/draw`); each must match `^/[a-z][a-z0-9-]{0,20}$`, must be globally unique across assistants, and `/help` is reserved for the daemon. Omit (or pass `""`, and don't use `--template`) to mark this assistant as a fallback that fires on messages with no `/cmd` match. The flag only takes bare names — to attach a per-command `desc` / `usage` (rendered in `/help`), edit each entry in `~/.muc/assistants/<name>/config.json` after creation: `{ "name": "/img", "desc": "AI 图像生成", "usage": "/img <prompt>" }`. |
-| `muc assistant-templates` | List starter templates available to `assistant-new --template <id>`. Two roots are searched: bundled (ships with muc-cli) and `~/.muc/templates/<id>/` (user-managed); when an id exists in both, **user wins**. Each row reports `id`, `source` (`bundled` \| `user`), `description`, default `backend` / `model` / `reasoning_effort` / `commands`, declared `placeholders`, host-side `prereqs`, whether the template ships a `bin/` helper directory, and the absolute `path`. To author a template, drop a directory under `~/.muc/templates/<your-id>/` containing `template.json` (with `id` matching `^[a-z][a-z0-9-]{0,40}$`), `system-prompt.md`, optional `setup-notes.md`, and an optional `bin/`. To override a bundled template without forking, copy it under `~/.muc/templates/<same-id>/` and edit in place. |
-| `muc assistant-list` | List registered assistants with their backend, priority, claimed `commands` (legacy name array) plus `command_specs` (rich `{name,desc?,usage?}` array), `is_fallback` flag, scope, and whether the daemon currently has them attached. |
-| `muc assistant-start <name>` | Tell the running daemon to start routing matching events to this assistant. |
-| `muc assistant-stop [name]` | Detach a single assistant; omit the name to detach **all**. Scaffolds stay on disk. |
-| `muc assistant-edit <name>` | Open this assistant's persona `system-prompt.md` in `$EDITOR` / `$VISUAL` / `vi`. |
-| `muc assistant-memory <name> [--tid <tid>] [--all] [--clear]` | Inspect the per-thread memory shards the backend sees. Default action: list every thread with its entry count. `--tid <tid>` (e.g. `team_g:<groupId>` or `p2p:<UID>`) shows one thread's journal; `--all` is the legacy cross-thread dump (debug only). `--clear` truncates — combine with `--tid` for one thread or `--all` for everything. Storage: `~/.muc/assistants/<name>/threads/<safe-tid>.jsonl`. |
-| `muc assistant-delete <name>` | Detach (if the daemon's up) and remove the scaffold (config, prompt, memory). |
-
-#### Starter templates
-
-`muc assistant-templates` lists every template available to `assistant-new --template <id>`. A template is a directory with this layout:
-
-```
-<root>/<id>/
-  template.json        # id, description, default backend / model / reasoning_effort (codex only) / commands, declared placeholders, host-side prereqs
-  system-prompt.md     # persona prompt (with <PLACEHOLDER> substitutions)
-  setup-notes.md       # optional — printed verbatim after `assistant-new` finishes
-  bin/                 # optional — copied to ~/.muc/assistants/<name>/bin/ and chmod +x
-```
-
-Two roots are searched user-first:
-
-- `~/.muc/templates/<id>/` — user-managed; sharable by `tar` / `cp`; no muc release needed.
-- bundled (ships with muc-cli) — listed with `source: "bundled"`.
-
-Same id in both → user wins. To override a bundled template without forking, copy it to `~/.muc/templates/<same-id>/` and edit in place.
-
-`<ASSISTANT_NAME>` / `<USER_NAME>` / `<MUC_ASSISTANT_DIR>` / `<MUC_ASSISTANT_BIN_DIR>` placeholders in `system-prompt.md` and `setup-notes.md` are substituted at create-time. At runtime, the daemon also exports `MUC_ASSISTANT_NAME` / `MUC_ASSISTANT_DIR` / `MUC_ASSISTANT_BIN_DIR` to the backend process, so a prompt can reference its own bundled scripts as `$MUC_ASSISTANT_BIN_DIR/<helper>` without absolute paths.
-
-Bundled today: **`code-handler`** — GitLab code assistant. A single `/code [<gitlab-url>] [<desc>]` command covers review / implement / refine / explain / Q&A; the assistant decides the action from the URL kind and description, and the URL can be omitted when it's resolvable from the conversation context. Authorization is keyed off GitLab project membership rather than a config-file allowlist; commit author is taken from the trigger's MUC UID. Prereqs: `glab auth login` against your internal GitLab. Run `muc assistant-templates --json` for the full list and per-template `prereqs`.
-
-#### Per-assistant config — `~/.muc/assistants/<name>/config.json`
-
-Hand-edit, or seeded by `assistant-new`:
-
-| Field | Type | Default | Notes |
-|---|---|---|---|
-| `name` | string | (arg) | `^[a-zA-Z0-9_-]{1,40}$` — also the directory name |
-| `backend` | enum | `claude-code` | `claude-code` requires the `claude` CLI on PATH; `codex` requires the `codex` CLI on PATH (logged in via `codex login` or `OPENAI_API_KEY`) — defaults to `gpt-5.6-sol`; `gpt-5.6-terra`, `gpt-5.6-luna`, and older model ids remain selectable through the `model` field; `gemini` requires the `gemini` CLI on PATH (logged in via `gemini` interactive first-run, or `GEMINI_API_KEY` / `GOOGLE_API_KEY`) — defaults to `auto-gemini-3` (lets gemini auto-route between gemini-3-pro and gemini-3-flash, falling back to gemini-2.5-pro if no preview access), override via the `model` field; `cursor` requires the `cursor-agent` CLI on PATH (logged in via `cursor-agent login` OAuth, or `CURSOR_API_KEY`) — defaults to `auto` (Cursor's router), override via the `model` field; `antigravity` requires the `agy` CLI on PATH (logged in via `agy` interactive Google-OAuth first-run) — the `model` field is advisory only (used for the disclosed label; agy runs whatever model is selected in its own picker, defaulting to `"Gemini 3.5 Flash (High)"`) |
-| `model` | string | — | optional backend-specific model override |
-| `reasoning_effort` | enum | — | codex backend only — `minimal` \| `low` \| `medium` \| `high` \| `xhigh`. Forwarded as `codex -c model_reasoning_effort=<level>`. `xhigh` is model-dependent (codex falls back to `high` on models that don't support it). Other backends ignore the field. Omit to let codex use its built-in default. Templates seed this from `template.json`'s `reasoning_effort`. |
-| `scope.scenes` | `("p2p"\|"team_g")[]` | — | restrict to DMs and / or group chats |
-| `scope.tids` | `string[]` | — | only these `team_id`s match (groups only — DMs are filtered via `scope.from_uids`) |
-| `scope.from_uids` | `string[]` | — | only messages from these senders match |
-| `scope.keywords` | `string[]` | — | substring-match on body text |
-| `commands` | `Array<string \| {name,desc?,usage?}>` | `[]` | slash-commands this assistant claims. Each entry is either a bare name (`"/img"`) or a rich spec (`{ "name":"/img", "desc":"AI 图像生成", "usage":"/img <prompt>" }`); both shapes coexist in one array. `name` matches `^/[a-z][a-z0-9-]{0,20}$`, is globally unique across assistants, and `/help` is reserved for the daemon. `desc`/`usage` ≤ 200 chars each — surfaced in the daemon's `/help` menu (defaults: `usage` falls back to `name`; `desc` falls back to `help_text`, then `<name>（<backend>[/<model>]）`). Empty list = fallback assistant for its scope. |
-| `priority` | int | `100` | lower wins when multiple assistants tie for the same command or fallback bucket; ties are logged to `~/.muc/assistant/conflicts.log` |
-| `memory_window` | int (0–500) | `30` | rolling history entries kept per thread |
-| `bootstrap_history` | bool | `true` | seed memory from server-side roaming history on first event in a thread |
-| `reply_timeout_ms` | int (≥5s) | `120000` | backend invocation timeout |
-| `help_text` | string | built-in fallback | sent verbatim when the backend returns `{"action":"skip","blocks":[]}` |
-| `restrict.shell_grants` | `string[]` | — | optional opt-in tightening. **Absent** ⇒ permissive-by-default: every backend runs in its sandbox-but-permissive mode (writes inside the per-turn cwd, network on, native muc-verb deny still loads). **Set** ⇒ revert to a per-prefix allow-list backends enforce natively where possible (`claude --allowed-tools "Bash(<prefix>*)"`, cursor `cli.json` `permissions.allow`, gemini `--allowed-tools ShellTool(<prefix>)`). codex has no native flag — entries surface as a prompt-side advisory only. Templates seed this from `template.json`'s `restrict.shell_grants`; placeholders (`<MUC_ASSISTANT_BIN_DIR>` etc.) are pre-substituted at `assistant-new` time. |
-
-> **Per-turn workspace + repo cache.** Every dispatch gets a private dir
-> `~/.muc/assistants/<name>/workspace/turn-<msgId>/` that the daemon hands
-> the backend as `cwd` and exports as `MUC_ASSISTANT_REPO_CACHE`'s parent
-> (`MUC_ASSISTANT_REPO_CACHE=<turn-cwd>/.cache/repos`). Template-bundled
-> helper scripts (e.g. `prep-repo`) honor that var so all writes — bare-
-> caches, worktrees, scratch files — stay inside the turn dir and are
-> wiped on cleanup. There is no separate `writable_roots` config to
-> maintain anymore.
-
-#### Routing & dispatch
-
-1. Inbound message passes the trigger gate (DMs always; groups only on `@me`; never self; only `kind:"text"`).
-2. Per-assistant scope filter (scenes / tids / from_uids / keywords) narrows the eligible set.
-3. **`/help`** is daemon-owned. Renders a per-thread menu of every claimed `command` from in-scope active assistants — one line per command, formatted as `• <usage> — <desc>` (with `usage`/`desc` pulled from each command's spec, falling back to `name` and `help_text` / `<name>（<backend>）` respectively). Includes a `• 其他消息 → <name>` line if a fallback is in scope. Reachable even when no assistants are active. Sent as a richtext bubble with a real `@<asker>` mention so the response is clickable in the group.
-4. **`/<cmd>`** dispatches to the assistant that registered it (lower `priority` wins on ties). A `/cmd` that no in-scope assistant owns triggers the daemon's `unknown command <cmd> — type /help…` reply. A bare `/` or malformed `/CMD` (uppercase, leading digit, etc.) gets the same treatment — never silently flows into a fallback.
-5. **No `/` prefix** falls back to the in-scope assistant whose `commands` list is empty (lowest `priority` wins). If no fallback is in scope, the daemon sends `no_route_hint` so the user knows there's nothing listening.
-6. Backend returns a JSON envelope `{"action":"reply"|"skip","blocks":[…]}`. `action:"skip"` ⇒ daemon sends `help_text` (or the built-in fallback) to the thread. `action:"reply"` ⇒ daemon ships the blocks straight to the thread and appends a `\n\n— <assistant> · <model>` signature tail to every reply. (No self-DM mirror — use `muc assistant-ui` / `muc assistant-log` to audit outbound traffic.)
-7. The signature tail is also the **loop-stop**: any inbound whose last paragraph matches that exact shape is dropped before routing, so two assistants on opposite ends can't ping-pong.
-8. Outbound failures (server reject or socket throw) emit IPC `outbound_failed` and fire a macOS notification.
-
-```bash
-# v1: foreground only; wrap in tmux/screen for persistence.
-muc assistantd-start                               # default iPad slot
-muc assistant-new desk-bot --description "out-of-hours triage in IT 值班群"
-$EDITOR ~/.muc/assistants/desk-bot/config.json     # add scope.tids etc.
-muc assistant-edit desk-bot                        # tune the persona
-muc assistant-start desk-bot                       # attach to running daemon
-muc assistant-list --json | jq '.data.assistants[] | {name,active,commands,scope}'
-
-# Specialist with a slash-command claim (paired with a fallback chatter):
-muc assistant-new img-gen --commands /img,/draw --description "image generation"
-muc assistant-new chatter --description "general triage in IT 值班群"
-muc assistant-start img-gen
-muc assistant-start chatter
-# /img cat → img-gen ;  /help → daemon menu ;  anything else → chatter
-
-# Inspect / unwind
-muc assistantd-status --json
-muc assistant-memory desk-bot --clear
-muc assistant-stop desk-bot
-muc assistantd-stop
-```
-
-**Message tail (signature)**: by default `muc send` appends a short tail to
-the text it sends (e.g. `"\n—— 来自王璐璐的muc-cli"`) so recipients can
-tell automated traffic from a typed message. The check is idempotent —
-if your text already ends with the resolved tail, it is not appended a
-second time. Customise it with the
-`messageTail` field in `~/.muc/config.json` — set to a non-empty string to
-override, or to `""` to disable entirely. You can also use
-`muc init --message-tail "<custom>"` / `muc init --no-message-tail` to
-write the value, and per-call flags `muc send --tail "<one-off>"` /
-`muc send --no-tail` to override on a single send. Only `muc send`
-(plain-text) is affected; `send-file` / `send-image` / `send-voice` are
-not.
-
-```bash
-muc tcp-ping --wait 8                         # safe protocol smoke test
-muc send "hello from the CLI"                 # to-self (default)
-muc send --peer ZHANG_W2 "ping" --yes-not-self
-muc send --team 9009876543210000 "team message" --yes-not-self
-
-muc send-file ./report.pdf --to-self                                  # self test
-muc send-image ./screenshot.png --peer ZHANG_W2 --yes-not-self        # auto width/height
-muc send-voice ./clip.amr --duration 3500 --to-self                   # 3.5 s clip
-
-muc download --file-key /chat/m/WANGLULU8/.../<md5> --out ./got.bin   # by explicit key
-muc download --mid 69ef1ae07e5462c465c05e00 --to-self                 # look up body via roaming
-muc download --mid <MID> --peer YANWENYU --out ./inbox/                # save into a directory
-```
-
-`download` is the only file-channel command that **doesn't** open a chat
-session — it speaks only port 6101 (and a one-time bucket lookup on first
-call). Run it from any environment without disturbing your desktop or phone.
-
-## Coexistence
-
-**REST commands always coexist** with a running desktop and phone — the
-server allows concurrent `accessToken`s. `whoami`, `search`, `search-dept`,
-`search-app`, `search-sno`, `history`, `whois`, `set-signature`, `groups`, `default-emojis`, and
-`download` are REST-only (or 6101-only, in `download`'s case) and safe to
-run anytime.
-
-**Chat-channel commands** (`sync`, `search-team`, `team-members`, `send`, `send-file`,
-`send-image`, `send-voice`, `withdraw`, `clear-session`, `pin`, `unpin`, `pinned`) open a TCP-8101
-session and share a per-user **three-slot** model with real devices:
-
-| Slot | `--os` values |
-|---|---|
-| PC | `Windows`, `"OS X"`, `Mac` |
-| Mobile | `iOS`, `Android` |
-| iPad | `iPad` (default; wire `os:"iOS", browser:"iPad"`) |
-
-A second login in the same slot kicks the previous client off the realtime
-channel — the IM panel goes offline, but tokens stay valid (reopen to
-recover). The Mac desktop signs in as `"OS X"` (PC); the iPhone signs in as
-`iOS` (Mobile); the iPad app adds `browser:"iPad"` (iPad).
-
-The CLI defaults to `--os iPad`, so desktop and phone can remain online.
-Only a real iPad on the same account may be kicked by the default. Explicit
-PC or Mobile values intentionally target those older slots.
-
-`tcp-ping` only does TCP connect + NEGOTIATE (no `auth/login`), so it can't
-kick anything. Run it first to confirm the wire protocol is happy on your
-network.
-
-If you do get kicked, reopen the desktop's IM panel or relaunch the mobile
-app to recover — tokens stay valid.
-
-## Examples
-
-```bash
-$ printf '%s' "$MY_PWD" | muc login --account WANGLULU8 --password-stdin
-uid: WANGLULU8
-empId: 5394483846707200
-name: 王璐璐
-accessToken: TV5l…u9kQ (redacted; use --json for raw)
-accessTokenExpireAt: 1745678340000
-tokenPwdRefreshed: true
-tokenPwdExpireAt: 1748097540000
-
-$ muc whoami
-uid: WANGLULU8
-empId: 5394483846707200
-name: 王璐璐
-deviceId: 8e413b4141…
-deviceName: WANGLULU8-mbp.local (muc-cli)
-accessToken: TV5l…u9kQ (redacted; use --json for raw)
-accessTokenExpireAt: 1745678340000
-tokenPwdSet: true
-tokenPwdExpireAt: 1748097540000
-savedAt: 1745073540000
-credentialsPath: ~/.muc/credentials.json
-
-$ muc search 张
-ZHANG_W2       张伟      飞行部 / 机长室
-ZHANGSAN03     张三      地面服务部
-…
-
-$ muc whois ZHANG_W2
-uid        ZHANG_W2
-name       张伟
-empId      4892173049281024
-mobile     1380013…
-email      zhang.wei@ceair.com
-dept       飞行部 / 机长室
-title      机长
-
-$ muc groups
-starred:
-  [常用] (3)
-    9001234567890123     IT 值班群
-    9001234567890124     运行联络
-    9001234567890125     部门通知
-dept groups: 1
-  9009876543210000     飞行部 / 机长室
-
-$ muc default-emojis
-emojis:
-  - [+1]
-  - [DONE]
-  - [GET]
-  ...
-reactions:
-  - [+1]
-  - [收到]
-  - [加油]
-  - [OK]
-  - [点赞]
-  - [鼓掌]
-  - [DONE]
-defaultReaction: [点赞]
-```
-
-## Files & paths
-
-| Path | Purpose | Mode |
-|---|---|---|
-| `~/.muc/config.json` | tenant config: APP_KEY, APP_ID, signing secrets, hosts/ports | 600 |
-| `~/.muc/credentials.json` | accessToken, tokenPwd, profile | 600 |
-| `~/.muc/device-id` | stable per-CLI deviceId (sha256 hex) | 600 |
-| `~/.muc/remember.salt` | salt for the optional `--remember` password blob | 600 |
-| `~/.muc/runtime/daemon.sock`, `daemon.pid`, `daemon-state.json`, `daemon-events-*.ndjson` | personal daemon IPC, pid/state, and raw event history | — |
-| `~/.muc/assistant/config.json`, `credentials.json`, `device-id`, … | the daemon's [dedicated account](#dedicated-account-for-the-daemon), when provisioned — same file set as above, scoped to one profile dir | 600 |
-| `~/.muc/assistant/` (other files) | daemon runtime: `daemon.pid`, `assistant.sock`, `state.json`, `inbox.ndjson`, `events-*.ndjson`, `conflicts.log` | — |
-| `~/.muc/assistants/<name>/` | per-assistant persona: `config.json`, `system-prompt.md`, `threads/`, `workspace/` | — |
-
-Everything shares the `~/.muc/` parent (mode 700). The CLI creates these on
-first use; you should never need to edit the `config.json` / `credentials.json`
-files by hand.
-
-## Changelog
-
-#### Unreleased
-- Add the third iPad chat slot. Logical `--os iPad` serializes as `os:"iOS", browser:"iPad"` and is now the built-in default for personal commands, the personal daemon, and assistantd. Existing explicit `defaultChatOs` values remain authoritative.
-- Slot safety guidance is now non-blocking: skills remind that a real iPad may be kicked and continue without asking for slot confirmation. Recipient, content, and destructive-action confirmations are unchanged.
-- Add the personal daemon command family: `muc daemon-start`, `daemon-status`, `daemon-stop`, and `daemon-events`. Ordinary chat-channel commands now route only through the personal daemon and report `daemon_kind:"personal"` when routed.
-- Dedicated `assistantd` is no longer borrowed by ordinary commands. Without a dedicated assistant profile, `assistantd-start` now requires explicit `muc init --allow-assistant-shared-profile`; same-uid shared-profile assistantd conflicts with the personal daemon / direct ordinary TCP via `DAEMON_CONFLICT`.
-- Add raw event cursors (`<epoch_ms>-<sequence>`), 90-day personal daemon event retention, and `CURSOR_NOT_FOUND` handling for missing retained cursors.
-
-#### `0.5.0`
-`2026.05.11`
-- Add `muc assistant-init` / `muc assistant-login` and `muc whoami --assistant`: the assistant daemon can authenticate as a **dedicated account** under `~/.muc/assistant/`, fully separate from the personal profile. At this release it defaulted to the PC slot; the current Unreleased behavior supersedes that with the iPad default. `assistant-login` still defaults REST `--platform` to `mac`.
-- Internals: `config.json` / `credentials.json` / `device-id` / `remember.salt` / `runtime/refresh-log.ndjson` paths now resolve through a process-wide *profile root* (default `~/.muc`) instead of being hardcoded. `configPath` / `credentialsPath` / `configDir` are now functions.
-
-#### `0.4.1`
-`2026.05.03`
-- Redesign assistant routing around globally-unique slash-commands (`assistant-new --commands /img,/draw`) plus a `commands:[]` fallback bucket; `/help` is now a daemon-owned per-thread menu reachable even when no assistants are active. Drop the draft / 👍 / DONE approval flow, `auto_send`, `cooldown_ms`, `draft_ttl_ms`, and `scope.default` — replies ship straight to the thread.
-- Loop-stop is now structural: every reply carries a `\n\n— <assistant> · <model>` signature tail, and any inbound whose last paragraph matches that shape is dropped before routing. The `__SKIP__` literal is gone — backends return `{"action":"skip","blocks":[]}` instead.
-- Outbound send failures emit IPC `outbound_failed` and fire a macOS notification. The monitor (`muc assistant-ui`) and `muc assistant-log` surface the daemon-owned routing replies (`help_menu_sent` / `unknown_command_sent` / `no_route_hint_sent`) under the synthetic `daemon` owner.
-- Existing `~/.muc/assistants/<name>/config.json` files are migrated in place on read: removed fields stripped, `commands: []` injected.
-
-#### `0.4.0`
-`2026.04.30`
-- Add `muc assistantd-start` / `assistantd-status` / `assistantd-stop` (foreground daemon, holds one TCP slot, owns the chat socket for the rest of the CLI via IPC)
-- Add `muc assistant-new` / `assistant-list` / `assistant-start` / `assistant-stop` / `assistant-edit` / `assistant-memory` / `assistant-delete` to manage named auto-reply assistants under `~/.muc/assistants/<name>/`
-- Pluggable backends (`claude-code`, `codex`, `gemini`, `cursor`); per-assistant scope rules, priority, persona overlay on a bundled safety-rails prompt, rolling memory window
-- Other chat-channel commands (`send`, `send-file`, `send-image`, `send-voice`, `withdraw`, `sync`, `wait-react`, `listen`) now route through the daemon when it's running; `--json` output gains `route: "daemon" \| "direct"`. Conflicting `--os` and `listen --include-offline` are rejected up front; a parked daemon yields `code:"DAEMON_UNAVAILABLE"`
-
-#### `0.3.1`
-`2026.04.29`
-- Add `defaultChatOs` to `~/.muc/config.json`. At this release the accepted values stopped at Android and the built-in fallback was `iOS`; current Unreleased behavior also accepts `ipad` and defaults to `iPad`.
-
-#### `0.3.0`
-`2026.04.29`
-- Add `muc react` / `muc unreact` / `muc reactions` to add, revoke, and list emoticon reactions on existing messages
-- Add `muc wait-react` to block until a human reacts to a given mid; useful as a "human-in-the-loop approval" gate after `muc send`
-- Add `muc listen`, a long-lived TCP tap with sender / chat / keyword / `--at-me` filters, one NDJSON line per match
-- Exit code `5` now also covers `TIMEOUT` and `KICKED`
-
-#### `0.2.2`
-`2026.04.28`
-- `muc send` plain-text now appends an idempotent signature tail by default; override via `--tail` / `--no-tail`, `muc init --message-tail`, or `messageTail` in `~/.muc/config.json`
-
-#### `0.2.1`
-`2026.04.28`
-- Skills unified across macOS / Linux / Windows
-- On Windows, file mode `600` is silently ignored — use NTFS ACLs on shared hosts to protect `~/.muc/`
-
-#### `0.2.0`
-`2026.04.27`
-- Add `muc init`: extract `appKey` / `appId` / signing secrets out of source code, write to `~/.muc/config.json` (mode 600)
-- Companion subcommands: `muc init --check` / `--show` / `--reset`
-- License changed to MIT; package published to npm with public access
-
-## What it can't do (yet)
-
-- **Richtext messages** (`subType=11`, mixed text + image + @-mention in one
-  bubble). The image segments share the file-channel upload path so the
-  bulk of the work is already there; just needs a body-builder + a
-  `send-rich` command.
-- **Forwarded / merged messages** (`subType=26`).
-- **SSO / scan-to-login.** REST username+password works; the SSO flow is
-  not wired up.
-- **Image thumbnails.** The upload step asks the server to make `tn1`/`tn5`
-  thumbs, but `muc download` only fetches the original `fileKey`.
-- **End-to-end-encrypted file content.** Not active on the default tenant
-  and the CLI doesn't implement it.
-
-## Troubleshooting
-
-- `code: CONFIG_MISSING` (exit 6) — `~/.muc/config.json` is absent. Run
-  `muc init` to create it. The CLI cannot guess your tenant's signing
-  secrets.
-- `code: CONFIG_INVALID` (exit 7) — the file exists but failed schema
-  validation (corruption, manual edit gone wrong, or a stale schema after
-  upgrade). Run `muc init` to repair it; `--reset --yes` to start clean.
-- `login failed: code=…` — sign or DES is wrong. Double-check the signing
-  secrets and `appKey` / `appId` you supplied to `muc init` against the
-  values your MUC admin provided. `muc init --show` (secrets redacted) lets
-  you confirm what's currently saved; `muc init` (interactive) lets you
-  re-enter the values.
-- `error: not logged in` (exit 3, code `AUTH_REQUIRED`) — the saved
-  credentials file is missing or unreadable. Check `~/.muc/credentials.json`
-  and re-run `muc login`.
-- `code: AUTH_EXPIRED` (exit 3) — accessToken or tokenPwd was rejected by
-  the server. On the personal profile (`~/.muc`), re-run `muc login --token-pwd`
-  (or full `muc login` if `tokenPwd` is also stale). On the dedicated
-  assistant profile (`~/.muc/assistant/config.json` present — the daemon
-  account), substitute `muc assistant-login --token-pwd` /
-  `muc assistant-login` — `muc login` only touches the personal credentials.
-- `EPROTO` / TLS errors — corporate proxy or VPN intercepting traffic.
-  `muc-cli` does not pin certificates, so adding the proxy CA to your Node
-  trust store should suffice (`NODE_EXTRA_CA_CERTS=/path/to/ca.pem`).
-- A TCP command kicks a client off the IM panel — the CLI's `--os` value
-  collided with that client's slot. The default `--os iPad` only risks a
-  real iPad; explicit PC or Mobile values risk the matching client.
-
-### 5.9 Gemini CLI headless timeout
-
-If a `backend: "gemini"` assistant times out with empty stdout/stderr,
-the current adapter is already passing `--skip-trust`, closing stdin,
-and killing the full process tree on timeout. Round-5 live probes against
-Gemini CLI `0.40.0` still found an environment-specific failure mode
-where Node `child_process.spawn()` never receives JSON output even after
-testing:
-
-- `stdin.end(payload)` vs `write()+destroy()`
-- `detached: true` vs `false`
-- explicit `TERM` / `CI` / `GEMINI_*` / `GOOGLE_*` / `NO_COLOR` env sync
-- `mkdtemp()` dir mode `0700` vs `0755`
-- `stdio: ['pipe','inherit','inherit']`
-- `GEMINI_CLI_TRUST_WORKSPACE=true`
-
-If the same `gemini ... --output-format json` command works in your
-interactive terminal but not when spawned from Node, treat it as an
-external Gemini CLI runtime issue rather than a muc prompt/JSON bug. The
-daemon now fails fast with a timeout instead of hanging indefinitely; use
-`claude-code` or `codex` for unattended runs on hosts where Gemini only
-works interactively.
-
-### Exit-code summary
-
-| Exit | Code |
-|---|---|
-| 0 | success |
-| 1 | INTERNAL |
-| 2 | USAGE |
-| 3 | AUTH_REQUIRED, AUTH_EXPIRED |
-| 4 | NOT_FOUND |
-| 5 | REMOTE_ERROR, NETWORK, TIMEOUT, KICKED, DAEMON_UNAVAILABLE |
-| 6 | CONFIG_MISSING |
-| 7 | CONFIG_INVALID |
-
-## Security
-
-- Both files in `~/.muc/` are written with mode `600`. **Don't** check them
-  into git or copy them to shared machines.
-- **Don't share `~/.muc/config.json`** — it contains your tenant's signing
-  secrets (`signSecretRest`, `signSecretSecure`, `pwdDesKey`, `appKey`).
-  Anyone with these can impersonate API calls against your MUC tenant.
-- `MUC_PASSWORD` ends up in shell history; prefer `--password-stdin` or
-  `--token-pwd` for refreshes.
-- **Prefer interactive `muc init` over env vars.** Environment variables
-  leak through shell history and `/proc/<pid>/environ` to other processes
-  on the same machine. Use the interactive prompt or one-shot flags pulled
-  from a secret manager rather than persistent `MUC_*` exports.
-- TCP login over 8101 registers a device session in one of three slots per
-  user (PC, Mobile, or iPad). A second login in the same slot kicks the first.
-  Default `--os iPad` only risks a real iPad on the same account.
-- `tcp-ping` is the only chat-channel command that cannot kick anything —
-  use it as a network smoke-test before trying TCP sends.
+普通文件发送默认不带尾注（包括带说明的文件消息）；明确 `--tail` 才添加。文件上传须完成服务端扫描并取得未来有效期，才会进入消息发送；扫描失败不会降级发送过期文件。