polygram 0.12.0-rc.8 → 0.12.0

package/lib/handlers/gate-inbound.js

@@ -0,0 +1,188 @@
+'use strict';
+
+/**
+ * gateInbound — the ONE intake gate (0.13 D5, docs/0.13-channels-lifecycle-design.md §3 D4+D5).
+ *
+ * Pre-0.13, polygram had four gate depths (seam S11): the fresh-message chain in
+ * dispatchRegularMessage, edit-redelivery's bare shouldHandle, the mid-turn edit
+ * injector's none, and boot-replay's none. The divergences were themselves bugs:
+ * an edit to "/stop" was injected into the very turn it tried to kill; an edit
+ * during a free-text "Other" capture never became the answer; any group member's
+ * bare "stop" aborted others' turns pre-gate.
+ *
+ * Every entry point now runs the same ordered chain, with a tier flag declaring
+ * per stage whether it EVALUATES, EXECUTES side effects, or is SKIPPED:
+ *
+ *   stage            | fresh            | edit             | redelivery
+ *   -----------------|------------------|------------------|--------------------------
+ *   abort            | eval + execute*  | eval + execute*  | eval, never exec → blocked
+ *   admin / pair     | eval + dispatch  | eval + dispatch  | eval, never exec → blocked
+ *   rewind           | eval + execute   | skip             | skip
+ *   question-consume | eval + execute   | eval + execute   | skip (already consumed once)
+ *   shouldHandle     | evaluate         | evaluate         | evaluate
+ *   final            | dispatch         | return 'pass'    | return 'pass'
+ *
+ *   * identity-gated: DM ‖ paired ‖ @mention ‖ reply-to-bot. Closes the
+ *     pre-existing bystander-abort hole (abort ran before shouldHandle with
+ *     zero identity checks — any group member's "stop" killed the in-flight
+ *     turn) BEFORE the edit tier gains abort semantics.
+ *
+ * Return shape: { action: 'dispatched'|'handled'|'blocked'|'pass', stage?, reason? }
+ *   dispatched — handed to dispatchHandleMessage (fresh final, admin stage)
+ *   handled    — a stage consumed it (abort executed, question answered, rewind)
+ *   blocked    — gate dropped it (caller logs; redelivery callers emit no-redeliver)
+ *   pass       — edit/redelivery tiers: caller owns the next step
+ *
+ * Late-bound deps are getters (botUsername/mentionRe are assigned after bot
+ * init; rewind/question handlers are wired late in main()) — the established
+ * `let x = null; wired in main()` pattern, made explicit.
+ */
+
+const ADMIN_CMD_RE = /^\/(model|effort|config|pair-code|pairings|unpair|new|reset|context|compact)(\s|$)/;
+const PAIR_CLAIM_RE = /^\/pair\s+\S+/;
+
+function createGateInbound({
+  config,
+  getBotUsername,
+  getMentionRe,
+  pairings = null,
+  isAbortRequest,
+  handleAbortIfRequested,
+  getRewindHandler = () => null,
+  isRewindCommand = () => false,
+  getQuestionHandlers = () => null,
+  shouldHandle,
+  getSessionKey,
+  dispatchHandleMessage,
+  bot,
+  botName,
+  logEvent = () => {},
+  logger = console,
+} = {}) {
+  if (typeof shouldHandle !== 'function') throw new TypeError('gateInbound: shouldHandle required');
+  if (typeof dispatchHandleMessage !== 'function') throw new TypeError('gateInbound: dispatchHandleMessage required');
+  if (typeof getSessionKey !== 'function') throw new TypeError('gateInbound: getSessionKey required');
+
+  /**
+   * The abort identity gate: is this sender plausibly addressing the BOT
+   * (vs a teammate)? DM ‖ paired ‖ @mention ‖ reply-to-bot. Mirrors the
+   * shouldHandle signals but is evaluated BEFORE shouldHandle because abort
+   * (deliberately) outranks the mention gate for addressed senders.
+   */
+  function isAddressedIdentity(msg, chatId) {
+    if (msg.chat?.type === 'private') return true;
+    const botUsername = getBotUsername?.() || '';
+    const text = msg.text || msg.caption || '';
+    if (botUsername && text.includes(`@${botUsername}`)) return true;
+    if (botUsername && msg.reply_to_message?.from?.username === botUsername) return true;
+    if (pairings && msg.from?.id
+      && pairings.hasLivePairing({ bot_name: botName, user_id: msg.from.id, chat_id: chatId })) {
+      return true;
+    }
+    return false;
+  }
+
+  return async function gateInbound(msg, { tier = 'fresh' } = {}) {
+    const chatId = msg.chat.id.toString();
+    const chatConfig = config.chats[chatId];
+    if (!chatConfig) return { action: 'blocked', stage: 'chat', reason: 'unconfigured chat' };
+
+    const mentionRe = getMentionRe?.();
+    const rawText = msg.text || '';
+    const cleanText = mentionRe ? rawText.replace(mentionRe, '').trim() : rawText.trim();
+    const threadId = msg.message_thread_id?.toString();
+    const sessionKey = getSessionKey(chatId, threadId, chatConfig);
+
+    // ── abort ────────────────────────────────────────────────────────────
+    if (typeof isAbortRequest === 'function' && isAbortRequest(cleanText)) {
+      if (tier === 'redelivery') {
+        // An auto-redelivered abort would execute in a context the user never
+        // intended (their original "stop" targeted work long since settled).
+        return { action: 'blocked', stage: 'abort', reason: 'abort-shaped content is never auto-re-executed' };
+      }
+      if (!isAddressedIdentity(msg, chatId)) {
+        logEvent('abort-identity-blocked', {
+          chat_id: chatId, msg_id: msg.message_id, user_id: msg.from?.id ?? null, tier,
+        });
+        return { action: 'blocked', stage: 'abort', reason: 'abort from unaddressed sender' };
+      }
+      const handled = await handleAbortIfRequested(msg, chatId, chatConfig, cleanText);
+      if (handled) return { action: 'handled', stage: 'abort' };
+      // The predicate matched but the handler declined (defensive) — fall through.
+    }
+
+    // ── admin command / pair claim ───────────────────────────────────────
+    const botAllowsCommands = !!config.bot?.allowConfigCommands;
+    const isAdminCmd = botAllowsCommands && ADMIN_CMD_RE.test(cleanText);
+    const isPairClaim = PAIR_CLAIM_RE.test(cleanText);
+    if (isAdminCmd || isPairClaim) {
+      if (tier === 'redelivery') {
+        return { action: 'blocked', stage: 'admin', reason: 'admin/pair-shaped content is never auto-re-executed' };
+      }
+      msg.text = cleanText;
+      // 0.13 D5: through the dispatcher wrapper — the admin path gains
+      // handler-error events, the in-flight counter, and terminal
+      // handler_status on throw (pre-P2 it called bare handleMessage and
+      // errors bubbled to grammy's bot.catch with the row left 'dispatched').
+      dispatchHandleMessage(sessionKey, chatId, msg, bot);
+      return { action: 'dispatched', stage: 'admin' };
+    }
+
+    // ── /rewind ── fresh only (an edited or replayed /rewind is nonsensical) ──
+    if (tier === 'fresh') {
+      const rewindHandler = getRewindHandler?.();
+      if (rewindHandler && isRewindCommand(cleanText)) {
+        try {
+          // Operator identity: explicit operatorUserId, else the admin user — a PRIVATE
+          // adminChatId equals that user's Telegram id. A group adminChatId (negative) is
+          // not a user id → never matches a positive sender id → default-deny.
+          const opId = config.bot?.operatorUserId;
+          const adminChatId = config.bot?.adminChatId;
+          const operatorUid = opId != null ? Number(opId) : (adminChatId != null ? Number(adminChatId) : null);
+          const isOperatorIdentity = operatorUid != null && msg.from?.id != null && Number(msg.from.id) === operatorUid;
+          const paired = pairings && msg.from?.id
+            ? pairings.hasLivePairing({ bot_name: botName, user_id: msg.from.id, chat_id: chatId })
+            : false;
+          const accessMode = chatConfig?.rewindAccess === 'paired' ? 'paired' : 'operator';
+          const rewindSafe = msg.chat?.type === 'private' || chatConfig?.isolateTopics === true;
+          const r = await rewindHandler.tryConsume({
+            sessionKey, chatId, threadId, msg, cleanText,
+            botUsername: getBotUsername?.() || '',
+            rewindSafe, isOperatorIdentity, paired, accessMode,
+          });
+          if (r.consumed) return { action: 'handled', stage: 'rewind' };
+        } catch (err) {
+          // The text IS a recognized /rewind — on an internal error, consume it
+          // anyway; falling through would send "/rewind" to claude as a prompt.
+          logger.error?.(`[${botName}] rewind tryConsume failed: ${err?.message || err}`);
+          return { action: 'handled', stage: 'rewind', reason: 'consumed-on-error' };
+        }
+      }
+    }
+
+    // ── question-consume / ownsOpenOther ── fresh + edit; redelivery skips
+    // (a replayed row already had its question-capture moment when fresh)
+    const questionHandlers = tier !== 'redelivery' ? getQuestionHandlers?.() : null;
+    const ownsOpenOther = questionHandlers
+      ? questionHandlers.isAwaitingOtherFrom(sessionKey, msg.from?.id)
+      : false;
+
+    // ── shouldHandle (mention/pairing gate) ── all tiers
+    if (!ownsOpenOther && !shouldHandle(msg, chatConfig, getBotUsername?.() || '')) {
+      return { action: 'blocked', stage: 'shouldHandle' };
+    }
+    if (getBotUsername?.()) msg.text = cleanText;
+
+    if (questionHandlers) {
+      const r = await questionHandlers.tryConsumeAsAnswer({ sessionKey, fromId: msg.from?.id, text: cleanText });
+      if (r.consumed) return { action: 'handled', stage: 'question-consume' };
+    }
+
+    // ── final ──
+    if (tier !== 'fresh') return { action: 'pass', sessionKey, chatId, cleanText };
+    dispatchHandleMessage(sessionKey, chatId, msg, bot);
+    return { action: 'dispatched' };
+  };
+}
+
+module.exports = { createGateInbound, ADMIN_CMD_RE, PAIR_CLAIM_RE };

package/lib/handlers/questions.js

@@ -0,0 +1,289 @@
+/**
+ * Interactive-question handlers (0.12 ask feature) — the integration glue between
+ * the pure state machine (lib/questions/questions.js), the store
+ * (lib/questions/store.js), Telegram, and the bridge answer write-back.
+ *
+ *   renderAsk            — claude called `ask`: issue a row, send the keyboard.
+ *   handleQuestionCallback — a `q:` button tap: validate, mutate, advance/resolve.
+ *   tryConsumeAsAnswer   — dispatcher hook: a typed message while a question is
+ *                          open (free-text "Other", or a nudge for the wrong user).
+ *   expireQuestion       — timeout sweep / cancel: answer {timedout}/{cancelled}, strip.
+ *
+ * Security (review): per-row 128-bit token in callback_data + claim-on-first-tap
+ * respondent authz + plain-text body (no parse_mode) for agent content.
+ *
+ * Anti-hang invariant (review-hardened): claude's `ask` tool call must be answered
+ * EXACTLY once and never hang. Therefore every terminal path hands the result to
+ * claude *first* (guarded) and only then marks the row terminal — `finalize()`. If
+ * the write-back THROWS, the row is LEFT pending so the timeout sweep can recover
+ * with {timedout} (never resolved-but-hung). If the write-back is an undelivered
+ * NO-OP (returns false — session gone / no live bridge), it is surfaced loudly and
+ * the row is still resolved (a dead session can't be delivered; the bridge's own
+ * 20-min ceiling backstops the rare live-proc case). A failed Telegram send is also
+ * hang-safe: we answer {cancelled} rather than leaving a pending row with no
+ * on-screen keyboard. renderAsk that throws BEFORE issuing a row answers {cancelled}
+ * itself (no row exists for the sweep to find); tryConsumeAsAnswer never throws out
+ * of the dispatcher (a store error degrades to "not an answer", never a dropped msg).
+ */
+
+'use strict';
+
+const Q = require('../questions/questions');
+const { tokensEqual } = require('../questions/store');
+
+function createQuestionHandlers({
+  questions,        // store (lib/questions/store.js)
+  tg,
+  bot,
+  botName,
+  logEvent = () => {},
+  answerQuestion,   // (sessionKey, toolCallId, result) → write question_answer to the bridge
+  logger = console,
+} = {}) {
+
+  function strip(chatId, msgId, threadId, text) {
+    if (msgId == null) return Promise.resolve();
+    return tg(bot, 'editMessageText', {
+      chat_id: chatId, message_id: msgId, text,
+      ...(threadId && { message_thread_id: threadId }),
+    }, { source: 'question-edit', botName })
+      .catch((e) => logger.error?.(`[${botName}] question strip failed: ${e.message}`));
+  }
+
+  async function sendCurrent(row, state) {
+    const view = Q.renderCurrent(state, `q:${row.id}:${row.callback_token}`);
+    if (!view) return null;
+    // PLAIN-TEXT (no parse_mode): option labels/descriptions are agent-authored.
+    const sent = await tg(bot, 'sendMessage', {
+      chat_id: row.chat_id, text: view.text, reply_markup: view.reply_markup,
+      ...(row.thread_id && { message_thread_id: row.thread_id }),
+    }, { source: 'question', botName }).catch((e) => {
+      logger.error?.(`[${botName}] question send failed: ${e.message}`);
+      return null;
+    });
+    return sent?.message_id ?? null;
+  }
+
+  /**
+   * Hand the result to claude FIRST (guarded), then mark the row terminal. On
+   * write-back failure: leave the row pending (the timeout sweep recovers it) and
+   * return false — NEVER resolved-but-hung. Returns true when claude was answered.
+   */
+  function finalize(row, result, status = 'answered') {
+    let delivered;
+    try {
+      delivered = answerQuestion?.(row.session_key, row.tool_call_id, result);
+    } catch (e) {
+      logger.error?.(`[${botName}] answerQuestion failed for ${row.tool_call_id}: ${e.message}`);
+      return false;   // threw → leave the row pending; the timeout sweep recovers it
+    }
+    // A *false* return is a silent no-op (session gone / no live bridge), NOT a
+    // throw. Surface it loudly and still resolve: a dead session can never be
+    // delivered, so leaving it pending would have the 30s sweep re-strip +
+    // re-answer it forever. The rare live-proc-but-unwritable-bridge case is
+    // backstopped by the bridge's own 20-min answer ceiling.
+    if (delivered === false) {
+      logger.error?.(`[${botName}] answerQuestion undelivered (session gone / no bridge) for ${row.tool_call_id}`);
+      logEvent('question-answer-undelivered', { session_key: row.session_key, tool_call_id: row.tool_call_id });
+    }
+    questions.resolve(row.id, status);
+    return true;
+  }
+
+  // ── claude called ask → render the first question ──────────────────
+  async function renderAsk({ sessionKey, chatId, threadId = null, turnId = null, toolCallId, questions: qs }) {
+    let row = null;
+    try {
+      // Idempotency: a bridge retry of the same tool_call_id must not double-render.
+      if (questions.getByToolCallId(toolCallId)) return null;
+
+      if (!Array.isArray(qs) || qs.length === 0) {
+        try { answerQuestion?.(sessionKey, toolCallId, { answers: [] }); } catch (e) {
+          logger.error?.(`[${botName}] answerQuestion(empty) failed: ${e.message}`);
+        }
+        return null;
+      }
+      // One open question per session: cancel + unblock any prior open ask first.
+      const prior = questions.getOpenForSession(sessionKey);
+      if (prior) {
+        finalize(prior, { cancelled: true }, 'cancelled');
+        const pIds = JSON.parse(prior.message_ids_json || '[]');
+        if (pIds[0]) strip(prior.chat_id, pIds[0], prior.thread_id, 'This question was replaced.');
+      }
+      const state = Q.initState(qs);
+      row = questions.issue({
+        bot_name: botName, session_key: sessionKey, chat_id: chatId, thread_id: threadId,
+        turn_id: turnId, tool_call_id: toolCallId, questions: qs, state,
+      });
+      const msgId = await sendCurrent(row, state);
+      if (msgId == null) {
+        // Couldn't deliver the keyboard — don't strand claude on a pending row.
+        finalize(row, { cancelled: true, error: 'failed to deliver the question' }, 'cancelled');
+        logEvent('question-send-failed', { session_key: sessionKey, tool_call_id: toolCallId, phase: 'first' });
+        return null;
+      }
+      questions.setMessageIds(row.id, [msgId]);
+      logEvent('question-asked', { session_key: sessionKey, chat_id: chatId, tool_call_id: toolCallId, count: qs.length });
+      return row;
+    } catch (e) {
+      logger.error?.(`[${botName}] renderAsk failed for ${toolCallId}: ${e.message}`);
+      // Anti-hang: a throw BEFORE the row was issued (store error, etc.) leaves
+      // claude blocked with no row for the sweep to recover → answer {cancelled}
+      // now. If the row WAS issued (throw in a later step), it is pending and the
+      // timeout sweep will recover it with {timedout}.
+      if (!row) {
+        try { answerQuestion?.(sessionKey, toolCallId, { cancelled: true, error: 'failed to render question' }); } catch (e2) {
+          logger.error?.(`[${botName}] renderAsk fallback answer failed for ${toolCallId}: ${e2.message}`);
+        }
+      }
+      return null;
+    }
+  }
+
+  // ── a `q:<id>:<token>:<action>` button tap ─────────────────────────
+  async function handleQuestionCallback(ctx) {
+    const data = ctx.callbackQuery?.data || '';
+    const m = String(data).match(/^q:(\d+):([^:]+):(.+)$/);
+    if (!m) return;
+    const id = parseInt(m[1], 10);
+    const token = m[2];
+    const actionStr = m[3];
+
+    const row = questions.getById(id);
+    if (!row) { await ack(ctx, 'This question expired.', true); return; }
+    if (!tokensEqual(row.callback_token, token)) {
+      logEvent('question-token-mismatch', { id, from_user: ctx.from?.id });
+      await ack(ctx, 'Bad token.', true); return;
+    }
+    if (row.status !== 'pending') { await ack(ctx, `Already ${row.status}.`, true); return; }
+
+    // Respondent authorization: first tapper claims the question; others rejected.
+    const auth = questions.claimOrCheck(id, ctx.from?.id);
+    if (!auth.ok) {
+      logEvent('question-foreign-responder', { id, from_user: ctx.from?.id, owner: row.from_id });
+      await ack(ctx, 'This question is for someone else.', true); return;
+    }
+
+    const state = JSON.parse(row.state_json);
+    const res = Q.applyTap(state, Q.parseAction(actionStr));
+    const msgId = (JSON.parse(row.message_ids_json || '[]'))[0];
+
+    if (res.kind === 'reject') { await ack(ctx, res.message, true); return; }
+
+    if (res.kind === 'toggled') {
+      questions.updateState(id, res.state, false);
+      const view = Q.renderCurrent(res.state, `q:${id}:${token}`);
+      await tg(bot, 'editMessageReplyMarkup', {
+        chat_id: row.chat_id, message_id: msgId, reply_markup: view.reply_markup,
+        ...(row.thread_id && { message_thread_id: row.thread_id }),
+      }, { source: 'question-edit', botName })
+        .catch((e) => logger.error?.(`[${botName}] toggle re-render failed (q ${id}): ${e.message}`));
+      await ack(ctx);
+      return;
+    }
+
+    if (res.kind === 'awaiting-other') {
+      questions.updateState(id, res.state, true);
+      await strip(row.chat_id, msgId, row.thread_id, 'Send your answer as a message.');
+      await ack(ctx, 'Type your answer ↓');
+      return;
+    }
+
+    // advanced — record + receipt, then next question or finish.
+    await advance(ctx, row, res, false);
+  }
+
+  // ── a typed message while a question is open (Other / nudge) ────────
+  async function tryConsumeAsAnswer({ sessionKey, fromId, text }) {
+    try {
+      const row = questions.getOpenForSession(sessionKey);
+      if (!row) return { consumed: false };
+      // Only an in-progress free-text capture diverts typed messages. A question
+      // awaiting a BUTTON tap does not swallow ordinary chatter (review: do not eat
+      // every group member's message for the whole question lifetime).
+      if (!row.awaiting_other) return { consumed: false };
+      // /stop, /new and other commands are never consumed as a free-text answer.
+      if (/^\/(stop|new|reset|cancel|abort)\b/i.test(String(text || '').trim())) return { consumed: false };
+      // Identity: only the claimed owner supplies the free-text answer.
+      const auth = questions.claimOrCheck(row.id, fromId);
+      if (!auth.ok) {
+        tg(bot, 'sendMessage', { chat_id: row.chat_id, text: 'Please answer the open question above first.',
+          ...(row.thread_id && { message_thread_id: row.thread_id }) }, { source: 'question-nudge', botName })
+          .catch((e) => logger.error?.(`[${botName}] question nudge failed: ${e.message}`));
+        return { consumed: true };
+      }
+      const state = JSON.parse(row.state_json);
+      const res = Q.applyFreeText(state, text);
+      if (res.kind !== 'advanced') return { consumed: false };
+      await advance({ from: { id: fromId } }, row, res, true);
+      return { consumed: true };
+    } catch (e) {
+      // Never throw out of the message dispatcher: a store/parse error here must
+      // degrade to "not an answer" so the user's message still reaches normal
+      // dispatch instead of being silently dropped.
+      logger.error?.(`[${botName}] tryConsumeAsAnswer failed: ${e.message}`);
+      return { consumed: false };
+    }
+  }
+
+  // Does `fromId` own an open free-text ("Other") capture for this session? The
+  // dispatcher uses this to let the owner's typed answer bypass a group's mention
+  // gate — only the claimed owner, never a bystander.
+  function isAwaitingOtherFrom(sessionKey, fromId) {
+    if (fromId == null) return false;
+    try {
+      const row = questions.getOpenForSession(sessionKey);
+      return !!(row && row.awaiting_other && row.from_id != null && Number(row.from_id) === Number(fromId));
+    } catch { return false; }
+  }
+
+  // ── timeout sweep / external cancel ────────────────────────────────
+  async function expireQuestion(row, { status = 'timeout', message = 'This question timed out.' } = {}) {
+    const ids = JSON.parse(row.message_ids_json || '[]');
+    if (ids[0]) await strip(row.chat_id, ids[0], row.thread_id, message);
+    const result = status === 'cancelled' ? { cancelled: true } : { timedout: true };
+    finalize(row, result, status);
+    logEvent('question-expired', { session_key: row.session_key, tool_call_id: row.tool_call_id, status });
+  }
+
+  // shared: record an advanced result, post a receipt, then next-Q or resolve.
+  async function advance(ctx, row, res, fromText) {
+    const msgId = (JSON.parse(row.message_ids_json || '[]'))[0];
+    // Visible receipt on the question card — for BOTH a button tap and a typed "Other"
+    // answer. The typed-answer path used to skip this entirely, so a free-text answer (esp.
+    // the LAST question) left the card frozen on "Send your answer as a message." with no
+    // acknowledgment — "I answered and nothing happened" (prod: hire topic 2026-06-09).
+    await strip(row.chat_id, msgId, row.thread_id, `✓ ${res.receipt}`);
+    if (!fromText) await ack(ctx, 'Recorded');   // callback-query ack — button taps only
+
+    if (res.done) {
+      questions.updateState(row.id, res.state, false);
+      // Answer claude FIRST (guarded), THEN mark answered. If the write-back
+      // throws, leave the row pending → the timeout sweep recovers it.
+      if (!finalize(row, Q.assemble(res.state), 'answered')) {
+        logEvent('question-answer-writeback-failed', { session_key: row.session_key, tool_call_id: row.tool_call_id });
+        return;
+      }
+      logEvent('question-answered', { session_key: row.session_key, tool_call_id: row.tool_call_id });
+      return;
+    }
+    // next question → new message; on send failure, don't strand claude.
+    const nextMsgId = await sendCurrent(row, res.state);
+    if (nextMsgId == null) {
+      finalize(row, { cancelled: true, error: 'failed to deliver the next question' }, 'cancelled');
+      logEvent('question-send-failed', { session_key: row.session_key, tool_call_id: row.tool_call_id, phase: 'next', q_index: res.state.qIndex });
+      return;
+    }
+    questions.updateState(row.id, res.state, false);
+    questions.setMessageIds(row.id, [nextMsgId]);
+  }
+
+  function ack(ctx, text, alert = false) {
+    if (!ctx || typeof ctx.answerCallbackQuery !== 'function') return Promise.resolve();
+    return ctx.answerCallbackQuery(text ? { text, show_alert: alert } : undefined).catch(() => {});
+  }
+
+  return { renderAsk, handleQuestionCallback, tryConsumeAsAnswer, expireQuestion, isAwaitingOtherFrom };
+}
+
+module.exports = { createQuestionHandlers };

package/lib/handlers/redeliver.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * redeliverAsFreshTurn — the ONE redelivery tail (0.13 D4,
+ * docs/0.13-channels-lifecycle-design.md §3 D4+D5).
+ *
+ * Pre-0.13, "re-dispatch a message as a fresh turn" existed in five shapes
+ * (seam S10) — boot-replay, edit-redelivery, startup-auto-retry, auto-resume,
+ * compact-replay — each with different gating, one-shot, ack, and tagging
+ * semantics. This module is the shared tail every re-dispatch converges on:
+ *
+ *   1. once-only per (chatId, msgId) for the daemon lifetime — duplicates are
+ *      the double-answer failure mode, hard-capped here (FIFO-bounded set);
+ *   2. `_isReplay` tag — no new editable row, excluded from boot replay,
+ *      error replies suppressed (the boot-replay contract, generalized);
+ *   3. gate at tier 'redelivery' (D5) — abort/admin-shaped content is
+ *      EVALUATED but never auto-re-executed (logged `input-dropped-no-redeliver`);
+ *      skippable for same-process retries whose object already passed the
+ *      full fresh gate this boot (startup-auto-retry);
+ *   4. optional one-shot DB pre-mark (the boot-replay 'replay-attempted'
+ *      pattern: even if THIS attempt dies mid-turn, the next boot won't loop);
+ *   5. ack reaction (👀) — a re-dispatch must never be silent (rc.33 lesson);
+ *      callers may suppress for deliberately-silent retries;
+ *   6. dispatchHandleMessage — the normal turn path.
+ *
+ * Callers (P2): boot-replay. Callers (P3): the InputLedger drop-redeliverer.
+ * Deliberately NOT callers: edit-redelivery (edits are legitimately repeatable
+ * per message — this module's once-only is drop/replay semantics; edits share
+ * the D5 gate upstream instead), startup-auto-retry (its error path must
+ * SURFACE the friendly reset reply, which the _isReplay tag would suppress;
+ * its msg object already passed the full fresh gate this boot), compact-replay
+ * (a system re-push of the operator's own recorded command — outside the
+ * user-message gate by design, §6.7), and auto-resume (a continuation of a
+ * live turn, not a redelivery).
+ */
+
+const REDELIVERED_CAP = 256;
+
+function createRedeliver({
+  gateInbound,
+  dispatchHandleMessage,
+  getSessionKey,
+  config,
+  db = null,
+  dbWrite = (fn) => fn(),
+  setInboundHandlerStatus = null,   // override for tests; defaults to db.setInboundHandlerStatus
+  react = null,
+  bot,
+  logEvent = () => {},
+  logger = console,
+} = {}) {
+  if (typeof dispatchHandleMessage !== 'function') throw new TypeError('redeliver: dispatchHandleMessage required');
+  if (typeof getSessionKey !== 'function') throw new TypeError('redeliver: getSessionKey required');
+
+  const redelivered = new Set();   // `${chatId}:${msgId}` — once-only, FIFO-bounded
+  const redeliveredOrder = [];
+
+  /**
+   * @param {object} opts
+   * @param {string} opts.chatId
+   * @param {object} opts.msg       — grammy-shaped message (fresh, reconstructed, or synthetic)
+   * @param {string} opts.source    — 'boot-replay' | 'edit' | 'drop' | 'startup-retry' (telemetry)
+   * @param {string|null} [opts.preMark]  — handler_status to pre-mark (one-shot guard), e.g. 'replay-attempted'
+   * @param {boolean} [opts.gate=true]    — run the D5 gate at tier 'redelivery'
+   * @param {boolean} [opts.ack=true]     — 👀 on the redelivered message
+   * @returns {Promise<{ok:boolean, reason?:string}>}
+   */
+  return async function redeliverAsFreshTurn({
+    chatId, msg, source, preMark = null, gate = true, ack = true,
+  } = {}) {
+    if (!msg || !msg.chat || msg.message_id == null) return { ok: false, reason: 'malformed message' };
+    const chatConfig = config.chats[String(chatId)];
+    if (!chatConfig) return { ok: false, reason: 'unconfigured chat' };
+
+    const key = `${chatId}:${msg.message_id}`;
+    if (redelivered.has(key)) {
+      logEvent('redeliver-suppressed-duplicate', { chat_id: chatId, msg_id: msg.message_id, source });
+      return { ok: false, reason: 'already-redelivered' };
+    }
+    redelivered.add(key);
+    redeliveredOrder.push(key);
+    while (redeliveredOrder.length > REDELIVERED_CAP) redelivered.delete(redeliveredOrder.shift());
+
+    msg._isReplay = true;
+
+    // Pre-mark BEFORE the gate: the one-shot DB guard must hold even when the
+    // gate blocks the content — otherwise a blocked row (abort/admin-shaped)
+    // would stay replay-eligible and re-block on every subsequent boot.
+    if (preMark) {
+      const mark = setInboundHandlerStatus || ((args) => db?.setInboundHandlerStatus?.(args));
+      dbWrite(
+        () => mark({ chat_id: chatId, msg_id: msg.message_id, status: preMark }),
+        `set handler_status=${preMark}`,
+      );
+    }
+
+    if (gate) {
+      if (typeof gateInbound !== 'function') return { ok: false, reason: 'gate unavailable' };
+      const res = await gateInbound(msg, { tier: 'redelivery' });
+      if (res.action !== 'pass') {
+        logEvent('input-dropped-no-redeliver', {
+          chat_id: chatId, msg_id: msg.message_id, source, stage: res.stage ?? null,
+        });
+        return { ok: false, reason: res.stage || res.action };
+      }
+    }
+
+    if (ack) {
+      try { react?.(chatId, msg.message_id); } catch { /* best-effort — never blocks */ }
+    }
+
+    const threadId = msg.message_thread_id?.toString();
+    const sessionKey = getSessionKey(String(chatId), threadId, chatConfig);
+    logEvent('redelivered-as-fresh-turn', {
+      chat_id: chatId, msg_id: msg.message_id, source, session_key: sessionKey,
+    });
+    dispatchHandleMessage(sessionKey, String(chatId), msg, bot);
+    return { ok: true };
+  };
+}
+
+module.exports = { createRedeliver };