slack-term 1.31.5 → 1.32.0

package/package.json

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

package/ts/cli.ts

@@ -2615,6 +2615,37 @@ async function cmdDoctor(token: string): Promise<void> {
 }
 
 // --- schedule ---
+
+/** The xoxb bot token, or a clean exit. `--as-bot` is only ever a token switch,
+ *  and its failure is always the same one: the env var is not set. */
+function requireBotToken(): string {
+  const botToken = resolveBotToken();
+  if (!botToken) {
+    console.error(
+      "Error: --as-bot needs a bot token, but no xoxb- token was found.\n" +
+      "  Set SLACK_BOT_TOKEN=xoxb-... in ~/.config/slack-cli/.env (or your shell).",
+    );
+    process.exit(1);
+  }
+  return botToken;
+}
+
+/** The bot↔user DM for an `@handle`. The handle is resolved on the USER token
+ *  (which has users:read) and the DM is opened on the BOT token, so the channel
+ *  is the bot's IM with that person and not the person's own self-DM. That
+ *  distinction is the entire point of `--as-bot` here: Slack never notifies you
+ *  about your own message, so a digest scheduled into a self-DM is delivered
+ *  into silence at the one moment nobody is at the terminal to notice. */
+async function botDmForTarget(
+  target: string,
+  botToken: string,
+  userToken: string,
+  userCookie?: string,
+): Promise<string> {
+  const userId = await resolveUserId(userToken, target, userCookie);
+  return openDm(botToken, userId);
+}
+
 function parsePostAt(at: string): number {
   if (/^\d{10,}$/.test(at)) return parseInt(at, 10);
   const d = new Date(at.replace(" ", "T"));
@@ -2650,6 +2681,10 @@ interface ScheduleSendArgs {
   channelId?: string;
   userId?: string;
   cookie?: string;
+  asBot?: boolean;
+  /** How the caller overrode the target text, e.g. `--user-id U0123`. Set only
+   *  when a FLAG supplied it — never when the command resolved the id itself. */
+  targetOverride?: string;
 }
 async function cmdScheduleSend(token: string, args: ScheduleSendArgs): Promise<void> {
   const getSelf = selfLookup(token, args.cookie);
@@ -2670,19 +2705,30 @@ async function cmdScheduleSend(token: string, args: ScheduleSendArgs): Promise<v
   // Self-DM is worst here: the message fires later, unattended, and Slack never
   // notifies you about your own post — so a scheduled reminder to yourself is
   // delivered into silence at exactly the moment you were counting on it.
-  if (await isSelfDmChannel(token, channelId, self?.userId, args.cookie)) {
+  // --as-bot is exempt: that posts as the app, a different identity, which does
+  // notify you. Being unable to say that is what made this warning a dead end —
+  // it named the problem and offered no way out.
+  if (!args.asBot && await isSelfDmChannel(token, channelId, self?.userId, args.cookie)) {
     console.error(
-      `Warning: "${args.target}" is a DM to yourself — Slack will NOT notify you when this fires.`,
+      `Warning: "${args.target}" is a DM to yourself — Slack will NOT notify you when this fires.\n` +
+      `  To be notified, schedule it as the bot:  slack schedule send '${args.target}' '...' --at '${args.at}' --as-bot`,
     );
   }
 
   const code = safetyCode(channelId, args.message, String(postAt), self?.userId ?? "");
 
+  // `--channel-id` / `--user-id` win over the target text, so the target stops
+  // being where this goes the moment the two disagree — and the gate printed
+  // only the target. `schedule send @alice … --user-id <bob>` read "To: @alice"
+  // and went to bob. A confirm gate that names the wrong recipient with no sign
+  // it was overridden is worse than no gate: it gets read, and it gets passed.
+  const destOverride = args.targetOverride ? `  [${args.targetOverride} → ${channelId}]` : "";
+
   if (args.code !== code) {
     requireCode(args.code, code, [
       `--- Scheduling message -----------------------`,
-      fromLine(self, { pad: 9 }),
-      `  To:      ${ref}${threadTs ? ` (thread ${threadTs})` : ""}`,
+      fromLine(self, { asBot: args.asBot, pad: 9 }),
+      `  To:      ${ref}${threadTs ? ` (thread ${threadTs})` : ""}${destOverride}`,
       `  At:      ${fmtPostAt(postAt)}`,
       `  Message: ${args.message}`,
       `---------------------------------------------`,
@@ -2690,6 +2736,37 @@ async function cmdScheduleSend(token: string, args: ScheduleSendArgs): Promise<v
   }
   const id = await scheduleMessage(token, channelId, args.message, postAt, threadTs, args.cookie);
   console.log(`✓ Scheduled (id: ${id}, at: ${postAtDate})`);
+
+  if (args.asBot) {
+    // The message now belongs to the BOT, so `schedule ls` on the user token
+    // cannot see it and `schedule rm` cannot cancel it. Said at the only moment
+    // the id is in front of the reader.
+    console.error(
+      `  Scheduled as the bot — the user token cannot see or cancel it. Use the same flag:\n` +
+      `    slack schedule ls --as-bot\n` +
+      `    slack schedule rm '${args.target}' ${id} --as-bot`,
+    );
+    // A scheduled bot DM fires unattended, so an app that cannot actually carry
+    // a DM fails at the one moment nobody is watching. Same check `send --as-bot`
+    // runs after the fact; here it is the difference between finding out now and
+    // finding out from an empty inbox.
+    if (channelId.startsWith("D")) {
+      try {
+        const diag = await diagnoseBotMessaging(token);
+        if (!diag.ok) {
+          for (const line of formatDiagnosis(diag, true)) console.error(line);
+        } else {
+          const appUrl = diag.appId ? `https://api.slack.com/apps/${diag.appId}` : "https://api.slack.com/apps";
+          console.error(
+            `Note: if ${args.target} can't reply (app messaging may be off), ` +
+            `enable Messages Tab: ${appUrl} → App Home.`,
+          );
+        }
+      } catch {
+        // diagnosis is best-effort; never turn a successful schedule into a failure.
+      }
+    }
+  }
 }
 
 async function cmdScheduleList(token: string, target?: string, channelId?: string, cookie?: string): Promise<void> {
@@ -2716,6 +2793,9 @@ interface ScheduleRmArgs {
   code?: string;
   channelId?: string;
   cookie?: string;
+  asBot?: boolean;
+  /** How the caller overrode the target text, e.g. `--channel-id C0123`. */
+  targetOverride?: string;
 }
 async function cmdScheduleRm(token: string, args: ScheduleRmArgs): Promise<void> {
   let channelId: string;
@@ -2727,8 +2807,8 @@ async function cmdScheduleRm(token: string, args: ScheduleRmArgs): Promise<void>
   if (args.code !== code) {
     requireCode(args.code, code, [
       `--- Deleting scheduled message ---------------`,
-      fromLine(self, { pad: 9 }),
-      `  Channel: ${args.target}`,
+      fromLine(self, { asBot: args.asBot, pad: 9 }),
+      `  Channel: ${args.target}${args.targetOverride ? `  [${args.targetOverride} → ${channelId}]` : ""}`,
       `  ID:      ${args.id}`,
       `---------------------------------------------`,
     ]);
@@ -3317,17 +3397,23 @@ async function main(): Promise<void> {
           (y2) => y2.positional("user", { type: "string", demandOption: true, describe: "@handle or user ID" }),
           async (argv) => {
             const token = tok(argv as W);
-            const ref = argv.user!.startsWith("@") ? argv.user!.slice(1) : argv.user!;
-            // If not a Slack user ID (U + alphanumeric), resolve from users list by handle
-            let userId = ref;
-            if (!/^U[A-Z0-9]+$/.test(ref)) {
-              const listResp = (await listUsers(token, ck(argv as W))) as Record<string, Json>;
-              const match = asArray(listResp.members).map(asRecord)
-                .find((u) => String(u.name ?? "") === ref);
-              if (!match) { console.error(`User not found: @${ref}`); process.exit(1); }
-              userId = String(match.id);
+            const cookie = ck(argv as W);
+            const ref = argv.user!.startsWith("@") ? argv.user! : `@${argv.user!}`;
+            // resolveUserId owns every population: the id form, self, the
+            // workspace roster, and the Slack Connect partners users.list cannot
+            // see. Matching `u.name` against this list by hand — as this used to
+            // — missed display names, real names, and everyone from another team.
+            let userId = "";
+            try {
+              userId = await resolveUserId(token, ref, cookie);
+            } catch (e) {
+              console.error(e instanceof Error ? e.message : String(e));
+              process.exit(1);
             }
-            const resp = asRecord((await userInfo(token, userId)) as Json);
+            // The cookie is not optional here: on a desktop (xoxc-) token the
+            // public Web API answers invalid_auth without it, which read as
+            // "your token is wrong" on a lookup that was about to succeed.
+            const resp = asRecord((await userInfo(token, userId, cookie)) as Json);
             const u = asRecord(resp.user);
             const profile = asRecord(u.profile);
             const localTz = Intl.DateTimeFormat().resolvedOptions().timeZone;
@@ -3723,15 +3809,52 @@ async function main(): Promise<void> {
             .option("at", { type: "string", demandOption: true, describe: "Delivery time (ISO datetime or Unix ts)" })
             .option("code", { type: "string", describe: "Safety hash to confirm" })
             .option("channel-id", { type: "string", describe: "Raw channel ID" })
-            .option("user-id", { type: "string", describe: "Raw user ID (opens DM)" }),
+            .option("user-id", { type: "string", describe: "Raw user ID (opens DM)" })
+            .option("as-bot", { type: "boolean", default: false, describe: "Schedule via the bot token (xoxb / SLACK_BOT_TOKEN) so a DM notifies the recipient. Without it a scheduled DM to yourself is posted by you, and Slack never notifies you of your own message — it fires into silence." }),
           async (argv) => {
             const args: ScheduleSendArgs = { target: argv.target!, message: argv.message!, at: argv.at! };
             if (argv.code) args.code = argv.code;
-            if (argv["channel-id"]) args.channelId = argv["channel-id"];
-            if (argv["user-id"]) args.userId = argv["user-id"];
-            const cookie = ck(argv as W);
-            if (cookie) args.cookie = cookie;
-            await cmdScheduleSend(tok(argv as W), args);
+            // Recorded here, not in the command, because only a flag counts as an
+            // override — under --as-bot the command sets args.userId itself from
+            // the target, and claiming THAT was an override would be a new lie.
+            if (argv["channel-id"]) {
+              args.channelId = argv["channel-id"];
+              args.targetOverride = `--channel-id ${argv["channel-id"]}`;
+            }
+            if (argv["user-id"]) {
+              args.userId = argv["user-id"];
+              args.targetOverride = `--user-id ${argv["user-id"]}`;
+            }
+            let scheduleToken: string;
+            if (argv["as-bot"]) {
+              const botToken = requireBotToken();
+              // Resolve @user → user_id with the *user* token (has users:read),
+              // then let cmdScheduleSend open the DM with the bot token
+              // (im:write). Same split as `send --as-bot`: the bot never needs
+              // users:read, and the DM is bot↔user rather than a self-DM.
+              if (!args.channelId && !args.userId && args.target.startsWith("@")) {
+                try {
+                  args.userId = await resolveUserId(tok(argv as W), args.target, ck(argv as W));
+                } catch (e: unknown) {
+                  console.error(
+                    `Error: could not resolve ${args.target} to a user for the bot DM.\n` +
+                    `  ${e instanceof Error ? e.message : String(e)}\n` +
+                    `  Tip: pass --user-id <Uxxxx> to skip the lookup.`,
+                  );
+                  process.exit(1);
+                }
+              }
+              scheduleToken = botToken;
+              args.asBot = true;
+            } else {
+              scheduleToken = tok(argv as W);
+              // Session cookie for the token that will actually schedule — an
+              // xoxc- desktop token is rejected by the public API without it.
+              // Bot tokens need none.
+              const cookie = ck(argv as W);
+              if (cookie) args.cookie = cookie;
+            }
+            await cmdScheduleSend(scheduleToken, args);
           },
         )
         .command(
@@ -3739,9 +3862,20 @@ async function main(): Promise<void> {
           "List pending scheduled messages",
           (y2) => y2
             .positional("target", { type: "string", describe: "#channel to filter by" })
-            .option("channel-id", { type: "string", describe: "Raw channel ID" }),
+            .option("channel-id", { type: "string", describe: "Raw channel ID" })
+            .option("as-bot", { type: "boolean", default: false, describe: "List what the BOT token scheduled. A message from `schedule send --as-bot` belongs to the app, so the user token's listing does not contain it — and an invisible pending message cannot be cancelled." }),
           async (argv) => {
-            await cmdScheduleList(tok(argv as W), argv.target as string | undefined, argv["channel-id"], ck(argv as W));
+            const target = argv.target as string | undefined;
+            if (argv["as-bot"]) {
+              const botToken = requireBotToken();
+              let channelId = argv["channel-id"] as string | undefined;
+              if (!channelId && target?.startsWith("@")) {
+                channelId = await botDmForTarget(target, botToken, tok(argv as W), ck(argv as W));
+              }
+              await cmdScheduleList(botToken, target, channelId);
+              return;
+            }
+            await cmdScheduleList(tok(argv as W), target, argv["channel-id"], ck(argv as W));
           },
         )
         .command(
@@ -3751,13 +3885,26 @@ async function main(): Promise<void> {
             .positional("target", { type: "string", demandOption: true, describe: "#channel or @user" })
             .positional("id", { type: "string", demandOption: true, describe: "Scheduled message ID" })
             .option("code", { type: "string", describe: "Safety hash to confirm" })
-            .option("channel-id", { type: "string", describe: "Raw channel ID" }),
+            .option("channel-id", { type: "string", describe: "Raw channel ID" })
+            .option("as-bot", { type: "boolean", default: false, describe: "Cancel a message scheduled with `schedule send --as-bot`. It belongs to the bot token, so the user token cannot delete it." }),
           async (argv) => {
             const args: ScheduleRmArgs = { target: argv.target!, id: argv.id! };
             if (argv.code) args.code = argv.code;
+            if (argv["channel-id"]) {
+              args.channelId = argv["channel-id"];
+              args.targetOverride = `--channel-id ${argv["channel-id"]}`;
+            }
+            if (argv["as-bot"]) {
+              const botToken = requireBotToken();
+              if (!args.channelId && args.target.startsWith("@")) {
+                args.channelId = await botDmForTarget(args.target, botToken, tok(argv as W), ck(argv as W));
+              }
+              args.asBot = true;
+              await cmdScheduleRm(botToken, args);
+              return;
+            }
             const cookie = ck(argv as W);
             if (cookie) args.cookie = cookie;
-            if (argv["channel-id"]) args.channelId = argv["channel-id"];
             await cmdScheduleRm(tok(argv as W), args);
           },
         )

package/ts/slack.ts

@@ -501,46 +501,215 @@ export async function openDm(token: string, userId: string, cookie?: string): Pr
   return id;
 }
 
+/** The existing IM with `userId`, or "" when there is none. Paginated: a
+ *  workspace with many DMs pages its im list like any other conversation, and
+ *  reading only the first page is how a DM that exists reads as missing. */
+async function findExistingDm(token: string, userId: string, cookie?: string): Promise<string> {
+  let cursor = "";
+  while (true) {
+    const params: Record<string, string> = { types: "im", limit: "200" };
+    if (cursor) params.cursor = cursor;
+    const resp = (await get(token, "conversations.list", params, cookie)) as {
+      channels?: Array<{ id?: string; user?: string }>;
+      response_metadata?: { next_cursor?: string };
+    };
+    for (const ch of resp.channels ?? []) {
+      if (ch.user === userId) return String(ch.id ?? "");
+    }
+    cursor = resp.response_metadata?.next_cursor ?? "";
+    if (!cursor) break;
+  }
+  return "";
+}
+
+/** The DM channel with a known user id. Read-only on purpose: opening a DM
+ *  needs im:write, which plenty of read tokens do not carry, so an absent DM is
+ *  reported rather than created. */
+async function dmWithUser(token: string, userId: string, cookie?: string, label?: string): Promise<string> {
+  const dm = await findExistingDm(token, userId, cookie);
+  if (dm) return dm;
+  const who = label ? `${label} (${userId})` : userId;
+  throw new Error(`No existing DM with ${who}. Open it once in Slack first.`);
+}
+
 /** Normalize for loose matching: lowercase + strip hyphens/underscores/whitespace.
  *  Lets `@deploy-bot` match handles like `deploybot` or display names like `Deploy-Bot`. */
 function normName(s: string): string {
   return s.toLowerCase().replace(/[-_\s]/g, "");
 }
 
-/**
- * Resolve `@name` (or a raw U…/W… id) to a user ID. Used when DMing as a bot:
- * the lookup runs on a *user* token (which has users:read), then the caller
- * opens the DM with the bot token — so the bot never needs users:read.
- */
-export async function resolveUserId(token: string, ref: string, cookie?: string): Promise<string> {
-  if (!ref.startsWith("@")) {
-    if (/^[UW][A-Za-z0-9]{6,}$/.test(ref)) return ref;
-    throw new Error(`Expected @user or a user ID, got: ${ref}`);
-  }
-  const nameNorm = normName(ref.slice(1));
-  const selfInfo = (await get(token, "auth.test", {}, cookie)) as { user_id?: string; user?: string };
-  if (nameNorm === "you" || nameNorm === "me" || normName(selfInfo.user ?? "") === nameNorm) {
-    if (!selfInfo.user_id) throw new Error("auth.test did not return user_id");
-    return selfInfo.user_id;
-  }
+type Member = {
+  id?: string;
+  name?: string;
+  real_name?: string;
+  profile?: { display_name?: string; real_name?: string };
+};
+
+function memberMatches(u: Member, nameNorm: string): boolean {
+  const n = normName(u.name ?? "");
+  const rn = normName(u.real_name ?? u.profile?.real_name ?? "");
+  const dn = normName(u.profile?.display_name ?? "");
+  return n === nameNorm || rn === nameNorm || (!!dn && dn === nameNorm);
+}
+
+/** What a `@name` lookup found, and — when it found nothing — which populations
+ *  it actually searched. The counts are the whole point: "not found" out of 40
+ *  people is a wrong handle, "not found" out of 0 is a broken token, and the
+ *  caller cannot tell those apart from the sentence alone. */
+type UserSearch = {
+  /** "" when nothing matched. */
+  id: string;
+  /** The existing IM with them, when the match came from the DM scan. */
+  dm?: string;
+  workspaceCount: number;
+  connectCount: number;
+  /** DM partners whose profile could not be read, so they were never compared. */
+  skipped: number;
+  /** True when the scan stopped at CONNECT_SCAN_LIMIT with partners left over. */
+  capped: boolean;
+};
+
+/** How many non-roster DM partners a failed lookup will resolve one at a time.
+ *  Each costs a `users.info`, so an account with thousands of Slack Connect DMs
+ *  would otherwise turn a single typo into thousands of sequential calls and
+ *  rate-limit the caller out of the API. Past the cap the scan stops and says it
+ *  stopped — an incomplete answer that admits it beats a complete-looking one. */
+const CONNECT_SCAN_LIMIT = 200;
+
+/** Search every population this token can see for `@name`.
+ *
+ *  `users.list` is scoped to YOUR workspace, so a Slack Connect counterpart —
+ *  who belongs to another team entirely — is never in it, no matter what
+ *  parameters the call is given. The only place they exist is the membership of
+ *  a conversation you share, and for a person you DM the cheapest such place is
+ *  your own IM list: it costs one `users.info` per external DM partner and hands
+ *  back the channel id the caller was about to look up anyway. */
+async function searchUsers(token: string, nameNorm: string, cookie?: string): Promise<UserSearch> {
+  let workspaceCount = 0;
+  const known = new Set<string>();
   let cursor = "";
   while (true) {
     const params: Record<string, string> = { limit: "200" };
     if (cursor) params.cursor = cursor;
     const resp = (await get(token, "users.list", params, cookie)) as {
-      members?: Array<{ id?: string; name?: string; real_name?: string; profile?: { display_name?: string } }>;
+      members?: Member[];
       response_metadata?: { next_cursor?: string };
     };
     for (const u of resp.members ?? []) {
-      const n = normName(u.name ?? "");
-      const rn = normName(u.real_name ?? "");
-      const dn = normName(u.profile?.display_name ?? "");
-      if (n === nameNorm || rn === nameNorm || (dn && dn === nameNorm)) return u.id ?? "";
+      workspaceCount++;
+      if (u.id) known.add(u.id);
+      if (memberMatches(u, nameNorm)) {
+        return { id: u.id ?? "", workspaceCount, connectCount: 0, skipped: 0, capped: false };
+      }
     }
     cursor = resp.response_metadata?.next_cursor ?? "";
     if (!cursor) break;
   }
-  throw new Error(`User not found: ${ref}`);
+
+  let connectCount = 0;
+  let skipped = 0;
+  let capped = false;
+  let dmCursor = "";
+  while (true) {
+    const params: Record<string, string> = { types: "im", limit: "200" };
+    if (dmCursor) params.cursor = dmCursor;
+    const resp = (await get(token, "conversations.list", params, cookie)) as {
+      channels?: Array<{ id?: string; user?: string }>;
+      response_metadata?: { next_cursor?: string };
+    };
+    for (const ch of resp.channels ?? []) {
+      const uid = ch.user;
+      if (!uid || known.has(uid)) continue;
+      if (connectCount >= CONNECT_SCAN_LIMIT) {
+        capped = true;
+        break;
+      }
+      known.add(uid);
+      connectCount++;
+      let u: Member | undefined;
+      try {
+        u = ((await get(token, "users.info", { user: uid }, cookie)) as { user?: Member }).user;
+      } catch (e) {
+        // A rate limit is not "this person does not match" — it is the scan
+        // being cut off mid-way, and swallowing it is precisely how a lookup
+        // that could not see its population ends up reporting absence. Let it
+        // out. Any other per-profile failure costs us that one person, and is
+        // counted so the error can admit the search was incomplete.
+        if (e instanceof RateLimitError) throw e;
+        skipped++;
+        continue;
+      }
+      if (u && memberMatches(u, nameNorm)) {
+        return { id: uid, dm: String(ch.id ?? ""), workspaceCount, connectCount, skipped, capped };
+      }
+    }
+    if (capped) break;
+    dmCursor = resp.response_metadata?.next_cursor ?? "";
+    if (!dmCursor) break;
+  }
+  return { id: "", workspaceCount, connectCount, skipped, capped };
+}
+
+/** The error for a lookup that came back empty. An empty roster and a wrong
+ *  handle must not share a sentence: the first is a token or scope fault the
+ *  caller can fix, the second is a typo, and "User not found" told both stories
+ *  at once — so a lookup that could not see its population reported absence.
+ *
+ *  "account(s)", not "member(s)", and the count will not match `user ls`: that
+ *  command hides deleted accounts and bots, and this counts the raw users.list
+ *  the search actually walked. The two differ by design — the number here is a
+ *  report on the search, not a headcount of the workspace. */
+function userNotFoundError(ref: string, found: UserSearch): Error {
+  if (found.workspaceCount === 0) {
+    return new Error(
+      `Cannot resolve ${ref}: users.list returned no members at all, so nothing could have matched.\n` +
+      `That is a token or scope fault, not a wrong handle — this says nothing about whether ${ref} exists.\n` +
+      `  Check who you are:  slack auth ls`,
+    );
+  }
+  const searched = found.connectCount
+    ? `${found.workspaceCount} workspace account(s) and ${found.connectCount} Slack Connect DM partner(s)`
+    : `${found.workspaceCount} workspace account(s)`;
+  // Anything the scan did not actually look at is said out loud. "None matched"
+  // is only true of what was compared, and the gap between that and "not there"
+  // is the whole bug this function exists to stop repeating.
+  const gaps: string[] = [];
+  if (found.capped) {
+    gaps.push(`stopped after ${CONNECT_SCAN_LIMIT} Slack Connect DM partners, so there may be more`);
+  }
+  if (found.skipped) {
+    gaps.push(`${found.skipped} DM partner profile(s) could not be read and were never compared`);
+  }
+  return new Error(
+    `User not found: ${ref} — searched ${searched}, none matched.\n` +
+    (gaps.length ? `This search was incomplete: ${gaps.join("; ")}.\n` : "") +
+    `Slack Connect people from another workspace are not in users.list, so if they never\n` +
+    `DMed you they cannot be found by name at all. Look them up and use their ID:\n` +
+    `  slack user ls --external`,
+  );
+}
+
+/**
+ * Resolve `@name` (or a raw U…/W… id) to a user ID. Used when DMing as a bot:
+ * the lookup runs on a *user* token (which has users:read), then the caller
+ * opens the DM with the bot token — so the bot never needs users:read.
+ */
+export async function resolveUserId(token: string, ref: string, cookie?: string): Promise<string> {
+  // `@U0123456789` — an id wearing the `@` that every other user target takes.
+  // Nobody is NAMED that, so the name walk below would end in "user not found"
+  // and point at the wrong problem: the user is there, only the `@` is not.
+  const bare = ref.startsWith("@") ? ref.slice(1) : ref;
+  if (isUserId(bare)) return bare;
+  if (!ref.startsWith("@")) throw new Error(`Expected @user or a user ID, got: ${ref}`);
+  const nameNorm = normName(bare);
+  const selfInfo = (await get(token, "auth.test", {}, cookie)) as { user_id?: string; user?: string };
+  if (nameNorm === "you" || nameNorm === "me" || normName(selfInfo.user ?? "") === nameNorm) {
+    if (!selfInfo.user_id) throw new Error("auth.test did not return user_id");
+    return selfInfo.user_id;
+  }
+  const found = await searchUsers(token, nameNorm, cookie);
+  if (found.id) return found.id;
+  throw userNotFoundError(ref, found);
 }
 
 /** Parse a Slack permalink, returning channel ID, optional message ts, and optional thread_ts.
@@ -576,6 +745,13 @@ function isChannelId(s: string): boolean {
   return /^[CDG][A-Z0-9]{8,}$/.test(s);
 }
 
+/** A Slack user ID: `U…` (member) or `W…` (Enterprise Grid member). Upper-case
+ *  only — that is what keeps a lowercase handle like `@u1234567` reading as a
+ *  name instead of being swallowed by the id branch. */
+function isUserId(s: string): boolean {
+  return /^[UW][A-Z0-9]{6,}$/.test(s);
+}
+
 export async function resolveChannel(token: string, ref: string, cookie?: string): Promise<string> {
   // Accept Slack permalinks directly
   const fromUrl = parseSlackUrl(ref);
@@ -583,6 +759,10 @@ export async function resolveChannel(token: string, ref: string, cookie?: string
   // Accept raw IDs (C..., D..., G...) as-is
   if (!ref.startsWith("@") && !ref.startsWith("#")) {
     if (isChannelId(ref)) return ref;
+    // A bare `U…` names a person, and the conversation meant by a person is the
+    // DM with them. Refusing it as a malformed target sent callers hunting for a
+    // syntax error when what they had handed over was a perfectly good user.
+    if (isUserId(ref)) return dmWithUser(token, ref, cookie);
     throw new Error(`Target must start with # or @ (or be a Slack URL/ID), got: ${ref}`);
   }
   // `#C0123456789` — an ID that was given the `#` every other target form takes.
@@ -596,6 +776,9 @@ export async function resolveChannel(token: string, ref: string, cookie?: string
   const nameNorm = normName(rawName);
 
   if (isIm) {
+    // `@U0123456789` — the id form wearing the `@`, same reasoning as the bare
+    // id above: resolve it as a person, not as a name nobody has.
+    if (isUserId(rawName)) return dmWithUser(token, rawName, cookie);
     // Use auth.test to check if @name refers to self (avoids users:read scope requirement).
     // auth.test is always available; users.list requires users:read which xoxc- tokens lack.
     const selfInfo = (await get(token, "auth.test", {}, cookie)) as { user_id?: string; user?: string };
@@ -603,55 +786,16 @@ export async function resolveChannel(token: string, ref: string, cookie?: string
     if (isSelf) {
       const userId = selfInfo.user_id;
       if (!userId) throw new Error("auth.test did not return user_id");
-      const dmResp = (await get(token, "conversations.list", { types: "im", limit: "200" }, cookie)) as {
-        channels?: Array<{ id?: string; user?: string }>;
-      };
-      const dm = (dmResp.channels ?? []).find((ch) => ch.user === userId);
-      if (dm?.id) return String(dm.id);
-      return openDm(token, userId, cookie);
+      const dm = await findExistingDm(token, userId, cookie);
+      return dm || openDm(token, userId, cookie);
     }
 
-    // Find user ID first via users.list (batch), then locate existing DM.
-    let userId = "";
-    let userCursor = "";
-    while (true) {
-      const params: Record<string, string> = { limit: "200" };
-      if (userCursor) params.cursor = userCursor;
-      const resp = (await get(token, "users.list", params, cookie)) as {
-        members?: Array<{ id?: string; name?: string; real_name?: string; profile?: { display_name?: string } }>;
-        response_metadata?: { next_cursor?: string };
-      };
-      for (const u of resp.members ?? []) {
-        const n = normName(u.name ?? "");
-        const rn = normName(u.real_name ?? "");
-        const dn = normName(u.profile?.display_name ?? "");
-        if (n === nameNorm || rn === nameNorm || (dn && dn === nameNorm)) {
-          userId = u.id ?? "";
-          break;
-        }
-      }
-      if (userId) break;
-      userCursor = resp.response_metadata?.next_cursor ?? "";
-      if (!userCursor) break;
-    }
-    if (!userId) throw new Error(`User not found: ${ref}`);
-
-    // Find an existing DM (avoids needing im:write scope)
-    let dmCursor = "";
-    while (true) {
-      const params: Record<string, string> = { types: "im", limit: "200" };
-      if (dmCursor) params.cursor = dmCursor;
-      const resp = (await get(token, "conversations.list", params, cookie)) as {
-        channels?: Array<{ id?: string; user?: string }>;
-        response_metadata?: { next_cursor?: string };
-      };
-      for (const ch of resp.channels ?? []) {
-        if (ch.user === userId) return String(ch.id ?? "");
-      }
-      dmCursor = resp.response_metadata?.next_cursor ?? "";
-      if (!dmCursor) break;
-    }
-    throw new Error(`No existing DM with ${ref} (${userId}). Open it once in Slack first.`);
+    const found = await searchUsers(token, nameNorm, cookie);
+    if (!found.id) throw userNotFoundError(ref, found);
+    // The Connect scan already walked the IM list to find them, so it knows the
+    // channel — asking again would only pay for the same pages twice.
+    if (found.dm) return found.dm;
+    return dmWithUser(token, found.id, cookie, ref);
   }
 
   // Channel lookup

package/ts/tail.ts

@@ -238,7 +238,9 @@ export async function cmdTail(
     process.exit(1);
   }
 
-  const channelId = await resolveChannel(token, target);
+  // Cookie included: a desktop (xoxc-) token is rejected by the public Web API
+  // without it, so dropping it here failed the lookup before the tail started.
+  const channelId = await resolveChannel(token, target, opts.cookie);
   const interval = opts.interval ?? 60000;
   // Optional auto-stop deadline (e.g. wait at most 30m for a reply).
   const deadline = opts.timeout ? _internals.now() + parseSince(opts.timeout) * 1000 : Infinity;