slack-term 1.42.0 → 1.44.0

package/ts/cli.ts

@@ -12,15 +12,19 @@ import { guardUrlBoundaries } from "./urlGuard.ts";
 import { listProfiles, removeProfile, resolveBotToken, resolveCookie, resolveToken, useProfile, type Profile } from "./profiles.ts";
 import { diagnoseBotMessaging, formatDiagnosis } from "./botdoctor.ts";
 import { cmdAuthLogin, cmdAuthLoginChrome, cmdAuthChrome, cmdAuthFirefox, cmdAuthToken, cmdAuthApp, cmdAuthSave, cmdAuthTokens } from "./auth.ts";
-import { cmdTail } from "./tail.ts";
+import { cmdTail, parseSince as parseDuration } from "./tail.ts";
+import { runStream, webClient } from "./stream.ts";
+import { relaySubscriber } from "./relay.ts";
 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,
@@ -58,6 +62,7 @@ import { attributionEnabled, attributionMetadata, captureAttribution, markAskCol
 import {
   authTest,
   authScopes,
+  botsInfo,
   authTestSession,
   conversationInfoSession,
   createChannel,
@@ -90,6 +95,7 @@ import {
   openDm,
   parseSlackPermalink,
   replies,
+  repliesPage,
   resolveChannel,
   resolveUserId,
   search,
@@ -2454,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;
@@ -2473,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;
@@ -2497,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;
@@ -2611,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
@@ -2679,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));
@@ -2709,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;
@@ -2751,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,
@@ -2766,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;
 
@@ -2842,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.
@@ -2892,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) };
@@ -3038,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
@@ -3099,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
@@ -3119,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);
       }
@@ -3164,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) {
@@ -3174,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);
 }
 
@@ -3303,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
@@ -3354,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)`,
       `--------------------------------────────────`,
@@ -3382,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);
@@ -3438,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;
@@ -3597,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);
@@ -3632,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)})`),
     );
@@ -3762,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
@@ -3807,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 });
@@ -3855,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 で確認)`);
   }
@@ -3863,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()})`,
   );
 }
@@ -3887,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 {
@@ -3981,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;
     }
@@ -4027,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;
@@ -4181,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,
@@ -4199,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;
@@ -5742,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." })
@@ -5757,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" })
@@ -5881,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)) {
@@ -5970,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);
@@ -6008,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"];
@@ -7226,6 +7395,153 @@ async function main(): Promise<void> {
         )
         .command("$0", false as unknown as string, () => {}, () => { y.showHelp(); process.exit(0); }),
     )
+    .command(
+      "stream",
+      "Print every new message matching --grep, across all channels the identity is in (threads included); resumable",
+      (y) => y
+        .option("grep", { alias: "e", type: "string", demandOption: true, describe: "Regex matched against each message's text (raw, e.g. <@U00000001>). Non-matching messages are never printed or logged" })
+        .option("ignore-case", { alias: "i", type: "boolean", default: false, describe: "Case-insensitive --grep" })
+        .option("channel", { type: "array", string: true, describe: "Only these channels (#name, id or permalink); repeatable" })
+        .option("replies-to", { type: "array", string: true, describe: "Also print replies in threads this id started or replied in (user U…/bot B…; `self` = the streaming identity), --grep or not; repeatable" })
+        .option("json", { type: "boolean", default: false, describe: "One JSON object per match: type, channel{id,name}, ts, thread_ts, user{id,name}, text, permalink, match (grep | replies-to)" })
+        .option("once", { type: "boolean", default: false, describe: "Scan once from the saved cursor (or --since) and exit: 0 = matches printed, 2 = none, 3 = failure" })
+        .option("since", { type: "string", describe: "Replay from this long ago (e.g. 30m, 2h), ignoring the saved cursor" })
+        .option("interval", { type: "string", default: "45s", describe: "Poll interval (e.g. 30s, 2m)" })
+        .option("thread-window", { type: "string", default: "3d", describe: "Watch replies in threads whose parent is at most this old" })
+        .option("thread-scan", { type: "string", default: "3m", describe: "Polling: re-read each channel's whole --thread-window this often (cycles in between read only what is new)" })
+        .option("calls-per-min", { type: "number", default: 40, describe: "Polling: pace conversations.history/replies to this many calls per minute (0 = unpaced)" })
+        .option("state", { type: "string", describe: "Cursor file (default: one per identity+grep+channels under $XDG_STATE_HOME/slack-term/stream/)" })
+        .option("as-user", { type: "boolean", default: false, describe: "Stream as the user identity (sees the user's DMs) instead of the bot" })
+        .option("relay", { type: "boolean", default: true, describe: "Use the doorbell relay (worker/) when SLACK_RELAY_URL and SLACK_RELAY_TOKEN are set; --no-relay polls only" })
+        .option("reconcile", { type: "string", default: "5m", describe: "While the relay is connected, poll this rarely as a safety net" }),
+      async (argv) => {
+        let re: RegExp;
+        let reconcileMs: number;
+        let intervalMs: number;
+        let windowSec: number;
+        let threadScanSec: number;
+        let sinceSec: number | undefined;
+        try {
+          re = new RegExp(argv.grep, argv["ignore-case"] ? "i" : "");
+          intervalMs = parseDuration(argv.interval) * 1000;
+          windowSec = parseDuration(argv["thread-window"]);
+          threadScanSec = parseDuration(argv["thread-scan"]);
+          sinceSec = argv.since !== undefined ? parseDuration(argv.since) : undefined;
+          reconcileMs = parseDuration(argv.reconcile) * 1000;
+        } catch (e) {
+          console.error(`slack stream: ${e instanceof Error ? e.message : String(e)}`);
+          process.exit(1);
+        }
+        // Privacy-safe default: the bot sees only the channels it was invited
+        // to, never the user's DMs. The user identity is an explicit opt-in.
+        const bot = resolveBotToken();
+        const asUser = argv["as-user"] === true || !bot;
+        const token = asUser ? tok(argv as W) : bot!;
+        const cookie = asUser ? ck(argv as W) : undefined;
+        if (!bot && argv["as-user"] !== true) {
+          console.error("slack stream: no bot token (SLACK_BOT_TOKEN) — streaming as the USER identity, which includes its DMs.");
+        }
+        let me: Awaited<ReturnType<typeof authScopes>>;
+        try {
+          me = await authScopes(token, cookie);
+        } catch (e) {
+          console.error(`slack stream: fatal: ${e instanceof Error ? e.message : String(e)}`);
+          process.exit(3);
+        }
+        // Self-echo exclusion is by sender id: the identity's own user id, its
+        // bot id, and — when streaming as the user — the bot's posts too.
+        const selfUsers = new Set([me.userId].filter(Boolean));
+        const selfBots = new Set([me.botId].filter(Boolean));
+        if (asUser && bot) {
+          try {
+            const b = await authScopes(bot);
+            if (b.userId) selfUsers.add(b.userId);
+            if (b.botId) selfBots.add(b.botId);
+          } catch { /* a dead bot token posts nothing to exclude */ }
+        }
+        // Slack names a bot in a thread either way: `parent_user_id` holds its
+        // bot USER id (auth.test user_id), `reply_users` sometimes its B… bot
+        // id — so `self` stands for both.
+        let repliesTo: Set<string> | undefined;
+        if (argv["replies-to"]?.length) {
+          repliesTo = new Set();
+          for (const r of argv["replies-to"].map(String)) {
+            if (r === "self") {
+              for (const id of [me.userId, me.botId]) if (id) repliesTo.add(id);
+              continue;
+            }
+            if (!/^[UWB][A-Z0-9]{2,}$/.test(r)) {
+              console.error(`slack stream: --replies-to: "${r}" is not a user or bot id (U…/W…/B…) or "self"`);
+              process.exit(1);
+            }
+            repliesTo.add(r);
+            // A bot can be listed under its user id too: add that alias.
+            if (r.startsWith("B")) {
+              try {
+                const { userId } = await botsInfo(token, r, cookie);
+                if (userId) repliesTo.add(userId);
+              } catch (e) {
+                console.error(`slack stream: --replies-to ${r}: cannot resolve its bot user id (${e instanceof Error ? e.message : String(e)}); threads where it shows as a user id are missed`);
+              }
+            }
+          }
+        }
+        let channels: string[] | undefined;
+        if (argv.channel?.length) {
+          try {
+            channels = [];
+            for (const c of argv.channel) channels.push(await resolveChannel(token, String(c), cookie));
+          } catch (e) {
+            console.error(`slack stream: --channel: ${e instanceof Error ? e.message : String(e)}`);
+            process.exit(1);
+          }
+        }
+        const key = createHash("sha256")
+          .update(JSON.stringify([me.url, me.userId, re.source, re.flags, [...(channels ?? [])].sort(),
+            // As given, not as resolved: a failed bots.info lookup must not
+            // move the stream to a fresh state file.
+            ...(argv["replies-to"]?.length ? [[...argv["replies-to"].map(String)].sort()] : [])]))
+          .digest("hex").slice(0, 16);
+        const stateHome = process.env.XDG_STATE_HOME || join(homedir(), ".local", "state");
+        const statePath = argv.state ?? join(stateHome, "slack-term", "stream", `${key}.json`);
+        console.error(`slack stream: as ${asUser ? "user" : "bot"} @${me.user} (${me.userId}); state ${statePath}`);
+        // The relay rings for what the Slack app's bot can see, so it only
+        // stands in for polling when streaming as that bot.
+        const relayUrl = process.env.SLACK_RELAY_URL;
+        const relayToken = process.env.SLACK_RELAY_TOKEN;
+        const relay = argv.relay && !asUser && !argv.once && relayUrl && relayToken
+          ? { url: relayUrl, subscribe: relaySubscriber(relayUrl, relayToken), reconcileMs }
+          : undefined;
+        if (argv.relay && asUser && relayUrl) console.error("slack stream: relay not used with --as-user (it only sees the bot's channels)");
+        const pollReason = !argv.relay ? "--no-relay"
+          : asUser ? (relayUrl ? "--as-user: the relay only rings for the bot's channels" : "streaming as the user; the relay serves the bot identity")
+            : "SLACK_RELAY_URL / SLACK_RELAY_TOKEN not set";
+        const ac = new AbortController();
+        process.on("SIGINT", () => ac.abort());
+        process.on("SIGTERM", () => ac.abort());
+        const code = await runStream(webClient(token, cookie), {
+          grep: re,
+          ...(repliesTo ? { repliesTo } : {}),
+          ...(channels ? { channels } : {}),
+          selfUsers,
+          selfBots,
+          json: argv.json,
+          once: argv.once,
+          ...(sinceSec !== undefined ? { sinceSec } : {}),
+          intervalMs,
+          threadWindowSec: windowSec,
+          threadScanSec,
+          callsPerMin: argv["calls-per-min"],
+          ...(relay ? {} : { pollReason }),
+          statePath,
+          teamUrl: me.url,
+          identity: me.userId,
+          signal: ac.signal,
+          ...(relay ? { relay } : {}),
+        });
+        process.exit(code);
+      },
+    )
     .command(
       "tail [target]",
       "Stream new messages in real time (like tail -f)",