slack-term 1.26.6 → 1.27.0

package/ts/cli.ts

@@ -13,6 +13,14 @@ import { diagnoseBotMessaging, formatDiagnosis } from "./botdoctor.ts";
 import { cmdAuthLogin, cmdAuthChrome, cmdAuthFirefox, cmdAuthToken, cmdAuthApp } from "./auth.ts";
 import { cmdTail } from "./tail.ts";
 
+import {
+  ASK_KEYCAPS,
+  ASK_MAX_REACTION_CHOICES,
+  askBuildText,
+  askBuildResolvedText,
+  askParseMessage,
+  type AskFound,
+} from "./ask.ts";
 import {
   authTest,
   authScopes,
@@ -1519,6 +1527,634 @@ async function cmdSend(token: string, args: SendArgs): Promise<void> {
   }
 }
 
+// --- ask ---
+//
+// Post a question with its choices PRE-SEEDED as 1️⃣..🔟 reactions, so answering
+// costs one tap on an existing pill instead of a trip through the emoji picker.
+//
+// Reactions, not Block Kit buttons: `block_actions` are delivered only to a
+// Request URL or a Socket Mode socket, neither of which a short-lived CLI can
+// own without losing clicks. A reaction is durable state — any number of
+// concurrent waiters can read it back from `conversations.history`, repeatedly,
+// long after it was pressed.
+//
+// Exit codes are the contract for `--wait`, and a non-zero one must never be
+// mistakable for "an answer arrived":
+//   0  answered   (the answer text is on stdout, and nothing else is)
+//   2  timed out
+//   3  transport/config failure
+// Everything human-facing goes to stderr, so `ANS=$(slack ask ... --wait)` is safe.
+
+const ASK_EXIT_TIMEOUT = 2;
+const ASK_EXIT_ERROR = 3;
+
+const ASK_PHI = 1.618033988749895;
+const ASK_POLL_MIN_MS = 1000;
+const ASK_POLL_MAX_MS = 5000;
+const ASK_MAX_CONSECUTIVE_ERRORS = 8;
+
+
+interface AskArgs {
+  target: string;
+  question: string;
+  choices: string[];
+  body?: string;
+  code?: string;
+  channelId?: string;
+  userId?: string;
+  asBot?: boolean;
+  wait?: boolean;
+  timeout?: number;
+  cookie?: string;
+  // Token used to resolve the @tags that decide who may answer (needs
+  // users:read). Defaults to the ask token; set to the user token under
+  // --as-bot so the bot token need not carry users:read. There is no
+  // --no-mentions here: the tags ARE the authorization, so leaving them as
+  // plain text would leave the question addressed to nobody.
+  mentionToken?: string;
+  mentionCookie?: string;
+}
+
+
+const askSleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+// A thread reply sent with "also send to channel" ticked arrives as a normal
+// message carrying this subtype. Dropping every subtype would discard those —
+// and where thread replies are the only text path, that means discarding real
+// answers.
+const ASK_ANSWERABLE_SUBTYPES = new Set(["thread_broadcast"]);
+
+// `@here` / `@channel` / `@everyone` — Slack's channel-wide tags. Same lookbehind
+// guard as the user-mention regex (skips emails, `<!here>` already encoded, `@@`),
+// and a lookahead rather than `\b` so a CJK character right after the tag still
+// ends it (`\b` is unreliable outside ASCII).
+const ASK_BROADCAST_RE = /(?<![A-Za-z0-9._@<-])@(here|channel|everyone)(?![A-Za-z0-9._-])/giu;
+
+/** Rewrite `@here`/`@channel`/`@everyone` to the `<!here>` form Slack actually
+ *  broadcasts on, and report which were used. Run BEFORE user-mention encoding
+ *  so those tokens are never offered to the directory as if they were handles. */
+function askEncodeBroadcasts(s: string): { text: string; kinds: Set<string> } {
+  const kinds = new Set<string>();
+  const text = s.replace(ASK_BROADCAST_RE, (_m, k: string) => {
+    const kind = k.toLowerCase();
+    kinds.add(kind);
+    return `<!${kind}>`;
+  });
+  return { text, kinds };
+}
+
+/** The other party in a 1:1 DM, or undefined for anything else (including a
+ *  failed lookup). Fail-soft on purpose, but note the caller treats "unknown"
+ *  as "no implicit audience" — fail-closed on WHO MAY ANSWER, which is the
+ *  direction that cannot silently hand a decision to the wrong person. */
+async function imCounterpart(token: string, channelId: string, cookie?: string): Promise<string | undefined> {
+  if (!channelId.startsWith("D")) return undefined;
+  try {
+    const info = asRecord((await conversationInfo(token, channelId, cookie)) as Json);
+    const ch = asRecord(info.channel);
+    return ch.is_im === true && typeof ch.user === "string" ? ch.user : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Everything the answer poller needs. `--wait` fills it in from what it just
+ *  posted; `--waitFor` recovers the same fields from the message itself. */
+interface AskWaitCtx {
+  channelId: string;
+  ts: string;
+  /** Set only when the question is itself a thread reply. Such a message never
+   *  appears in `conversations.history`, so the whole poll has to run through
+   *  `conversations.replies` instead. */
+  threadParentTs?: string;
+  question: string;
+  reactable: string[];
+  threadOnly: boolean;
+  /** Who may answer. Empty + broadcast=false would accept nobody, which is why
+   *  posting an unaddressed question is refused up front. */
+  audience: Set<string>;
+  broadcast: boolean;
+  /** The asker as the POSTED MESSAGE shows them — not the current token. On
+   *  resume the two can differ, and taking the current identity would count the
+   *  original asker's seeds as answers. */
+  askerUserId: string;
+  askerBotId: string;
+  timeout: number;
+  cookie?: string;
+  shown: string;
+  /** Only so the resume hint printed on timeout names the right identity — the
+   *  ✅ rewrite can be done by the original poster alone. */
+  asBot: boolean;
+}
+
+/** Poll until answered. Never returns: exits 0 with the answer on stdout, or 2
+ *  on timeout. A timeout of 0 means "look exactly once", so a caller can poll
+ *  cheaply on its own schedule instead of parking a process on `--wait`. */
+async function askWaitForAnswer(token: string, ctx: AskWaitCtx): Promise<never> {
+  const { channelId, ts, question, reactable, threadOnly, audience, broadcast, cookie, timeout, shown } = ctx;
+  const askerUserId = ctx.askerUserId;
+  const askerBotId = ctx.askerBotId;
+
+  // Only the people the question actually addresses. Excluding the asker is what
+  // stops a seed being counted as an answer; restricting to `audience` is what
+  // stops a bystander in a busy channel from deciding it. `@here`/`@channel`
+  // deliberately opens it to everyone — that is what the asker asked for.
+  const isAnswerer = (user: unknown): user is string =>
+    typeof user === "string" && !!user && user !== askerUserId && (broadcast || audience.has(user));
+
+  /** Every seed an answerer is on — not just the first. Changing your mind
+   *  leaves BOTH reactions in place (Slack only drops one when you actively
+   *  un-react), so taking the lowest index would answer with the abandoned
+   *  choice. Array order cannot break the tie either: it is add-order, and we
+   *  added every seed before anyone touched it. */
+  function humanChoices(msg: Record<string, Json>): { index: number; users: string[] }[] {
+    const reactions = asArray(msg.reactions).map(asRecord);
+    const out: { index: number; users: string[] }[] = [];
+    for (let i = 0; i < reactable.length; i++) {
+      const r = reactions.find((x) => x.name === ASK_KEYCAPS[i]!.name);
+      const users = r ? asArray(r.users).filter(isAnswerer) : [];
+      if (users.length) out.push({ index: i, users });
+    }
+    return out;
+  }
+
+  // Two reactions means two answers, and this command exists for decisions that
+  // are expensive to get wrong — so an ambiguous state is never resolved by
+  // guessing. Say so in the thread and keep waiting; removing one reaction (or
+  // replying with text) settles it on the next poll.
+  let ambiguityNotified = false;
+
+  async function answerFromReactions(msg: Record<string, Json>): Promise<AskFound | null> {
+    const picks = humanChoices(msg);
+    if (!picks.length) return null;
+    if (picks.length === 1) {
+      const { index, users } = picks[0]!;
+      return { answer: reactable[index]!, how: `リアクション ${ASK_KEYCAPS[index]!.glyph}`, who: users[0]! };
+    }
+    const glyphs = picks.map((p) => ASK_KEYCAPS[p.index]!.glyph).join(" / ");
+    if (!ambiguityNotified) {
+      ambiguityNotified = true;
+      console.error(`  (${glyphs} が同時に選ばれています。1 つに絞ってもらうまで待ちます)`);
+      try {
+        await slackSend(token, channelId, `${glyphs} が同時に選ばれています。回答を確定できないので、1 つだけ残るようにリアクションを外すか、このスレッドで返信してください。`, ts, false, cookie);
+      } catch (e: unknown) {
+        console.error(`  (確認の返信を送れませんでした: ${e instanceof Error ? e.message : String(e)})`);
+      }
+    }
+    return null;
+  }
+
+  function answerFromMessages(messages: Record<string, Json>[], before = Infinity): AskFound | null {
+    // Oldest first: if someone wrote twice, the first reply is the answer.
+    const ordered = [...messages].sort((a, b) => Number(a.ts) - Number(b.ts));
+    for (const m of ordered) {
+      // Strictly after the question. A question posted INTO an existing thread
+      // sits among replies that predate it, and those answered something else.
+      if (!(Number(m.ts) > Number(ts))) continue;
+      if (!isAnswerer(m.user)) continue;
+      if (typeof m.subtype === "string" && !ASK_ANSWERABLE_SUBTYPES.has(m.subtype)) continue;
+      if (Number(m.ts) >= before) break;
+      const t = typeof m.text === "string" ? m.text.trim() : "";
+      if (t) return { answer: t, how: "返信", who: m.user };
+    }
+    return null;
+  }
+
+  async function poll(): Promise<AskFound | null> {
+    // A question that is itself a thread reply is invisible to
+    // `conversations.history`, so the entire poll — reactions included — has to
+    // come from the thread.
+    if (ctx.threadParentTs) {
+      const rep = asRecord((await replies(token, channelId, ctx.threadParentTs, 100, cookie)) as Json);
+      const messages = asArray(rep.messages).map(asRecord);
+      const own = messages.find((m) => m.ts === ts);
+      if (own) {
+        const byReaction = await answerFromReactions(own);
+        if (byReaction) return byReaction;
+      }
+      return answerFromMessages(messages);
+    }
+
+    // inclusive: `oldest` excludes the message at that exact ts, and that
+    // message IS the question — without this the reactions and reply_count we
+    // are polling for never come back at all.
+    const hist = asRecord((await history(token, channelId, 30, ts, undefined, cookie, true)) as Json);
+    const messages = asArray(hist.messages).map(asRecord);
+    const own = messages.find((m) => m.ts === ts);
+
+    // A reaction is the intended path, so it wins when both are present.
+    if (own) {
+      const byReaction = await answerFromReactions(own);
+      if (byReaction) return byReaction;
+    }
+
+    if (!threadOnly) {
+      // A plain DM reply is ambiguous only while several questions are open at
+      // once: it belongs to whichever was newest when it was written. Bound the
+      // search by the ts of our NEXT question in this conversation, so an older
+      // waiter falls back to reactions/thread replies and never steals the
+      // newer one's answer.
+      const nextQuestionTs = messages
+        .filter((m) => Number(m.ts) > Number(ts) && (
+          (askerBotId && m.bot_id === askerBotId) || (askerUserId && m.user === askerUserId)))
+        .reduce((min, m) => Math.min(min, Number(m.ts)), Infinity);
+      const byMessage = answerFromMessages(messages, nextQuestionTs);
+      if (byMessage) return byMessage;
+    }
+
+    // Thread replies never appear in history; only pay for the extra call once
+    // the parent says there is something to fetch.
+    if (own && Number(own.reply_count) > 0) {
+      const rep = asRecord((await replies(token, channelId, ts, 30, cookie)) as Json);
+      const byThread = answerFromMessages(asArray(rep.messages).map(asRecord));
+      if (byThread) return byThread;
+    }
+    return null;
+  }
+
+  /** Stamp the question resolved. Removing our seeds clears the pills that still
+   *  invite an answer; the answerer's own reaction cannot be removed by us and
+   *  stays put — which is exactly what leaves the chosen number visible. */
+  async function markResolved(found: AskFound): Promise<void> {
+    for (let i = 0; i < reactable.length; i++) {
+      try {
+        await reactionRemove(token, channelId, ts, ASK_KEYCAPS[i]!.name, cookie);
+      } catch {
+        // Already removed, or someone else's reaction — neither is fatal.
+      }
+    }
+    let who = "";
+    if (found.who) {
+      try {
+        who = await userName(token, found.who, cookie);
+      } catch {
+        who = found.who;
+      }
+    }
+    // Who answered never reaches stdout — callers do ANS=$(slack ask --wait ...)
+    // and must keep getting the answer body alone.
+    if (who) console.error(`  回答者: ${stripTerminalControls(who)}`);
+    try {
+      await editMessage(token, channelId, ts, askBuildResolvedText(question, found, who), cookie);
+    } catch (e: unknown) {
+      // The edit is bookkeeping, not the answer. It fails whenever the resuming
+      // token is not the one that posted (Slack lets only the author update), and
+      // that must not cost the caller an answer it already has.
+      console.error(`  (元メッセージの更新に失敗: ${e instanceof Error ? e.message : String(e)})`);
+    }
+  }
+
+  const deadline = Date.now() + timeout * 1000;
+  let errors = 0;
+  let delay = ASK_POLL_MIN_MS;
+  for (;;) {
+    let found: AskFound | null = null;
+    try {
+      found = await poll();
+      errors = 0;
+    } catch (e: unknown) {
+      // A dropped poll is expected occasionally; only give up if it keeps failing.
+      errors++;
+      if (errors >= ASK_MAX_CONSECUTIVE_ERRORS) {
+        console.error(`Error: Slack への問い合わせに ${errors} 回連続で失敗しました: ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(ASK_EXIT_ERROR);
+      }
+      console.error(`  (Slack エラー ${errors}/${ASK_MAX_CONSECUTIVE_ERRORS}, 再試行します: ${e instanceof Error ? e.message : String(e)})`);
+    }
+    if (found) {
+      await markResolved(found);
+      // stdout gets the answer and nothing else.
+      console.log(found.answer);
+      process.exit(0);
+    }
+    // Checked after the first poll, never before it: `--timeout 0` means one
+    // look, and one look must still be a real look.
+    if (Date.now() >= deadline) break;
+    await askSleep(Math.min(delay, Math.max(0, deadline - Date.now())));
+    delay = Math.min(delay * ASK_PHI, ASK_POLL_MAX_MS);
+  }
+
+  // A timeout is the moment the caller most needs the collect command: the
+  // question is still standing, and they have just decided not to block on it.
+  // Printing only the permalink here leaves them where `ask` used to: holding a
+  // link with nothing that reads a pressed pill back.
+  if (timeout === 0) {
+    console.error(`まだ回答がありません: ${shown}`);
+  } else {
+    console.error(`Error: ${timeout}s 以内に回答がありませんでした (メッセージはそのまま残っています)`);
+    console.error(`  ${shown}`);
+    console.error(`  あとで回収する:  ${askResumeCommand(shown, ctx.asBot)}`);
+  }
+  process.exit(ASK_EXIT_TIMEOUT);
+}
+
+/** The `slack ask --waitFor=…` line handed to a caller that did not block.
+ *  Printed as a runnable command rather than a bare permalink: the collect step
+ *  is the half everyone forgets, and a link does not tell you how to collect. */
+function askResumeCommand(shown: string, asBot: boolean): string {
+  return `slack ask --waitFor='${shown}'${asBot ? " --as-bot" : ""}`;
+}
+
+async function cmdAsk(token: string, args: AskArgs): Promise<void> {
+  const { ref, threadTs } = parseTargetThread(args.target);
+  const cookie = args.cookie;
+  const getSelf = selfLookup(token, cookie);
+
+  let channelId: string;
+  if (args.channelId) channelId = args.channelId;
+  else if (args.userId) channelId = await openDm(token, args.userId, cookie);
+  else channelId = await resolveChannel(token, ref, cookie);
+
+  const selfId = (await getSelf())?.userId ?? "";
+  const counterpart = await imCounterpart(token, channelId, cookie);
+
+  // Same silent-delivery footgun as `send`: Slack never notifies you about your
+  // own message, so a question asked in your own DM is delivered and then never
+  // seen — and `--wait` would sit there until it timed out.
+  if (!args.asBot && !!selfId && counterpart === selfId) {
+    console.error(
+      `Warning: "${args.target}" is a DM to yourself — Slack will NOT notify you of your own message.\n` +
+      `  To reach yourself with a notification, ask as the bot:  slack ask '${args.target}' '...' --as-bot`,
+    );
+  }
+
+  // --- who may answer -------------------------------------------------------
+  //
+  // A question with no addressee is the actual failure mode this guards: post it
+  // into a busy channel and the first person to react has decided something that
+  // was never theirs to decide. So the audience is taken from the @tags in the
+  // text — the same names the reader sees — and an untargeted ask is refused
+  // outright rather than defaulted to "whoever gets there first".
+  const qEnc = askEncodeBroadcasts(args.question);
+  const bEnc = askEncodeBroadcasts(args.body ?? "");
+  const broadcastKinds = new Set([...qEnc.kinds, ...bEnc.kinds]);
+  const mentionToken = args.mentionToken ?? token;
+  const qRep = await encodeMentionsDetailed(mentionToken, qEnc.text, channelId, args.mentionCookie);
+  const bRep = bEnc.text
+    ? await encodeMentionsDetailed(mentionToken, bEnc.text, channelId, args.mentionCookie)
+    : { text: "", resolved: [], unresolved: [] } as MentionEncodeResult;
+  const question = qRep.text;
+  const body = bRep.text;
+  const resolved = [...qRep.resolved, ...bRep.resolved];
+  const unresolved = [...qRep.unresolved, ...bRep.unresolved];
+  // An unresolved tag is not just cosmetic here: it names nobody, so it grants
+  // nobody the right to answer. Say so before the rejection below.
+  for (const line of mentionWarnings(unresolved)) console.error(`⚠ ${stripTerminalControls(line)}`);
+
+  const broadcast = broadcastKinds.size > 0;
+  // Tagging yourself grants nothing — your own reactions are the seeds.
+  const audience = new Set(resolved.map((r) => r.userId).filter((id) => id !== selfId));
+  const audienceNames = new Map(resolved.map((r) => [r.userId, r.display]));
+  let audienceLabel: string;
+  if (broadcast) {
+    audienceLabel = `anyone in ${ref} (${[...broadcastKinds].map((k) => `@${k}`).join(", ")})`;
+  } else {
+    // 1:1 DM: the other party IS the audience — there is no one else it could
+    // be, so requiring a redundant @tag would buy no clarity. Only here; a group
+    // DM or channel still has to name someone.
+    if (!audience.size && counterpart && counterpart !== selfId) {
+      audience.add(counterpart);
+      audienceNames.set(counterpart, await userName(token, counterpart, cookie));
+    }
+    if (!audience.size) {
+      console.error(
+        `Error: \`ask\` will not post a question nobody is addressed to — no one is tagged.\n` +
+        (unresolved.length
+          ? `  (${unresolved.map((u) => stripTerminalControls(u.surface)).join(", ")} matched no one, so it names nobody.)\n`
+          : "") +
+        `  Tag the person who should answer:  slack ask '${args.target}' '@alice ${args.question}' ...\n` +
+        `  Or open it to the whole channel:   slack ask '${args.target}' '@here ${args.question}' ...\n` +
+        `  (In a 1:1 DM the other person counts automatically.)`,
+      );
+      process.exit(ASK_EXIT_ERROR);
+    }
+    audienceLabel = [...audience]
+      .map((id) => `@${stripTerminalControls(audienceNames.get(id) ?? id)} (${id})`)
+      .join(", ");
+  }
+
+  const reactable = args.choices.slice(0, ASK_MAX_REACTION_CHOICES);
+  const overflow = args.choices.slice(ASK_MAX_REACTION_CHOICES);
+
+  // Where free-text answers may come from. A 1:1 DM carries no unrelated
+  // traffic, so a plain reply there is an answer. A channel does, so only
+  // reactions and thread replies count — both name the message they belong to,
+  // which makes channel mode unambiguous by construction. A question posted
+  // INTO a thread is thread-scoped for the same reason.
+  const threadOnly = !channelId.startsWith("D") || !!threadTs;
+  const message = askBuildText(question, body, reactable, overflow, threadOnly);
+
+  // Preview the destination's last message, exactly as `send` does — the gate's
+  // job is to make you look at where this is going before it goes. Fail-soft:
+  // a token without history scope can still ask; only the preview degrades.
+  let lastText = "";
+  let lastUser = "?";
+  try {
+    const ctx = (await history(token, channelId, 1, undefined, undefined, cookie)) as Record<string, Json>;
+    const lastMsg = asArray(ctx.messages).map(asRecord).filter((m) => m.subtype === undefined || m.subtype === null)[0];
+    lastText = typeof lastMsg?.text === "string" ? lastMsg.text : "";
+    lastUser = typeof lastMsg?.user === "string"
+      ? await userName(token, lastMsg.user, cookie)
+      : typeof lastMsg?.username === "string" ? lastMsg.username : "?";
+  } catch {
+    // best-effort preview only
+  }
+
+  // Same gate as `send`, deliberately: 追記 4 settled that the two-step code is
+  // not "a human in the loop" but "look again before committing", which a script
+  // satisfies by calling twice. The hash binds destination, thread, the exact
+  // posted body (question AND choices) and the asking identity.
+  const self = await getSelf();
+  const code = safetyCode(channelId, threadTs ?? "", lastText, message, self?.userId ?? "");
+  if (args.code !== code) {
+    const dest = await destLabel(token, channelId, ref, cookie);
+    const choiceLines = reactable.length
+      ? [`--- Choices (seeded as reactions) ------------`,
+         ...reactable.map((s, i) => `  ${ASK_KEYCAPS[i]!.glyph} ${s}`),
+         ...overflow.map((s, i) => `  (${i + 11}) ${s} — text answer only`)]
+      : [`--- Choices ----------------------------------`, `  (none — free-text reply)`];
+    requireCode(args.code, code, [
+      `--- Last message in channel ------------------`,
+      `  ${lastUser}: ${lastText.split("\n")[0]?.slice(0, 100) ?? "(empty)"}`,
+      ...choiceLines,
+      `--- Asking -----------------------------------`,
+      fromLine(self, { asBot: args.asBot }),
+      `  → ${dest}${threadTs ? " — THREAD REPLY" : " — NEW top-level message"}`,
+      `  Question: ${question}`,
+      // The audience is the part that decides whose answer is binding, so it is
+      // shown as its own line rather than left to be inferred from the body.
+      `  Answerable by: ${audienceLabel}`,
+      `  Via:      ${threadOnly ? "reactions or thread replies" : "reactions or replies in this DM"}`,
+      `--------------------------------────────────`,
+    ]);
+  }
+
+  const ts = await slackSend(token, channelId, message, threadTs, false, cookie);
+
+  // Seeded one at a time and in order: Slack keeps reactions in the order they
+  // were added, so sequential adds are what make the pills read 1,2,3 rather
+  // than shuffled. A parallel add is not an optimization here, it is a bug.
+  for (let i = 0; i < reactable.length; i++) {
+    try {
+      await reactionAdd(token, channelId, ts, ASK_KEYCAPS[i]!.name, cookie);
+    } catch (e: unknown) {
+      // A missing seed only costs the answerer a trip to the emoji picker, so
+      // warn and keep going rather than abandon a question already posted.
+      console.error(`  (リアクション ${ASK_KEYCAPS[i]!.name} を付けられませんでした: ${e instanceof Error ? e.message : String(e)})`);
+    }
+  }
+
+  let permalink = "";
+  try {
+    permalink = await getPermalink(token, channelId, ts, cookie);
+  } catch {
+    // fail-soft, same as send: a permalink lookup failure must not mask success
+  }
+  const shown = permalink || `${channelId}:${ts}`;
+  console.error(`✓ Asked: ${shown}`);
+
+  if (!args.wait) {
+    // Not waiting. stdout is the RESUME COMMAND, not just a link: nothing else
+    // reads a pressed pill back — `tail` only sees `type: "message"` events and
+    // drops `message_changed`, so both the reaction and the ✅ rewrite are
+    // invisible to it. A question posted with no way to collect it is how an
+    // answer gets pressed and nobody ever hears about it.
+    console.log(askResumeCommand(shown, !!args.asBot));
+    return;
+  }
+
+  const timeout = args.timeout ?? 3600;
+  console.error(`  回答を待っています (最大 ${timeout}s)… Ctrl-C で中断`);
+
+  const ctx: AskWaitCtx = {
+    channelId,
+    ts,
+    question,
+    reactable,
+    threadOnly,
+    audience,
+    broadcast,
+    askerUserId: self?.userId ?? "",
+    askerBotId: self?.botId ?? "",
+    timeout,
+    shown,
+    asBot: !!args.asBot,
+  };
+  if (threadTs) ctx.threadParentTs = threadTs;
+  if (cookie) ctx.cookie = cookie;
+  await askWaitForAnswer(token, ctx);
+}
+
+
+
+/** `slack ask --waitFor <permalink>` — collect the answer to a question that was
+ *  posted without blocking.
+ *
+ *  Nothing about the question is stored locally, so everything the poller needs
+ *  is read back out of the message itself. That is a deliberate trade: no state
+ *  file to go stale, lose, or disagree with Slack, and any machine holding the
+ *  permalink can collect — at the cost of the body being a parseable format
+ *  (`askBuildText` ⇄ `askParseMessage`). */
+async function cmdAskWaitFor(token: string, args: { link: string; timeout: number; asBot: boolean; cookie?: string }): Promise<void> {
+  const url = parseSlackPermalink(args.link);
+  let channelId: string;
+  let ts: string;
+  let threadTs: string | undefined;
+  if (url?.ts) {
+    channelId = url.channel;
+    ts = url.ts;
+    threadTs = url.threadTs && url.threadTs !== url.ts ? url.threadTs : undefined;
+  } else {
+    // `C…:1700000000.000100` — the fallback `ask` prints when the permalink
+    // lookup itself failed, so it has to be collectable too.
+    const m = args.link.match(/^([A-Za-z0-9]+):(\d{10}\.\d{6})$/);
+    if (!m) {
+      console.error(
+        `Error: --waitFor needs the permalink of a question (or 'C…:1700000000.000100').\n` +
+        `  Got: ${stripTerminalControls(args.link)}`,
+      );
+      process.exit(ASK_EXIT_ERROR);
+    }
+    channelId = m[1]!;
+    ts = m[2]!;
+  }
+
+  // Fetch the one message. A question posted into a thread is not in history at
+  // all, so where the permalink says it is a reply, read it from the thread.
+  let msg: Record<string, Json> | undefined;
+  if (threadTs) {
+    const rep = asRecord((await replies(token, channelId, threadTs, 100, args.cookie)) as Json);
+    msg = asArray(rep.messages).map(asRecord).find((m) => m.ts === ts);
+  } else {
+    const hist = asRecord((await history(token, channelId, 1, ts, undefined, args.cookie, true)) as Json);
+    msg = asArray(hist.messages).map(asRecord).find((m) => m.ts === ts);
+  }
+  if (!msg) {
+    console.error(`Error: そのメッセージが見つかりません: ${stripTerminalControls(args.link)}`);
+    process.exit(ASK_EXIT_ERROR);
+  }
+
+  const text = typeof msg.text === "string" ? msg.text : "";
+  const parsed = askParseMessage(text);
+  if (parsed.kind === "other") {
+    console.error(
+      `Error: これは \`slack ask\` の質問ではありません (回答の読み取り方が分かりません)。\n` +
+      `  ${stripTerminalControls(args.link)}`,
+    );
+    process.exit(ASK_EXIT_ERROR);
+  }
+  if (parsed.kind === "resolved") {
+    // Answered while nobody was watching — the case that makes fire-and-forget
+    // safe. Report it exactly as `--wait` would have.
+    console.error(`✓ 回答済み: ${stripTerminalControls(parsed.question)}`);
+    console.log(parsed.answer);
+    return;
+  }
+
+  // Who may answer, recovered from the tags the readers can see. They are
+  // already `<@U…>`-encoded in the stored text, so no directory lookup is
+  // needed — and the asker is excluded here for the same reason as when
+  // posting: their tag of themselves grants nothing, and their reactions are
+  // the seeds.
+  const askerUserId = typeof msg.user === "string" ? msg.user : "";
+  const askerBotId = typeof msg.bot_id === "string" ? msg.bot_id : "";
+  const broadcast = /<!(here|channel|everyone)(\^[^>]*)?(\|[^>]*)?>/.test(text);
+  const audience = new Set<string>();
+  for (const m of text.matchAll(/<@([UW][A-Z0-9]+)>/g)) {
+    if (m[1] !== askerUserId) audience.add(m[1]!);
+  }
+  if (!audience.size && !broadcast) {
+    // A 1:1 DM needs no tag — the other party is the only person it could be.
+    const counterpart = await imCounterpart(token, channelId, args.cookie);
+    if (counterpart && counterpart !== askerUserId) audience.add(counterpart);
+  }
+  if (!audience.size && !broadcast) {
+    console.error(`Error: この質問は誰にも宛てられていないため、有効な回答者を判定できません: ${stripTerminalControls(args.link)}`);
+    process.exit(ASK_EXIT_ERROR);
+  }
+
+  if (args.timeout > 0) {
+    console.error(`  回答を待っています (最大 ${args.timeout}s)… Ctrl-C で中断`);
+  }
+  const ctx: AskWaitCtx = {
+    channelId,
+    ts,
+    question: parsed.question,
+    reactable: parsed.reactable,
+    threadOnly: parsed.threadOnly,
+    audience,
+    broadcast,
+    askerUserId,
+    askerBotId,
+    timeout: args.timeout,
+    shown: args.link,
+    asBot: args.asBot,
+  };
+  if (threadTs) ctx.threadParentTs = threadTs;
+  if (args.cookie) ctx.cookie = args.cookie;
+  await askWaitForAnswer(token, ctx);
+}
+
 async function cmdDoctor(token: string): Promise<void> {
   const diag = await diagnoseBotMessaging(token);
   for (const line of formatDiagnosis(diag, false)) console.log(line);
@@ -2308,6 +2944,131 @@ async function main(): Promise<void> {
         }
       },
     )
+    .command(
+      "ask [target] [question] [choices..]",
+      "Ask a question with its choices pre-seeded as 1️⃣..🔟 reactions (confirm-hash safety gate)",
+      (y) => y
+        .positional("target", { type: "string", describe: "#chan, @user, #chan:thread_ts, or permalink (omit with --waitFor)" })
+        .positional("question", { type: "string", describe: "The question. Must @tag whoever may answer (@alice), or the whole channel (@here / @channel / @everyone) — only their answer counts. In a 1:1 DM the other party counts automatically." })
+        .positional("choices", { type: "string", array: true, describe: "Up to 10 choices, seeded as 1️⃣..🔟 reactions. Beyond 10 they are listed but answerable only by text. With none, the question asks for a free-text reply." })
+        .option("code", { type: "string", describe: "Safety hash to confirm the ask" })
+        .option("body", { type: "string", describe: "Extra context shown under the question" })
+        .option("wait", { type: "boolean", default: false, describe: "Block until answered; print ONLY the answer on stdout. Exit 0 = answered, 2 = timed out, 3 = transport failure." })
+        .option("waitFor", { type: "string", describe: "Collect the answer to a question already posted: pass its permalink. Nothing is posted. Same stdout/exit contract as --wait; --timeout 0 checks once and exits 2 if still open." })
+        .option("timeout", { type: "number", default: 3600, describe: "Overall limit for --wait / --waitFor, in seconds (0 with --waitFor = check once)" })
+        .option("channel-id", { type: "string", describe: "Raw channel ID" })
+        .option("user-id", { type: "string", describe: "Raw user ID (opens DM)" })
+        .option("as-bot", { type: "boolean", default: false, describe: "Ask via the bot token (xoxb / SLACK_BOT_TOKEN) so a DM notifies the recipient" }),
+      async (argv) => {
+        const waitFor = argv.waitFor ? String(argv.waitFor) : "";
+        const timeout = Number(argv.timeout);
+        // 0 is a real value only for --waitFor ("look once"). For --wait it would
+        // mean "give up before asking", which is never what anyone meant.
+        if (!Number.isFinite(timeout) || timeout < 0 || (timeout === 0 && !waitFor)) {
+          console.error("Error: --timeout must be a positive number of seconds");
+          process.exit(ASK_EXIT_ERROR);
+        }
+        if (waitFor) {
+          // Collect-only: nothing is posted, so there is no confirm gate and no
+          // question to supply. Anything that would have been posted is a sign
+          // the caller mixed the two modes up.
+          if (argv.target || argv.question || (argv.choices as string[] | undefined)?.length) {
+            console.error("Error: --waitFor collects an existing question — do not also pass a target/question/choices.");
+            process.exit(ASK_EXIT_ERROR);
+          }
+          let waitToken: string;
+          let waitCookie: string | undefined;
+          if (argv["as-bot"]) {
+            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(ASK_EXIT_ERROR);
+            }
+            waitToken = botToken;
+          } else {
+            waitToken = tok(argv as W);
+            waitCookie = ck(argv as W);
+          }
+          try {
+            const a: { link: string; timeout: number; asBot: boolean; cookie?: string } = { link: waitFor, timeout, asBot: !!argv["as-bot"] };
+            if (waitCookie) a.cookie = waitCookie;
+            await cmdAskWaitFor(waitToken, a);
+          } catch (e: unknown) {
+            console.error(friendlySlackError(e));
+            process.exit(ASK_EXIT_ERROR);
+          }
+          return;
+        }
+        if (!argv.target) {
+          console.error("Error: target is required (or use --waitFor <permalink> to collect an answer)");
+          process.exit(ASK_EXIT_ERROR);
+        }
+        const question = String(argv.question ?? "").trim();
+        if (!question) {
+          console.error("Error: question is empty");
+          process.exit(ASK_EXIT_ERROR);
+        }
+        const args: AskArgs = {
+          target: argv.target!,
+          question,
+          choices: ((argv.choices as string[] | undefined) ?? []).map((s) => String(s).trim()).filter(Boolean),
+          timeout,
+        };
+        if (argv.code) args.code = argv.code;
+        if (argv.body) args.body = argv.body;
+        if (argv.wait) args.wait = true;
+        if (argv["channel-id"]) args.channelId = argv["channel-id"];
+        if (argv["user-id"]) args.userId = argv["user-id"];
+        // Always resolve @tags with the user token (it has users:read), even
+        // when the question itself is posted by the bot.
+        args.mentionToken = tok(argv as W);
+        const mc = ck(argv as W);
+        if (mc) args.mentionCookie = mc;
+
+        let askToken: string;
+        if (argv["as-bot"]) {
+          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(ASK_EXIT_ERROR);
+          }
+          // Resolve @user with the *user* token (has users:read), then let cmdAsk
+          // open the DM with the bot token — same split as `send --as-bot`.
+          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(ASK_EXIT_ERROR);
+            }
+          }
+          askToken = botToken;
+          args.asBot = true;
+        } else {
+          askToken = tok(argv as W);
+          const sc = ck(argv as W);
+          if (sc) args.cookie = sc;
+        }
+        try {
+          await cmdAsk(askToken, args);
+        } catch (e: unknown) {
+          console.error(friendlySlackError(e));
+          // 3, not 1: `--wait` callers branch on the exit code, and a transport
+          // failure must be distinguishable from "timed out" (2).
+          process.exit(ASK_EXIT_ERROR);
+        }
+      },
+    )
     .command(
       "doctor",
       "Check the bot token (xoxb) can carry a two-way DM (scopes + Messages Tab)",