@mu-cabin/muc-cli 0.2.2 → 0.3.0

package/README.md

@@ -13,11 +13,14 @@ with real devices; see [Coexistence](#coexistence) below before sending.
 
 A single command (`muc`) packaging:
 
-- **Send** — 1:1 and group text, files, images, and voice clips.
+- **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, and directory search (people, departments, apps, service numbers).
+  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.
+  download a chat-attached file, wait for a human emoticon reaction before
+  proceeding (`wait-react`).
 - **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.
@@ -186,6 +189,9 @@ MUC_ACCOUNT=WANGLULU8 MUC_PASSWORD='…' muc login
 | `muc emoticons` | Sticker packages installed on your account. |
 | `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> --sticker-id <id> [target]` | Add an emoticon reaction to an existing message. **Visible.** Defaults to `--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`,
@@ -214,6 +220,8 @@ muc history --team 9009876543210000 --before 2026-04-20 --json | jq .
 | `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 wait-react --mid <MID> [--from-uid UID] [--sticker-id ID] [--timeout 300]` | Block until someone reacts with an emoticon 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` defaults to `iOS`. Valid values: `Windows`, `OS X`, `Mac`, `iOS`,
 `Android`. **`--os` does not provide coexistence — read the section below
@@ -351,6 +359,30 @@ $ muc emoticons
 Both files share the `~/.muc/` parent (mode 700). The CLI creates them on
 first use; you should never need to edit them by hand.
 
+## Changelog
+
+#### `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
@@ -360,8 +392,6 @@ first use; you should never need to edit them by hand.
 - **Forwarded / merged messages** (`subType=26`).
 - **SSO / scan-to-login.** REST username+password works; the SSO flow is
   not wired up.
-- **Live push streaming.** Use `muc history` for server-side message
-  retrieval; there is no long-lived `talk/msg` listener 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
@@ -404,7 +434,7 @@ first use; you should never need to edit them by hand.
 | 2 | USAGE |
 | 3 | AUTH_REQUIRED, AUTH_EXPIRED |
 | 4 | NOT_FOUND |
-| 5 | REMOTE_ERROR, NETWORK |
+| 5 | REMOTE_ERROR, NETWORK, TIMEOUT, KICKED |
 | 6 | CONFIG_MISSING |
 | 7 | CONFIG_INVALID |
 

package/dist/muc.mjs

@@ -21403,6 +21403,8 @@ var EXIT_CODES = {
   NOT_FOUND: 4,
   REMOTE_ERROR: 5,
   NETWORK: 5,
+  TIMEOUT: 5,
+  KICKED: 5,
   CONFIG_MISSING: 6,
   CONFIG_INVALID: 7,
   INTERNAL: 1
@@ -21420,6 +21422,9 @@ var JSON_MODE = false;
 function setJsonMode(v) {
   JSON_MODE = v;
 }
+function isJsonMode() {
+  return JSON_MODE;
+}
 function stableStringify(value) {
   return JSON.stringify(value, (_k, v) => {
     if (v && typeof v === "object" && !Array.isArray(v)) {
@@ -21591,6 +21596,24 @@ function requireSingleTarget(opts, label) {
     );
   }
 }
+function defineStream(program3, spec) {
+  const cmd = program3.command(spec.name).description(spec.description);
+  spec.configure?.(cmd);
+  cmd.action(async () => {
+    try {
+      await spec.run(cmd);
+    } catch (e) {
+      if (e instanceof CliError) fail(e.code, e.message, e.hint);
+      const cls = classifyError(e);
+      fail(cls.code, cls.msg, cls.hint);
+    }
+  });
+  REGISTRY.push({
+    name: spec.name,
+    description: spec.description,
+    output_schema: spec.streamSchema ?? { type: "object", description: "NDJSON-stream command \u2014 one JSON object per stdout line" }
+  });
+}
 function define2(program3, spec) {
   const cmd = program3.command(spec.name).description(spec.description);
   spec.configure?.(cmd);
@@ -22835,17 +22858,20 @@ var MucChatSocket = class extends EventEmitter {
   host;
   port;
   ackTimeoutMs;
+  idleTimeoutMs;
   debug;
   sock = null;
   reader;
   sq = 2;
   pending = /* @__PURE__ */ new Map();
   closed = false;
+  idleTimer = null;
   constructor(opts) {
     super();
     this.host = opts.host;
     this.port = opts.port;
     this.ackTimeoutMs = opts.ackTimeoutMs ?? 25e3;
+    this.idleTimeoutMs = opts.idleTimeoutMs ?? 75e3;
     this.debug = !!opts.debug;
     this.reader = new FrameReader((f) => this.handleFrame(f));
   }
@@ -22855,12 +22881,20 @@ var MucChatSocket = class extends EventEmitter {
       const sock = createConnection({ host: this.host, port: this.port });
       this.sock = sock;
       sock.setKeepAlive(true, 2e4);
+      const errorSink = (_e) => {
+      };
+      this.on("error", errorSink);
       const onErr = (e) => {
         cleanup();
         reject(e);
       };
+      const onPreReadyClose = () => {
+        cleanup();
+        reject(new Error("chat socket closed before negotiate-ack"));
+      };
       const cleanup = () => {
         sock.off("error", onErr);
+        sock.off("close", onPreReadyClose);
         this.off("ready", onReady);
       };
       const onReady = () => {
@@ -22868,26 +22902,56 @@ var MucChatSocket = class extends EventEmitter {
         resolve2();
       };
       sock.once("error", onErr);
+      sock.once("close", onPreReadyClose);
       this.once("ready", onReady);
       sock.on("connect", () => {
         if (this.debug) console.error("[wire] tcp connect");
         this.emit("connect");
+        this.armIdle();
         this.sendNegotiate();
       });
-      sock.on("data", (buf) => this.reader.feed(buf));
-      sock.on("error", (e) => this.emit("error", e));
-      sock.on("close", () => {
-        if (this.closed) return;
-        this.closed = true;
-        for (const { reject: reject2, timer } of this.pending.values()) {
-          clearTimeout(timer);
-          reject2(new Error("socket closed"));
-        }
-        this.pending.clear();
-        this.emit("close");
+      sock.on("data", (buf) => {
+        this.armIdle();
+        this.reader.feed(buf);
       });
+      sock.on("error", (e) => this.emit("error", e));
+      sock.on("close", () => this.teardown(new Error("socket closed")));
     });
   }
+  /**
+   * (Re)arm the inactivity watchdog. Called every time inbound bytes land
+   * (data callback) or any active confirmation. If no traffic arrives for
+   * `idleTimeoutMs`, we synthesize a teardown so commands don't hang on a
+   * half-open socket the kernel hasn't surfaced yet.
+   */
+  armIdle() {
+    if (this.closed) return;
+    if (this.idleTimer) clearTimeout(this.idleTimer);
+    this.idleTimer = setTimeout(() => {
+      if (this.closed) return;
+      this.emit("error", new Error(`chat socket idle for ${Math.round(this.idleTimeoutMs / 1e3)}s \u2014 tearing down`));
+      try {
+        this.sock?.destroy();
+      } catch {
+      }
+      this.teardown(new Error("idle timeout"));
+    }, this.idleTimeoutMs);
+  }
+  /** Single owner of close-side cleanup: clears idle timer, rejects all pending sends, emits 'close' once. */
+  teardown(reason) {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.idleTimer) {
+      clearTimeout(this.idleTimer);
+      this.idleTimer = null;
+    }
+    for (const { reject, timer } of this.pending.values()) {
+      clearTimeout(timer);
+      reject(reason);
+    }
+    this.pending.clear();
+    this.emit("close");
+  }
   sendNegotiate() {
     const frame = buildFrame(T.NEGOTIATE, NEGOTIATE_BODY, NEGOTIATE_CRC);
     if (this.debug) console.error("[wire] \u2192 NEGOTIATE", frame.toString("hex"));
@@ -22926,11 +22990,26 @@ var MucChatSocket = class extends EventEmitter {
     if (!this.sock || this.closed) throw new Error("not connected");
     this.sock.write(buildFrame(type, payload, crcOverride));
   }
+  /**
+   * Send an unsolicited frame that *re-uses* a sq from a server-pushed frame
+   * (rather than allocating a new one via nextSq). This is how the desktop
+   * SDK ACKs inbound `talk/msg` (message-server/modules/message.js:961-984):
+   * it echoes the original frame's sq back with `{sid, cid, data:{tids}}`.
+   * Fire-and-forget — no pending registration, no response expected.
+   */
+  sendAck(sid, cid, sq, data = {}) {
+    if (!this.sock || this.closed) throw new Error("not connected");
+    const obj = { sid, cid, sq, data };
+    const payload = aesEncrypt(JSON.stringify(obj));
+    if (this.debug) console.error(`[wire] \u2192 ACK ${sid}/${cid} sq=${sq}`);
+    this.sock.write(buildFrame(T.AES_JSON, payload));
+  }
   close() {
     if (!this.sock || this.closed) return;
-    this.closed = true;
+    const sock = this.sock;
+    this.teardown(new Error("socket closed by client"));
     try {
-      this.sock.end();
+      sock.end();
     } catch {
     }
   }
@@ -22940,10 +23019,10 @@ var MucChatSocket = class extends EventEmitter {
       try {
         bodyText = aesDecrypt(f.payload);
       } catch (e) {
-        if (this.listenerCount("error") > 0) {
-          this.emit("error", new Error(`aes decrypt failed (type=${f.type} len=${f.payload.length}): ${e.message}`));
-        } else {
-          console.error(`[wire] aes decrypt failed (type=${f.type} len=${f.payload.length}): ${e.message}`);
+        const err = new Error(`aes decrypt failed (type=${f.type} len=${f.payload.length}): ${e.message}`);
+        this.emit("error", err);
+        if (this.listenerCount("error") <= 1) {
+          console.error(`[wire] ${err.message}`);
         }
         return;
       }
@@ -25091,8 +25170,634 @@ function register21(program3) {
   });
 }
 
-// src/commands/manifest.ts
+// src/lib/reactions.ts
+async function saveReply(cfg, args) {
+  const { ctx, stickerId, senderName, isFromMe, selfAppKey } = args;
+  const isGroup = ctx.scene === "team_g";
+  const targetApp = ctx.targetApp ?? selfAppKey;
+  const body = {
+    sid: ctx.sid,
+    mid: ctx.mid,
+    appkey: selfAppKey,
+    toId: isGroup ? ctx.sid : isFromMe ? ctx.peerUid : ctx.srcSenderId,
+    toAppKey: isGroup ? targetApp : isFromMe ? targetApp : ctx.srcSenderApp || ctx.peerApp,
+    groupId: isGroup ? ctx.sid : void 0,
+    stickerId,
+    senderName,
+    srcSenderId: ctx.srcSenderId,
+    srcSenderApp: ctx.srcSenderApp
+  };
+  return await request({
+    method: "POST",
+    auth: true,
+    url: `${apiUrls(cfg).IMM}/emoticon/reply/save`,
+    body,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+async function listReplies(cfg, mid) {
+  return await request({
+    method: "GET",
+    auth: true,
+    url: `${apiUrls(cfg).IMM}/emoticon/reply/list`,
+    qs: { mid }
+  });
+}
+async function revokeReply(cfg, args) {
+  const { emoticonId, ctx, isFromMe, selfAppKey } = args;
+  const targetApp = ctx.targetApp ?? selfAppKey;
+  const body = {
+    emoticonId,
+    appKey: selfAppKey
+  };
+  if (ctx.scene === "p2p") {
+    body.toId = isFromMe ? ctx.peerUid : ctx.srcSenderId;
+    body.toAppKey = isFromMe ? targetApp : ctx.srcSenderApp || ctx.peerApp;
+  } else {
+    body.groupId = ctx.sid;
+    body.toAppKey = targetApp;
+  }
+  return await request({
+    method: "POST",
+    auth: true,
+    url: `${apiUrls(cfg).IMM}/emoticon/reply/revocation`,
+    body,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+
+// src/commands/react.ts
 var Output22 = external_exports.object({
+  scene: external_exports.enum(["p2p", "team_g"]),
+  sId: external_exports.string(),
+  mid: external_exports.string(),
+  stickerId: external_exports.string(),
+  emoticonId: external_exports.string().optional(),
+  raw: external_exports.unknown()
+});
+function register22(program3) {
+  define2(program3, {
+    name: "react",
+    description: "Add an emoticon reaction to a message (POST emoticon/reply/save). VISIBLE TO THE TARGET CHAT \u2014 non-self targets require --yes-not-self.",
+    output: Output22,
+    configure: (cmd) => {
+      cmd.requiredOption("--mid <mid>", "message id to react to").requiredOption("--sticker-id <id>", "emoticon/sticker id (run `muc emoticons` to list packages)").option("--peer <uid>", "1:1 chat with a peer uid (the OTHER side of the conversation)").option("--team <id>", "group chat with a team id").option("--to-self", "react in your self-chat (default if no target)").option("--src-sender-id <uid>", "UID of the ORIGINAL message sender (defaults to current user \u2014 i.e. reacting to your own message)").option("--src-sender-app <appkey>", "appKey of the original message sender (defaults to your app key)").option("--target-app-key <appkey>", "original message `app_key` field \u2014 distinct from --src-sender-app (`fApp`); only matters in cross-tenant reacts. Defaults to your app key.").option("--sender-name <name>", "override displayed sender name (defaults to your saved name)").option("--yes-not-self", "required to confirm reacting in a non-self conversation");
+    },
+    run: async (cmd) => {
+      const opts = cmd.opts();
+      const cfg = requireConfig();
+      const cred = requireAuth(loadCredentials());
+      requireSingleTarget(opts, "react");
+      let scene;
+      let peerUid;
+      if (opts.team) {
+        scene = "team_g";
+      } else if (opts.toSelf || !opts.peer && !opts.team) {
+        scene = "p2p";
+        peerUid = cred.uid;
+      } else {
+        scene = "p2p";
+        peerUid = opts.peer.toUpperCase();
+      }
+      const isSelf = scene === "p2p" && peerUid === cred.uid;
+      if (!isSelf && !opts.yesNotSelf) {
+        throw new CliError(
+          "USAGE",
+          `refusing to react in ${scene}:${opts.team ?? peerUid} without --yes-not-self`,
+          "add --yes-not-self to confirm \u2014 reactions are visible to all participants"
+        );
+      }
+      const srcSenderId = (opts.srcSenderId ?? cred.uid).toUpperCase();
+      const srcSenderApp = opts.srcSenderApp ?? cfg.appKey;
+      const isFromMe = srcSenderId === cred.uid && srcSenderApp === cfg.appKey;
+      const sid = scene === "team_g" ? opts.team : buildSId("p2p", cred.uid, peerUid);
+      const ctx = {
+        scene,
+        sid,
+        mid: opts.mid,
+        srcSenderId,
+        srcSenderApp,
+        peerUid,
+        peerApp: cfg.appKey,
+        targetApp: opts.targetAppKey
+      };
+      const res = await saveReply(cfg, {
+        ctx,
+        stickerId: opts.stickerId,
+        senderName: opts.senderName ?? cred.name ?? cred.uid,
+        isFromMe,
+        selfAppKey: cfg.appKey
+      });
+      if (res.code !== 0) {
+        throw new CliError("REMOTE_ERROR", `react rejected: code=${res.code} msg=${res.msg ?? ""}`.trim());
+      }
+      const data = res.data ?? {};
+      const emoticonId = pickEmoticonId(data);
+      return {
+        scene,
+        sId: sid,
+        mid: opts.mid,
+        stickerId: opts.stickerId,
+        emoticonId,
+        raw: res
+      };
+    }
+  });
+}
+function pickEmoticonId(data) {
+  if (!data || typeof data !== "object") return void 0;
+  const d = data;
+  for (const k of ["emoticonId", "id", "replyId", "commentId"]) {
+    const v = d[k];
+    if (typeof v === "string" && v.length > 0) return v;
+    if (typeof v === "number") return String(v);
+  }
+  return void 0;
+}
+
+// src/commands/reactions.ts
+var Output23 = external_exports.object({
+  mid: external_exports.string(),
+  count: external_exports.number(),
+  reactions: external_exports.array(external_exports.unknown()),
+  raw: external_exports.unknown()
+});
+function register23(program3) {
+  define2(program3, {
+    name: "reactions",
+    description: "List emoticon reactions on a message (GET emoticon/reply/list?mid=\u2026).",
+    output: Output23,
+    configure: (cmd) => {
+      cmd.requiredOption("--mid <mid>", "message id to inspect");
+    },
+    run: async (cmd) => {
+      const { mid } = cmd.opts();
+      const cfg = requireConfig();
+      requireAuth(loadCredentials());
+      const res = await listReplies(cfg, mid);
+      if (res.code !== 0) {
+        throw new CliError("REMOTE_ERROR", `reactions list rejected: code=${res.code} msg=${res.msg ?? ""}`.trim());
+      }
+      const reactions = extractList(res.data);
+      return {
+        mid,
+        count: reactions.length,
+        reactions,
+        raw: res
+      };
+    }
+  });
+}
+function extractList(data) {
+  if (Array.isArray(data)) return data;
+  if (data && typeof data === "object") {
+    for (const k of ["list", "reactions", "replies", "records", "items"]) {
+      const v = data[k];
+      if (Array.isArray(v)) return v;
+    }
+  }
+  return [];
+}
+
+// src/commands/unreact.ts
+var Output24 = external_exports.object({
+  scene: external_exports.enum(["p2p", "team_g"]),
+  emoticonId: external_exports.string(),
+  raw: external_exports.unknown()
+});
+function register24(program3) {
+  define2(program3, {
+    name: "unreact",
+    description: "Revoke one of your emoticon reactions (POST emoticon/reply/revocation). VISIBLE TO THE TARGET CHAT \u2014 non-self targets require --yes-not-self.",
+    output: Output24,
+    configure: (cmd) => {
+      cmd.requiredOption("--emoticon-id <id>", "reaction id (returned by `muc react` or seen in `muc reactions --mid \u2026`)").option("--peer <uid>", "1:1 chat with a peer uid").option("--team <id>", "group chat with a team id").option("--to-self", "revoke in your self-chat (default if no target)").option("--src-sender-id <uid>", "UID of the original message sender (defaults to current user)").option("--src-sender-app <appkey>", "appKey of the original message sender (defaults to your app key)").option("--target-app-key <appkey>", "original message `app_key` field \u2014 distinct from --src-sender-app (`fApp`); only matters in cross-tenant revokes. Defaults to your app key.").option("--yes-not-self", "required to confirm revoking in a non-self conversation");
+    },
+    run: async (cmd) => {
+      const opts = cmd.opts();
+      const cfg = requireConfig();
+      const cred = requireAuth(loadCredentials());
+      requireSingleTarget(opts, "unreact");
+      let scene;
+      let peerUid;
+      if (opts.team) {
+        scene = "team_g";
+      } else if (opts.toSelf || !opts.peer && !opts.team) {
+        scene = "p2p";
+        peerUid = cred.uid;
+      } else {
+        scene = "p2p";
+        peerUid = opts.peer.toUpperCase();
+      }
+      const isSelf = scene === "p2p" && peerUid === cred.uid;
+      if (!isSelf && !opts.yesNotSelf) {
+        throw new CliError(
+          "USAGE",
+          `refusing to revoke reaction in ${scene}:${opts.team ?? peerUid} without --yes-not-self`,
+          "add --yes-not-self to confirm"
+        );
+      }
+      const srcSenderId = (opts.srcSenderId ?? cred.uid).toUpperCase();
+      const srcSenderApp = opts.srcSenderApp ?? cfg.appKey;
+      const isFromMe = srcSenderId === cred.uid && srcSenderApp === cfg.appKey;
+      const sid = scene === "team_g" ? opts.team : buildSId("p2p", cred.uid, peerUid);
+      const ctx = {
+        scene,
+        sid,
+        // mid not needed for revoke (server identifies by emoticonId)
+        mid: "",
+        srcSenderId,
+        srcSenderApp,
+        peerUid,
+        peerApp: cfg.appKey,
+        targetApp: opts.targetAppKey
+      };
+      const res = await revokeReply(cfg, {
+        emoticonId: opts.emoticonId,
+        ctx,
+        isFromMe,
+        selfAppKey: cfg.appKey
+      });
+      if (res.code !== 0) {
+        throw new CliError("REMOTE_ERROR", `unreact rejected: code=${res.code} msg=${res.msg ?? ""}`.trim());
+      }
+      return {
+        scene,
+        emoticonId: opts.emoticonId,
+        raw: res
+      };
+    }
+  });
+}
+
+// src/commands/wait-react.ts
+var Output25 = external_exports.object({
+  matched: external_exports.literal(true),
+  mid: external_exports.string(),
+  reaction: external_exports.unknown()
+});
+function register25(program3) {
+  define2(program3, {
+    name: "wait-react",
+    description: "Block until someone adds an emoticon reaction (subType=300) to --mid. Consumes a TCP slot \u2014 defaults to --os iOS (Mobile slot).",
+    output: Output25,
+    configure: (cmd) => {
+      cmd.requiredOption("--mid <mid>", "message id to wait for a reaction on").option("--from-uid <uid>", "only consider reactions from this UID (case-insensitive match against fId of the type=3 notification)").option("--sticker-id <id>", "only consider reactions whose stickerId matches").option("--timeout <seconds>", "give up after this many seconds (default 300)", parsePosInt("--timeout"), 300).option("--os <os>", "chat-channel os slot", parseChatOs, DEFAULT_CHAT_OS).option("--debug", "forward wire-level debug events to stderr");
+    },
+    run: async (cmd) => {
+      const opts = cmd.opts();
+      const cred = requireAuth(loadCredentials());
+      const wantedFrom = opts.fromUid?.toUpperCase();
+      const session = await openChatSession(cred, { os: opts.os, debug: opts.debug });
+      const { socket } = session;
+      try {
+        return await new Promise((resolve2, reject) => {
+          const timer = setTimeout(() => {
+            reject(new CliError(
+              "TIMEOUT",
+              `no matching reaction on mid=${opts.mid} after ${opts.timeout}s`
+            ));
+          }, opts.timeout * 1e3);
+          const cleanup = () => clearTimeout(timer);
+          socket.on("kicked", (payload) => {
+            cleanup();
+            reject(new CliError(
+              "KICKED",
+              `chat session kicked: ${JSON.stringify(payload).slice(0, 200)}`,
+              "another login claimed the same device slot \u2014 see HANDOFF.md slot model"
+            ));
+          });
+          socket.on("error", (e) => {
+            cleanup();
+            reject(new CliError("NETWORK", `chat socket error: ${e.message}`));
+          });
+          socket.on("close", () => {
+            cleanup();
+            reject(new CliError("NETWORK", "chat socket closed before a matching reaction arrived"));
+          });
+          socket.on("push", (frame) => {
+            ackInboundIfNeeded(socket, frame);
+            if (frame.sid !== "talk") return;
+            if (frame.cid !== "msg" && frame.cid !== "offMsg") return;
+            const msgs = frame.data?.msgs ?? [];
+            for (const m of msgs) {
+              if (m?.type !== 3 || m?.subType !== 300) continue;
+              const body = m.body ?? {};
+              const refMid = String(body.mid ?? body.refMid ?? "");
+              if (refMid !== opts.mid) continue;
+              if (wantedFrom && String(m.fId ?? "").toUpperCase() !== wantedFrom) continue;
+              if (opts.stickerId) {
+                const sid = String(body.stickerId ?? "");
+                if (sid !== opts.stickerId) continue;
+              }
+              cleanup();
+              resolve2({ matched: true, mid: opts.mid, reaction: m });
+              return;
+            }
+          });
+          socket.send("sync", "syncDone", { timestamp: 0 }).catch(() => {
+          });
+        });
+      } finally {
+        socket.close();
+      }
+    }
+  });
+}
+function ackInboundIfNeeded(socket, frame) {
+  if (frame.sid !== "talk") return;
+  if (frame.cid !== "msg" && frame.cid !== "offMsg") return;
+  const sqRaw = frame.sq;
+  const sq = typeof sqRaw === "number" ? sqRaw : Number.parseInt(String(sqRaw ?? ""), 10);
+  if (!Number.isFinite(sq)) return;
+  const tids = Array.isArray(frame.data?.tids) ? frame.data.tids : [];
+  if (tids.length === 0) return;
+  try {
+    socket.sendAck(frame.sid, frame.cid, sq, { tids });
+  } catch {
+  }
+}
+
+// src/commands/listen.ts
+var MESSAGE_DATA_SCHEMA = {
+  type: "object",
+  properties: {
+    mid: { type: "string" },
+    sId: { type: "string" },
+    fId: { type: "string" },
+    fApp: { type: "string" },
+    toId: { type: "string" },
+    scene: { type: "string", enum: ["p2p", "team_g"] },
+    type: { type: "number" },
+    subType: { type: "number" },
+    timestamp: { type: "number" },
+    timestamp_u: { type: "number" },
+    body: {}
+  }
+};
+var STREAM_SCHEMA = {
+  description: "NDJSON stream of envelopes. Under --json each stdout line is one JSON object: either {ok:true, schema_version, data:<message>} for a match, or {ok:false, schema_version, code, msg, hint?} for an in-band error (KICKED / NETWORK). Without --json each line is a one-line human summary (NOT JSON). Use --json for any pipe consumer.",
+  oneOf: [
+    {
+      type: "object",
+      required: ["ok", "schema_version", "data"],
+      properties: {
+        ok: { const: true },
+        schema_version: { type: "number" },
+        data: MESSAGE_DATA_SCHEMA
+      }
+    },
+    {
+      type: "object",
+      required: ["ok", "schema_version", "code", "msg"],
+      properties: {
+        ok: { const: false },
+        schema_version: { type: "number" },
+        // The streaming `push` path emits KICKED / NETWORK in-band; the
+        // wrapping `defineStream` action handler may also fail() with any
+        // CliError code raised before the loop starts (USAGE for bad
+        // --regex/--type, AUTH_REQUIRED/AUTH_EXPIRED from the credential
+        // gate, CONFIG_MISSING/CONFIG_INVALID from `requireConfig`,
+        // REMOTE_ERROR from the chat-login refresh path, INTERNAL for
+        // unexpected throws). Advertise all of them.
+        code: {
+          type: "string",
+          enum: [
+            "KICKED",
+            "NETWORK",
+            "TIMEOUT",
+            "USAGE",
+            "AUTH_REQUIRED",
+            "AUTH_EXPIRED",
+            "NOT_FOUND",
+            "REMOTE_ERROR",
+            "CONFIG_MISSING",
+            "CONFIG_INVALID",
+            "INTERNAL"
+          ]
+        },
+        msg: { type: "string" },
+        hint: { type: "string" }
+      }
+    }
+  ]
+};
+function register26(program3) {
+  defineStream(program3, {
+    name: "listen",
+    description: "Tail incoming chat messages, filtered by sender / team / peer / keyword / regex / @-mention. Emit one line per match \u2014 NDJSON envelope under `--json`, human summary otherwise. Consumes a TCP slot.",
+    streamSchema: STREAM_SCHEMA,
+    configure: (cmd) => {
+      cmd.option("--from-uid <uid>", "only emit messages from this UID (repeat for OR; matched against fId, case-insensitive)", collect, []).option("--team <id>", "only emit messages in this team (repeat for OR)", collect, []).option("--peer <uid>", "only emit p2p messages with this peer UID (repeat for OR)", collect, []).option("--contains <text>", "only emit messages whose text contains this substring, case-insensitive (repeat for OR)", collect, []).option("--regex <pattern>", "only emit messages whose text matches this RE2-flavoured regex (repeat for OR)", collect, []).option("--type <n>", "only emit messages of this `type` field (default 1; repeat for OR)", collectInt("--type"), []).option("--subtype <n>", "only emit messages of this `subType` field (repeat for OR; default = any)", collectInt("--subtype"), []).option("--max <n>", "exit after emitting this many matching lines", parsePosInt("--max")).option("--at-me", "only emit group messages that @-mention you (mirrors the desktop SDK isAtMe: scene=team_g, fId\u2260self, atIds includes self uid). Implies excluding self.").option("--include-self", "do not filter out messages whose fId is your own UID").option("--include-reactions", "also emit type=3 sub=300/301 (reaction add/remove) frames").option("--include-offline", "also emit messages flushed via cid=offMsg on connect (default: only post-connect msg)").option("--os <os>", "chat-channel os slot", parseChatOs, DEFAULT_CHAT_OS).option("--debug", "forward wire-level debug events to stderr");
+    },
+    run: async (cmd) => {
+      const opts = cmd.opts();
+      const cred = requireAuth(loadCredentials());
+      const wantedFromUids = new Set(opts.fromUid.map((s) => s.toUpperCase()));
+      const wantedTeams = new Set(opts.team.map((s) => s));
+      const wantedPeers = new Set(opts.peer.map((s) => s.toUpperCase()));
+      const containsTerms = opts.contains.map((s) => s.toLowerCase());
+      const regexes = opts.regex.map((p) => {
+        try {
+          return new RegExp(p);
+        } catch (e) {
+          throw new CliError("USAGE", `invalid --regex "${p}": ${e.message}`);
+        }
+      });
+      const subtypeImpliesReactions = opts.subtype.some((s) => s === 300 || s === 301);
+      const wantedTypes = opts.type.length ? new Set(opts.type) : /* @__PURE__ */ new Set([1, ...opts.includeReactions || subtypeImpliesReactions ? [3] : []]);
+      const wantedSubtypes = opts.subtype.length ? new Set(opts.subtype) : null;
+      const includeReactions = !!opts.includeReactions;
+      const max = opts.max;
+      const atMeOnly = !!opts.atMe;
+      if (atMeOnly && opts.includeSelf) {
+        throw new CliError("USAGE", "--at-me and --include-self are mutually exclusive (--at-me only matches messages from other users)");
+      }
+      const includeSelf = !!opts.includeSelf;
+      const selfUidUpper = cred.uid.toUpperCase();
+      const selfAppKey = requireConfig().appKey;
+      const session = await openChatSession(cred, { os: opts.os, debug: opts.debug });
+      const { socket } = session;
+      const json = isJsonMode();
+      let matched = 0;
+      let exited = false;
+      const closeAndExit = (code) => {
+        if (exited) return;
+        exited = true;
+        try {
+          socket.close();
+        } catch {
+        }
+        process.exit(code);
+      };
+      const onSigint = () => closeAndExit(0);
+      process.on("SIGINT", onSigint);
+      process.on("SIGTERM", onSigint);
+      socket.on("kicked", (payload) => {
+        emitErr(
+          "KICKED",
+          `chat session kicked: ${JSON.stringify(payload).slice(0, 200)}`,
+          "another login claimed the same device slot \u2014 see HANDOFF.md slot model"
+        );
+        closeAndExit(5);
+      });
+      socket.on("error", (e) => {
+        emitErr("NETWORK", `chat socket error: ${e.message}`);
+        closeAndExit(5);
+      });
+      socket.on("close", () => {
+        if (!exited) {
+          emitErr("NETWORK", "chat socket closed unexpectedly");
+          closeAndExit(5);
+        }
+      });
+      socket.on("push", (frame) => {
+        ackInboundIfNeeded2(socket, frame);
+        if (frame.sid !== "talk") return;
+        if (frame.cid !== "msg" && !(opts.includeOffline && frame.cid === "offMsg")) return;
+        const msgs = frame.data?.msgs ?? [];
+        for (const m of msgs) {
+          if (!matches(m)) continue;
+          emitMatch(m);
+          matched++;
+          if (max && matched >= max) {
+            closeAndExit(0);
+            return;
+          }
+        }
+      });
+      socket.send("sync", "syncDone", { timestamp: 0 }).catch(() => {
+      });
+      function matches(m) {
+        if (!m || typeof m !== "object") return false;
+        if (!wantedTypes.has(m.type)) {
+          return false;
+        }
+        if (wantedSubtypes && !wantedSubtypes.has(m.subType)) return false;
+        if (m.type === 3 && (m.subType === 300 || m.subType === 301) && !includeReactions && !opts.subtype.length && !opts.type.length) {
+          return false;
+        }
+        if (!includeSelf && String(m.fId ?? "").toUpperCase() === selfUidUpper) {
+          return false;
+        }
+        if (atMeOnly) {
+          if (m.scene !== "team_g") return false;
+          if (String(m.fId ?? "").toUpperCase() === selfUidUpper) return false;
+          const atIds = Array.isArray(m.atIds) ? m.atIds : [];
+          const idx = atIds.findIndex((id) => String(id ?? "").toUpperCase() === selfUidUpper);
+          if (idx < 0) return false;
+          const atAppkeys = Array.isArray(m.atAppkeys) ? m.atAppkeys : void 0;
+          if (atAppkeys && selfAppKey) {
+            const includesSelfApp = atAppkeys.includes(selfAppKey);
+            const slotEmpty = !atAppkeys[idx];
+            if (!includesSelfApp && !slotEmpty) return false;
+          }
+        }
+        if (wantedFromUids.size && !wantedFromUids.has(String(m.fId ?? "").toUpperCase())) return false;
+        if (wantedTeams.size) {
+          if (m.scene !== "team_g") return false;
+          if (!wantedTeams.has(String(m.toId ?? ""))) return false;
+        }
+        if (wantedPeers.size) {
+          if (m.scene !== "p2p") return false;
+          const fromId = String(m.fId ?? "").toUpperCase();
+          const toId = String(m.toId ?? "").toUpperCase();
+          const peer = fromId === cred.uid.toUpperCase() ? toId : fromId;
+          if (!wantedPeers.has(peer)) return false;
+        }
+        if (containsTerms.length || regexes.length) {
+          const text = extractText(m).toLowerCase();
+          if (containsTerms.length && !containsTerms.some((t) => text.includes(t))) return false;
+          if (regexes.length && !regexes.some((r) => r.test(text))) return false;
+        }
+        return true;
+      }
+      function emitMatch(m) {
+        const out = {
+          mid: String(m.mid ?? ""),
+          sId: String(m.sId ?? ""),
+          fId: String(m.fId ?? ""),
+          fApp: String(m.fApp ?? ""),
+          toId: String(m.toId ?? ""),
+          scene: m.scene,
+          type: m.type,
+          subType: m.subType,
+          timestamp: m.timestamp,
+          timestamp_u: m.timestamp_u,
+          body: m.body
+        };
+        if (json) {
+          process.stdout.write(JSON.stringify({ ok: true, schema_version: SCHEMA_VERSION, data: out }) + "\n");
+        } else {
+          process.stdout.write(formatHuman(out) + "\n");
+        }
+      }
+      function emitErr(code, msg, hint) {
+        if (json) {
+          process.stdout.write(JSON.stringify({ ok: false, schema_version: SCHEMA_VERSION, code, msg, hint }) + "\n");
+        } else {
+          process.stderr.write(`error: ${msg}
+`);
+          if (hint) process.stderr.write(`  hint: ${hint}
+`);
+          process.stderr.write(`  code: ${code}
+`);
+        }
+      }
+      await new Promise(() => {
+      });
+    }
+  });
+}
+function collect(value, prev) {
+  return [...prev, value];
+}
+function collectInt(label) {
+  return (raw, prev) => {
+    if (!/^\d+$/.test(raw)) throw new CliError("USAGE", `${label} must be a non-negative integer (got ${raw})`);
+    return [...prev, Number(raw)];
+  };
+}
+function ackInboundIfNeeded2(socket, frame) {
+  if (frame.sid !== "talk") return;
+  if (frame.cid !== "msg" && frame.cid !== "offMsg") return;
+  const sqRaw = frame.sq;
+  const sq = typeof sqRaw === "number" ? sqRaw : Number.parseInt(String(sqRaw ?? ""), 10);
+  if (!Number.isFinite(sq)) return;
+  const tids = Array.isArray(frame.data?.tids) ? frame.data.tids : [];
+  if (tids.length === 0) return;
+  try {
+    socket.sendAck(frame.sid, frame.cid, sq, { tids });
+  } catch {
+  }
+}
+function extractText(m) {
+  const body = m?.body;
+  if (typeof body === "string") return body;
+  if (Array.isArray(body)) {
+    return body.map((seg) => typeof seg?.content === "string" ? seg.content : typeof seg?.text === "string" ? seg.text : "").join(" ");
+  }
+  if (body && typeof body === "object") {
+    const candidates = ["text", "content", "fName", "name"];
+    for (const k of candidates) {
+      if (typeof body[k] === "string") return body[k];
+    }
+  }
+  return "";
+}
+function formatHuman(m) {
+  const ts = typeof m.timestamp === "number" ? new Date(m.timestamp * 1e3).toISOString() : "?";
+  const where = m.scene === "team_g" ? `team:${m.toId}` : `p2p:${m.toId}`;
+  const text = (() => {
+    if (typeof m.body === "string") return m.body;
+    if (m.body == null) return "";
+    return JSON.stringify(m.body).slice(0, 200);
+  })();
+  return `${ts} ${m.fId} \u2192 ${where} (type=${m.type}/${m.subType}): ${text}`;
+}
+
+// src/commands/manifest.ts
+var Output26 = external_exports.object({
   version: external_exports.string(),
   schema_version: external_exports.literal(1),
   commands: external_exports.array(external_exports.object({
@@ -25101,11 +25806,11 @@ var Output22 = external_exports.object({
     output_schema: external_exports.unknown()
   }))
 });
-function register22(program3) {
+function register27(program3) {
   define2(program3, {
     name: "manifest",
     description: "Emit the full command graph + per-command output JSON Schema. Skill authors should consume this rather than parse --help.",
-    output: Output22,
+    output: Output26,
     run: async () => ({
       version: CLI_VERSION,
       schema_version: 1,
@@ -25152,6 +25857,11 @@ register19(program2);
 register20(program2);
 register21(program2);
 register22(program2);
+register23(program2);
+register24(program2);
+register25(program2);
+register26(program2);
+register27(program2);
 async function main() {
   try {
     await program2.parseAsync(argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mu-cabin/muc-cli",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Terminal client for MUC IM (com.meicloud.im.dh).",
   "license": "MIT",
   "type": "module",