slack-term 1.43.0 → 1.44.0

package/package.json

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

package/ts/ask.ts

@@ -41,6 +41,15 @@ export type AskFound = { answer: string; how: string; who?: string; ts?: string;
 export const ASK_MARKER = "question";
 export const ASK_MARKER_PREFIX = `:${ASK_MARKER}: `;
 
+/** The "explain" pill (`--explain`): pressing it asks the asker to explain the
+ *  question, and is NEVER an answer. Reported 2026-10-14: an "explain" offered
+ *  as a numbered choice was collected as the decision and closed the question.
+ *  Not ❓: ❓ means "none of these fit — my answer follows as a reply", and that
+ *  reply resolves the question; ℹ️ means "I cannot answer yet", and the question
+ *  stays open for a real answer after the explanation. */
+export const ASK_EXPLAIN_MARKER = "information_source";
+export const ASK_EXPLAIN_PREFIX = `:${ASK_EXPLAIN_MARKER}: `;
+
 // The copy a reader sees, per language. Japanese is the default and its
 // strings are a WIRE FORMAT: questions already in flight were posted with them
 // and are recognised by them, so they must never be reworded. Adding a language
@@ -118,6 +127,14 @@ interface AskCopy {
   overflowNote: string;
   otherThread: string;
   otherHere: string;
+  /** The free-text parser matches this exactly (`askIsExplainCopy`), so it is
+   *  a wire format too: questions in flight carry it. */
+  explainLine: string;
+  /** WIRE FORMAT — never reword. `--wait`/`--waitFor` find a question's
+   *  thread note by this exact copy (`askIsExplainNote`), so a reworded note
+   *  is not found by later runs, which would post a second one, and the old
+   *  note would stop being excluded from answers and notes. */
+  explainNote: string;
   invalidPrefix: string;
   answeredVia: (how: string, who: string) => string;
   howReaction: (glyph: string) => string;
@@ -149,6 +166,8 @@ export const ASK_COPY: Record<AskLang, AskCopy> = {
     overflowNote: "_11 番目以降はリアクションがないので、返信で答えてください。_",
     otherThread: `${ASK_MARKER_PREFIX}その他 — スレッドで返信してください`,
     otherHere: `${ASK_MARKER_PREFIX}その他 — このメッセージに返信してください`,
+    explainLine: `${ASK_EXPLAIN_PREFIX}説明して — 押すと質問者に説明を頼みます (回答にはなりません)`,
+    explainNote: `${ASK_EXPLAIN_PREFIX}説明のリクエストを受け付けました — このスレッドで説明します。質問はまだ開いているので、回答はそのあとで大丈夫です。`,
     invalidPrefix: "_:warning: 同時に複数選ばれているため回答として数えていません — どれか 1 つだけ残してください: ",
     answeredVia: (how, who) => `_${how}で回答済み${who ? ` (${who})` : ""}_`,
     howReaction: (glyph) => `リアクション ${glyph}`,
@@ -168,6 +187,8 @@ export const ASK_COPY: Record<AskLang, AskCopy> = {
     overflowNote: "_Choices 11 and up have no reaction — answer them with a reply._",
     otherThread: `${ASK_MARKER_PREFIX}Other — reply in the thread`,
     otherHere: `${ASK_MARKER_PREFIX}Other — reply to this message`,
+    explainLine: `${ASK_EXPLAIN_PREFIX}Explain — press to ask the asker for more detail (not an answer)`,
+    explainNote: `${ASK_EXPLAIN_PREFIX}Explanation requested — it will follow in this thread. The question stays open; answer it after that.`,
     invalidPrefix: "_:warning: Several choices are selected, so this is not counted as an answer — keep only one: ",
     answeredVia: (how, who) => `_Answered by ${how}${who ? ` (${who})` : ""}_`,
     howReaction: (glyph) => `reaction ${glyph}`,
@@ -185,6 +206,22 @@ function askIsOtherLine(line: string | undefined): boolean {
   return line !== undefined && (line.startsWith(ASK_MARKER_PREFIX) || line.startsWith("❓ "));
 }
 
+/** True for the explain line, in either spelling. Matched by prefix, like the
+ *  other line — used where position alone identifies it (under ❓). */
+function askIsExplainLine(line: string | undefined): boolean {
+  return line !== undefined && (line.startsWith(ASK_EXPLAIN_PREFIX) || line.startsWith("ℹ️ "));
+}
+
+/** True only for this language's explain line AS WRITTEN (either spelling of
+ *  the marker). For a free-text question, where nothing but position separates
+ *  the explain line from the body above it: a body whose own last line starts
+ *  with ℹ️ must not be read as the pill, so the copy has to match exactly. */
+function askIsExplainCopy(line: string | undefined, c: AskCopy): boolean {
+  if (line === undefined) return false;
+  const norm = line.startsWith("ℹ️ ") ? ASK_EXPLAIN_PREFIX + line.slice("ℹ️ ".length) : line;
+  return norm === c.explainLine;
+}
+
 // The invalid-ballot notice, shared by `ask` and `poll` and written INTO the
 // message rather than only onto the collector's terminal. The person who has to
 // fix it is the voter, and the voter is in Slack — a warning that only the
@@ -228,6 +265,14 @@ export function applyInvalidNotice(text: string, invalid: string[], lang: AskLan
   return out === text ? text : out;
 }
 
+/** True for the thread note `--wait`/`--waitFor` posts when ℹ️ is pressed, in
+ *  either language. Our own bookkeeping: never an answer, never a note — even
+ *  when the identity that posted it is in the audience (an @here question
+ *  collected with another token). */
+export function askIsExplainNote(text: unknown): boolean {
+  return typeof text === "string" && ASK_LANGS.some((l) => ASK_COPY[l].explainNote === text.trim());
+}
+
 /** True if this line is the notice — parsers skip it when walking up. */
 export function isInvalidNotice(line: string | undefined): boolean {
   return invalidLang(line) !== null;
@@ -293,7 +338,7 @@ export function askFlatten(s: string): string {
 /** Question body: the prompt, the numbered choices matching the seeded pills,
  *  and an instruction naming the answer paths this command actually reads.
  *  `askParseMessage` is its inverse — keep the two in step. */
-export function askBuildText(question: string, body: string, reactable: string[], overflow: string[], threadOnly: boolean, lang: AskLang = "ja"): string {
+export function askBuildText(question: string, body: string, reactable: string[], overflow: string[], threadOnly: boolean, lang: AskLang = "ja", explain = false): string {
   const c = ASK_COPY[lang];
   const lines: string[] = [`${ASK_MARKER_PREFIX}*${question}*`];
   if (body) lines.push("", body);
@@ -309,6 +354,8 @@ export function askBuildText(question: string, body: string, reactable: string[]
     lines.push(...reactable.map((s, i) => `${askPill(i)} ${askFlatten(s)}`));
     // Directly under the pills, matching the ❓ seeded right after them.
     lines.push(threadOnly ? c.otherThread : c.otherHere);
+    // Under ❓, matching the ℹ️ seeded right after it.
+    if (explain) lines.push(c.explainLine);
     if (overflow.length) {
       lines.push("");
       lines.push(...overflow.map((s, i) => `(${i + 11}) ${askFlatten(s)}`));
@@ -321,6 +368,7 @@ export function askBuildText(question: string, body: string, reactable: string[]
     lines.push(threadOnly ? c.instructionReactionThread : c.instructionReactionHere);
   } else {
     lines.push("");
+    if (explain) lines.push(c.explainLine, "");
     lines.push(threadOnly ? c.instructionTextThread : c.instructionTextHere);
   }
   return lines.join("\n");
@@ -405,7 +453,7 @@ export function askSalvageUnreadable(text: string): { question: string; body: st
     for (const instr of [c.instructionReactionThread, c.instructionReactionHere, c.instructionTextThread, c.instructionTextHere]) {
       if (body.includes(instr)) wasAsk = true;
     }
-    for (const fixed of [c.instructionReactionThread, c.instructionReactionHere, c.instructionTextThread, c.instructionTextHere, c.overflowNote, c.otherThread, c.otherHere]) {
+    for (const fixed of [c.instructionReactionThread, c.instructionReactionHere, c.instructionTextThread, c.instructionTextHere, c.overflowNote, c.otherThread, c.otherHere, c.explainLine]) {
       body = body.split(fixed).join(" ");
     }
     const at = body.indexOf(c.invalidPrefix);
@@ -454,7 +502,8 @@ function askDecodeEntities(s: string): string {
 }
 
 export type AskParsed =
-  | { kind: "open"; question: string; body: string; reactable: string[]; overflow: string[]; threadOnly: boolean; lang: AskLang }
+  /** `explain`: the body offers the ℹ️ explain pill (`--explain`). */
+  | { kind: "open"; question: string; body: string; reactable: string[]; overflow: string[]; threadOnly: boolean; lang: AskLang; explain: boolean }
   | { kind: "resolved"; question: string; answer: string }
   /** Voided (無効化). `reason` is the stamp line as written; `supersededBy` the
    *  replacement's link when one was given. */
@@ -594,6 +643,7 @@ export function askParseMessage(text: string): AskParsed {
   // there is the body — kept by the ✅ rewrite.
   let bodyEnd = lines.length - 1;
   if (isInvalidNotice(lines[bodyEnd - 1])) bodyEnd--;
+  let explain = false;
   if (hasChoices) {
     // Walk UP from the instruction line rather than down from the question. The
     // choice block is anchored to the bottom of the body, and scanning downward
@@ -609,6 +659,7 @@ export function askParseMessage(text: string): AskParsed {
       if (lines[i] !== "") return { kind: "other" };
       i--;
     }
+    if (askIsExplainLine(lines[i])) { explain = true; i--; }
     if (askIsOtherLine(lines[i])) i--;
     const raw: string[] = [];
     while (i >= 0) {
@@ -634,10 +685,16 @@ export function askParseMessage(text: string): AskParsed {
     for (let n = 0; n < overflow.length; n++) {
       if (!lines.includes(`(${n + 11}) ${overflow[n]}`)) return { kind: "other" };
     }
+  } else if (lines[bodyEnd - 1] === "" && askIsExplainCopy(lines[bodyEnd - 2], c) && lines[bodyEnd - 3] === "" && bodyEnd - 3 >= end) {
+    // A free-text question's explain line: blank, the line, blank, instruction
+    // — and the line is our copy verbatim. A body that merely ENDS on a line
+    // starting with ℹ️ (a question built without --explain) stays body.
+    explain = true;
+    bodyEnd -= 2;
   }
 
   const body = lines.slice(end + 1, bodyEnd).join("\n").replace(/^\n+|\n+$/g, "");
-  return { kind: "open", question, body, reactable, overflow, threadOnly, lang };
+  return { kind: "open", question, body, reactable, overflow, threadOnly, lang, explain };
 }
 
 /** Did a free-text reply actually PICK one of the offered choices?

package/ts/cli.ts

@@ -20,9 +20,11 @@ import { agentCommands } from "./agent.ts";
 import {
   ASK_KEYCAPS,
   ASK_MARKER,
+  ASK_EXPLAIN_MARKER,
   ASK_RESOLVED_MARKER,
   ASK_MAX_REACTION_CHOICES,
   askBuildText,
+  askIsExplainNote,
   askBuildResolvedText,
   askParseMessage,
   askExplainReject,
@@ -93,6 +95,7 @@ import {
   openDm,
   parseSlackPermalink,
   replies,
+  repliesPage,
   resolveChannel,
   resolveUserId,
   search,
@@ -2457,6 +2460,8 @@ async function cmdSend(token: string, args: SendArgs): Promise<void> {
 //      pressed later still settles it (`--waitFor … --after=<reply ts>`).
 //   6  the question was VOIDED (無効化, `slack ask --void`) — it will never be
 //      answered; stop waiting. stdout stays empty.
+//   7  only with --explain-exit: someone pressed ℹ️ (explain) — the question is
+//      STILL OPEN; explain in its thread, then collect again. stdout stays empty.
 // Everything human-facing goes to stderr, so `ANS=$(slack ask ... --wait)` is safe.
 
 const ASK_EXIT_TIMEOUT = 2;
@@ -2476,6 +2481,20 @@ const ASK_EXIT_FREETEXT = 5;
  *  Neither "open" nor "answered": a monitor that kept waiting on it would wait
  *  forever, and one that read it as answered would act on nothing. */
 const ASK_EXIT_VOID = 6;
+/** `--explain-exit` only: an audience member pressed ℹ️ and asked for an
+ *  explanation. Not an answer and not a state of the question — it stays open —
+ *  but a caller parked on `--waitFor` cannot explain anything until it hears.
+ *  Opt-in, so no existing caller meets a code it does not know. */
+const ASK_EXIT_EXPLAIN = 7;
+/** How many 200-reply pages the explain-note lookup reads before giving up. */
+const ASK_EXPLAIN_NOTE_MAX_PAGES = 10;
+
+/** Whether a new question offers the ℹ️ explain pill when neither --explain nor
+ *  --no-explain is given: `SLACK_TERM_ASK_EXPLAIN=1` turns it on for every ask
+ *  from a fleet, without every caller having to remember the flag. */
+function askExplainDefault(): boolean {
+  return /^(1|true|yes|on)$/i.test(process.env.SLACK_TERM_ASK_EXPLAIN ?? "");
+}
 
 const ASK_PHI = 1.618033988749895;
 const ASK_POLL_MIN_MS = 1000;
@@ -2500,6 +2519,10 @@ interface AskArgs {
   userId?: string;
   asBot?: boolean;
   wait?: boolean;
+  /** `--explain`: offer the ℹ️ pill — "explain this first", never an answer. */
+  explain?: boolean;
+  /** `--explain-exit` with `--wait`: exit 7 when an explanation is requested. */
+  explainExit?: boolean;
   /** `--json` with `--wait`: one JSON object on stdout (answer, notes, cursor). */
   json?: boolean;
   timeout?: number;
@@ -2614,6 +2637,11 @@ interface AskWaitCtx {
   /** `--json`: stdout is one JSON object (answer + notes + cursor) instead of
    *  the bare answer. Exit codes are the same either way. */
   json: boolean;
+  /** `--explain-exit`: stop with exit 7 the first time an explanation is
+   *  requested (the run that posts the thread note), instead of waiting on. */
+  explainExit?: boolean;
+  /** The question offers the ℹ️ pill — so the ✅ rewrite takes our seed off. */
+  explain?: boolean;
 }
 
 /** A reply from the question's audience that is NOT the answer — an extra
@@ -2682,7 +2710,7 @@ async function askCollectNotes(token: string, sc: AskNoteScope, after: string |
     // integration's) is excluded here, so nothing echoes back as a "note".
     .filter((m) => sc.isAnswerer(m.user) && !m.bot_id)
     .filter((m) => typeof m.subtype !== "string" || ASK_ANSWERABLE_SUBTYPES.has(m.subtype))
-    .filter((m) => typeof m.text === "string" && m.text.trim() !== "")
+    .filter((m) => typeof m.text === "string" && m.text.trim() !== "" && !askIsExplainNote(m.text))
     // Sorted BEFORE `skip`, which may be stateful ("the first reply that …").
     .sort((a, b) => Number(a.ts) - Number(b.ts))
     .filter((m) => !skip(m));
@@ -2712,12 +2740,15 @@ function askNextCursor(...tss: (string | undefined)[]): string {
 async function askEmit(
   token: string,
   o: { json: boolean; shown: string; asBot: boolean; cookie?: string | undefined },
-  r: { status: "answered" | "freetext" | "ambiguous" | "timeout" | "void"; answer: string | null; how?: string; who?: string; reason?: string; supersededBy?: string; notes: AskNote[]; cursor: string },
+  r: { status: "answered" | "freetext" | "ambiguous" | "timeout" | "void" | "explain"; answer: string | null; how?: string; who?: string; reason?: string; supersededBy?: string; notes: AskNote[]; cursor: string; explain?: string[] },
 ): Promise<void> {
   if (o.json) {
     console.log(JSON.stringify({
       status: r.status, answer: r.answer, how: r.how ?? null, who: r.who ?? null,
       ...(r.status === "void" ? { reason: r.reason ?? "", supersededBy: r.supersededBy ?? null } : {}),
+      // Who is asking for an explanation right now. Only when someone is, so
+      // the object every existing caller reads is unchanged otherwise.
+      ...(r.explain?.length ? { explain: r.explain } : {}),
       notes: r.notes, cursor: r.cursor, permalink: o.shown,
     }));
     return;
@@ -2754,6 +2785,13 @@ interface AskPollState {
   replyCount?: number;
   /** The question's text as last read — what the ✅ rewrite keeps the body of. */
   ownText?: string;
+  /** Who is on ℹ️ (explain) right now — audience only, never a bot, never the
+   *  asker. Recomputed every pass, so a press taken back stops counting. Only
+   *  on a question that offers ℹ️ (`ctx.explain`). */
+  explainNow: string[];
+  /** THIS run posted the explain thread note — the one run `--explain-exit`
+   *  stops on. Never set read-only (`--pending` posts nothing). */
+  explainPosted: boolean;
 }
 
 /** The polling half of `--wait`: one `poll()` is one look at the question,
@@ -2769,7 +2807,7 @@ function askPoller(token: string, ctx: AskWaitCtx, readOnly = false): {
 } {
   const { channelId, ts, reactable, threadOnly, audience, broadcast, cookie } = ctx;
   const copy = ASK_COPY[ctx.lang];
-  const state: AskPollState = {};
+  const state: AskPollState = { explainNow: [], explainPosted: false };
   const askerUserId = ctx.askerUserId;
   const askerBotId = ctx.askerBotId;
 
@@ -2845,7 +2883,93 @@ function askPoller(token: string, ctx: AskWaitCtx, readOnly = false): {
     }
   }
 
+  const explainReported = new Set<string>();
+  const botCache = new Map<string, boolean>();
+  /** The thread note is settled for this run (found already there, or posted). */
+  let explainNoted = false;
+  /** Null when it cannot be told — not cached, so the next pass asks again.
+   *  Until then the press does not count: a bot must never post the note or
+   *  wake an --explain-exit caller, and a person is only delayed a tick. */
+  async function isBotUser(u: string): Promise<boolean | null> {
+    if (u === "USLACKBOT") return true;
+    const hit = botCache.get(u);
+    if (hit !== undefined) return hit;
+    try {
+      // A reply with no boolean is_bot tells us nothing — unknown, not human.
+      const bot = asRecord(asRecord((await userInfo(token, u, cookie)) as Json).user).is_bot;
+      if (typeof bot !== "boolean") return null;
+      botCache.set(u, bot);
+      return bot;
+    } catch {
+      return null;
+    }
+  }
+  /** One thread note per QUESTION, however many presses and runs: the thread
+   *  itself is the record, so there is no local state to lose. The note is
+   *  recognised by its exact copy (either language), whoever posted it — the
+   *  identity that collects now need not be the one that collected before, and
+   *  under @here it may even be in the audience.
+   *
+   *  The whole thread after the question is read (paged), not one page: a
+   *  question posted into a long thread may have more than a page before its
+   *  note. Past the page cap it is not posted at all ("exists") rather than
+   *  risk a duplicate.
+   *
+   *  "unread": the thread could not be read — nothing is posted, and the next
+   *  pass tries again rather than risk a duplicate. "failed": the post itself
+   *  failed — not retried this run (no error every tick) and NOT a reason for
+   *  --explain-exit, which promises a note is up; the next run tries again. */
+  async function postExplainNote(): Promise<"exists" | "posted" | "unread" | "failed"> {
+    const root = ctx.threadParentTs ?? ts;
+    try {
+      let cursor: string | undefined;
+      let pages = 0;
+      for (;;) {
+        const rep = asRecord((await repliesPage(token, channelId, root, { oldest: ts, ...(cursor ? { cursor } : {}) }, cookie)) as Json);
+        if (asArray(rep.messages).map(asRecord).some((m) => Number(m.ts) > Number(ts) && askIsExplainNote(m.text))) return "exists";
+        cursor = String(asRecord(rep.response_metadata).next_cursor ?? "") || undefined;
+        if (!cursor) break;
+        if (++pages >= ASK_EXPLAIN_NOTE_MAX_PAGES) return "exists";
+      }
+    } catch (e: unknown) {
+      console.error(`  (スレッドを読めないため、説明リクエストの案内はまだ出していません: ${e instanceof Error ? e.message : String(e)})`);
+      return "unread";
+    }
+    try {
+      await slackSend(token, channelId, copy.explainNote, root, false, cookie, true);
+    } catch (e: unknown) {
+      // The press is still reported on stderr; the note is a courtesy.
+      console.error(`  (説明リクエストの案内をスレッドに出せませんでした: ${e instanceof Error ? e.message : String(e)})`);
+      return "failed";
+    }
+    return "posted";
+  }
+  async function noteExplain(msg: Record<string, Json>): Promise<void> {
+    const r = asArray(msg.reactions).map(asRecord).find((x) => x.name === ASK_EXPLAIN_MARKER);
+    const now: string[] = [];
+    for (const u of r ? asArray(r.users).filter(isAnswerer) : []) {
+      if ((await isBotUser(u)) !== false) continue;
+      now.push(u);
+      if (explainReported.has(u)) continue;
+      explainReported.add(u);
+      if (!readOnly) console.error(`  (<@${u}> が ℹ️ 説明して を押しました — 回答ではありません。スレッドで説明してください。回答は待ち続けます)`);
+    }
+    state.explainNow = now;
+    // Read-only (`--pending`): the press is reported, the note is not posted —
+    // that is the waiting session's to do.
+    if (now.length && !explainNoted && !readOnly) {
+      const r = await postExplainNote();
+      if (r !== "unread") {
+        explainNoted = true;
+        state.explainPosted = r === "posted";
+      }
+    }
+  }
+
   async function answerFromReactions(msg: Record<string, Json>): Promise<AskFound | null> {
+    // Only a question that offers ℹ️ treats it as a request — on any other,
+    // ℹ️ is just an emoji somebody added.
+    if (ctx.explain) await noteExplain(msg);
     if (reactable.length) noteOther(msg);
     const picks = humanChoices(msg);
     // Nothing ambiguous any more — take the notice back down if one is up.
@@ -2895,7 +3019,9 @@ function askPoller(token: string, ctx: AskWaitCtx, readOnly = false): {
       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) continue;
+      // Our ℹ️ note is bookkeeping — only on a question that offers ℹ️, so an
+      // older question's reply is never second-guessed.
+      if (!t || (ctx.explain && askIsExplainNote(t))) continue;
       // A question asked WITHOUT choices is answered by whatever comes back —
       // there is nothing to match against, and every reply is the answer.
       if (!candidates.length) return { answer: t, how: copy.howReply, who: m.user, ts: String(m.ts) };
@@ -3041,6 +3167,12 @@ async function askWaitForAnswer(token: string, ctx: AskWaitCtx): Promise<never>
       } catch {
         // Cosmetic: the ✅ in the body is what actually marks it resolved.
       }
+      try {
+        // Asking for an explanation is over once it is answered.
+        if (ctx.explain) await reactionRemove(token, channelId, ts, ASK_EXPLAIN_MARKER, cookie);
+      } catch {
+        // Cosmetic: the ✅ in the body is what actually marks it resolved.
+      }
     } 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
@@ -3102,6 +3234,15 @@ async function askWaitForAnswer(token: string, ctx: AskWaitCtx): Promise<never>
       await askEmit(token, ctx, r);
       process.exit(0);
     }
+    // ℹ️ is never an answer: the question stays open, ✅ is not written, the
+    // seeds stay. Only a caller that asked to hear about it stops here — and
+    // only on the run that posted the thread note, so a `--timeout 0` poller is
+    // woken once per question, not on every look.
+    if (state.explainPosted && ctx.explainExit) {
+      console.error(`  説明を求められています (質問はまだ開いています)。スレッドで説明してから回収する:  ${askResumeCommand(shown, ctx.asBot, ctx.after)}`);
+      if (ctx.json) await askEmit(token, ctx, { status: "explain", answer: null, notes: [], cursor: askNextCursor(ts, ctx.after), explain: state.explainNow });
+      process.exit(ASK_EXIT_EXPLAIN);
+    }
     // A free-text reply that picks nothing is delivered NOW, not held until the
     // deadline: it is usually an instruction or a question back, and the only
     // one who can act on it is the caller. Left unstamped — a pill pressed
@@ -3122,7 +3263,7 @@ async function askWaitForAnswer(token: string, ctx: AskWaitCtx): Promise<never>
       // but still reports a pill pressed after it.
       markAskDelivered(channelId, ts, unchosen.text, askNextCursor(ts, ctx.after, unchosen.ts));
       if (ctx.json) {
-        await askEmit(token, ctx, { status: "freetext", answer: unchosen.text, who: unchosen.who, notes: [], cursor: askNextCursor(ts, ctx.after, unchosen.ts) });
+        await askEmit(token, ctx, { status: "freetext", answer: unchosen.text, who: unchosen.who, notes: [], cursor: askNextCursor(ts, ctx.after, unchosen.ts), explain: state.explainNow });
       } else {
         console.log(unchosen.text);
       }
@@ -3167,7 +3308,7 @@ async function askWaitForAnswer(token: string, ctx: AskWaitCtx): Promise<never>
     console.error(`  選択肢: ${candidates.map((c, i) => `${i + 1}. ${stripTerminalControls(askFlatten(c))}`).join("  ")}`);
     console.error(`  ${shown}`);
     console.error(`  返答してから回収する:  ${askResumeCommand(shown, ctx.asBot, ctx.after)}`);
-    if (ctx.json) await askEmit(token, ctx, { status: "ambiguous", answer: null, notes: [], cursor: askNextCursor(ts, ctx.after) });
+    if (ctx.json) await askEmit(token, ctx, { status: "ambiguous", answer: null, notes: [], cursor: askNextCursor(ts, ctx.after), explain: state.explainNow });
     process.exit(ASK_EXIT_UNCHOSEN);
   }
   if (timeout === 0) {
@@ -3177,7 +3318,7 @@ async function askWaitForAnswer(token: string, ctx: AskWaitCtx): Promise<never>
     console.error(`  ${shown}`);
     console.error(`  あとで回収する:  ${askResumeCommand(shown, ctx.asBot, ctx.after)}`);
   }
-  if (ctx.json) await askEmit(token, ctx, { status: "timeout", answer: null, notes: [], cursor: askNextCursor(ts, ctx.after) });
+  if (ctx.json) await askEmit(token, ctx, { status: "timeout", answer: null, notes: [], cursor: askNextCursor(ts, ctx.after), explain: state.explainNow });
   process.exit(ASK_EXIT_TIMEOUT);
 }
 
@@ -3306,7 +3447,8 @@ async function cmdAsk(token: string, args: AskArgs): Promise<void> {
     process.exit(ASK_EXIT_ERROR);
   }
   const lang = picked.lang;
-  const message = askBuildText(question, body, reactable, overflow, threadOnly, lang);
+  const explain = args.explain ?? askExplainDefault();
+  const message = askBuildText(question, body, reactable, overflow, threadOnly, lang, explain);
   guardUrlBoundaries(message, args.allowUrlAdjacent);
 
   // Preview the destination's last message, exactly as `send` does — the gate's
@@ -3357,6 +3499,7 @@ async function cmdAsk(token: string, args: AskArgs): Promise<void> {
       // 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"}`,
+      ...(explain ? [`  Explain:  ℹ️ pill offered — pressing it asks you to explain; it is never an answer`] : []),
       ...(args.voidAfter ? [`  Then 無効化: ${stripTerminalControls(args.voidAfter.link)} (reason: ${stripTerminalControls(args.voidAfter.reason || "none")}) — replaced by this question`] : []),
       `  Language: ${lang} (${({ flag: "--lang", env: "SLACK_TERM_LANG", readers: "answerers' Slack locale", content: "the question's text", system: "system locale", default: "default" })[picked.source]}; override with --lang)`,
       `--------------------------------────────────`,
@@ -3385,7 +3528,7 @@ async function cmdAsk(token: string, args: AskArgs): Promise<void> {
   // `two|one|question|three`. See ts/reactionSeed.ts for the evidence and for
   // SLACK_REACTION_SEED_GAP_MS.
   await seedReactionsInOrder(
-    [...reactable.map((_, i) => ASK_KEYCAPS[i]!.name), ASK_MARKER],
+    [...reactable.map((_, i) => ASK_KEYCAPS[i]!.name), ASK_MARKER, ...(explain ? [ASK_EXPLAIN_MARKER] : [])],
     (name) => reactionAdd(token, channelId, ts, name, cookie),
     (name, e) => {
       const why = e instanceof Error ? e.message : String(e);
@@ -3441,6 +3584,8 @@ async function cmdAsk(token: string, args: AskArgs): Promise<void> {
     shown,
     asBot: !!args.asBot,
     json: !!args.json,
+    explain,
+    explainExit: !!args.explainExit,
   };
   if (threadTs) ctx.threadParentTs = threadTs;
   if (cookie) ctx.cookie = cookie;
@@ -3600,7 +3745,7 @@ async function cmdAskEdit(token: string, args: {
   const reactable = choices.slice(0, ASK_MAX_REACTION_CHOICES);
   const overflow = choices.slice(ASK_MAX_REACTION_CHOICES);
   const oldText = typeof t.msg.text === "string" ? t.msg.text : "";
-  let next = askBuildText(question, body, reactable, overflow, old.threadOnly, lang);
+  let next = askBuildText(question, body, reactable, overflow, old.threadOnly, lang, old.explain);
   // An invalid-ballot notice still in force stays (it names the people who
   // have to fix their vote); it is only possible when the options did not change.
   const invalid = readInvalidNotice(oldText);
@@ -3635,11 +3780,12 @@ async function cmdAskEdit(token: string, args: {
   await editMessage(token, t.channelId, t.ts, next, args.cookie, true);
   if (choicesChanged) {
     // Re-seed in order: 1..n then ❓ last, as a fresh question has them.
-    for (const name of [...old.reactable.map((_, i) => ASK_KEYCAPS[i]!.name), ASK_MARKER]) {
+    const tail = old.explain ? [ASK_MARKER, ASK_EXPLAIN_MARKER] : [ASK_MARKER];
+    for (const name of [...old.reactable.map((_, i) => ASK_KEYCAPS[i]!.name), ...tail]) {
       try { await reactionRemove(token, t.channelId, t.ts, name, args.cookie); } catch { /* already gone */ }
     }
     await seedReactionsInOrder(
-      [...reactable.map((_, i) => ASK_KEYCAPS[i]!.name), ASK_MARKER],
+      [...reactable.map((_, i) => ASK_KEYCAPS[i]!.name), ...tail],
       (name) => reactionAdd(token, t.channelId, t.ts, name, args.cookie),
       (name, e) => console.error(`  (リアクション ${name} を付けられませんでした: ${e instanceof Error ? e.message : String(e)})`),
     );
@@ -3765,7 +3911,10 @@ async function cmdAskPending(
   }
   const rows = opts.channel ? all.filter((r) => r.channel === opts.channel || r.target === opts.channel) : all;
   const pending: AskPendingItem[] = [];
-  const count = { unanswered: 0, ambiguous: 0, resolved: 0, void: 0 };
+  const count = { unanswered: 0, ambiguous: 0, resolved: 0, void: 0, explain: 0 };
+  /** Open questions someone pressed ℹ️ on — reported only: the thread note is
+   *  the waiting session's to post (`--pending` writes nothing). */
+  const explainAsked: string[] = [];
   const problems: string[] = [];
   // The log is machine-wide, but a token reads one workspace. Asks recorded
   // under another workspace are counted and named, not probed with the wrong
@@ -3810,6 +3959,10 @@ async function cmdAskPending(
       const unchosen = poller.state.unchosen;
       if (poller.state.voided) { count.void++; continue; }
       const collect = askResumeCommand(link, asBot, after);
+      if (poller.state.explainNow.length) {
+        count.explain++;
+        explainAsked.push(`${link}: ℹ️ 説明を求められています (${poller.state.explainNow.map((u) => `<@${u}>`).join(" ")}) — スレッドで説明してください`);
+      }
       const base = { row, link, question: parsed.question, collect, alive: senderAlive(row) };
       if (found) {
         pending.push({ ...base, answer: found.answer, how: found.how, freeText: false });
@@ -3858,6 +4011,7 @@ async function cmdAskPending(
     }
   }
   for (const p of problems) console.error(`  (${stripTerminalControls(p)})`);
+  for (const p of explainAsked) console.error(`  (${stripTerminalControls(p)})`);
   for (const [team, n] of otherTeams) {
     console.error(`  (${n} 件は別のワークスペース「${stripTerminalControls(team)}」の質問です — slack -w <name> ask --pending で確認)`);
   }
@@ -3866,6 +4020,7 @@ async function cmdAskPending(
     (count.ambiguous ? `, ${count.ambiguous} 件は返信が複数の選択肢に一致 (未確定)` : "") +
     (count.resolved ? `, ${count.resolved} 件は ✅ 回収済み` : "") +
     (count.void ? `, ${count.void} 件は無効化済み` : "") +
+    (count.explain ? `, ${count.explain} 件は ℹ️ 説明のリクエストあり` : "") +
     ` — ${rows.length} 件の未回収の質問を確認 (log: ${sentDbPath()})`,
   );
 }
@@ -3890,7 +4045,7 @@ async function askApplyVoid(token: string, t: AskVoidTarget, reason: string, sup
     console.error(`✗ ${shown}: 書き換えに失敗しました: ${e instanceof Error ? e.message : String(e)}`);
     return false;
   }
-  for (const name of [...t.parsed.reactable.map((_, i) => ASK_KEYCAPS[i]!.name), ASK_MARKER]) {
+  for (const name of [...t.parsed.reactable.map((_, i) => ASK_KEYCAPS[i]!.name), ASK_MARKER, ...(t.parsed.explain ? [ASK_EXPLAIN_MARKER] : [])]) {
     try { await reactionRemove(token, t.channelId, t.ts, name, cookie); } catch { /* not ours / already gone */ }
   }
   try {
@@ -3984,6 +4139,8 @@ async function cmdAskVoid(token: string, args: { links: string[]; reason: string
         // Placeholders: only the COUNT is used — which of our keycap seeds to take off.
         reactable: Array.from({ length: seeded.length ? Math.max(...seeded) + 1 : 0 }, () => ""),
         overflow: [], threadOnly: true, lang: askDetectLang(text) ?? "ja",
+        // Our ℹ️ seed comes off too, if we put one on.
+        explain: asArray(msg.reactions).map(asRecord).some((r) => r.name === ASK_EXPLAIN_MARKER && asArray(r.users).includes(self?.userId ?? "\u0000")),
       };
       unreadable = true;
     }
@@ -4030,7 +4187,7 @@ async function cmdAskVoid(token: string, args: { links: string[]; reason: string
  *  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; json: boolean; cookie?: string; after?: string }): Promise<void> {
+async function cmdAskWaitFor(token: string, args: { link: string; timeout: number; asBot: boolean; json: boolean; cookie?: string; after?: string; explainExit?: boolean }): Promise<void> {
   const url = parseSlackPermalink(args.link);
   let channelId: string;
   let ts: string;
@@ -4184,7 +4341,7 @@ function askWaitCtxFrom(
   q: AskReadBack,
   parsed: Extract<AskReadBack["parsed"], { kind: "open" }>,
   loc: { channelId: string; ts: string; threadTs?: string | undefined },
-  o: { timeout: number; link: string; asBot: boolean; json: boolean; cookie?: string | undefined; after?: string | undefined },
+  o: { timeout: number; link: string; asBot: boolean; json: boolean; cookie?: string | undefined; after?: string | undefined; explainExit?: boolean | undefined },
 ): AskWaitCtx {
   const ctx: AskWaitCtx = {
     channelId: loc.channelId,
@@ -4202,6 +4359,8 @@ function askWaitCtxFrom(
     shown: o.link,
     asBot: o.asBot,
     json: o.json,
+    explain: parsed.explain,
+    explainExit: !!o.explainExit,
   };
   if (loc.threadTs) ctx.threadParentTs = loc.threadTs;
   if (o.cookie) ctx.cookie = o.cookie;
@@ -5745,8 +5904,8 @@ async function main(): Promise<void> {
         .option("allow-url-adjacent", { type: "boolean", default: false, describe: "Warn instead of refusing ambiguous bare URL boundaries" })
         .option("body", { type: "string", describe: "Extra context shown under the question" })
         .option("lang", { type: "string", choices: [...ASK_LANGS], describe: "Language of the instructions in the posted body. Default: $SLACK_TERM_LANG, else the answerers' Slack locale, else the question's own language, else the system locale, else ja" })
-        .option("wait", { type: "boolean", default: false, describe: "Block until answered; print ONLY the answer on stdout. Exit 0 = answered, 2 = nobody replied, 3 = transport failure, 4 = a reply matched several choices (stdout empty), 5 = a free-text reply that picked none of the choices (the reply is on stdout; NOT a decision — the question stays open), 6 = the question was voided (無効化, `slack ask void`) — stop waiting." })
-        .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("wait", { type: "boolean", default: false, describe: "Block until answered; print ONLY the answer on stdout. Exit 0 = answered, 2 = nobody replied, 3 = transport failure, 4 = a reply matched several choices (stdout empty), 5 = a free-text reply that picked none of the choices (the reply is on stdout; NOT a decision — the question stays open), 6 = the question was voided (無効化, `slack ask void`) — stop waiting. 7 = only with --explain-exit: ℹ️ pressed, explain and collect again (the question stays open)." })
+        .option("waitFor", { type: "string", describe: "Collect the answer to a question already posted: pass its permalink. Nothing is posted (except, on an --explain question someone pressed ℹ️ on, one thread note per question). Same stdout/exit contract as --wait; --timeout 0 checks once and exits 2 if still open." })
         .option("after", { type: "string", describe: "With --waitFor: the cursor — everything at or before this ts was already delivered. Text replies there are neither answers nor notes again (pass the `cursor` a previous --json result gave you, or the reply ts an exit 5 printed). Reactions still count." })
         .option("void", { type: "string", array: true, describe: "無効化: void question(s) you posted that expired or stopped meaning anything — --void=<permalink>, repeatable. The text becomes 🚫 with --reason (body kept, options removed), our pills come off, and --wait/--waitFor on it exits 6. Same --code gate. Only your own questions (--as-bot for the bot's). Alias: `slack ask void <link…>`." })
         .option("reask", { type: "boolean", default: false, describe: "With ONE --void: post the question again (same channel/thread, same text and choices unless you give new ones as positionals / --body) and void the old one as replaced by it — one gate for both. The way to change the options of a question someone already answered." })
@@ -5760,6 +5919,8 @@ async function main(): Promise<void> {
         .option("limit", { type: "number", default: 50, describe: "With --ls: how many recent asks to check" })
         .option("reason", { type: "string", describe: "With --void: why it is void (written into the message)" })
         .option("superseded-by", { type: "string", describe: "With --void: permalink of the question that replaces it" })
+        .option("explain", { type: "boolean", describe: "Also offer an ℹ️ 'explain' pill (seeded after ❓): pressing it asks YOU to explain the question in its thread and is never an answer — the question stays open. --wait/--waitFor report it on stderr (and as `explain` in --json), and post one thread note per question. Default: $SLACK_TERM_ASK_EXPLAIN=1 turns it on; --no-explain turns it off." })
+        .option("explain-exit", { type: "boolean", default: false, describe: "With --wait / --waitFor: exit 7 (stdout empty; --json status \"explain\") when someone presses ℹ️ — once per question, on the run that posts the thread note. The question stays open: explain, then collect again." })
         .option("json", { type: "boolean", default: false, describe: "With --pending: one JSON object per answered question (sender, answer, collect command). With --wait / --waitFor: print ONE JSON object on stdout — {status, answer, how, who, notes:[{ts,user,text,permalink}], cursor, permalink} — instead of the bare answer. `notes` are the audience's replies that are not the answer (thread replies; plain replies too in a 1:1 DM). Exit codes unchanged." })
         .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" })
@@ -5884,6 +6045,8 @@ async function main(): Promise<void> {
           argv.choices = newChoices.length ? newChoices : [...t.parsed.reactable, ...t.parsed.overflow].map(escapeArg);
           if (argv.body === undefined && t.parsed.body) argv.body = escapeArg(t.parsed.body);
           if (!argv.lang) argv.lang = t.parsed.lang;
+          // A re-ask offers what the old question offered, unless told otherwise.
+          if (argv.explain === undefined && t.parsed.explain) argv.explain = true;
           argv.void = undefined;
         }
         if (!voidAfter && (argv.target === "void" || voidFlag.length)) {
@@ -5973,7 +6136,8 @@ async function main(): Promise<void> {
             waitCookie = ck(argv as W);
           }
           try {
-            const a: { link: string; timeout: number; asBot: boolean; json: boolean; cookie?: string; after?: string } = { link: waitFor, timeout, asBot: !!argv["as-bot"], json: !!argv.json };
+            const a: { link: string; timeout: number; asBot: boolean; json: boolean; cookie?: string; after?: string; explainExit?: boolean } = { link: waitFor, timeout, asBot: !!argv["as-bot"], json: !!argv.json };
+            if (argv["explain-exit"]) a.explainExit = true;
             if (waitCookie) a.cookie = waitCookie;
             if (argv.after) {
               const after = String(argv.after);
@@ -6011,6 +6175,8 @@ async function main(): Promise<void> {
         if (argv.lang) args.lang = String(argv.lang);
         if (argv.wait) args.wait = true;
         if (argv.json) args.json = true;
+        if (typeof argv.explain === "boolean") args.explain = argv.explain;
+        if (argv["explain-exit"]) args.explainExit = true;
         if (voidAfter) args.voidAfter = voidAfter;
         if (argv["channel-id"]) args.channelId = argv["channel-id"];
         if (argv["user-id"]) args.userId = argv["user-id"];