slack-term 1.43.0 → 1.45.0

package/ts/cli.ts

@@ -20,11 +20,16 @@ import { agentCommands } from "./agent.ts";
 import {
   ASK_KEYCAPS,
   ASK_MARKER,
+  ASK_OTHER_MARKER,
+  ASK_OTHER_MARKERS,
+  ASK_EXPLAIN_MARKER,
   ASK_RESOLVED_MARKER,
   ASK_MAX_REACTION_CHOICES,
   askBuildText,
+  askIsExplainNote,
   askBuildResolvedText,
   askParseMessage,
+  askSeedMarker,
   askExplainReject,
   askFlatten,
   askMatchChoice,
@@ -93,6 +98,7 @@ import {
   openDm,
   parseSlackPermalink,
   replies,
+  repliesPage,
   resolveChannel,
   resolveUserId,
   search,
@@ -2457,6 +2463,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 +2484,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 +2522,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;
@@ -2589,6 +2615,9 @@ interface AskWaitCtx {
    *  nothing". */
   overflow: string[];
   threadOnly: boolean;
+  /** The marker reaction this question was seeded with (➕, or ❓ on a
+   *  free-text question or one posted before ➕) — what the ✅ swap takes off. */
+  seedMarker: string;
   /** The language the question's copy is in — the ✅ stamp and the
    *  invalid-ballot line are written in the same one. */
   lang: AskLang;
@@ -2614,6 +2643,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 +2716,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 +2746,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 +2791,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 +2813,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;
 
@@ -2831,21 +2875,111 @@ function askPoller(token: string, ctx: AskWaitCtx, readOnly = false): {
     }
   }
 
-  /** Who has pressed ❓ ("other"). Not an answer — ❓ carries no text — so it
-   *  never resolves anything; the reply that should follow it does. Reported
-   *  once per person so the operator knows a reply is on its way rather than
-   *  reading the silence as "nobody looked". */
+  /** Who has pressed ➕ ("other") — or ❓, the other pill on questions posted
+   *  before ➕, which is still pressed out of habit. Not an answer — neither
+   *  carries text — so it never resolves anything; the reply that should
+   *  follow it does. Reported once per person so the operator knows a reply is
+   *  on its way rather than reading the silence as "nobody looked". */
   const otherReported = new Set<string>();
   function noteOther(msg: Record<string, Json>): void {
-    const r = asArray(msg.reactions).map(asRecord).find((x) => x.name === ASK_MARKER);
+    for (const r of asArray(msg.reactions).map(asRecord)) {
+      if (typeof r.name !== "string" || !ASK_OTHER_MARKERS.includes(r.name)) continue;
+      const glyph = r.name === ASK_OTHER_MARKER ? "➕" : "❓";
+      for (const u of asArray(r.users).filter(isAnswerer)) {
+        if (otherReported.has(u)) continue;
+        otherReported.add(u);
+        if (!readOnly) console.error(`  (<@${u}> が ${glyph} その他 を押しました。返信を待ちます)`);
+      }
+    }
+  }
+
+  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 (otherReported.has(u)) continue;
-      otherReported.add(u);
-      if (!readOnly) console.error(`  (<@${u}> が ❓ その他 を押しました。返信を待ちます)`);
+      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 +3029,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) };
@@ -3032,12 +3168,18 @@ async function askWaitForAnswer(token: string, ctx: AskWaitCtx): Promise<never>
       const keep = state.ownText ? askResolvedKeep(state.ownText, found.choice) : undefined;
       await editMessage(token, channelId, ts, askBuildResolvedText(question, found, who, ctx.lang, keep), cookie, true);
       // Swap the marker for the resolved one so search reflects reality:
-      // `has::question:` should list what still needs answering, not everything
-      // ever asked. Removal last — a crash between the two leaves the question
+      // `has::question: OR has::heavy_plus_sign:` should list what still needs
+      // answering, not everything ever asked. Removal last — a crash between the two leaves the question
       // findable under BOTH, which is recoverable; the reverse loses it.
       try {
         await reactionAdd(token, channelId, ts, ASK_RESOLVED_MARKER, cookie);
-        await reactionRemove(token, channelId, ts, ASK_MARKER, cookie);
+        await reactionRemove(token, channelId, ts, ctx.seedMarker, cookie);
+      } 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.
       }
@@ -3102,6 +3244,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 +3273,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 +3318,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 +3328,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 +3457,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 +3509,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)`,
       `--------------------------------────────────`,
@@ -3370,10 +3523,12 @@ async function cmdAsk(token: string, args: AskArgs): Promise<void> {
   const ts = await slackSend(token, channelId, message, threadTs, false, cookie, true, attr.metadata);
 
   // The marker goes on LAST, after 1,2,3, because it doubles as the "other"
-  // choice the body lists under the numbered ones (people were already pressing
-  // ❓ for "none of these fit"). It is a reaction so
-  // `has::question:` lists every question the way `has::pushpin:` lists every
-  // todo. Body text cannot do that job: Slack's index splits on punctuation, so
+  // choice the body lists under the numbered ones: ➕ (ASK_OTHER_MARKER). A
+  // free-text question has no other choice and seeds ❓. It is a reaction so
+  // `has::question: OR has::heavy_plus_sign:` lists every open question the
+  // way `has::pushpin:` lists every todo — though ➕ is a common emoji, so that
+  // search can also match unrelated messages (`slack ask --ls` reads the local
+  // sent-log and is unaffected). Body text cannot do that job: Slack's index splits on punctuation, so
   // a `:question:` written in the text is indexed as the word "question" and
   // matches unrelated messages (measured). Only a real reaction is searchable.
   //
@@ -3384,14 +3539,15 @@ async function cmdAsk(token: string, args: AskArgs): Promise<void> {
   // enough: measured on two real questions from the same build, one came back
   // `two|one|question|three`. See ts/reactionSeed.ts for the evidence and for
   // SLACK_REACTION_SEED_GAP_MS.
+  const seedMarker = reactable.length ? ASK_OTHER_MARKER : ASK_MARKER;
   await seedReactionsInOrder(
-    [...reactable.map((_, i) => ASK_KEYCAPS[i]!.name), ASK_MARKER],
+    [...reactable.map((_, i) => ASK_KEYCAPS[i]!.name), seedMarker, ...(explain ? [ASK_EXPLAIN_MARKER] : [])],
     (name) => reactionAdd(token, channelId, ts, name, cookie),
     (name, e) => {
       const why = e instanceof Error ? e.message : String(e);
       // The marker is cosmetic + searchability; a keycap only costs the
       // answerer a trip to the emoji picker. Neither abandons a posted question.
-      if (name === ASK_MARKER) console.error(`  (marker ${name} を付けられませんでした: ${why})`);
+      if (name === seedMarker) console.error(`  (marker ${name} を付けられませんでした: ${why})`);
       else console.error(`  (リアクション ${name} を付けられませんでした: ${why})`);
     },
   );
@@ -3432,6 +3588,7 @@ async function cmdAsk(token: string, args: AskArgs): Promise<void> {
     reactable,
     overflow,
     threadOnly,
+    seedMarker,
     lang,
     audience,
     broadcast,
@@ -3441,6 +3598,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;
@@ -3522,7 +3681,7 @@ async function askLoadOwnOpen(token: string, link: string, self: Self | null, as
   if (parsed.kind === "void") return "void";
   if (parsed.kind === "resolved") { console.error(`✗ ${shown}: 回答済みの質問です（回答: ${stripTerminalControls(parsed.answer.split("\n")[0] ?? "")}）— 変更できません`); return null; }
   if (parsed.kind !== "open") { console.error(`✗ ${shown}: \`slack ask\` の質問として読み取れません — ${askExplainReject(text)}`); return null; }
-  const out: AskVoidTarget & { msg: Record<string, Json>; threadTs?: string } = { link, channelId: got.channelId, ts: got.ts, parsed, msg };
+  const out: AskVoidTarget & { msg: Record<string, Json>; threadTs?: string } = { link, channelId: got.channelId, ts: got.ts, parsed, seedMarker: askSeedMarker(text) ?? ASK_MARKER, msg };
   if (got.threadTs) out.threadTs = got.threadTs;
   return out;
 }
@@ -3550,7 +3709,7 @@ async function askHasResponses(token: string, t: { channelId: string; ts: string
 }
 
 /** `slack ask --edit=<link> ["new question" [choices…]] [--body …]` — change an
- *  open question THROUGH the ask builder, so pills, ❓, the instructions and the
+ *  open question THROUGH the ask builder, so pills, ➕, the instructions and the
  *  body stay in the layout collect reads back (a free-hand `slack edit` is what
  *  this replaces; `edit` now refuses ask messages without --force).
  *
@@ -3600,7 +3759,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);
@@ -3633,16 +3792,32 @@ async function cmdAskEdit(token: string, args: {
   }
 
   await editMessage(token, t.channelId, t.ts, next, args.cookie, true);
+  // The body was rebuilt, so its other line now says ➕ (or there is none, on
+  // a free-text question) — the marker seed follows it.
+  const seedMarker = reactable.length ? ASK_OTHER_MARKER : ASK_MARKER;
+  const oldSeed = askSeedMarker(oldText) ?? ASK_MARKER;
   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]) {
+    // Re-seed in order: 1..n then ➕ last, as a fresh question has them. The
+    // old marker comes off as whatever it was seeded as (❓ on an old pill).
+    const tail = (m: string) => old.explain ? [m, ASK_EXPLAIN_MARKER] : [m];
+    for (const name of [...old.reactable.map((_, i) => ASK_KEYCAPS[i]!.name), ...tail(oldSeed)]) {
       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(seedMarker)],
       (name) => reactionAdd(token, t.channelId, t.ts, name, args.cookie),
       (name, e) => console.error(`  (リアクション ${name} を付けられませんでした: ${e instanceof Error ? e.message : String(e)})`),
     );
+  } else if (oldSeed !== seedMarker) {
+    // An old ❓ pill edited without touching its choices: the body now lists
+    // ➕, so swap the seed to match. Add before remove, as the ✅ swap does —
+    // a failure in between leaves both, which still collects.
+    try {
+      await reactionAdd(token, t.channelId, t.ts, seedMarker, args.cookie);
+      await reactionRemove(token, t.channelId, t.ts, oldSeed, args.cookie);
+    } catch (e: unknown) {
+      console.error(`  (marker を ${seedMarker} に替えられませんでした: ${e instanceof Error ? e.message : String(e)})`);
+    }
   }
   console.error(`✓ 編集しました: ${stripTerminalControls(args.link)}`);
 }
@@ -3765,7 +3940,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 +3988,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 +4040,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 +4049,7 @@ async function cmdAskPending(
     (count.ambiguous ? `, ${count.ambiguous} 件は返信が複数の選択肢に一致 (未確定)` : "") +
     (count.resolved ? `, ${count.resolved} 件は ✅ 回収済み` : "") +
     (count.void ? `, ${count.void} 件は無効化済み` : "") +
+    (count.explain ? `, ${count.explain} 件は ℹ️ 説明のリクエストあり` : "") +
     ` — ${rows.length} 件の未回収の質問を確認 (log: ${sentDbPath()})`,
   );
 }
@@ -3876,9 +4060,12 @@ interface AskVoidTarget {
   channelId: string;
   ts: string;
   parsed: Extract<ReturnType<typeof askParseMessage>, { kind: "open" }>;
+  /** The marker reaction it was seeded with (➕, or ❓ on an old pill / free
+   *  text) — what the void takes off. */
+  seedMarker: string;
 }
 
-/** Void one question: the 🚫 text (body kept), our seeds and ❓ off, 🚫 on.
+/** Void one question: the 🚫 text (body kept), our seeds and marker (➕, or ❓) off, 🚫 on.
  *  The text is what marks it void; the reactions are cleanup + searchability,
  *  so a failure there is reported and does not undo the void. */
 async function askApplyVoid(token: string, t: AskVoidTarget, reason: string, supersededBy: string | undefined, cookie?: string): Promise<boolean> {
@@ -3890,7 +4077,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), t.seedMarker, ...(t.parsed.explain ? [ASK_EXPLAIN_MARKER] : [])]) {
     try { await reactionRemove(token, t.channelId, t.ts, name, cookie); } catch { /* not ours / already gone */ }
   }
   try {
@@ -3913,7 +4100,7 @@ async function askApplyVoid(token: string, t: AskVoidTarget, reason: string, sup
  *
  *  What voiding does, per question: the text becomes the 🚫 form (head, void
  *  stamp with the reason, optional pointer to the replacement, the body); our
- *  seeded pills and the ❓ marker come off; a 🚫 reaction goes on. Pills someone
+ *  seeded pills and the marker (➕, or ❓) come off; a 🚫 reaction goes on. Pills someone
  *  already pressed stay — Slack lets only their owner remove them — and are
  *  never collected, because a void is never polled again.
  *
@@ -3946,7 +4133,7 @@ async function cmdAskVoid(token: string, args: { links: string[]; reason: string
       process.exit(ASK_EXIT_ERROR);
     }
   }
-  type Target = { link: string; channelId: string; ts: string; text: string; parsed: Extract<ReturnType<typeof askParseMessage>, { kind: "open" }>; pressed: string[]; unreadable?: boolean };
+  type Target = { link: string; channelId: string; ts: string; text: string; parsed: Extract<ReturnType<typeof askParseMessage>, { kind: "open" }>; seedMarker: string; pressed: string[]; unreadable?: boolean };
   const targets: Target[] = [];
   let refused = 0;
   for (const link of args.links) {
@@ -3984,14 +4171,21 @@ 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;
     }
+    // Our marker: what the body names, or — for an unreadable body — ➕ if we
+    // seeded one, else ❓ (an old pill, or free text).
+    const seedMarker = unreadable
+      ? (asArray(msg.reactions).map(asRecord).some((r) => r.name === ASK_OTHER_MARKER && asArray(r.users).includes(self?.userId ?? "\u0000")) ? ASK_OTHER_MARKER : ASK_MARKER)
+      : askSeedMarker(text) ?? ASK_MARKER;
     const pressed = asArray(msg.reactions).map(asRecord)
       .filter((r) => typeof r.name === "string" && ASK_KEYCAPS.some((k) => k.name === r.name))
       .filter((r) => asArray(r.users).some((u) => u !== self?.userId))
       .map((r) => `:${String(r.name)}:`);
-    targets.push({ link, channelId: got.channelId, ts: got.ts, text, parsed, pressed, ...(unreadable ? { unreadable } : {}) });
+    targets.push({ link, channelId: got.channelId, ts: got.ts, text, parsed, seedMarker, pressed, ...(unreadable ? { unreadable } : {}) });
   }
   if (!targets.length) {
     console.error(refused ? "無効化できる質問がありません。" : "何もすることがありません。");
@@ -4009,7 +4203,7 @@ async function cmdAskVoid(token: string, args: { links: string[]; reason: string
       ...targets.map((t) => `   • ${stripTerminalControls(t.link)}\n     ${stripTerminalControls(t.parsed.question.split("\n")[0] ?? "").slice(0, 100)}` +
         (t.pressed.length ? `\n     (already pressed: ${t.pressed.join(" ")} — left in place, never collected)` : "") +
         (t.unreadable ? `\n     ⚠ its layout no longer reads as an ask (edited by hand?) — voided from a best-effort read: question and the rest of the text kept as they are` : "")),
-      `  Each becomes 🚫 (body kept, options and instructions removed); our pills and ❓ come off; a 🚫 reaction is added.`,
+      `  Each becomes 🚫 (body kept, options and instructions removed); our pills and marker (➕, or ❓) come off; a 🚫 reaction is added.`,
       ...(refused ? [`  (${refused} link(s) above were refused and will be skipped)`] : []),
       `----------------------------------------------`,
     ]);
@@ -4030,7 +4224,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 +4378,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,
@@ -4193,6 +4387,7 @@ function askWaitCtxFrom(
     reactable: parsed.reactable,
     overflow: parsed.overflow,
     threadOnly: parsed.threadOnly,
+    seedMarker: askSeedMarker(q.text) ?? ASK_MARKER,
     lang: parsed.lang,
     audience: q.audience,
     broadcast: q.broadcast,
@@ -4202,6 +4397,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 +5942,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 +5957,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 +6083,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 +6174,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 +6213,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"];