slack-term 1.21.2 → 1.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slack-term",
-  "version": "1.21.2",
+  "version": "1.23.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/snomiao/slack-term.git"

package/ts/cli.ts

@@ -15,6 +15,7 @@ import { cmdTail } from "./tail.ts";
 
 import {
   authTest,
+  authScopes,
   authTestSession,
   conversationInfoSession,
   createChannel,
@@ -51,7 +52,7 @@ import {
   getPath,
   type Json,
 } from "./slack.ts";
-import { dayLabel, encodeMentions, findUntaggedMentions, formatYmdHm, resolveDateMarkup, resolveMentions } from "./format.ts";
+import { dayLabel, encodeMentions, encodeMentionsDetailed, findUntaggedMentions, formatYmdHm, mentionWarnings, resolveDateMarkup, resolveMentions, type MentionEncodeResult } from "./format.ts";
 
 function loadDotenv(path: string): void {
   if (!existsSync(path)) return;
@@ -590,6 +591,23 @@ function safetyCode(...parts: string[]): string {
   return sha256Hex(parts.join("\n")).slice(0, 4);
 }
 
+/** Strip ANSI escape sequences and control characters before drawing text the
+ *  terminal treats as trusted. Slack lets any user pick their own display name,
+ *  so an attacker could embed color/cursor codes; neutralize them here. */
+function stripTerminalControls(s: string): string {
+  return s
+    // CSI sequences (colors, cursor moves, …)
+    // eslint-disable-next-line no-control-regex
+    .replace(/\x1b\[[0-9;:?]*[ -/]*[@-~]/g, "")
+    // any remaining control chars, including a lone ESC and C1 range
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x1f\x7f-\x9f]/g, "")
+    // Unicode bidi controls (marks, embeddings, overrides, isolates) — a crafted
+    // display name could use these to spoof or reorder the rendered line.
+    // ALM, LRM/RLM, LRE/RLE/PDF/LRO/RLO, LRI/RLI/FSI/PDI.
+    .replace(/[\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, "");
+}
+
 // Slack API method → the token scope that grants it, for missing_scope guidance.
 const SCOPE_FOR_METHOD: Record<string, string> = {
   "reactions.add": "reactions:write",
@@ -912,6 +930,9 @@ interface SendArgs {
   // send token; set to the user token when sending --as-bot so the bot token
   // need not carry users:read.
   mentionToken?: string;
+  // Session cookie (xoxd) for the mention token — required for an xoxc- user
+  // token to call users.list on the public API (it is rejected without it).
+  mentionCookie?: string;
 }
 
 // Detect the silent-failure footgun: DMing yourself with your own user token.
@@ -948,23 +969,50 @@ async function cmdSend(token: string, args: SendArgs): Promise<void> {
   else if (args.userId) channelId = await openDm(token, args.userId);
   else channelId = await resolveChannel(token, ref);
 
-  // Convert @handle tokens to <@USERID> before hashing/sending so the safety
-  // gate covers exactly what will be posted. Unresolved handles stay as text.
-  const message = args.mentions
-    ? await encodeMentions(args.mentionToken ?? token, args.message, channelId)
-    : args.message;
+  // Convert @handle / @名前 tokens to <@USERID> before hashing/sending so the
+  // safety gate covers exactly what will be posted. Unresolved tokens stay as
+  // text. The detailed report drives the confirm-gate mention preview below.
+  let message = args.message;
+  let mentionReport: MentionEncodeResult | null = null;
+  if (args.mentions) {
+    mentionReport = await encodeMentionsDetailed(args.mentionToken ?? token, args.message, channelId, args.mentionCookie);
+    message = mentionReport.text;
+    // Prominent, always-visible warning for any @token that will NOT notify —
+    // so a mistyped or unresolved name (esp. a Japanese display name) is caught
+    // before it goes out as inert plain text. Shown even when --code is passed.
+    // Wording is shared with the library wrapper via mentionWarnings(). Strip
+    // control chars — the surfaces embed Slack-controlled display text.
+    for (const line of mentionWarnings(mentionReport.unresolved)) console.error(`⚠ ${stripTerminalControls(line)}`);
+  }
 
-  // Warn-only lint: names written as plain text that map to a known workspace
-  // member but aren't <@USERID>-tagged — they won't be notified. Never blocks;
-  // fail-soft (a missing users:read scope or API error must not stall a send).
+  // Warn-only lint: names written as plain text (no leading @) that map to a
+  // known workspace member but aren't <@USERID>-tagged — they won't be notified.
+  // Never blocks; fail-soft (a missing users:read scope or API error must not
+  // stall a send).
   try {
-    for (const u of await findUntaggedMentions(args.mentionToken ?? token, message)) {
-      console.error(`⚠ possible untagged mention: ${u.surface} — @${u.display} won't be notified (did you mean <@${u.userId}>?)`);
+    for (const u of await findUntaggedMentions(args.mentionToken ?? token, message, args.mentionCookie)) {
+      // u.surface / u.display carry Slack-controlled display text — strip control chars.
+      console.error(`⚠ possible untagged mention: ${stripTerminalControls(u.surface)} — @${stripTerminalControls(u.display)} won't be notified (did you mean <@${u.userId}>?)`);
     }
   } catch {
     // best-effort; ignore
   }
 
+  // Confirm-gate mention preview: exactly who resolves (→ notified) and who
+  // stays literal. Inserted into the dry-run block so the sender eyeballs the
+  // tagging before committing with --code.
+  const mentionLines: string[] = [];
+  if (mentionReport && (mentionReport.resolved.length > 0 || mentionReport.unresolved.length > 0)) {
+    mentionLines.push(`--- Mentions ---------------------------------`);
+    for (const r of mentionReport.resolved) {
+      mentionLines.push(`  ✓ ${stripTerminalControls(r.surface)} → @${stripTerminalControls(r.display)} (${r.userId}) — will notify`);
+    }
+    for (const u of mentionReport.unresolved) {
+      const why = u.reason === "ambiguous" ? "ambiguous" : u.reason === "unavailable" ? "lookup unavailable" : "no match";
+      mentionLines.push(`  ⚠ ${stripTerminalControls(u.surface)} — plain text, NOT notified (${why})`);
+    }
+  }
+
   // Gather context for the confirm gate. For a THREAD reply, pull the thread's
   // own recent messages so the preview shows what's already been said there —
   // this is what stops accidental duplicate replies (the channel's last message
@@ -974,6 +1022,15 @@ async function cmdSend(token: string, args: SendArgs): Promise<void> {
   let lastText = "";
   let lastUser = "?";
   let threadMsgs: Record<string, Json>[] = [];
+  // Author of the destination's TRUE most recent message (thread-scoped for a
+  // thread reply, channel-scoped for a top-level send) — feeds the unreplied-warn
+  // check below. Tracks `user` (normal message) and `bot_id` (a `bot_message`
+  // subtype post — e.g. `send --as-bot` — which carries bot_id/username but no
+  // `user`) so ownership can be determined either way. Undefined when the
+  // preview fetch failed (fail-soft).
+  let lastMsgUserId: string | undefined;
+  let lastMsgBotId: string | undefined;
+  let lastMsgTs: string | undefined;
   if (threadTs) {
     try {
       // Fetch a generous window and preview its tail. conversations.replies is
@@ -985,14 +1042,23 @@ async function cmdSend(token: string, args: SendArgs): Promise<void> {
       // Bind the hash to the thread's most recent message: if someone replies
       // between preview and confirm, the code invalidates and re-previews.
       lastText = typeof lastMsg?.text === "string" ? lastMsg.text : "";
+      lastMsgUserId = typeof lastMsg?.user === "string" ? lastMsg.user : undefined;
+      lastMsgBotId = typeof lastMsg?.bot_id === "string" ? lastMsg.bot_id : undefined;
+      lastMsgTs = typeof lastMsg?.ts === "string" ? lastMsg.ts : undefined;
     } catch {
       // best-effort preview only
     }
   } else {
     try {
       const ctx = (await history(token, channelId, 1)) as Record<string, Json>;
-      const lastMsg = asArray(ctx.messages).map(asRecord)
-        .filter((m) => m.subtype === undefined || m.subtype === null)[0];
+      // limit=1 already narrows this to exactly the channel's true last message
+      // (subtype or not) — take it raw for the ownership check below. The
+      // subtype filter is only for the human-readable preview text/author: it
+      // deliberately hides system events (channel_join etc.), but a bot_message
+      // post is a real message and must NOT be dropped here, or a bot's own
+      // last post would silently disable the unreplied-warn for --as-bot sends.
+      const rawMsgs = asArray(ctx.messages).map(asRecord);
+      const lastMsg = rawMsgs.filter((m) => m.subtype === undefined || m.subtype === null)[0];
       lastText = typeof lastMsg?.text === "string" ? lastMsg.text : "";
       // Resolve the author's user ID to a display name for the preview; fall back
       // to the bot username, then the raw ID. userName() is fail-soft.
@@ -1001,11 +1067,54 @@ async function cmdSend(token: string, args: SendArgs): Promise<void> {
         : typeof lastMsg?.username === "string"
         ? lastMsg.username
         : "?";
+      const rawLast = rawMsgs[0];
+      lastMsgUserId = typeof rawLast?.user === "string" ? rawLast.user : undefined;
+      lastMsgBotId = typeof rawLast?.bot_id === "string" ? rawLast.bot_id : undefined;
+      lastMsgTs = typeof rawLast?.ts === "string" ? rawLast.ts : undefined;
     } catch {
       // best-effort preview only
     }
   }
 
+  // Unreplied guard: the destination's last message is our own and no one has
+  // replied since (by definition, since it's still the most recent message) —
+  // sending another new message risks spamming the same person twice. Warn
+  // (never block) and point at `slack edit` on that message instead. Reply-status
+  // based, not time-based, so it still fires even long after the last send.
+  // Self-identity covers both a normal post (`user` = our user id) and a
+  // `bot_message`-subtype post (`bot_id` = our app's bot id, no `user`), the
+  // shape `send --as-bot` produces. Opt out with SLACK_UNREPLIED_WARN=0.
+  if (process.env.SLACK_UNREPLIED_WARN !== "0" && lastMsgTs && (lastMsgUserId || lastMsgBotId)) {
+    try {
+      const self = await authScopes(token);
+      const isSelfAuthor =
+        (!!lastMsgUserId && !!self.userId && self.userId === lastMsgUserId) ||
+        (!!lastMsgBotId && !!self.botId && self.botId === lastMsgBotId);
+      if (isSelfAuthor) {
+        // Prefer a real permalink (exact, copy-pasteable). If that lookup fails,
+        // fall back to a form guaranteed parseable by `slack edit` regardless of
+        // what shape `ref` is in (a bare channel/user name, a raw ID resolved
+        // from a permalink, or a thread ref) — `#<channelId>:<ts>` always yields
+        // a ts split, and `--channel-id` makes the leading "#name" irrelevant to
+        // resolution, so it never depends on ref's original prefix or an
+        // embedded thread_ts colliding with the appended message ts.
+        let editCmd = `slack edit "#${channelId}:${lastMsgTs}" "<新しい本文>" --channel-id ${channelId}`;
+        try {
+          const permalink = await getPermalink(token, channelId, lastMsgTs);
+          if (permalink) editCmd = `slack edit "${permalink}" "<新しい本文>"`;
+        } catch {
+          // fall back to the --channel-id form above
+        }
+        console.error(`⚠ 相手はまだ返信していません(最後のメッセージはあなたのものです)。`);
+        console.error(`  連投を避けるため、新規送信でなく直前のメッセージの edit を検討してください:`);
+        console.error(`    ${editCmd}`);
+        console.error(`  このまま送信する場合は --code=XXXX で確定。`);
+      }
+    } catch {
+      // best-effort; a failed self-identity lookup must not block the send
+    }
+  }
+
   // Duplicate guard: if the outgoing message closely matches something already
   // in the thread, warn (never block). Catches re-posting a reply you already
   // sent. Threshold is deliberately high so only near-identical text trips it.
@@ -1040,6 +1149,7 @@ async function cmdSend(token: string, args: SendArgs): Promise<void> {
       requireCode(args.code, code, [
         `--- Recent messages in thread ----------------`,
         ...recentLines,
+        ...mentionLines,
         `--- Sending ----------------------------------`,
         `  → ${dest} thread of ${parentLine} — THREAD REPLY`,
         `  Message: ${message}`,
@@ -1049,6 +1159,7 @@ async function cmdSend(token: string, args: SendArgs): Promise<void> {
       requireCode(args.code, code, [
         `--- Last message in channel ------------------`,
         `  ${lastUser}: ${lastText.split("\n")[0]?.slice(0, 100) ?? "(empty)"}`,
+        ...mentionLines,
         `--- Sending ----------------------------------`,
         `  → ${dest} — NEW top-level message`,
         `  Message: ${message}`,
@@ -1597,8 +1708,11 @@ async function main(): Promise<void> {
         if (argv.mentions !== false) {
           args.mentions = true;
           // Resolve mentions with the user token (has users:read) even when the
-          // message itself is sent via the bot token.
+          // message itself is sent via the bot token. Pass its cookie too so an
+          // xoxc- desktop token can reach users.list (rejected without the cookie).
           args.mentionToken = tok(argv as W);
+          const mc = ck(argv as W);
+          if (mc) args.mentionCookie = mc;
         }
         let sendToken: string;
         if (argv["as-bot"]) {

package/ts/format.ts

@@ -2,16 +2,6 @@
 
 import { listConversationMembers, listUsers, userInfo, userName, type Json } from "./slack.ts";
 
-/** Match an `@handle` token at a word boundary, capturing the handle.
- *  - The negative lookbehind keeps `@` inside emails (`a@b.com`) from matching,
- *    and the `<` keeps already-encoded mentions (`<@U0123>`) from being picked up
- *    as a handle named after the user ID (Slack resolves those natively).
- *  - Each `.` must be followed by more handle chars, so a trailing sentence dot
- *    (`thanks @taku.`) is left out of the capture. */
-function mentionRe(): RegExp {
-  return /(?<![A-Za-z0-9._@<-])@([A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*)/g;
-}
-
 /** Lowercase + strip hyphens/underscores/whitespace for loose handle matching. */
 function normHandle(s: string): string {
   return s.toLowerCase().replace(/[-_\s]/g, "");
@@ -32,65 +22,260 @@ function userMatchesHandle(u: Record<string, Json>, handle: string): boolean {
   return email !== "" && email === handle.toLowerCase();
 }
 
+export type MentionResolution = { surface: string; display: string; userId: string };
+// "no-match": the full intended lookup ran and the token genuinely matched no one.
+// "unavailable": a directory source needed to resolve it could not be consulted
+//   (users:read missing, or an API/connection error) — so we cannot claim it is a
+//   non-user. "ambiguous": several users matched exactly.
+export type UnresolvedMention = { surface: string; reason: "no-match" | "ambiguous" | "unavailable" };
+/** Structured outcome of mention encoding, so callers (the send confirm gate)
+ *  can preview exactly who will — and won't — be notified. */
+export type MentionEncodeResult = {
+  text: string;
+  resolved: MentionResolution[];
+  unresolved: UnresolvedMention[];
+};
+
+/** Full normalized name-forms of a member — the WHOLE display_name / real_name /
+ *  name, never split into parts. An explicit `@name` mention must match a full
+ *  name (`@柏原大空`), never a bare surname fragment (`@柏原`), which would be
+ *  ambiguous. Length ≥ 2. */
+function fullNameForms(u: Record<string, Json>): string[] {
+  const profile = asRecord(u.profile);
+  const forms = new Set<string>();
+  for (const v of [profile.display_name, u.real_name, u.name, profile.real_name]) {
+    if (typeof v === "string" && v) {
+      const n = normHandle(v);
+      if (n.length >= 2) forms.add(n);
+    }
+  }
+  return [...forms];
+}
+
+type CjkMatch = { userId: string; matchLen: number; display: string } | "ambiguous" | undefined;
+
+/** Directory match for a CJK `@名前` token. `run` is the raw token after `@`
+ *  (e.g. "柏原大空さん"). A user resolves only when the token equals their full
+ *  name exactly, or equals their full name followed by exactly one trailing
+ *  honorific ("さん", "様", …) which is then left in the message text rather than
+ *  swallowed into the tag. Deliberately NOT a partial-prefix match: it would
+ *  mis-tag a surname-only member from a longer given name. `matchLen` is a RAW
+ *  index into `run` (the length of the name part), computed with raw string ops
+ *  so it stays correct even when the name contains characters `normHandle` drops
+ *  (spaces, `-`, `_`). Returns "ambiguous" when two distinct users tie on the
+ *  longest name match. */
+function matchCjkRun(run: string, dir: Record<string, Json>[]): CjkMatch {
+  const nr = normHandle(run);
+  let best: { userId: string; matchLen: number; formLen: number; display: string } | undefined;
+  let ambiguous = false;
+  for (const u of dir) {
+    const id = typeof u.id === "string" ? u.id : "";
+    if (!id) continue;
+    for (const form of fullNameForms(u)) {
+      // Raw length of the name part matching `form`, or -1. Either the whole token
+      // is the name (exact), or the token ends with exactly one honorific and the
+      // remainder (raw) normalizes to the name. No particle / partial-prefix match:
+      // Japanese cannot distinguish "山田は…" (particle) from "山田はるか" (given
+      // name), so under-tag rather than risk notifying the wrong person.
+      let rawLen = -1;
+      if (nr === form) {
+        rawLen = run.length;
+      } else {
+        for (const h of HONORIFIC_SUFFIXES) {
+          if (run.length > h.length && run.endsWith(h) && normHandle(run.slice(0, run.length - h.length)) === form) {
+            rawLen = run.length - h.length;
+            break;
+          }
+        }
+      }
+      if (rawLen < 0) continue;
+      if (!best || form.length > best.formLen) {
+        best = { userId: id, matchLen: rawLen, formLen: form.length, display: displayNameOf(u) };
+        ambiguous = false;
+      } else if (form.length === best.formLen && best.userId !== id) {
+        ambiguous = true;
+      }
+    }
+  }
+  if (!best) return undefined;
+  return ambiguous ? "ambiguous" : { userId: best.userId, matchLen: best.matchLen, display: best.display };
+}
+
 /**
- * Rewrite `@handle` tokens in `text` to `<@USERID>` so Slack renders them as
- * real mentions. Resolution order per handle:
- *   1. workspace users.list (name / real_name / display_name / email)
- *   2. the target channel's members (conversations.members → users.info) — this
- *      reaches Slack Connect guests absent from the workspace users.list
- * Handles that resolve to nothing are left as plain text (never destroyed) and
- * reported via `warn`. Lookups are cached so each API call runs at most once.
+ * Rewrite `@handle` / `@名前` tokens in `text` to `<@USERID>` so Slack renders
+ * them as real mentions, returning a structured report of what did and did not
+ * resolve. Two kinds of token are recognized:
+ *   - ASCII handles (`@alice`, `@t.matsuda19790127`) — matched whole against
+ *     name / real_name / display_name / email.
+ *   - CJK names (`@柏原大空`, `@柏原大空さん`) — matched against the directory by
+ *     exact full name, or full name + one trailing honorific (kept outside the
+ *     tag). A display name written in kanji/kana (which the old ASCII-only regex
+ *     could not even capture) resolves; anything only partially matching stays
+ *     literal, to never notify the wrong person.
+ * Resolution order: (1) workspace users.list, then (2) the target channel's
+ * members (reaches Slack Connect guests absent from users.list). users.list is
+ * fail-soft: a lookup that cannot run (missing `users:read`, API error) yields an
+ * "unavailable" report entry instead of aborting the send, and is never reported
+ * as a definite "no-match". A name matching several users exactly is always left
+ * literal + reported "ambiguous" (fail-safe) — channel membership is never used
+ * to guess which duplicate was meant. Unresolved tokens are never destroyed.
  */
-export async function encodeMentions(
+export async function encodeMentionsDetailed(
   token: string,
   text: string,
   channelId: string | undefined,
-  opts: { warn?: (msg: string) => void } = {},
-): Promise<string> {
-  const warn = opts.warn ?? ((m: string) => process.stderr.write(`${m}\n`));
-
-  const handles = new Set<string>();
-  for (const m of text.matchAll(mentionRe())) handles.add(m[1]!);
-  if (handles.size === 0) return text;
-
-  const resolved = new Map<string, string>(); // handle -> user ID
-
-  // Step 1: workspace users.list (fetched once).
-  const wsResp = (await listUsers(token)) as { members?: Json[] };
-  const wsUsers = (wsResp.members ?? []).map(asRecord);
-  const unresolved: string[] = [];
-  for (const handle of handles) {
-    const hit = wsUsers.find((u) => userMatchesHandle(u, handle));
-    const id = hit && typeof hit.id === "string" ? hit.id : "";
-    if (id) resolved.set(handle, id);
-    else unresolved.push(handle);
+  cookie?: string,
+): Promise<MentionEncodeResult> {
+  const NAME_RUN = `[${NAME_CHARS}ー]+`;
+  // One mention token = runs of name characters (any script) joined by internal
+  // `. _ -`, so a mixed-script / dotted handle is captured WHOLE: `@田中Taro`,
+  // `@佐藤.dev`, `@t.matsuda19790127`, `@Alice-A`. It never ends on a separator,
+  // so a trailing sentence dot ("@taku.") is left out. Capturing the FULL token —
+  // never a script-boundary prefix — is what lets the fail-closed exact match
+  // refuse to tag "田中" from "@田中Taro". Lookbehind guard skips emails (`a@b`),
+  // already-encoded `<@U…>`, and doubled `@@`.
+  const TOKEN = `${NAME_RUN}(?:[._-]+${NAME_RUN})*`;
+  const tokenRe = new RegExp(`(?<![A-Za-z0-9._@<-])@(${TOKEN})`, "gu");
+
+  const tokens = new Set<string>();
+  for (const m of text.matchAll(tokenRe)) tokens.add(m[1]!);
+  if (tokens.size === 0) return { text, resolved: [], unresolved: [] };
+
+  type R =
+    | { status: "resolved"; userId: string; matchLen: number; display: string }
+    | { status: "ambiguous" }
+    | { status: "pending" };
+  const res = new Map<string, R>();
+  for (const t of tokens) res.set(t, { status: "pending" });
+
+  const resolveAgainst = (dir: Record<string, Json>[]): void => {
+    for (const t of tokens) {
+      if (res.get(t)!.status !== "pending") continue;
+      if (isCjk(t)) {
+        const m = matchCjkRun(t, dir);
+        if (m === "ambiguous") res.set(t, { status: "ambiguous" });
+        else if (m) res.set(t, { status: "resolved", userId: m.userId, matchLen: m.matchLen, display: m.display });
+      } else {
+        // Fail-closed like the CJK path: userMatchesHandle also matches loosely on
+        // real_name / display_name / email, so if two distinct users match the same
+        // handle, resolve nothing and report ambiguous rather than notify the wrong
+        // person on a first-match win.
+        const hits = dir.filter((u) => userMatchesHandle(u, t));
+        const ids = new Set(hits.map((u) => (typeof u.id === "string" ? u.id : "")).filter(Boolean));
+        if (ids.size === 1) {
+          const hit = hits.find((u) => typeof u.id === "string")!;
+          res.set(t, { status: "resolved", userId: hit.id as string, matchLen: t.length, display: displayNameOf(hit) });
+        } else if (ids.size > 1) {
+          res.set(t, { status: "ambiguous" });
+        }
+        // ids.size === 0 → stays pending; may still resolve via the channel pass.
+      }
+    }
+  };
+
+  // Track each directory source's availability separately, so a still-unresolved
+  // token is only reported as a genuine "no-match" when every source that could
+  // have resolved it was actually consulted. A failed source (missing users:read,
+  // API error) makes the outcome "unavailable" (indeterminate) — never a false
+  // "not a user". Fail-soft throughout: a lookup error must never abort the send.
+
+  // Step 1: workspace users.list.
+  let wsOk = false;
+  try {
+    const wsResp = (await listUsers(token, cookie)) as { members?: Json[] };
+    resolveAgainst((wsResp.members ?? []).map(asRecord));
+    wsOk = true;
+  } catch {
+    wsOk = false;
   }
 
   // Step 2: channel members (fetched once) — covers external/Connect guests.
-  if (unresolved.length > 0 && channelId) {
-    const memberIds = await listConversationMembers(token, channelId);
-    const infos: Record<string, Json>[] = [];
-    for (const uid of memberIds) {
-      const info = asRecord((await userInfo(token, uid)) as Json);
-      const u = asRecord(info.user);
-      if (typeof u.id !== "string") u.id = uid;
-      infos.push(u);
-    }
-    for (const handle of unresolved) {
-      const hit = infos.find((u) => userMatchesHandle(u, handle));
-      const id = hit && typeof hit.id === "string" ? hit.id : "";
-      if (id) resolved.set(handle, id);
+  // Only ever resolves tokens still "pending"; an ambiguous token stays ambiguous
+  // (fail-safe: we never let channel membership guess which duplicate was meant).
+  const stillPending = [...tokens].some((t) => res.get(t)!.status === "pending");
+  let channelAttempted = false;
+  let channelOk = true;
+  if (stillPending && channelId) {
+    channelAttempted = true;
+    try {
+      const memberIds = await listConversationMembers(token, channelId, cookie);
+      const infos: Record<string, Json>[] = [];
+      for (const uid of memberIds) {
+        const info = asRecord((await userInfo(token, uid, cookie)) as Json);
+        const u = asRecord(info.user);
+        if (typeof u.id !== "string") u.id = uid;
+        infos.push(u);
+      }
+      resolveAgainst(infos);
+    } catch {
+      // best-effort; a preview degrading is fine, aborting a send is not.
+      channelOk = false;
     }
   }
 
-  for (const handle of handles) {
-    if (!resolved.has(handle)) warn(`warn: unresolved mention @${handle} (left as text)`);
+  // A token is a true no-match only if the workspace list was read AND — when a
+  // channel exists to check for Connect guests — that channel was actually
+  // consulted and succeeded. If the channel lookup was skipped or failed we can't
+  // claim the token is a non-user, so it stays "unavailable" (indeterminate).
+  const searchedFully = wsOk && (channelId ? (channelAttempted && channelOk) : true);
+
+  const resolved: MentionResolution[] = [];
+  const unresolved: UnresolvedMention[] = [];
+  for (const t of tokens) {
+    const r = res.get(t)!;
+    if (r.status === "resolved") {
+      resolved.push({ surface: `@${t.slice(0, r.matchLen)}`, display: r.display, userId: r.userId });
+    } else if (r.status === "ambiguous") {
+      unresolved.push({ surface: `@${t}`, reason: "ambiguous" });
+    } else {
+      unresolved.push({ surface: `@${t}`, reason: searchedFully ? "no-match" : "unavailable" });
+    }
   }
 
-  return text.replace(mentionRe(), (full, handle: string) => {
-    const id = resolved.get(handle);
-    return id ? `<@${id}>` : full;
+  const out = text.replace(tokenRe, (full, tk: string) => {
+    const r = res.get(tk);
+    // For a CJK match, keep the un-matched tail (a trailing honorific) as text.
+    if (r && r.status === "resolved") return `<@${r.userId}>${tk.slice(r.matchLen)}`;
+    return full;
   });
+
+  return { text: out, resolved, unresolved };
+}
+
+/** User-facing warning lines for mentions that will NOT notify, deduped (the
+ *  "unavailable" cause is shared, so it is reported once). The single source of
+ *  this wording — the encodeMentions wrapper and the CLI send/edit flows both use
+ *  it, so their messages never drift. Each caller adds its own prefix. */
+export function mentionWarnings(unresolved: UnresolvedMention[]): string[] {
+  const lines: string[] = [];
+  let saidUnavailable = false;
+  for (const u of unresolved) {
+    if (u.reason === "ambiguous") {
+      lines.push(`${u.surface} matches multiple people — not tagged, sent as plain text (use <@USERID> to tag)`);
+    } else if (u.reason === "unavailable") {
+      if (saidUnavailable) continue;
+      lines.push(`could not fetch the user list (users:read missing or an API/connection error) — @mentions not tagged, sent as plain text`);
+      saidUnavailable = true;
+    } else {
+      lines.push(`${u.surface} matched no one — not tagged, sent as plain text`);
+    }
+  }
+  return lines;
+}
+
+/** String-returning wrapper over {@link encodeMentionsDetailed}: rewrites tokens
+ *  and emits a `warn` line per token that stayed literal. Preserved for callers
+ *  (and tests) that only need the encoded text. */
+export async function encodeMentions(
+  token: string,
+  text: string,
+  channelId: string | undefined,
+  opts: { warn?: (msg: string) => void; cookie?: string } = {},
+): Promise<string> {
+  const warn = opts.warn ?? ((m: string) => process.stderr.write(`${m}\n`));
+  const rep = await encodeMentionsDetailed(token, text, channelId, opts.cookie);
+  for (const line of mentionWarnings(rep.unresolved)) warn(`warn: ${line}`);
+  return rep.text;
 }
 
 // --- untagged-mention lint (warn-only) -------------------------------------
@@ -173,14 +358,14 @@ export type UntaggedMention = { surface: string; display: string; userId: string
 /** Warn-only lint: person-references in `text` that resolve to a workspace
  *  member but carry no <@USERID> tag. Returns [] cheaply (no users.list fetch)
  *  when the text has no person-reference cue. */
-export async function findUntaggedMentions(token: string, text: string): Promise<UntaggedMention[]> {
+export async function findUntaggedMentions(token: string, text: string, cookie?: string): Promise<UntaggedMention[]> {
   const refs = extractPersonRefs(text);
   if (refs.length === 0) return [];
 
   const taggedIds = new Set<string>();
   for (const m of text.matchAll(/<@([A-Z0-9]+)(?:\|[^>]*)?>/g)) taggedIds.add(m[1]!);
 
-  const wsResp = (await listUsers(token)) as { members?: Json[] };
+  const wsResp = (await listUsers(token, cookie)) as { members?: Json[] };
   const pool = (wsResp.members ?? [])
     .map(asRecord)
     .filter((u) => u.deleted !== true && u.is_bot !== true && u.id !== "USLACKBOT")

package/ts/slack.ts

@@ -607,13 +607,13 @@ export async function userName(token: string, userId: string): Promise<string> {
   }
 }
 
-export async function listUsers(token: string): Promise<Json> {
+export async function listUsers(token: string, cookie?: string): Promise<Json> {
   const allMembers: Json[] = [];
   let cursor = "";
   while (true) {
     const params: Record<string, string> = { limit: "200" };
     if (cursor) params.cursor = cursor;
-    const resp = (await get(token, "users.list", params)) as {
+    const resp = (await get(token, "users.list", params, cookie)) as {
       members?: Json[];
       response_metadata?: { next_cursor?: string };
     };
@@ -627,13 +627,13 @@ export async function listUsers(token: string): Promise<Json> {
 /** List the member user IDs of a channel/DM (paginated).
  *  Used by mention encoding to reach members — including Slack Connect guests —
  *  who do not appear in the workspace-wide users.list. */
-export async function listConversationMembers(token: string, channel: string): Promise<string[]> {
+export async function listConversationMembers(token: string, channel: string, cookie?: string): Promise<string[]> {
   const all: string[] = [];
   let cursor = "";
   while (true) {
     const params: Record<string, string> = { channel, limit: "200" };
     if (cursor) params.cursor = cursor;
-    const resp = (await get(token, "conversations.members", params)) as {
+    const resp = (await get(token, "conversations.members", params, cookie)) as {
       members?: string[];
       response_metadata?: { next_cursor?: string };
     };
@@ -696,8 +696,8 @@ export async function conversationInfoSession(token: string, channelId: string,
   return postSession(token, "conversations.info", { channel: channelId }, cookie);
 }
 
-export async function userInfo(token: string, userId: string): Promise<Json> {
-  return get(token, "users.info", { user: userId });
+export async function userInfo(token: string, userId: string, cookie?: string): Promise<Json> {
+  return get(token, "users.info", { user: userId }, cookie);
 }
 
 export async function conversationInfo(token: string, channelId: string): Promise<Json> {