@mu-cabin/muc-cli 0.2.2 → 0.3.1

package/dist/muc.mjs

@@ -21288,6 +21288,7 @@ import { join } from "node:path";
 var DIR = join(homedir(), ".muc");
 var FILE = join(DIR, "config.json");
 var CONFIG_SCHEMA_VERSION = 1;
+var CHAT_OS_VALUES = ["Windows", "OS X", "Mac", "iOS", "Android"];
 var MucConfigSchema = external_exports.object({
   appKey: external_exports.string().regex(/^[0-9a-f]{8}$/, "appKey must be 8 lowercase hex chars"),
   appId: external_exports.string().regex(/^[0-9a-f]{24}$/, "appId must be 24 lowercase hex chars"),
@@ -21307,6 +21308,10 @@ var MucConfigSchema = external_exports.object({
   //   any other → that literal string (e.g. "\n— bot")
   // Per-call `--tail` / `--no-tail` flags on `muc send` override this.
   messageTail: external_exports.string().max(200).optional(),
+  // Default chat-channel `os` slot for TCP commands when --os is not passed.
+  // PC ({Windows, OS X, Mac}) vs Mobile ({iOS, Android}); same slot as the
+  // running desktop will kick it. Built-in fallback is 'iOS' (Mobile).
+  defaultChatOs: external_exports.enum(CHAT_OS_VALUES).optional(),
   savedAt: external_exports.number().int().nonnegative(),
   schemaVersion: external_exports.literal(CONFIG_SCHEMA_VERSION)
 });
@@ -21394,6 +21399,47 @@ function saveCredentials(c) {
 }
 var credentialsPath = FILE2;
 
+// src/lib/constants.ts
+var APP_NAME = "MUC";
+var APP_VERSION = "3.3.1-250925001";
+var APP_VERSION_IOS = "3.3.0301";
+var PLATFORM_IOS = 1;
+var PLATFORM_ANDROID = 2;
+var PLATFORM_WIN = 4;
+var PLATFORM_MAC = 5;
+var SECURE_SYS_KEY = "mx_app_key";
+var PWD_DES_IV = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8]);
+var DEFAULT_CHAT_OS = "iOS";
+var DEFAULT_REST_PLATFORM = PLATFORM_IOS;
+function defaultMessageTail(userName) {
+  const name = userName.trim() || "unknown";
+  return `
+\u2014\u2014 \u6765\u81EA${name}\u7684muc-cli`;
+}
+var DEFAULTS = {
+  // Hosts/ports for the 东航 deployment. Other tenants override at init.
+  restHost: "https://muc.ceair.com/",
+  ssoHost: "https://store.ceair.com/",
+  imHost: "muc.ceair.com",
+  imPort: 8101,
+  fileHost: "muc.ceair.com",
+  filePort: 6101
+};
+function apiUrls(cfg) {
+  const host = cfg.restHost.endsWith("/") ? cfg.restHost : `${cfg.restHost}/`;
+  return {
+    SYS: `${host}sysconfig/v5/app`,
+    MUC: `${host}muc/v5/app`,
+    MAM: `${host}mam/v5/app`,
+    MAS: `${host}mas/v5/app`,
+    MPM: `${host}mpm/v5/app`,
+    IMM: `${host}imm/v5/app`,
+    MRM: `${host}mrm/v5/app`,
+    CONTACT: `${host}contacts/v5/app`,
+    SECURE: `${host}contacts/secure/v5/app`
+  };
+}
+
 // src/lib/cli.ts
 var SCHEMA_VERSION = 1;
 var EXIT_CODES = {
@@ -21403,6 +21449,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 +21468,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)) {
@@ -21568,6 +21619,11 @@ function parseChatOs(raw) {
     "expected windows|osx|mac|ios|android"
   );
 }
+function resolveChatOs(optsOs, cfg) {
+  if (optsOs !== void 0) return optsOs;
+  if (cfg.defaultChatOs !== void 0) return cfg.defaultChatOs;
+  return DEFAULT_CHAT_OS;
+}
 function parseMoment(label) {
   return (raw) => {
     if (/^\d+$/.test(raw)) {
@@ -21591,6 +21647,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);
@@ -21694,47 +21768,6 @@ function getDeviceName() {
   return `${hostname()} (muc-cli)`;
 }
 
-// src/lib/constants.ts
-var APP_NAME = "MUC";
-var APP_VERSION = "3.3.1-250925001";
-var APP_VERSION_IOS = "3.3.0301";
-var PLATFORM_IOS = 1;
-var PLATFORM_ANDROID = 2;
-var PLATFORM_WIN = 4;
-var PLATFORM_MAC = 5;
-var SECURE_SYS_KEY = "mx_app_key";
-var PWD_DES_IV = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8]);
-var DEFAULT_CHAT_OS = "iOS";
-var DEFAULT_REST_PLATFORM = PLATFORM_IOS;
-function defaultMessageTail(userName) {
-  const name = userName.trim() || "unknown";
-  return `
-\u2014\u2014 \u6765\u81EA${name}\u7684muc-cli`;
-}
-var DEFAULTS = {
-  // Hosts/ports for the 东航 deployment. Other tenants override at init.
-  restHost: "https://muc.ceair.com/",
-  ssoHost: "https://store.ceair.com/",
-  imHost: "muc.ceair.com",
-  imPort: 8101,
-  fileHost: "muc.ceair.com",
-  filePort: 6101
-};
-function apiUrls(cfg) {
-  const host = cfg.restHost.endsWith("/") ? cfg.restHost : `${cfg.restHost}/`;
-  return {
-    SYS: `${host}sysconfig/v5/app`,
-    MUC: `${host}muc/v5/app`,
-    MAM: `${host}mam/v5/app`,
-    MAS: `${host}mas/v5/app`,
-    MPM: `${host}mpm/v5/app`,
-    IMM: `${host}imm/v5/app`,
-    MRM: `${host}mrm/v5/app`,
-    CONTACT: `${host}contacts/v5/app`,
-    SECURE: `${host}contacts/secure/v5/app`
-  };
-}
-
 // src/lib/http.ts
 var UA = `MUC/${APP_VERSION} (CLI; muc-cli/${CLI_VERSION})`;
 var SENSITIVE_QS = /* @__PURE__ */ new Set(["accessToken", "tokenPwd", "sign"]);
@@ -22113,6 +22146,8 @@ var FingerprintShape = external_exports.object({
   filePort: external_exports.number(),
   messageTail: external_exports.string(),
   // summary: "default" / "none" / "custom (N chars)"
+  defaultChatOs: external_exports.string(),
+  // summary: explicit value or "default (iOS)"
   savedAt: external_exports.number(),
   schemaVersion: external_exports.literal(CONFIG_SCHEMA_VERSION)
 });
@@ -22138,6 +22173,10 @@ function summarizeTail(t) {
   if (t === "") return "none";
   return `custom (${t.length} chars)`;
 }
+function summarizeChatOs(v) {
+  if (v === void 0) return `default (${DEFAULT_CHAT_OS})`;
+  return v;
+}
 function redactConfig(c) {
   return {
     appKey: fingerprint2(c.appKey),
@@ -22152,6 +22191,7 @@ function redactConfig(c) {
     fileHost: c.fileHost,
     filePort: c.filePort,
     messageTail: summarizeTail(c.messageTail),
+    defaultChatOs: summarizeChatOs(c.defaultChatOs),
     savedAt: c.savedAt,
     schemaVersion: c.schemaVersion
   };
@@ -22297,7 +22337,7 @@ function register2(program3) {
     description: "Bootstrap or update ~/.muc/config.json (tenant config: APP_KEY, APP_ID, signing secrets, hosts/ports). Interactive prompts by default; non-interactive via flags or MUC_* env vars. WARNING: env vars are visible to other processes via /proc/<pid>/environ and shell history \u2014 prefer interactive or flag-based for production.",
     output: Output2,
     configure: (cmd) => {
-      cmd.option("--check", "verify config presence and validity (exit 0 ok / 6 missing / 7 invalid); does not modify").option("--show", "print the saved config (secrets are always redacted in both human and JSON output; cat ~/.muc/config.json for raw values)").option("--reset", "delete ~/.muc/config.json (requires --yes)").option("--yes", "confirm a destructive action like --reset").option("--no-interactive", "fail rather than prompt for missing fields").option("--app-key <hex>", "tenant APP_KEY (8 lowercase hex)").option("--app-id <hex>", "tenant APP_ID (24 lowercase hex)").option("--sign-secret-rest <s>", "REST signing secret").option("--sign-secret-secure <s>", "secure-API signing secret").option("--pwd-des-key <s>", "password DES key (defaults to APP_KEY)").option("--rest-host <url>", "REST host URL").option("--sso-host <url>", "SSO host URL (optional)").option("--im-host <h>", "IM TCP host").option("--im-port <n>", "IM TCP port").option("--file-host <h>", "file-channel TCP host").option("--file-port <n>", "file-channel TCP port").option("--message-tail <text>", "custom signature appended to outbound `muc send` text (max 200 chars)").option("--no-message-tail", "explicitly disable the message tail (no signature appended)");
+      cmd.option("--check", "verify config presence and validity (exit 0 ok / 6 missing / 7 invalid); does not modify").option("--show", "print the saved config (secrets are always redacted in both human and JSON output; cat ~/.muc/config.json for raw values)").option("--reset", "delete ~/.muc/config.json (requires --yes)").option("--yes", "confirm a destructive action like --reset").option("--no-interactive", "fail rather than prompt for missing fields").option("--app-key <hex>", "tenant APP_KEY (8 lowercase hex)").option("--app-id <hex>", "tenant APP_ID (24 lowercase hex)").option("--sign-secret-rest <s>", "REST signing secret").option("--sign-secret-secure <s>", "secure-API signing secret").option("--pwd-des-key <s>", "password DES key (defaults to APP_KEY)").option("--rest-host <url>", "REST host URL").option("--sso-host <url>", "SSO host URL (optional)").option("--im-host <h>", "IM TCP host").option("--im-port <n>", "IM TCP port").option("--file-host <h>", "file-channel TCP host").option("--file-port <n>", "file-channel TCP port").option("--message-tail <text>", "custom signature appended to outbound `muc send` text (max 200 chars)").option("--no-message-tail", "explicitly disable the message tail (no signature appended)").option("--default-os <os>", "default chat-channel os slot for TCP commands when --os is not passed (windows|osx|mac|ios|android); built-in fallback is iOS");
     },
     run: async (cmd) => {
       const opts = cmd.opts();
@@ -22407,6 +22447,26 @@ function register2(program3) {
       } else if (existing && "messageTail" in existing) {
         messageTail = existing.messageTail;
       }
+      let defaultChatOs;
+      let dcoRaw;
+      const dcoFlag = opts.defaultOs;
+      const dcoEnv = process.env.MUC_DEFAULT_OS;
+      if (typeof dcoFlag === "string" && dcoFlag.length > 0) {
+        dcoRaw = dcoFlag;
+      } else if (dcoEnv !== void 0 && dcoEnv.length > 0) {
+        dcoRaw = dcoEnv;
+      } else if (existing?.defaultChatOs !== void 0) {
+        defaultChatOs = existing.defaultChatOs;
+      } else if (interactive) {
+        const answer = await readLine(
+          "Default chat OS slot (windows|osx|mac|ios|android)",
+          DEFAULT_CHAT_OS.toLowerCase()
+        );
+        if (answer.length > 0) dcoRaw = answer;
+      }
+      if (dcoRaw !== void 0) {
+        defaultChatOs = parseChatOs(dcoRaw);
+      }
       const draft = {
         appKey: String(partial.appKey ?? ""),
         appId: String(partial.appId ?? ""),
@@ -22420,6 +22480,7 @@ function register2(program3) {
         fileHost: String(partial.fileHost ?? ""),
         filePort: Number(partial.filePort ?? 0),
         messageTail,
+        defaultChatOs,
         savedAt: Date.now(),
         schemaVersion: CONFIG_SCHEMA_VERSION
       };
@@ -22835,17 +22896,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 +22919,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 +22940,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 +23028,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 +23057,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;
       }
@@ -23141,13 +23258,14 @@ function register9(program3) {
     description: 'Search groups the current user belongs to (TCP chat channel sid="team", cid="search_own_teams"). Pass --enrich for names + member counts. Will kick a session in the same online-slot.',
     output: Output9,
     configure: (cmd) => {
-      cmd.argument("<keyword>", "team name fragment").option("--enrich", "follow up with team/get_team per id").option("--os <os>", "chat-channel os slot", parseChatOs, DEFAULT_CHAT_OS).option("--debug", "forward wire-level debug events to stderr");
+      cmd.argument("<keyword>", "team name fragment").option("--enrich", "follow up with team/get_team per id").option("--os <os>", "chat-channel os slot (default: cfg.defaultChatOs ?? iOS)", parseChatOs).option("--debug", "forward wire-level debug events to stderr");
     },
     run: async (cmd) => {
       const [kw] = cmd.args;
-      const { enrich, os, debug } = cmd.opts();
+      const { enrich, os: optsOs, debug } = cmd.opts();
       const cfg = requireConfig();
       const cred = requireAuth(loadCredentials());
+      const os = resolveChatOs(optsOs, cfg);
       const session = await openChatSession(cred, { os, debug });
       const { socket } = session;
       try {
@@ -23333,11 +23451,13 @@ function register13(program3) {
     description: "After chat-login, run sync/syncDone, sync/syncSession, sync/syncWithdraws and return the raw responses.",
     output: Output13,
     configure: (cmd) => {
-      cmd.option("--os <os>", "chat-channel os slot", parseChatOs, DEFAULT_CHAT_OS).option("--debug", "forward wire-level debug events to stderr");
+      cmd.option("--os <os>", "chat-channel os slot (default: cfg.defaultChatOs ?? iOS)", parseChatOs).option("--debug", "forward wire-level debug events to stderr");
     },
     run: async (cmd) => {
-      const { os, debug } = cmd.opts();
+      const { os: optsOs, debug } = cmd.opts();
+      const cfg = requireConfig();
       const cred = requireAuth(loadCredentials());
+      const os = resolveChatOs(optsOs, cfg);
       const session = await openChatSession(cred, { os, debug });
       const { socket } = session;
       try {
@@ -23591,7 +23711,7 @@ function register15(program3) {
     description: "Send a plain-text chat message via the TCP chat channel. VISIBLE TO THE RECIPIENT \u2014 non-self targets require --yes-not-self.",
     output: Output15,
     configure: (cmd) => {
-      cmd.argument("<text...>", "message text (variadic; words rejoined with spaces)").option("--peer <uid>", "1:1 chat with a peer uid").option("--team <id>", "group chat with a team id").option("--to-self", "send to your own uid (default if no target given)").option("--yes-not-self", "required to confirm sending to anyone other than yourself").option("--dry-run", "build the frame but do not connect").option("--os <os>", "chat-channel os slot", parseChatOs, DEFAULT_CHAT_OS).option("--tail <text>", "override message tail for this call only").option("--no-tail", "do not append a message tail for this call").option("--debug", "forward wire-level debug events to stderr");
+      cmd.argument("<text...>", "message text (variadic; words rejoined with spaces)").option("--peer <uid>", "1:1 chat with a peer uid").option("--team <id>", "group chat with a team id").option("--to-self", "send to your own uid (default if no target given)").option("--yes-not-self", "required to confirm sending to anyone other than yourself").option("--dry-run", "build the frame but do not connect").option("--os <os>", "chat-channel os slot (default: cfg.defaultChatOs ?? iOS)", parseChatOs).option("--tail <text>", "override message tail for this call only").option("--no-tail", "do not append a message tail for this call").option("--debug", "forward wire-level debug events to stderr");
     },
     run: async (cmd) => {
       const text = cmd.args.join(" ").trim();
@@ -23599,6 +23719,7 @@ function register15(program3) {
       const opts = cmd.opts();
       const cfg = requireConfig();
       const cred = requireAuth(loadCredentials());
+      const os = resolveChatOs(opts.os, cfg);
       requireSingleTarget(opts, "send");
       const conflict = detectFlagConflict(process.argv.slice(2), "tail");
       if (conflict.sawValueForm && conflict.sawNegatedForm) {
@@ -23637,7 +23758,7 @@ function register15(program3) {
         subType: 1,
         body: finalText,
         fName: cred.name,
-        platform: opts.os === "Mac" || opts.os === "OS X" ? "Mac" : "Windows",
+        platform: os === "Mac" || os === "OS X" ? "Mac" : "Windows",
         appKey: cfg.appKey
       });
       if (opts.dryRun) {
@@ -23649,7 +23770,7 @@ function register15(program3) {
           frame: { sid: "talk", cid: "sendMsg", data: { msg } }
         };
       }
-      const session = await openChatSession(cred, { os: opts.os, debug: opts.debug });
+      const session = await openChatSession(cred, { os, debug: opts.debug });
       const { socket } = session;
       let res;
       try {
@@ -24389,7 +24510,7 @@ function register16(program3) {
     description: "Upload a local file (TCP 6101) and broadcast as MESSAGE_CHAT_FILE (subType=7). VISIBLE \u2014 non-self targets require --yes-not-self.",
     output: Output16,
     configure: (cmd) => {
-      cmd.argument("<file>", "absolute or relative path to a local file").option("--peer <uid>", "1:1 chat with a peer uid").option("--team <id>", "group chat with a team id").option("--to-self", "send to your own uid (default if no target given)").option("--yes-not-self", "required to confirm sending to anyone other than yourself").option("--dry-run", "resolve target + sanity-check the local file but do not upload or send").option("--os <os>", "chat-channel os slot for the talk/sendMsg", parseChatOs, DEFAULT_CHAT_OS).option("--debug", "forward wire-level debug events to stderr");
+      cmd.argument("<file>", "absolute or relative path to a local file").option("--peer <uid>", "1:1 chat with a peer uid").option("--team <id>", "group chat with a team id").option("--to-self", "send to your own uid (default if no target given)").option("--yes-not-self", "required to confirm sending to anyone other than yourself").option("--dry-run", "resolve target + sanity-check the local file but do not upload or send").option("--os <os>", "chat-channel os slot for the talk/sendMsg (default: cfg.defaultChatOs ?? iOS)", parseChatOs).option("--debug", "forward wire-level debug events to stderr");
     },
     run: async (cmd) => {
       const filePath = path2.resolve(String(cmd.args[0] ?? ""));
@@ -24397,6 +24518,7 @@ function register16(program3) {
       const opts = cmd.opts();
       const cfg = requireConfig();
       const cred = requireAuth(loadCredentials());
+      const os = resolveChatOs(opts.os, cfg);
       requireSingleTarget(opts, "send-file");
       let scene;
       let toId;
@@ -24447,10 +24569,10 @@ function register16(program3) {
           expiredDay: up.expiredDay
         }),
         fName: cred.name,
-        platform: opts.os === "Mac" || opts.os === "OS X" ? "Mac" : "Windows",
+        platform: os === "Mac" || os === "OS X" ? "Mac" : "Windows",
         appKey: cfg.appKey
       });
-      const session = await openChatSession(cred, { os: opts.os, debug: opts.debug });
+      const session = await openChatSession(cred, { os, debug: opts.debug });
       let res;
       try {
         res = await session.socket.send("talk", "sendMsg", { msg });
@@ -24563,13 +24685,14 @@ function register17(program3) {
     description: "Upload an image (TCP 6101) and broadcast as MESSAGE_CHAT_IMAGE (subType=8). VISIBLE \u2014 non-self targets require --yes-not-self.",
     output: Output17,
     configure: (cmd) => {
-      cmd.argument("<file>", "PNG/JPEG/GIF/BMP image path").option("--peer <uid>", "1:1 chat with a peer uid").option("--team <id>", "group chat with a team id").option("--to-self", "send to your own uid (default)").option("--yes-not-self", "required for non-self targets").option("--width <px>", "override probed image width", parsePosInt("--width")).option("--height <px>", "override probed image height", parsePosInt("--height")).option("--dry-run", "sanity-check the local file (probe + stat) but do not upload or send").option("--os <os>", "chat-channel os slot", parseChatOs, DEFAULT_CHAT_OS).option("--debug", "forward wire-level debug events to stderr");
+      cmd.argument("<file>", "PNG/JPEG/GIF/BMP image path").option("--peer <uid>", "1:1 chat with a peer uid").option("--team <id>", "group chat with a team id").option("--to-self", "send to your own uid (default)").option("--yes-not-self", "required for non-self targets").option("--width <px>", "override probed image width", parsePosInt("--width")).option("--height <px>", "override probed image height", parsePosInt("--height")).option("--dry-run", "sanity-check the local file (probe + stat) but do not upload or send").option("--os <os>", "chat-channel os slot (default: cfg.defaultChatOs ?? iOS)", parseChatOs).option("--debug", "forward wire-level debug events to stderr");
     },
     run: async (cmd) => {
       const filePath = path3.resolve(String(cmd.args[0] ?? ""));
       const opts = cmd.opts();
       const cfg = requireConfig();
       const cred = requireAuth(loadCredentials());
+      const os = resolveChatOs(opts.os, cfg);
       requireSingleTarget(opts, "send-image");
       let scene;
       let toId;
@@ -24635,10 +24758,10 @@ function register17(program3) {
           height
         }),
         fName: cred.name,
-        platform: opts.os === "Mac" || opts.os === "OS X" ? "Mac" : "Windows",
+        platform: os === "Mac" || os === "OS X" ? "Mac" : "Windows",
         appKey: cfg.appKey
       });
-      const session = await openChatSession(cred, { os: opts.os, debug: opts.debug });
+      const session = await openChatSession(cred, { os, debug: opts.debug });
       let res;
       try {
         res = await session.socket.send("talk", "sendMsg", { msg });
@@ -24717,13 +24840,14 @@ function register18(program3) {
     description: "Upload an audio clip (TCP 6101) and broadcast as MESSAGE_CHAT_AUDIO (subType=9). VISIBLE \u2014 non-self targets require --yes-not-self.",
     output: Output18,
     configure: (cmd) => {
-      cmd.argument("<file>", "audio file path (typically .amr)").requiredOption("--duration <ms>", "clip duration in milliseconds", parsePosInt("--duration")).option("--peer <uid>", "1:1 chat with a peer uid").option("--team <id>", "group chat with a team id").option("--to-self", "send to your own uid (default)").option("--yes-not-self", "required for non-self targets").option("--dry-run", "sanity-check the local file but do not upload or send").option("--os <os>", "chat-channel os slot", parseChatOs, DEFAULT_CHAT_OS).option("--debug", "forward wire-level debug events to stderr");
+      cmd.argument("<file>", "audio file path (typically .amr)").requiredOption("--duration <ms>", "clip duration in milliseconds", parsePosInt("--duration")).option("--peer <uid>", "1:1 chat with a peer uid").option("--team <id>", "group chat with a team id").option("--to-self", "send to your own uid (default)").option("--yes-not-self", "required for non-self targets").option("--dry-run", "sanity-check the local file but do not upload or send").option("--os <os>", "chat-channel os slot (default: cfg.defaultChatOs ?? iOS)", parseChatOs).option("--debug", "forward wire-level debug events to stderr");
     },
     run: async (cmd) => {
       const filePath = path4.resolve(String(cmd.args[0] ?? ""));
       const opts = cmd.opts();
       const cfg = requireConfig();
       const cred = requireAuth(loadCredentials());
+      const os = resolveChatOs(opts.os, cfg);
       requireSingleTarget(opts, "send-voice");
       let scene;
       let toId;
@@ -24782,10 +24906,10 @@ function register18(program3) {
           duration: opts.duration
         }),
         fName: cred.name,
-        platform: opts.os === "Mac" || opts.os === "OS X" ? "Mac" : "Windows",
+        platform: os === "Mac" || os === "OS X" ? "Mac" : "Windows",
         appKey: cfg.appKey
       });
-      const session = await openChatSession(cred, { os: opts.os, debug: opts.debug });
+      const session = await openChatSession(cred, { os, debug: opts.debug });
       let res;
       try {
         res = await session.socket.send("talk", "sendMsg", { msg });
@@ -24954,12 +25078,13 @@ function register20(program3) {
     description: "Withdraw a previously-sent message (P2P_MSG_CANCEL). VISIBLE TO THE RECIPIENT \u2014 non-self targets require --yes-not-self.",
     output: Output20,
     configure: (cmd) => {
-      cmd.requiredOption("--mid <mid>", "message id to withdraw").option("--peer <uid>", "1:1 chat with a peer uid").option("--team <id>", "group chat with a team id").option("--to-self", "withdraw in your self-chat (default if no target)").option("--yes-not-self", "required to confirm withdrawing in a non-self conversation").option("--dry-run", "build the frame but do not connect").option("--os <os>", "chat-channel os slot", parseChatOs, DEFAULT_CHAT_OS).option("--debug", "forward wire-level debug events to stderr");
+      cmd.requiredOption("--mid <mid>", "message id to withdraw").option("--peer <uid>", "1:1 chat with a peer uid").option("--team <id>", "group chat with a team id").option("--to-self", "withdraw in your self-chat (default if no target)").option("--yes-not-self", "required to confirm withdrawing in a non-self conversation").option("--dry-run", "build the frame but do not connect").option("--os <os>", "chat-channel os slot (default: cfg.defaultChatOs ?? iOS)", parseChatOs).option("--debug", "forward wire-level debug events to stderr");
     },
     run: async (cmd) => {
       const opts = cmd.opts();
       const cfg = requireConfig();
       const cred = requireAuth(loadCredentials());
+      const os = resolveChatOs(opts.os, cfg);
       requireSingleTarget(opts, "withdraw");
       let scene;
       let toId;
@@ -24989,7 +25114,7 @@ function register20(program3) {
         subType: 2,
         body: { mids: [opts.mid] },
         fName: cred.name,
-        platform: opts.os === "Mac" || opts.os === "OS X" ? "Mac" : "Windows",
+        platform: os === "Mac" || os === "OS X" ? "Mac" : "Windows",
         appKey: cfg.appKey
       });
       if (opts.dryRun) {
@@ -25001,7 +25126,7 @@ function register20(program3) {
           frame: { sid: "talk", cid: "sendMsg", data: { msg } }
         };
       }
-      const session = await openChatSession(cred, { os: opts.os, debug: opts.debug });
+      const session = await openChatSession(cred, { os, debug: opts.debug });
       const { socket } = session;
       let res;
       try {
@@ -25044,11 +25169,13 @@ function register21(program3) {
     description: "Send user/delSession to drop the local session record on all of the user's devices.",
     output: Output21,
     configure: (cmd) => {
-      cmd.option("--peer <uid>", "session with a peer uid").option("--team <id>", "session with a team id").option("--to-self", "self-chat session (default if no target)").option("--yes-not-self", "required to confirm clearing a non-self session").option("--dry-run", "build the frame but do not connect").option("--os <os>", "chat-channel os slot", parseChatOs, DEFAULT_CHAT_OS).option("--debug", "forward wire-level debug events to stderr");
+      cmd.option("--peer <uid>", "session with a peer uid").option("--team <id>", "session with a team id").option("--to-self", "self-chat session (default if no target)").option("--yes-not-self", "required to confirm clearing a non-self session").option("--dry-run", "build the frame but do not connect").option("--os <os>", "chat-channel os slot (default: cfg.defaultChatOs ?? iOS)", parseChatOs).option("--debug", "forward wire-level debug events to stderr");
     },
     run: async (cmd) => {
       const opts = cmd.opts();
+      const cfg = requireConfig();
       const cred = requireAuth(loadCredentials());
+      const os = resolveChatOs(opts.os, cfg);
       requireSingleTarget(opts, "clear-session");
       let scene;
       let toId;
@@ -25075,7 +25202,7 @@ function register21(program3) {
       if (opts.dryRun) {
         return { scene, toId, sId, dryRun: true, frame };
       }
-      const session = await openChatSession(cred, { os: opts.os, debug: opts.debug });
+      const session = await openChatSession(cred, { os, debug: opts.debug });
       const { socket } = session;
       let res;
       try {
@@ -25091,8 +25218,638 @@ 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 (default: cfg.defaultChatOs ?? iOS)", parseChatOs).option("--debug", "forward wire-level debug events to stderr");
+    },
+    run: async (cmd) => {
+      const opts = cmd.opts();
+      const cfg = requireConfig();
+      const cred = requireAuth(loadCredentials());
+      const os = resolveChatOs(opts.os, cfg);
+      const wantedFrom = opts.fromUid?.toUpperCase();
+      const session = await openChatSession(cred, { 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 (default: cfg.defaultChatOs ?? iOS)", parseChatOs).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 cfg = requireConfig();
+      const selfAppKey = cfg.appKey;
+      const os = resolveChatOs(opts.os, cfg);
+      const session = await openChatSession(cred, { 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 +25858,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 +25909,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);