polygram 0.12.0-rc.35 → 0.12.0-rc.36

package/lib/feedback/session-feedback.js

@@ -0,0 +1,91 @@
+'use strict';
+
+/**
+ * Session-scoped feedback controller (0.13 D3,
+ * docs/0.13-channels-lifecycle-design.md §3 D3).
+ *
+ * The per-turn reactor/typing pair lives in handleMessage's closure and dies
+ * with the turn (ROOT C). D1 extended the turn to claude's real cycle end —
+ * which closed the dead-air class for PRIMARY turns — but cycles with NO
+ * pending turn still had zero feedback surface:
+ *
+ *   - autonomous/wakeup cycles (ScheduleWakeup, fireUserMessage self-checks):
+ *     minutes of work with nothing visible until text lands;
+ *   - an injected follow-up picked up as its OWN next cycle: its message sat
+ *     with no indicator while claude worked it.
+ *
+ * This controller owns those: a session-level typing loop for the cycle's
+ * duration, plus — when the InputLedger knows which message the cycle picked
+ * up — a 🤔 anchored to that message, cleared at cycle end. Inputs are the
+ * previously-unconsumed lifecycle edges: 'turn-start' (UPS) with no pending,
+ * and 'idle'/'close' as the end signals (wired via lib/sdk/callbacks.js).
+ *
+ * Per-turn feedback (reactor cascade, streamer, waiting-on-user typing pause)
+ * stays where it is — this controller deliberately covers only the
+ * no-pending gap; it never touches a session that has a head pending.
+ */
+
+const { startTyping } = require('../telegram/typing');
+
+function createSessionFeedback({
+  bot,
+  tg,
+  getChatIdFromKey,
+  getThreadIdFromKey,
+  botName,
+  typingIntervalMs = undefined,   // override for tests; default = typing.js default
+  logEvent = () => {},
+  logger = console,
+} = {}) {
+  const active = new Map();   // sessionKey → { stop, anchor: {chatId, msgId}|null }
+
+  function startAutonomousCycle(sessionKey, { anchorMsgId = null } = {}) {
+    if (active.has(sessionKey)) return;
+    const chatId = getChatIdFromKey(sessionKey);
+    if (!chatId || !bot) return;
+    const threadIdRaw = getThreadIdFromKey?.(sessionKey);
+    const threadId = threadIdRaw ? parseInt(threadIdRaw, 10) : null;
+
+    const stop = startTyping({
+      bot, chatId,
+      ...(Number.isInteger(threadId) ? { threadId } : {}),
+      ...(typingIntervalMs ? { intervalMs: typingIntervalMs } : {}),
+      logger: { error: (m) => logger.error?.(`[${botName}] autonomous-typing: ${m}`) },
+    });
+
+    let anchor = null;
+    if (anchorMsgId != null) {
+      anchor = { chatId, msgId: Number(anchorMsgId) };
+      tg(bot, 'setMessageReaction', {
+        chat_id: chatId, message_id: anchor.msgId,
+        reaction: [{ type: 'emoji', emoji: '🤔' }],
+      }, { source: 'autonomous-cycle-anchor', botName }).catch(() => {});
+    }
+
+    active.set(sessionKey, { stop, anchor });
+    logEvent('autonomous-cycle-visuals', {
+      chat_id: chatId, session_key: sessionKey, state: 'start',
+      anchor_msg_id: anchor?.msgId ?? null,
+    });
+  }
+
+  function endCycle(sessionKey) {
+    const entry = active.get(sessionKey);
+    if (!entry) return;
+    active.delete(sessionKey);
+    try { entry.stop(); } catch { /* best-effort */ }
+    if (entry.anchor && bot) {
+      tg(bot, 'setMessageReaction', {
+        chat_id: entry.anchor.chatId, message_id: entry.anchor.msgId, reaction: [],
+      }, { source: 'autonomous-cycle-anchor-clear', botName }).catch(() => {});
+    }
+    logEvent('autonomous-cycle-visuals', {
+      chat_id: entry.anchor?.chatId ?? getChatIdFromKey(sessionKey),
+      session_key: sessionKey, state: 'end',
+    });
+  }
+
+  return { startAutonomousCycle, endCycle };
+}
+
+module.exports = { createSessionFeedback };

package/lib/handlers/autosteer.js

@@ -78,6 +78,7 @@ function createAutosteerHandlers({
       content: prompt,
       priority,
       msgId: msg.message_id,
+      source: 'autosteer',   // 0.13 D2: ledger source — drop detection + redelivery eligibility
     });
     if (!ok) return { autosteered: false };
 
@@ -86,6 +87,9 @@ function createAutosteerHandlers({
       chat_id: chatId, msg_id: msg.message_id,
       text_len: prompt?.length ?? 0,
       priority,
+      // 0.13 P1: per-event backend. The 14d fold/drop investigation had to
+      // reconstruct the cli-vs-sdk split by joining chats — never again.
+      backend: typeof pm.getBackend === 'function' ? pm.getBackend(sessionKey) : null,
     });
     return { autosteered: true, priority };
   }

package/lib/handlers/drop-redeliver.js

@@ -0,0 +1,69 @@
+'use strict';
+
+/**
+ * Drop-redeliverer (0.13 D2 → D4 glue, docs/0.13-channels-lifecycle-design.md §3 D2).
+ *
+ * Consumes CliProcess's 'input-dropped' event — a ledgered input that was
+ * confirmed dropped (never seen at pickup, never acknowledged via
+ * consumed_turn_ids, not superseded, with the ack contract observed in the
+ * cycle) — and redelivers it ONCE through the unified D4 tail.
+ *
+ * Eligibility (design's redelivery constraints):
+ *   - `primary` and `autosteer` sources only: both reconstruct from the
+ *     inbound DB row (recordInbound persisted the raw message), so the
+ *     redelivered turn re-formats through the NORMAL prompt path — no stored
+ *     prompt text, no double-formatting, events stay content-free (L13).
+ *   - `edit-fold` / `system` / `inject` park as telemetry
+ *     (input-dropped-no-redeliver): an edit correction has its own
+ *     re-delivery path, and system pushes are never auto-re-executed.
+ *
+ * The D4 tail then enforces: once-only, _isReplay, the D5 gate at tier
+ * 'redelivery' (an abort/admin-shaped drop is never auto-re-executed), the
+ * visible 👀 ack, and dispatch. Supersession was already decided ledger-side.
+ */
+
+function createDropRedeliverer({ db, redeliver, logEvent = () => {}, logger = console } = {}) {
+  if (typeof redeliver !== 'function') throw new TypeError('drop-redeliver: redeliver required');
+
+  return async function onInputDropped(sessionKey, payload = {}) {
+    try {
+      const { chatId, msgId, source, turnId } = payload;
+      if (source !== 'primary' && source !== 'autosteer') {
+        logEvent('input-dropped-no-redeliver', {
+          chat_id: chatId ?? null, msg_id: msgId ?? null, source: source ?? null,
+          turn_id: turnId ?? null, reason: 'source-not-redeliverable',
+        });
+        return;
+      }
+      if (msgId == null) {
+        logEvent('input-dropped-no-redeliver', {
+          chat_id: chatId ?? null, source, turn_id: turnId ?? null, reason: 'no-msg-id',
+        });
+        return;
+      }
+      const row = db.getMessage(String(chatId), Number(msgId));
+      if (!row) {
+        logEvent('input-dropped-no-redeliver', {
+          chat_id: chatId, msg_id: msgId, source, turn_id: turnId ?? null, reason: 'no-db-row',
+        });
+        return;
+      }
+      // Reconstruct the boot-replay way: enough of a grammy Message for the
+      // normal prompt/attachment path to re-run from the persisted row.
+      const reconstructed = {
+        chat: { id: Number(chatId), type: String(chatId).startsWith('-') ? 'supergroup' : 'private' },
+        message_id: Number(msgId),
+        from: { id: row.user_id, first_name: row.user },
+        text: row.text || '',
+        date: Math.floor((row.ts || Date.now()) / 1000),
+        ...(row.thread_id && { message_thread_id: Number(row.thread_id) }),
+        ...(row.reply_to_id && { reply_to_message: { message_id: row.reply_to_id } }),
+      };
+      await redeliver({ chatId: String(chatId), msg: reconstructed, source: 'drop' });
+    } catch (err) {
+      logger.error?.(`[drop-redeliver] ${err?.message || err}`);
+    }
+  };
+}
+
+module.exports = { createDropRedeliverer };

package/lib/handlers/edit-correction.js

@@ -59,6 +59,8 @@ function createEditCorrectionInjector({
     const ok = pm.injectUserMessage(sessionKey, {
       content: `[edit] I corrected my previous message — it now reads: ${newText}`,
       priority: 'next',
+      msgId: editedMsg.message_id,
+      source: 'edit-fold',   // 0.13 D2: ledgered (telemetry; edits have their own redelivery path)
     });
     if (!ok) {
       logger.error?.(`[${chatConfig.name || chatId}] edit-correction inject failed`);

package/lib/handlers/edit-redelivery.js

@@ -40,82 +40,97 @@ function createEditRedelivery({
   // botUsername / mentionRe arrive at CALL time — see @returns. Constructing with them threw
   // `ReferenceError: mentionRe is not defined` at boot (rc.34): the factory runs in main() where
   // those createBot locals don't exist. The edited_message handler passes the live values.
+  //
+  // 0.13 D5 (spec §5 as written): the in-flight interlock is per-(chatId,msgId),
+  // not per-session. A re-edit of the SAME message while its re-dispatch runs
+  // folds via inject; an edit of a DIFFERENT message proceeds as its own
+  // redelivery (dispatchHandleMessage autosteers it naturally if a turn is in
+  // flight — through the formatted-prompt path, not a hand-built string).
+  const redeliveredAt = new Map();   // `${chatId}:${msgId}` → ts
+  const INTERLOCK_TTL_MS = 10 * 60 * 1000;
+
   return function maybePostTurnEdit(editedMsg, oldText, botUsername, mentionRe = null) {
-    try {
-      if (!editedMsg?.chat) return false;
-      const chatId = editedMsg.chat.id.toString();
-      const chatConfig = config.chats[chatId];
-      if (!chatConfig) return false;
+  try {
+    if (!editedMsg?.chat) return false;
+    const chatId = editedMsg.chat.id.toString();
+    const chatConfig = config.chats[chatId];
+    if (!chatConfig) return false;
 
-      // Per-chat / bot-level opt-out (shared with the mid-turn injector). Default on.
-      const optOut = chatConfig.editCorrection != null
-        ? chatConfig.editCorrection === false
-        : config.bot?.editCorrection === false;
-      if (optOut) return false;
+    // Per-chat / bot-level opt-out (shared with the mid-turn injector). Default on.
+    const optOut = chatConfig.editCorrection != null
+      ? chatConfig.editCorrection === false
+      : config.bot?.editCorrection === false;
+    if (optOut) return false;
 
-      const newText = editedMsg.text || editedMsg.caption || '';
-      if (!newText) return false;                              // blanked / media-only → nothing to act on
-      // Changed-guard: skip metadata-only edits (link-preview load fires edited_message too). The
-      // caller MUST have read oldText before recordInbound overwrote the row; null = unknown → proceed.
-      if (oldText != null && oldText === newText) return false;
+    const newText = editedMsg.text || editedMsg.caption || '';
+    if (!newText) return false;                              // blanked / media-only → nothing to act on
+    // Changed-guard: skip metadata-only edits (link-preview load fires edited_message too). The
+    // caller MUST have read oldText before recordInbound overwrote the row; null = unknown → proceed.
+    if (oldText != null && oldText === newText) return false;
 
-      const threadId = editedMsg.message_thread_id?.toString() || null;
-      const sessionKey = getSessionKey(chatId, threadId, chatConfig);
+    const threadId = editedMsg.message_thread_id?.toString() || null;
+    const sessionKey = getSessionKey(chatId, threadId, chatConfig);
 
-      // Interlock: a turn is in flight (most likely OUR own re-run, whose _isReplay row reads
-      // not-live so the mid-turn injector skipped it and fell through to here). Fold the re-edit
-      // via inject instead of spawning a SECOND re-dispatch turn for the same message.
-      const proc = pm?.get?.(sessionKey);
-      if (proc?.inFlight) {
-        pm.injectUserMessage?.(sessionKey, {
-          content: `[edit] I edited my message again — it now reads: ${newText}`,
-          priority: 'next',
-          msgId: editedMsg.message_id,
-        });
-        logEvent('edit-redelivery-folded', { chat_id: chatId, session_key: sessionKey, msg_id: editedMsg.message_id });
-        return false;
-      }
+    // Interlock (per-message, 0.13 D5): only a re-edit of a message whose OWN
+    // re-dispatch is still running folds via inject — pre-0.13 this was
+    // per-session (any in-flight turn folded any edit, and it injected
+    // BEFORE the gate; the gate now runs upstream in the edited_message
+    // handler, so every path through here is already gated).
+    const proc = pm?.get?.(sessionKey);
+    const interlockKey = `${chatId}:${editedMsg.message_id}`;
+    const lastRedeliveredAt = redeliveredAt.get(interlockKey) || 0;
+    if (proc?.inFlight && (Date.now() - lastRedeliveredAt) < INTERLOCK_TTL_MS && lastRedeliveredAt > 0) {
+      pm.injectUserMessage?.(sessionKey, {
+        content: `[edit] I edited my message again — it now reads: ${newText}`,
+        priority: 'next',
+        msgId: editedMsg.message_id,
+        source: 'edit-fold',   // 0.13 D2
+      });
+      logEvent('edit-redelivery-folded', { chat_id: chatId, session_key: sessionKey, msg_id: editedMsg.message_id });
+      return false;
+    }
 
-      // GATE on the REAL edited message (its real from / new text / its own real reply_to, if any).
-      // NOT the synthetic — a self-reply_to would trip shouldHandle.repliesToOtherUser and drop a
-      // paired user editing an un-mentioned message in a mention-gated group.
-      if (!shouldHandle(editedMsg, chatConfig, botUsername)) return false;
+    // GATE on the REAL edited message (its real from / new text / its own real reply_to, if any).
+    // NOT the synthetic — a self-reply_to would trip shouldHandle.repliesToOtherUser and drop a
+    // paired user editing an un-mentioned message in a mention-gated group.
+    if (!shouldHandle(editedMsg, chatConfig, botUsername)) return false;
 
-      // Acknowledge immediately: a silent edit produces no new bubble, so show it registered before
-      // claude's reply lands (the rc.33 lesson). Best-effort; never blocks the re-dispatch.
-      try { react?.(chatId, editedMsg.message_id); } catch { /* best-effort */ }
+    // Acknowledge immediately: a silent edit produces no new bubble, so show it registered before
+    // claude's reply lands (the rc.33 lesson). Best-effort; never blocks the re-dispatch.
+    try { react?.(chatId, editedMsg.message_id); } catch { /* best-effort */ }
 
-      // Synthetic turn: NEW text in the body, OLD text in the reply_to so claude sees the change.
-      // reply_to_message carries `from` + `text` so resolveReplyTo takes the telegram branch and
-      // renders the OLD text — NOT db.getMessage (which now holds the overwritten new text).
-      const cleanNew = mentionRe ? newText.replace(mentionRe, '').trim() : newText.trim();
-      const synthetic = {
-        chat: editedMsg.chat,
+    // Synthetic turn: NEW text in the body, OLD text in the reply_to so claude sees the change.
+    // reply_to_message carries `from` + `text` so resolveReplyTo takes the telegram branch and
+    // renders the OLD text — NOT db.getMessage (which now holds the overwritten new text).
+    const cleanNew = mentionRe ? newText.replace(mentionRe, '').trim() : newText.trim();
+    const synthetic = {
+      chat: editedMsg.chat,
+      message_id: editedMsg.message_id,
+      from: editedMsg.from,
+      text: cleanNew,
+      date: editedMsg.date,
+      ...(threadId && { message_thread_id: Number(threadId) }),
+      reply_to_message: {
         message_id: editedMsg.message_id,
         from: editedMsg.from,
-        text: cleanNew,
+        text: oldText || '',
         date: editedMsg.date,
-        ...(threadId && { message_thread_id: Number(threadId) }),
-        reply_to_message: {
-          message_id: editedMsg.message_id,
-          from: editedMsg.from,
-          text: oldText || '',
-          date: editedMsg.date,
-        },
-        _isReplay: true,   // no new editable row, not replay-eligible, error reply suppressed
-      };
-      dispatchHandleMessage(sessionKey, chatId, synthetic, bot);
-      logEvent('edit-redelivered', {
-        chat_id: chatId, session_key: sessionKey, msg_id: editedMsg.message_id,
-        old_len: (oldText || '').length, new_len: newText.length,
-      });
-      return true;
-    } catch (e) {
-      // Never throw out of the edited_message handler.
-      logger.error?.(`[edit-redelivery] ${e.message}`);
-      return false;
-    }
-  };
+      },
+      _isReplay: true,   // no new editable row, not replay-eligible, error reply suppressed
+    };
+    redeliveredAt.set(interlockKey, Date.now());
+    dispatchHandleMessage(sessionKey, chatId, synthetic, bot);
+    logEvent('edit-redelivered', {
+      chat_id: chatId, session_key: sessionKey, msg_id: editedMsg.message_id,
+      old_len: (oldText || '').length, new_len: newText.length,
+    });
+    return true;
+  } catch (e) {
+    // Never throw out of the edited_message handler.
+    logger.error?.(`[edit-redelivery] ${e.message}`);
+    return false;
+  }
+};
 }
 
 module.exports = { createEditRedelivery };

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 };