polygram 0.8.0 → 0.9.0-rc.2

package/polygram.js

@@ -2,79 +2,90 @@
 /**
  * Telegram Bridge for Claude Code — Persistent Sessions
  *
- * Each chat gets a persistent claude process (stream-json multi-turn).
- * Process stays warm: no cold start, full prompt caching.
+ * Each chat gets a long-lived `@anthropic-ai/claude-agent-sdk` Query
+ * held warm in lib/process-manager-sdk.js. No cold start; full prompt
+ * caching across turns.
  *
  * Architecture:
  *   Telegram (grammy long-poll) → polygram receives message
  *   → looks up per-chat config (model, effort, agent, cwd)
- *   → sends to persistent claude process via stdin (stream-json)
- *   → reads response from stdout (stream-json)
- *   → sends reply to Telegram
+ *   → routes to the per-chat Query via pm.send / pm.injectUserMessage
+ *   → streams the assistant reply back to the chat live
  *   → writes every in/out message to per-bot SQLite (source of truth)
  *
- * Chat commands: /model <model>, /effort <level>, /config
+ * Chat commands: /model, /effort, /config, /context, /compact,
+ *                /new, /reset, /reload, /agent, /stop.
  */
 
+'use strict';
+
 const { Bot } = require('grammy');
-const { spawn } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const processGuard = require('./lib/process-guard');
 const dbClient = require('./lib/db');
-const { migrateJsonToDb, getClaudeSessionId } = require('./lib/sessions');
+const { migrateJsonToDb, getClaudeSessionId } = require('./lib/db/sessions');
 const { buildPrompt } = require('./lib/prompt');
-const { filterAttachments, MAX_FILE_BYTES } = require('./lib/attachments');
-const { ProcessManager } = require('./lib/process-manager');
-// 0.8.0 Phase 3: SDK-backed pm available behind POLYGRAM_USE_SDK=1.
+const { filterAttachments } = require('./lib/attachments');
+// 0.9.0: SDK ProcessManager is the only pm. CLI pm
+// (lib/process-manager.js) deleted in commit 6.
 // Both implementations expose the same public API (constructor +
 // callbacks), so the rest of polygram.js doesn't branch beyond the
 // pick-at-startup. Phase 4 deletes the CLI version after Phase 5
 // soak proves SDK stable. See docs/0.8.0-architecture-decisions.md.
-const { ProcessManagerSdk, extractAssistantText } = require('./lib/process-manager-sdk');
+const { ProcessManagerSdk, extractAssistantText } = require('./lib/sdk/process-manager');
 // rc.42: autosteer-buffer module deleted. Native SDK priority push
 // (pm.injectUserMessage) replaces the buffer + PostToolBatch detour.
 const { createAutosteeredRefs } = require('./lib/autosteered-refs');
-const { makeRouterPolicy, createPmRouter } = require('./lib/pm-router');
+const { createBuildSdkOptions } = require('./lib/sdk/build-options');
+const { createSdkCallbacks } = require('./lib/sdk/callbacks');
+const { createTranscribeVoiceAttachments } = require('./lib/handlers/voice');
+const { createDownloadAttachments } = require('./lib/handlers/download');
+const { createHandleConfigCallback } = require('./lib/handlers/config-callback');
+const { createHandleAbort } = require('./lib/handlers/abort');
+const { createAutosteerHandlers } = require('./lib/handlers/autosteer');
+const { createSlashCommands } = require('./lib/handlers/slash-commands');
+const { createApprovals } = require('./lib/handlers/approvals');
 const { canonicalizeToolInput } = require('./lib/canonical-json');
 const {
-  buildApprovalKeyboard,
   buildApprovalKeyboardWithAlways,
   formatToolInputForCard,
   approvalCardText,
-} = require('./lib/approval-ui');
+} = require('./lib/approvals/ui');
 const { buildHistoryBlock } = require('./lib/history-preload');
 const { formatContextReply, maybeContextFullHint } = require('./lib/context-format');
-const { appendDisplayHint, appendDisplayHintCliArgs } = require('./lib/telegram-prompt');
+// appendDisplayHint moved with buildSdkOptions extraction (commit 18) —
+// only consumer of that import is now lib/sdk/build-options.js itself.
 const { createAbortGrace } = require('./lib/abort-grace');
-const agentLoader = require('./lib/agent-loader');
-const USE_SDK = process.env.POLYGRAM_USE_SDK === '1';
-const { createSender } = require('./lib/telegram');
+const agentLoader = require('./lib/agents/loader');
+const { createSender } = require('./lib/telegram/api');
 const { createAsyncLock } = require('./lib/async-lock');
-const { sweepInbox } = require('./lib/inbox');
+const { sweepInbox } = require('./lib/db/inbox');
 const { parseBotArg, parseDbArg, filterConfigToBot } = require('./lib/config-scope');
-const { createStore: createPairingsStore, parseTtl: parsePairingTtl } = require('./lib/pairings');
-const { transcribe: transcribeVoice, isVoiceAttachment } = require('./lib/voice');
-const { createStreamer } = require('./lib/stream-reply');
-const { chunkMarkdownText } = require('./lib/telegram-chunk');
-const { deliverReplies } = require('./lib/deliver');
+const { createStore: createPairingsStore, parseTtl: parsePairingTtl } = require('./lib/db/pairings');
+const { transcribe: transcribeVoice, isVoiceAttachment } = require('./lib/telegram/voice');
+const { createStreamer } = require('./lib/telegram/streamer');
+const { chunkMarkdownText } = require('./lib/telegram/chunk');
+const { deliverReplies } = require('./lib/telegram/deliver');
 const { announce, shouldAnnounce } = require('./lib/announces');
 const { isAbortRequest } = require('./lib/abort-detector');
-const { startTyping } = require('./lib/typing-indicator');
-const { redactBotToken } = require('./lib/net-errors');
-const { createReactionManager, classifyToolName } = require('./lib/status-reactions');
+const { startTyping } = require('./lib/telegram/typing');
+// redactBotToken moved with download extraction (commit 21) — only
+// consumer is lib/handlers/download.js.
+const { createReactionManager, classifyToolName } = require('./lib/telegram/reactions');
 const { createMediaGroupBuffer } = require('./lib/media-group-buffer');
-const { classify: classifyError, isTransientHttpError } = require('./lib/error-classify');
-const { createAutoResumeTracker, isAutoResumable } = require('./lib/auto-resume');
-const { resolveReplayWindowMs } = require('./lib/replay-window');
-const { validateIpcFileParam } = require('./lib/ipc-file-validator');
+const { classify: classifyError, isTransientHttpError } = require('./lib/error/classify');
+const { createAutoResumeTracker, isAutoResumable } = require('./lib/db/auto-resume');
+const { resolveReplayWindowMs } = require('./lib/db/replay-window');
+// validateIpcFileParam moved with handleSendOverIpc to
+// lib/handlers/ipc-send.js (commit 36).
 const {
   createStore: createApprovalsStore,
   matchesAnyPattern: matchesApprovalPattern,
   tokensEqual: approvalTokensEqual,
   DEFAULT_TIMEOUT_MS: APPROVAL_DEFAULT_TIMEOUT_MS,
-} = require('./lib/approvals');
-const ipcServer = require('./lib/ipc-server');
+} = require('./lib/approvals/store');
+const ipcServer = require('./lib/ipc/server');
 
 // ─── Config ──────────────────────────────────────────────────────────
 //
@@ -107,7 +118,7 @@ let db;
 let tg; // unified sender, created after db opens
 let pairings; // pairings store, created after db opens
 let approvals; // approvals store, created after db opens
-let approvalWaiters = new Map(); // approval_id -> { resolve, reject, timer }
+// approvalWaiters Map moved to lib/handlers/approvals.js (commit 29).
 let approvalSweepTimer = null;
 let ipcCloser = null;
 // BOT_NAME and bot are set once in main() after filterConfigToBot. Because
@@ -124,79 +135,24 @@ let bot = null;       // grammy Bot for BOT_NAME
 // Allowlist of env var names passed through to spawned Claude processes.
 // Anything not listed here is dropped to prevent leaked secrets/ssh agents
 // from being read by a prompt-injected child. Prefixes match any var whose
-// name starts with that string.
-const CHILD_ENV_ALLOWLIST = new Set([
-  'PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'TERM', 'COLORTERM',
-  'TMPDIR', 'TMP', 'TEMP', 'TZ', 'LANG', 'PWD', 'SHLVL',
-]);
-const CHILD_ENV_PREFIXES = ['LC_', 'NODE_', 'CLAUDE_', 'ANTHROPIC_'];
-
-function filterEnv(src) {
-  const out = {};
-  for (const [k, v] of Object.entries(src)) {
-    if (CHILD_ENV_ALLOWLIST.has(k) || CHILD_ENV_PREFIXES.some((p) => k.startsWith(p))) {
-      out[k] = v;
-    }
-  }
-  return out;
-}
+// name starts with that string. (filterEnv + lists moved to
+// lib/sdk/build-options.js with the buildSdkOptions extraction.)
 
-function loadConfig() {
-  config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
-}
+// Config helpers extracted to lib/config.js. Thin wrappers below
+// keep the existing call shape — polygram.js owns the module-level
+// `config` / `stickerMap` / `emojiToSticker` and assigns from the
+// pure I/O functions.
+const configIO = require('./lib/config');
+const { isWellFormedMessage, isWellFormedCallbackQuery } = configIO;
 
+function loadConfig() { config = configIO.loadConfig(CONFIG_PATH); }
 function saveConfig() {
-  // Atomic read-merge-write. In-memory `config` is FILTERED (only one bot +
-  // its chats) because filterConfigToBot narrowed it at boot. Writing it
-  // back directly would clobber every OTHER bot's section on disk. Instead:
-  // read the current on-disk config fresh, apply our bot-scoped changes,
-  // write the merged result. This is safe against parallel writers because
-  // each bot only mutates entries inside its own scope (its bot entry + its
-  // own chats), and we use rename for atomicity.
-  const onDisk = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
-
-  // Apply our bot's changes.
-  if (BOT_NAME && config.bots?.[BOT_NAME]) {
-    onDisk.bots = onDisk.bots || {};
-    onDisk.bots[BOT_NAME] = config.bots[BOT_NAME];
-  }
-  // Apply chat changes — only chats the filter left in our memory belong
-  // to this bot; overwrite those keys, leave the rest of onDisk.chats alone.
-  if (config.chats) {
-    onDisk.chats = onDisk.chats || {};
-    for (const [chatId, chat] of Object.entries(config.chats)) {
-      onDisk.chats[chatId] = chat;
-    }
-  }
-  // Top-level non-bot-scoped fields (defaults, maxWarmProcesses, etc.)
-  // reflect ops-wide policy. Only copy if our in-memory value is newer —
-  // but detecting that is hard; simplest safe rule is: don't touch them
-  // from a bot-scoped process. Leave onDisk's values as-is.
-
-  const tmp = `${CONFIG_PATH}.tmp.${process.pid}`;
-  fs.writeFileSync(tmp, JSON.stringify(onDisk, null, 2));
-  fs.renameSync(tmp, CONFIG_PATH);
+  configIO.saveConfig({ configPath: CONFIG_PATH, botName: BOT_NAME, config });
 }
-
 function loadStickers() {
-  try {
-    const data = JSON.parse(fs.readFileSync(STICKERS_PATH, 'utf8'));
-    for (const [name, s] of Object.entries(data.stickers || {})) {
-      stickerMap[name] = s.file_id;
-      if (s.emoji) emojiToSticker[s.emoji] = s.file_id;
-    }
-    console.log(`Stickers: ${Object.keys(stickerMap).join(', ')}`);
-  } catch { console.log('No sticker map found'); }
-}
-
-// Quick shape check before we start hashing/DB-writing on an update.
-// Telegram updates are user-controlled; a hostile or malformed payload
-// without chat.id / message_id would throw deep in recordInbound.
-function isWellFormedMessage(msg) {
-  return !!(msg
-    && msg.chat
-    && (typeof msg.chat.id === 'number' || typeof msg.chat.id === 'bigint')
-    && typeof msg.message_id === 'number');
+  const { stickerMap: m, emojiToSticker: e } = configIO.loadStickers(STICKERS_PATH);
+  Object.assign(stickerMap, m);
+  Object.assign(emojiToSticker, e);
 }
 
 // ─── Session key — moved to lib/session-key.js so tests can import it. ─
@@ -286,405 +242,27 @@ function logEvent(kind, detail) {
   dbWrite(() => db.logEvent(kind, detail), `log ${kind}`);
 }
 
-function recordInbound(msg) {
-  // 0.6.4 wrapped the body in db.raw.transaction(...) for atomicity, but
-  // the wrap itself runs at call time — before dbWrite's null-db guard
-  // kicks in. A late-arriving inbound during shutdown (after db.raw.close())
-  // would TypeError and unhandled-reject grammy's update handler. Restore
-  // best-effort semantics with an explicit early-out.
-  if (!db) return;
-  const chatId = msg.chat.id.toString();
-  const threadId = msg.message_thread_id?.toString() || null;
-  const user = msg.from?.first_name || msg.from?.username || null;
-  const attachments = extractAttachments(msg);
-  const chatConfig = config.chats[chatId];
-  const ts = (msg.date || Math.floor(Date.now() / 1000)) * 1000;
-
-  // Atomic message + attachments write: all-or-nothing so a half-applied
-  // record can never leave a message row with zero (or partial) attachment
-  // rows that boot replay would silently treat as "no media." Wrapping in
-  // db.raw.transaction also collapses the message + N-attachment fsyncs
-  // into one commit (perf win for media groups: 7-attachment albums go
-  // from 8 sync writes to 1).
-  const writeInbound = db.raw.transaction(() => {
-    db.insertMessage({
-      chat_id: chatId,
-      thread_id: threadId,
-      msg_id: msg.message_id,
-      user,
-      user_id: msg.from?.id || null,
-      text: msg.text || msg.caption || '',
-      reply_to_id: msg.reply_to_message?.message_id || null,
-      direction: 'in',
-      source: 'polygram',
-      bot_name: BOT_NAME,
-      model: chatConfig?.model || null,
-      effort: chatConfig?.effort || null,
-      ts,
-    });
-
-    if (!attachments.length) return;
-    // Look up the just-inserted (or ON-CONFLICT-updated) message row id
-    // so attachments can FK to it. lastInsertRowid is unreliable across
-    // the upsert path; an explicit lookup is cheap and always correct.
-    const messageId = db.getInboundMessageId({ chat_id: chatId, msg_id: msg.message_id });
-    if (!messageId) return;
-    // Edit-safe insert: Telegram edited_message events re-fire
-    // recordInbound with the same (chat_id, msg_id). polygram doesn't
-    // currently handle media-edit cases (Bot API does support
-    // editMessageMedia, but we don't process it specially — the typical
-    // edit is text/caption). If rows already exist for this message_id
-    // they're correct as-is — re-inserting would (a) duplicate them,
-    // (b) reset download_status back to 'pending' and lose the
-    // local_path we already fetched. If we add media-edit support
-    // later, this guard needs to compare file_unique_id and replace
-    // selectively rather than skipping wholesale.
-    if (db.getAttachmentsByMessage(messageId).length > 0) return;
-    for (const att of attachments) {
-      db.insertAttachment({
-        message_id: messageId,
-        chat_id: chatId,
-        msg_id: msg.message_id,
-        thread_id: threadId,
-        bot_name: BOT_NAME,
-        file_id: att.file_id,
-        file_unique_id: att.file_unique_id,
-        kind: att.kind,
-        name: att.name,
-        mime_type: att.mime_type,
-        size_bytes: att.size,
-        ts,
-      });
-    }
-  });
-
-  dbWrite(() => writeInbound(), `insert inbound ${chatId}/${msg.message_id}`);
-}
-
-
-// ─── Attachment download ────────────────────────────────────────────
-
-function sanitizeFilename(name) {
-  if (!name) return 'file';
-  return name.replace(/[\/\\:\0]/g, '_').slice(0, 120);
-}
-
-// Short, filesystem-safe handle from the file_unique_id for auto-gen names.
-// Telegram guarantees file_unique_id is stable per file across sessions; 8
-// chars is collision-safe within a chat (~48 bits) and short enough to read.
-// Falls back to msg.message_id for the rare case where file_unique_id is
-// unset (very old Bot API rows). The pre-0.6.15 pattern embedded message_id
-// directly, which then went stale after media-group reassignment rewrote
-// the row's msg_id → name and msg_id disagreed about which Telegram message
-// the file came from. Using file_unique_id makes the name stable across
-// reassignment.
-function shortFileTag(fileUniqueId, fallback) {
-  if (fileUniqueId) {
-    return String(fileUniqueId).replace(/[^A-Za-z0-9_-]/g, '').slice(0, 8) || String(fallback);
-  }
-  return String(fallback);
-}
-
-function extractAttachments(msg) {
-  // Media-group bundling path: when we synthesised a single message from
-  // several siblings sharing a media_group_id, the merged attachment list
-  // was pre-computed in `_mergedAttachments`. Return it directly instead
-  // of running the per-field extraction against the primary message.
-  if (Array.isArray(msg._mergedAttachments)) return msg._mergedAttachments;
-
-  const items = [];
-  if (msg.document) {
-    const d = msg.document;
-    items.push({
-      file_id: d.file_id,
-      file_unique_id: d.file_unique_id,
-      name: d.file_name || `document-${shortFileTag(d.file_unique_id, msg.message_id)}`,
-      mime_type: d.mime_type || 'application/octet-stream',
-      size: d.file_size || 0,
-      kind: 'document',
-    });
-  }
-  if (msg.photo && msg.photo.length > 0) {
-    const largest = msg.photo[msg.photo.length - 1];
-    items.push({
-      file_id: largest.file_id,
-      file_unique_id: largest.file_unique_id,
-      name: `photo-${shortFileTag(largest.file_unique_id, msg.message_id)}.jpg`,
-      mime_type: 'image/jpeg',
-      size: largest.file_size || 0,
-      kind: 'photo',
-    });
-  }
-  if (msg.voice) {
-    items.push({
-      file_id: msg.voice.file_id,
-      file_unique_id: msg.voice.file_unique_id,
-      name: `voice-${shortFileTag(msg.voice.file_unique_id, msg.message_id)}.ogg`,
-      mime_type: msg.voice.mime_type || 'audio/ogg',
-      size: msg.voice.file_size || 0,
-      kind: 'voice',
-    });
-  }
-  if (msg.audio) {
-    const a = msg.audio;
-    items.push({
-      file_id: a.file_id,
-      file_unique_id: a.file_unique_id,
-      name: a.file_name || `audio-${shortFileTag(a.file_unique_id, msg.message_id)}.mp3`,
-      mime_type: a.mime_type || 'audio/mpeg',
-      size: a.file_size || 0,
-      kind: 'audio',
-    });
-  }
-  if (msg.video) {
-    const v = msg.video;
-    items.push({
-      file_id: v.file_id,
-      file_unique_id: v.file_unique_id,
-      name: v.file_name || `video-${shortFileTag(v.file_unique_id, msg.message_id)}.mp4`,
-      mime_type: v.mime_type || 'video/mp4',
-      size: v.file_size || 0,
-      kind: 'video',
-    });
-  }
-  return items;
-}
+// recordInbound extracted to lib/handlers/record-inbound.js. Wired
+// in main() once db + config + extractAttachments are available.
+let recordInbound = null;
 
-async function transcribeVoiceAttachments(downloaded, { chatId, msgId, label, botApi, threadId }) {
-  const voiceCfg = config.bot?.voice || config.voice;
-  if (!voiceCfg?.enabled) return { ackEmitted: false };
-  const provider = voiceCfg.provider || 'openai';
-  const providerCfg = voiceCfg[provider] || {};
-  const targets = downloaded.filter((a) => isVoiceAttachment(a) && a.path);
-  if (!targets.length) return { ackEmitted: false };
-
-  // Acknowledge receipt with a reaction so the user knows we heard them.
-  // Cheap, robust (no state), and survives transcription failure.
-  // 0.7.4 (item G): we report `ackEmitted: true` so the caller can skip
-  // the reactor's QUEUED → 👀 transition. Pre-fix, 👂 was visible for
-  // ~milliseconds before 👀 overwrote it on the same message — wasted
-  // API call and confusing flicker. Now 👂 stays until Claude actually
-  // starts work and the reactor flips to THINKING (🤔).
-  const ack = voiceCfg.ackReaction || '👂';
-  let ackEmitted = false;
-  if (ack && botApi) {
-    ackEmitted = true;
-    tg(botApi, 'setMessageReaction', {
-      chat_id: chatId, message_id: msgId,
-      reaction: [{ type: 'emoji', emoji: ack }],
-    }, { source: 'voice-ack', botName: BOT_NAME }).catch((err) => {
-      console.error(`[${label}] voice ack reaction failed: ${err.message}`);
-    });
-  }
 
-  await Promise.all(targets.map(async (a) => {
-    try {
-      const opts = {
-        provider,
-        ...providerCfg,
-        language: voiceCfg.language || 'auto',
-        maxDurationSec: voiceCfg.maxDurationSec,
-        maxDurationBytesPerSec: voiceCfg.maxDurationBytesPerSec,
-      };
-      const r = await transcribeVoice(a.path, opts);
-      a.transcription = r;
-      console.log(`[${label}] transcribed ${a.kind} (${r.duration_sec?.toFixed?.(1) || '?'}s, ${r.text.length} chars)`);
-      logEvent('voice-transcribed', {
-        chat_id: chatId, msg_id: msgId,
-        provider: r.provider, language: r.language,
-        duration_sec: r.duration_sec, chars: r.text.length,
-        cost_usd: r.cost_usd,
-      });
-    } catch (err) {
-      console.error(`[${label}] transcribe failed for ${a.name}: ${err.message}`);
-      logEvent('voice-transcribe-failed', {
-        chat_id: chatId, msg_id: msgId, name: a.name, error: err.message,
-      });
-    }
-  }));
+// ─── Attachment extraction ──────────────────────────────────────────
+// extractAttachments + shortFileTag live in lib/handlers/extract-attachments.js.
+// sanitizeFilename moved with downloadAttachments to lib/handlers/download.js.
+const { extractAttachments } = require('./lib/handlers/extract-attachments');
+const { createRecordInbound } = require('./lib/handlers/record-inbound');
+const { createHandleSendOverIpc } = require('./lib/handlers/ipc-send');
+const { createDispatcher } = require('./lib/handlers/dispatcher');
+const { createPollLoop } = require('./lib/handlers/poll');
 
-  // Persist transcription:
-  //   - Per-attachment: setAttachmentTranscription stores the full
-  //     transcription object (text + language + duration + provider) as
-  //     JSON in the attachments.transcription column. buildVoiceTags
-  //     parses it back when building the prompt.
-  //   - Message-level: setMessageText updates messages.text with the
-  //     combined transcript so FTS finds "what Maria said" via the
-  //     normal chat search path.
-  const successful = targets.filter((a) => a.transcription?.text);
-  if (!successful.length) return { ackEmitted };
-  for (const a of successful) {
-    if (a.id != null) {
-      dbWrite(() => db.setAttachmentTranscription(a.id, JSON.stringify(a.transcription)),
-        `setAttachmentTranscription ${a.id}`);
-    }
-  }
-  const combinedText = successful.map((a) => a.transcription.text).join(' ').trim();
-  dbWrite(() => db.setMessageText({
-    chat_id: chatId, msg_id: msgId, text: combinedText,
-  }), 'persist voice transcription');
-  return { ackEmitted };
-}
+// transcribeVoiceAttachments extracted to lib/handlers/voice.js.
+// Wired in main() once db + tg + config are available.
+let transcribeVoiceAttachments = null;
 
-// Bounded concurrency for parallel fetches. A 10-photo album used to be
-// 10× per-photo latency (each `await fetch` was serial); now in-flight
-// downloads are capped to a small pool. Telegram's per-bot rate limit is
-// ~30 req/s, so 6 concurrent fetches is comfortably under and keeps the
-// happy path responsive without burning sockets on a 100-file edge case.
-// Override via `config.bot.attachmentConcurrency` (per-bot) for ops-time
-// rate-limit tuning.
-const ATTACHMENT_DOWNLOAD_CONCURRENCY_DEFAULT = 6;
-function attachmentConcurrency() {
-  const v = Number(config.bot?.attachmentConcurrency);
-  return (Number.isInteger(v) && v > 0) ? v : ATTACHMENT_DOWNLOAD_CONCURRENCY_DEFAULT;
-}
-
-// Per-attachment download. Pure function over (att, deps) → result. Pulled
-// out of the loop so downloadAttachments can run several in parallel.
-async function downloadOneAttachment(bot, token, chatId, msg, chatDir, att) {
-  // Reuse path: row already says downloaded AND the file is on disk.
-  if (att.download_status === 'downloaded' && att.local_path) {
-    try {
-      if (fs.statSync(att.local_path).size > 0) {
-        return { ...att, path: att.local_path, size: att.size_bytes || 0, error: null };
-      }
-    } catch { /* fall through to refetch */ }
-  }
-  try {
-    const fileInfo = await bot.api.getFile(att.file_id);
-    if (!fileInfo?.file_path) throw new Error('no file_path from getFile');
-    const url = `https://api.telegram.org/file/bot${token}/${fileInfo.file_path}`;
-    const res = await fetch(url);
-    if (!res.ok) throw new Error(`HTTP ${res.status}`);
-    // Three-layer size enforcement, in order of cheapness:
-    //   1. Content-Length header — fail-fast before reading any body.
-    //   2. Streaming chunk-by-chunk accumulation — abort the moment the
-    //      cumulative byte count crosses the cap. This is the layer that
-    //      protects against an attacker omitting Content-Length: pre-0.6.14
-    //      we read the whole `res.arrayBuffer()` into RAM first and only
-    //      then checked the size. With the per-bot ATTACHMENT_DOWNLOAD_
-    //      CONCURRENCY default of 6, six unbounded reads in flight could
-    //      pin arbitrary RSS — real OOM angle for a malicious upload.
-    //   3. Final post-buffer check is now redundant but cheap; left as
-    //      defense-in-depth in case the streaming logic is ever changed.
-    const cl = parseInt(res.headers.get('content-length') || '0', 10);
-    if (cl > MAX_FILE_BYTES) {
-      throw new Error(`content-length ${cl} exceeds per-file cap ${MAX_FILE_BYTES}`);
-    }
-    let total = 0;
-    const chunks = [];
-    if (res.body && typeof res.body.getReader === 'function') {
-      const reader = res.body.getReader();
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        total += value.byteLength;
-        if (total > MAX_FILE_BYTES) {
-          try { await reader.cancel(); } catch {}
-          throw new Error(`stream ${total}+ bytes exceeds per-file cap ${MAX_FILE_BYTES}`);
-        }
-        chunks.push(value);
-      }
-    } else {
-      // Fallback for runtimes without WHATWG streams (shouldn't fire on
-      // Node 22+). Same arrayBuffer path as before, with the post-check.
-      const ab = await res.arrayBuffer();
-      if (ab.byteLength > MAX_FILE_BYTES) {
-        throw new Error(`body ${ab.byteLength} bytes exceeds per-file cap ${MAX_FILE_BYTES}`);
-      }
-      chunks.push(new Uint8Array(ab));
-      total = ab.byteLength;
-    }
-    const buf = Buffer.concat(chunks.map((c) => Buffer.from(c.buffer, c.byteOffset, c.byteLength)));
-    if (buf.length > MAX_FILE_BYTES) {
-      throw new Error(`body ${buf.length} bytes exceeds per-file cap ${MAX_FILE_BYTES}`);
-    }
-    const safeName = sanitizeFilename(att.name);
-    // Embed file_unique_id so two attachments with the same msg_id+name
-    // (album, resend) can't silently overwrite each other. Telegram
-    // guarantees file_unique_id is stable and globally unique per file.
-    const uniq = att.file_unique_id ? `-${att.file_unique_id}` : '';
-    const localName = `${msg.message_id}${uniq}-${safeName}`;
-    const localPath = path.join(chatDir, localName);
-    // Atomic write: create a temp with the unique PID+timestamp suffix,
-    // fill it, then rename to the canonical name. A crash mid-write leaves
-    // a `.tmp.*` file (swept later) rather than a truncated canonical file
-    // that the EEXIST dedup branch would happily serve on next request.
-    if (fs.existsSync(localPath)) {
-      console.log(`[attach] ${chatId} ← ${att.kind} ${safeName} (already on disk, reusing)`);
-    } else {
-      const tmpPath = `${localPath}.tmp.${process.pid}.${Date.now()}`;
-      try {
-        fs.writeFileSync(tmpPath, buf, { flag: 'wx' });
-        fs.renameSync(tmpPath, localPath);
-      } catch (e) {
-        // Clean up stray tmp on any failure; if the rename fell through
-        // because another process beat us, EEXIST on the target is fine.
-        try { fs.unlinkSync(tmpPath); } catch {}
-        if (e.code !== 'EEXIST') throw e;
-        console.log(`[attach] ${chatId} ← ${att.kind} ${safeName} (race: already on disk)`);
-      }
-    }
-    console.log(`[attach] ${chatId} ← ${att.kind} ${safeName} (${buf.length} bytes) → ${localPath}`);
-    dbWrite(() => db.markAttachmentDownloaded(att.id, {
-      local_path: localPath, size_bytes: att.size_bytes || buf.length,
-    }), `markAttachmentDownloaded ${att.id}`);
-    return { ...att, path: localPath, size: att.size_bytes || buf.length, error: null };
-  } catch (err) {
-    // Don't drop the attachment silently — push it through with the
-    // failure noted. buildAttachmentTags renders this as
-    // <attachment-failed reason="..." /> so claude tells the user
-    // "I couldn't see your <kind>" instead of pretending it received
-    // text only.
-    //
-    // Token redaction: the fetch URL embeds bot${TOKEN} (Telegram CDN
-    // requirement) and some undici/network error variants stringify
-    // the request including the URL into err.message. Persisting that
-    // raw to attachments.download_error or stderr would leak the bot
-    // token. 0.6.14: centralized in net-errors.redactBotToken which
-    // also handles URL-encoded (%3A) variants and bare token shapes
-    // missed by the original regex.
-    const raw = (err.message || 'unknown').slice(0, 200);
-    const reason = redactBotToken(raw);
-    console.error(`[attach] download failed for ${att.name}: ${reason}`);
-    dbWrite(() => db.markAttachmentFailed(att.id, reason),
-      `markAttachmentFailed ${att.id}`);
-    return { ...att, path: null, error: reason };
-  }
-}
-
-// 0.6.0: takes attachment ROW objects from the DB (not raw extracted
-// metadata). Each row has an `id` so we can mark status as we go.
-// On replay: a row with status='downloaded' and a local_path that's
-// still on disk is reused without re-fetching. Anything else (failed,
-// missing file, never downloaded) hits Telegram's CDN.
-//
-// 0.6.7: parallel fetches with bounded concurrency. The inner work is
-// stateless per-attachment (only writes go to DB / disk via paths
-// keyed on file_unique_id, so two parallel downloads can't collide).
-// Order of `results` is preserved by writing into a fixed-size array
-// at the original index — important so the prompt sees attachments in
-// the same order the user sent them in an album.
-async function downloadAttachments(bot, token, chatId, msg, rows) {
-  if (!rows.length) return [];
-  const chatDir = path.join(INBOX_DIR, String(chatId));
-  fs.mkdirSync(chatDir, { recursive: true });
-
-  const results = new Array(rows.length);
-  let cursor = 0;
-  const workers = Array.from(
-    { length: Math.min(attachmentConcurrency(), rows.length) },
-    async () => {
-      while (true) {
-        const idx = cursor++;
-        if (idx >= rows.length) return;
-        results[idx] = await downloadOneAttachment(bot, token, chatId, msg, chatDir, rows[idx]);
-      }
-    },
-  );
-  await Promise.all(workers);
-  return results;
-}
+// downloadAttachments extracted to lib/handlers/download.js. Wired
+// in main() once config + db + dbWrite + INBOX_DIR are available.
+let downloadAttachments = null;
 
 
 // ─── Prompt formatting ──────────────────────────────────────────────
@@ -787,222 +365,11 @@ async function clearAutosteeredReactions(sessionKey) {
   return autosteeredRefs.clear(sessionKey);
 }
 
-function spawnClaude(sessionKey, ctx) {
-  const { chatConfig, existingSessionId, label, chatId } = ctx;
-  // 0.7.3: Claude Code's Chrome-extension integration (browser
-  // automation via the "Claude in Chrome" extension) is OPT-IN and
-  // NOT enabled by default in `claude`. Polygram lets chats turn it
-  // on via `config.chats.<id>.chrome: true` (chat-level wins) or
-  // `config.bot.chrome: true` (per-bot default). When opting in, the
-  // extension must be installed in the daemon-user's Chrome and the
-  // user must have a live Aqua session (so Chrome is running). Falls
-  // back to --no-chrome for chats that don't opt in (matches our
-  // pre-0.7.3 default — defensive against any "enabled by default"
-  // that might have been set in claude's persistent state).
-  const wantChrome = chatConfig.chrome != null
-    ? chatConfig.chrome === true
-    : config.bot?.chrome === true;
-  const args = [
-    '-p',
-    '--input-format', 'stream-json',
-    '--output-format', 'stream-json',
-    '--verbose',
-    '--model', chatConfig.model || config.defaults.model,
-    '--effort', chatConfig.effort || config.defaults.effort,
-    '--permission-mode', 'bypassPermissions',
-    wantChrome ? '--chrome' : '--no-chrome',
-  ];
-  if (chatConfig.agent) args.push('--agent', chatConfig.agent);
-  if (existingSessionId) args.push('--resume', existingSessionId);
-  // Polygram-side display constraints — same hint the SDK pm appends
-  // via Options.systemPrompt. Keeps the table-width rule in
-  // infrastructure, not in agent docs.
-  args.push(...appendDisplayHintCliArgs());
-
-  console.log(`[${label}] Spawning process (${chatConfig.model}/${chatConfig.effort})`);
-
-  // Scrub env to an allowlist: under bypassPermissions a prompt-injected
-  // child can exfiltrate any env var, so we pass only what Claude Code and
-  // normal shell tools need. TELEGRAM_BOT_TOKEN is opt-in per bot via
-  // config.bot.needsToken — partner bots go through polygram for every
-  // outbound message and never need direct API access.
-  const botConfig = config.bot || {};
-  const childEnv = filterEnv(process.env);
-  childEnv.HOME = CHILD_HOME;
-  childEnv.CLAUDE_CHANNEL_BOT = BOT_NAME;
-  // Approval hook integration: the hook runs as a child of Claude and reads
-  // these to route its IPC. POLYGRAM_TURN_ID isn't set here (one session can
-  // run many turns) — the hook treats it as optional.
-  childEnv.POLYGRAM_BOT = BOT_NAME;
-  childEnv.POLYGRAM_CHAT_ID = String(chatId || '');
-  // Allow the PreToolUse approval hook to authenticate to the IPC socket.
-  if (process.env.POLYGRAM_IPC_SECRET) childEnv.POLYGRAM_IPC_SECRET = process.env.POLYGRAM_IPC_SECRET;
-  if (botConfig.needsToken) {
-    childEnv.TELEGRAM_BOT_TOKEN = botConfig.token || '';
-  }
-
-  const proc = spawn(CLAUDE_BIN, args, {
-    cwd: chatConfig.cwd,
-    env: childEnv,
-    stdio: ['pipe', 'pipe', 'pipe'],
-  });
-  proc.stderr.on('data', (d) => {
-    const m = d.toString().trim();
-    if (m) console.error(`[${label}] stderr: ${m.slice(0, 200)}`);
-  });
-  return proc;
-}
-
-/**
- * 0.8.0 Phase 3 — SDK pm spawn factory.
- *
- * Replacement for `spawnClaude` when POLYGRAM_USE_SDK=1. Returns
- * SdkOptions for the SDK pm to pass to `query({ prompt, options })`.
- * The SDK pm wraps this in its inputController + iteration loop;
- * polygram only needs to compose the Options object.
- *
- * Per v4 plan §6.5.7 — explicit env enumeration (Options.env is
- * SHADOW per Phase 0 gate 33), bypassPermissions +
- * allowDangerouslySkipPermissions both set for forward-compat,
- * agent-loader composes per-chat agent into systemPrompt + skills +
- * mcpServers, optional resume sessionId for continuity.
- */
-function buildSdkOptions(sessionKey, ctx) {
-  const { chatConfig, existingSessionId, label, chatId, threadId } = ctx;
-
-  // rc.48: per-topic config overrides. When `topics[threadId]` is an
-  // object (not a legacy string label), these fields take precedence
-  // over chat-level config. Principal use case: scope a single topic
-  // to a different agent, cwd, or permissionMode (e.g. flip music
-  // topic from `bypassPermissions` to `default` so settings.json
-  // permissions.allow gates apply).
-  //
-  // Per-topic overrides only apply meaningfully when isolateTopics is
-  // true — each topic has its own SDK Query. With isolateTopics: false
-  // all topics share one Query whose options are fixed at first-spawn.
-  // Startup validation (validateTopicConfigs) emits a one-time warning
-  // when a chat has topic overrides + isolateTopics: false.
-  const topicConfig = getTopicConfig(chatConfig, threadId);
-  const effectiveAgent = topicConfig.agent || chatConfig.agent;
-
-  // Per-chat agent (D14): if pinned, load & compose. Failure is
-  // non-fatal — chat falls back to defaults; logged for ops.
-  let agentBundle = null;
-  if (effectiveAgent) {
-    try {
-      agentBundle = agentLoader.loadAgent(effectiveAgent, {
-        homeDir: CHILD_HOME,
-        // Pass cwd so the loader checks Claude Code's project-level
-        // path (`<cwd>/.claude/agents/<name>.md`) before the
-        // user-level path or polygram's directory convention. rc.48:
-        // topic-level cwd takes precedence so topic-scoped agents
-        // load from the topic's project dir.
-        cwd: topicConfig.cwd || chatConfig.cwd,
-        logger: console,
-      });
-    } catch (err) {
-      console.error(`[${label}] agent-loader: ${err.message}`);
-      logEvent('agent-load-failed', {
-        chat_id: chatId, agent: effectiveAgent, error: err.message,
-        topic: threadId || null,
-      });
-    }
-  }
-
-  const effectiveModel = topicConfig.model || chatConfig.model;
-  const effectiveEffort = topicConfig.effort || chatConfig.effort;
-  const agentSuffix = effectiveAgent && effectiveAgent !== chatConfig.agent
-    ? ` agent=${effectiveAgent}` : '';
-  console.log(`[${label}] Spawning SDK Query (${effectiveModel}/${effectiveEffort}${agentSuffix})`);
-
-  // Env: SHADOW semantics (gate 33) — must enumerate every var
-  // pollygram needs in the spawned worker.
-  const botConfig = config.bot || {};
-  const childEnv = filterEnv(process.env);
-  childEnv.HOME = CHILD_HOME;
-  childEnv.CLAUDE_CHANNEL_BOT = BOT_NAME;
-  if (process.env.POLYGRAM_IPC_SECRET) {
-    childEnv.POLYGRAM_IPC_SECRET = process.env.POLYGRAM_IPC_SECRET;
-  }
-  if (botConfig.needsToken) {
-    childEnv.TELEGRAM_BOT_TOKEN = botConfig.token || '';
-  }
-
-  // 0.8.0 Phase 2 step 6: in-process approval flow via canUseTool.
-  // Wire up only when approvals.gatedTools is configured for this
-  // bot — otherwise leave canUseTool unset and rely on
-  // bypassPermissions for the full allow-all path.
-  const apprCfg = config.bot?.approvals;
-  const useCanUseTool = apprCfg && apprCfg.adminChatId
-    && Array.isArray(apprCfg.gatedTools) && apprCfg.gatedTools.length > 0;
-
-  // rc.42: PostToolBatch hook removed. Native SDK priority push
-  // (pm.injectUserMessage) replaces the absorb-via-additionalContext
-  // detour. The autosteered ✍ reaction now clears via the regular
-  // turn-end path (handleMessage finally + success branches —
-  // existing rc.38 cleanup).
-
-  // rc.52: dropped the SDK SessionStart hook registration. The hook
-  // never fired in production (verified: zero history-preloaded events
-  // across both production DBs since rc.21; SDK runtime grep showed
-  // exactly one occurrence of "SessionStart" — in the type listing,
-  // not in dispatch logic). The history preload is now done inline at
-  // formatPrompt time when the upcoming Query has no resume target,
-  // via lib/history-preload.buildHistoryBlock. See formatPrompt above.
-  const baseOpts = {
-    model: chatConfig.model || config.defaults.model,
-    effort: chatConfig.effort || config.defaults.effort,
-    cwd: chatConfig.cwd,
-    env: childEnv,
-    // permissionMode 'default' when canUseTool is wired (so the SDK
-    // actually consults our callback). Otherwise stick with
-    // bypassPermissions (matches today's CLI behaviour).
-    permissionMode: useCanUseTool ? 'default' : 'bypassPermissions',
-    allowDangerouslySkipPermissions: !useCanUseTool,
-    ...(useCanUseTool && { canUseTool: makeCanUseTool(sessionKey) }),
-    hooks: {},
-    executable: 'node',
-    ...(existingSessionId && { resume: existingSessionId }),
-    ...(process.env.POLYGRAM_CLAUDE_BIN && {
-      pathToClaudeCodeExecutable: process.env.POLYGRAM_CLAUDE_BIN,
-    }),
-  };
-
-  // Compose with agent overlay + chat-level config + per-topic overrides.
-  // agent-loader precedence: topicConfig > chatConfig > agent > defaults.
-  // The chatConfig keys we care about for SDK options are
-  // model/effort/cwd/thinking; others (agent, chrome, isolateTopics)
-  // are polygram-only and stripped by composeSdkOptions.
-  const composed = agentLoader.composeSdkOptions(
-    {
-      // chat-level overrides — only the keys SDK understands.
-      model: chatConfig.model,
-      effort: chatConfig.effort,
-      cwd: chatConfig.cwd,
-      ...(chatConfig.thinking && { thinking: chatConfig.thinking }),
-    },
-    agentBundle,
-    baseOpts,
-    topicConfig,  // rc.48: highest precedence — overrides chat-level fields.
-  );
-
-  // rc.48: keep permissionMode + allowDangerouslySkipPermissions
-  // consistent. baseOpts sets allowDangerouslySkipPermissions=true when
-  // permissionMode='bypassPermissions'. If a topic flipped permissionMode
-  // to anything else (typically 'default' to gate via settings.json),
-  // also disable allowDangerouslySkipPermissions so the SDK actually
-  // honours the permission gates instead of skipping them.
-  if (composed.permissionMode && composed.permissionMode !== 'bypassPermissions') {
-    composed.allowDangerouslySkipPermissions = false;
-  }
-
-  // Append polygram's display constraints to the systemPrompt.
-  // Infrastructure-layer hint — the agent's own prompt covers
-  // business logic; polygram adds "your output renders in Telegram,
-  // here's the width budget for tables".
-  composed.systemPrompt = appendDisplayHint(composed.systemPrompt);
-  return composed;
-}
+// SDK pm spawn factory — extracted to lib/sdk/build-options.js.
+// `buildSdkOptions` is wired in main() via createBuildSdkOptions(deps)
+// once the runtime context (config, BOT_NAME, makeCanUseTool, logEvent)
+// is available.
+let buildSdkOptions = null;
 
 function buildSpawnContext(sessionKey) {
   const chatId = getChatIdFromKey(sessionKey);
@@ -1069,293 +436,28 @@ async function sendToProcess(sessionKey, prompt, context = {}) {
 //   - emit a `queue-depth-warning` event if the count ever exceeds a
 //     threshold (abnormal inbound rate, slow pre-work, stuck bot)
 //   - (future) drain on shutdown if we want clean exit
-// Threshold for the queue-depth-warning event (operator-tuned signal
-// for "this session is getting hammered"). Override via
-// `config.bot.queueWarnThreshold`. Below the threshold no event fires.
-const CONCURRENT_WARN_THRESHOLD_DEFAULT = 20;
-function queueWarnThreshold() {
-  const v = Number(config.bot?.queueWarnThreshold);
-  return (Number.isInteger(v) && v > 0) ? v : CONCURRENT_WARN_THRESHOLD_DEFAULT;
-}
-const inFlightHandlers = new Map(); // sessionKey → count
-
-// Set true by the SIGTERM/SIGINT handler. Module-scoped so the
-// fire-and-forget catch in dispatchHandleMessage can check it: when
-// polygram is going down, in-flight handlers reject with "Process
-// killed" / "Process exited" but those failures aren't "real" — the
-// next boot's replay will re-dispatch them. Suppressing the user-facing
-// error reply during shutdown removes a misleading post-mortem apology
-// the user shouldn't see. (The boot replay's own _isReplay flag handles
-// the OTHER half: suppressing if the replay itself fails.)
+// dispatcher state. The dispatcher itself (errorReplyText,
+// queueWarnThreshold, dispatchHandleMessage, attemptAutoResume,
+// inFlightHandlers Map) lives in lib/handlers/dispatcher.js;
+// polygram owns the abortGrace + autoResumeTracker instances
+// + the isShuttingDown flag and threads them in.
 let isShuttingDown = false;
-
-// Map a handler-error to a user-facing reply that says what happened
-// and what to do next. The technical strings come from process-manager
-// (idle / wall-clock timeouts) and node child_process (Process exited /
-// killed). Anything we don't recognise falls back to a generic line
-// with a single-line snippet of the error so the user can at least
-// distinguish unique failures from the obvious "try again" cases.
-// 0.7.7: errorReplyText delegates to lib/error-classify.js so the
-// regex tables live in one place and stay in sync with future SDK
-// error subtypes (the 0.8.0 migration extends the classifier rather
-// than adding more if-branches here).
-//
-// classify() returns { kind, userMessage, isTransient, autoRecover }.
-// `userMessage: null` is a deliberate "suppress reply" signal —
-// today only used by INTERRUPTED in the abort-grace window. Callers
-// that already gate on isSessionRecentlyAborted will short-circuit
-// before reaching here, but we honour `null` defensively.
-function errorReplyText(err) {
-  const { userMessage } = classifyError(err);
-  return userMessage; // may be null — caller must handle
-}
-
-// Sessions the operator just /stop'd (or natural-language "стоп").
-// rc.25: extracted to lib/abort-grace.js so the timestamp/window
-// logic has its own unit tests. Behaviour identical: any pending
-// rejected within the grace window is considered abort-caused —
-// its generic error reply is suppressed and the streamer warning
-// is skipped.
 const abortGrace = createAbortGrace();
-
 function markSessionAborted(sessionKey) { abortGrace.mark(sessionKey); }
 function isSessionRecentlyAborted(sessionKey) { return abortGrace.isRecent(sessionKey); }
-
-// rc.54: per-session cooldown for auto-resume on 300s no-activity
-// timeout. Without the cooldown, a permanently-wedged tool would
-// trigger an infinite resume → timeout → resume loop.
 const autoResumeTracker = createAutoResumeTracker();
+const contextHintShown = new Set();
+let dispatchHandleMessage = null;
+let attemptAutoResume = null;
+let errorReplyText = null;
+let queueWarnThreshold = null;
+let inFlightHandlers = null;
 
 // rc.59: once-per-cycle gate for the contextHint. A session is added
 // to this Set when the hint fires, removed when the SDK emits
 // compact_boundary (so the next cycle can fire its own hint). Without
 // this gate, a chat over-threshold would see the hint on every turn
 // until auto-compact — noisy enough that Ivan called it out.
-const contextHintShown = new Set();
-
-// rc.54: spawn a fresh Query resuming the same session_id and ask
-// Claude to continue the timed-out work. The killed pm Query has
-// already torn down the wedged subprocess (via pm.kill on timeout);
-// getOrSpawnForChat creates a new entry that picks up the saved
-// session_id from `sessions` table and sets `--resume <id>` on the
-// SDK Options. The continuation message tells Claude what happened
-// and that it has full prior context to keep going.
-//
-// Returns the result.text on success (already-sent to chat); throws
-// on any failure (caller writes auto-resume-failed event + falls
-// back to the standard timeout reply).
-async function attemptAutoResume(sessionKey, chatId, originalMsg, bot) {
-  const threadId = originalMsg.message_thread_id || null;
-  // 1. Tell the user we're auto-resuming so they don't think nothing
-  //    happened. Threaded under the original user message.
-  await tg(bot, 'sendMessage', {
-    chat_id: chatId,
-    text: '🔁 Auto-resuming after timeout — continuing where the previous turn left off.',
-    reply_parameters: { message_id: originalMsg.message_id },
-    ...(threadId && { message_thread_id: threadId }),
-  }, { source: 'auto-resume-indicator', botName: BOT_NAME }).catch((sendErr) => {
-    // Indicator is informational; don't fail the whole resume on it.
-    console.error(`[${sessionKey}] auto-resume indicator send failed: ${sendErr.message}`);
-  });
-
-  // 2. Continuation prompt. Plain text — no XML wrapper. The SDK
-  //    Query resumes the saved session_id, so Claude has full prior
-  //    transcript context including its own partially-streamed text
-  //    and tool calls. We just need to tell it WHAT happened and
-  //    that it should pick up where it left off.
-  const continuation = '[polygram] Your previous turn timed out at 300s with no Claude activity (likely a wedged tool call — long Bash, hanging MCP, or stuck subagent). Continue from where you left off; do not restart from scratch. If the same operation would just hang again, abort it and tell me.';
-
-  // 3. No-op streamer + reactor. We don't need to stream the resume
-  //    turn's response (we'll send it as one message at the end). pm
-  //    invokes streamer/reactor methods only when present; passing
-  //    minimal stubs keeps pm happy.
-  const noopStreamer = {
-    onChunk: async () => {},
-    forceNewMessage: () => {},
-    finalize: async () => ({ streamed: false }),
-    flushDraft: async () => {},
-    discard: async () => {},
-  };
-  const noopReactor = {
-    setState: () => {},
-    heartbeat: () => {},
-    clear: async () => {},
-    stop: () => {},
-  };
-
-  const result = await sendToProcess(sessionKey, continuation, {
-    streamer: noopStreamer,
-    reactor: noopReactor,
-    sourceMsgId: originalMsg.message_id,
-    threadId,
-    onFirstStream: () => {},
-  });
-
-  if (result?.error) {
-    throw new Error(`auto-resume turn errored: ${String(result.error).slice(0, 200)}`);
-  }
-  if (!result?.text) {
-    throw new Error('auto-resume turn produced no text');
-  }
-
-  // 4. Send the continuation reply as regular Telegram message(s),
-  //    threaded under the original user message. Reuse the existing
-  //    chunked-delivery + markdown-formatting primitives.
-  const chunks = chunkMarkdownText(result.text, TG_MAX_LEN);
-  await deliverReplies({
-    bot,
-    send: (b, method, params, m) => tg(b, method, params, m),
-    chatId,
-    threadId,
-    chunks,
-    replyToMessageId: originalMsg.message_id,
-    meta: { source: 'auto-resume-reply', botName: BOT_NAME },
-    logger: { error: (m) => console.error(`[${sessionKey}] auto-resume deliver: ${m}`) },
-  });
-
-  return result.text;
-}
-
-// Called by bot.on('message') for every regular (non-admin, non-pair)
-// message. Runs handleMessage in a fire-and-forget manner with centralised
-// error handling. Replaces the old processQueue loop.
-function dispatchHandleMessage(sessionKey, chatId, msg, bot) {
-  const count = (inFlightHandlers.get(sessionKey) || 0) + 1;
-  inFlightHandlers.set(sessionKey, count);
-  const warnAt = queueWarnThreshold();
-  if (count === warnAt) {
-    logEvent('queue-depth-warning', {
-      chat_id: chatId, session_key: sessionKey,
-      in_flight: count, threshold: warnAt,
-    });
-  }
-  handleMessage(sessionKey, chatId, msg, bot).catch((err) => {
-    const wasAborted = isSessionRecentlyAborted(sessionKey);
-    const isReplay = msg._isReplay === true;
-    console.error(`[${sessionKey}] Error:`, err.message);
-    // Mark the row terminal so the right thing happens on next boot:
-    // - aborted: user explicitly stopped → 'aborted' (not replayable)
-    // - shutting down on a NEW turn: 'replay-pending' so the next
-    //   boot picks it up via getReplayCandidates. Pre-0.6.12 we marked
-    //   'failed' here, which excluded the row from replay — a clean
-    //   restart between user send and reply silently dropped the turn.
-    // - shutting down on a REPLAY turn (msg._isReplay=true): keep
-    //   'replay-attempted' so the one-shot guard from 0.6.4 still
-    //   holds. Without this, a replay interrupted by another shutdown
-    //   would be promoted to 'replay-pending' and the next boot would
-    //   replay it AGAIN — infinite loop on chained shutdowns.
-    // - everything else: 'failed' (genuine claude crash / timeout etc).
-    const status = wasAborted
-      ? 'aborted'
-      : isShuttingDown
-        ? (isReplay ? 'replay-attempted' : 'replay-pending')
-        : 'failed';
-    dbWrite(() => db.setInboundHandlerStatus({
-      chat_id: chatId, msg_id: msg.message_id, status,
-    }), `set handler_status=${status}`);
-    logEvent('handler-error', {
-      chat_id: chatId, session_key: sessionKey,
-      msg_id: msg?.message_id,
-      error: err.message?.slice(0, 500),
-      stack: err.stack?.split('\n').slice(0, 5).join('\n'),
-      aborted: wasAborted || undefined,
-      replay: isReplay || undefined,
-    });
-    // rc.55: surface replay failures with a meaningful message. Pre-rc.55
-    // any boot-replay turn that failed for ANY reason was silently dropped
-    // (the original logic assumed "user typed this minutes ago and moved
-    // on"). But the rc.51-onward boot-replay path is a recovery primitive,
-    // not stale-message handling — when it fails, the user IS still waiting
-    // for their answer. The Shumabit@UMI thread :24 wall-clock incident on
-    // 2026-05-04 hit exactly this: original turn SIGHUP'd by deploy → boot-
-    // replay redispatched → replay hit 1800s wall-clock → user saw nothing
-    // and didn't know their work had been lost.
-    //
-    // Now: send a tailored message on replay failures. Still suppress when
-    // the replay itself was killed by ANOTHER shutdown (the next boot will
-    // redispatch — same logic as before, just narrower).
-    if (isReplay && !wasAborted && !isShuttingDown) {
-      tg(bot, 'sendMessage', {
-        chat_id: chatId,
-        text: '⚠️ This turn was interrupted and didn\'t complete on retry — please rephrase or simplify, or split into smaller steps.',
-        reply_parameters: { message_id: msg.message_id },
-      }, { source: 'error-reply', botName: BOT_NAME }).catch((replyErr) => {
-        console.error(`[${sessionKey}] failed to send replay-failure reply: ${replyErr.message}`);
-      });
-    }
-    // Suppress the user-facing error reply when:
-    //  - boot replay (user typed this minutes ago and moved on)
-    //  - polygram is shutting down (the failure is "Process killed" /
-    //    "Process exited" which isn't a real error — boot replay will
-    //    re-dispatch it on next start)
-    //  - user just /stop'd (already saw their abort acknowledgement)
-    if (!wasAborted && !isReplay && !isShuttingDown) {
-      // rc.54: auto-resume on 300s no-activity timeout. Spawn a fresh
-      // Query resuming the same session_id and inject a continuation
-      // nudge. This recovers from wedged tool calls (long Bash, hung
-      // MCP, stuck subagent) that polygram's watchdog catches but
-      // currently leaves the user stranded with "try resending".
-      // Skipped when the failed turn was ITSELF an auto-resume
-      // (msg._isAutoResume) to prevent recursion; per-session
-      // cooldown blocks tight loops on permanent wedges.
-      const isResumeTurn = msg._isAutoResume === true;
-      const resumable = !isResumeTurn && isAutoResumable({
-        error: err, aborted: wasAborted, replay: isReplay, shuttingDown: isShuttingDown,
-      });
-      if (resumable && !autoResumeTracker.isInCooldown(sessionKey)) {
-        autoResumeTracker.markAttempt(sessionKey);
-        logEvent('auto-resume-attempted', {
-          chat_id: chatId, session_key: sessionKey, msg_id: msg.message_id,
-          original_error: err.message?.slice(0, 200),
-        });
-        attemptAutoResume(sessionKey, chatId, msg, bot)
-          .then(() => {
-            logEvent('auto-resume-success', {
-              chat_id: chatId, session_key: sessionKey, msg_id: msg.message_id,
-            });
-            autoResumeTracker.clear(sessionKey);
-          })
-          .catch((resumeErr) => {
-            console.error(`[${sessionKey}] auto-resume failed: ${resumeErr?.message}`);
-            logEvent('auto-resume-failed', {
-              chat_id: chatId, session_key: sessionKey, msg_id: msg.message_id,
-              error: resumeErr?.message?.slice(0, 200),
-            });
-            // Fall back to the original error reply so the user isn't
-            // left with just the 🔁 indicator and no answer.
-            const fallbackText = errorReplyText(err);
-            if (fallbackText) {
-              tg(bot, 'sendMessage', {
-                chat_id: chatId, text: fallbackText,
-                reply_parameters: { message_id: msg.message_id },
-              }, { source: 'error-reply', botName: BOT_NAME }).catch(() => {});
-            }
-          });
-        return;
-      }
-      // 0.7.7: errorReplyText may return null when the classifier
-      // says "suppress reply" (e.g. INTERRUPTED inside abort grace —
-      // user already saw their /stop ack). Skip the send call in
-      // that case rather than dispatching empty text (which would
-      // 400 at the lib/telegram.js empty-text guard added in 0.7.4).
-      const replyText = errorReplyText(err);
-      if (replyText) {
-        tg(bot, 'sendMessage', {
-          chat_id: chatId,
-          text: replyText,
-          reply_parameters: { message_id: msg.message_id },
-        }, { source: 'error-reply', botName: BOT_NAME }).catch((replyErr) => {
-          console.error(`[${sessionKey}] failed to send error reply: ${replyErr.message}`);
-        });
-      }
-    }
-  }).finally(() => {
-    const n = (inFlightHandlers.get(sessionKey) || 1) - 1;
-    if (n <= 0) inFlightHandlers.delete(sessionKey);
-    else inFlightHandlers.set(sessionKey, n);
-  });
-}
-
 // Per-session lock ordering stdin writes. Module is I/O-pure.
 const stdinLock = createAsyncLock();
 
@@ -1364,687 +466,77 @@ const stdinLock = createAsyncLock();
 // permanently 401s (bot blocked, chat deleted) doesn't have us
 // hammering sendChatAction every 4s for the full turn duration.
 
-// ─── Response parsing (stickers, reactions) ─────────────────────────
-// Implementation lives in lib/parse-response.js so tests can require it
-// without starting a bot (polygram.js is a top-level script that calls
-// main() at bottom). The wrapper here supplies the runtime stickerMap /
-// emojiToSticker that the parser looks up against.
-//
-// 0.7.5: parser also recognises a literal `[sticker:NAME]` pattern in
-// addition to single-emoji shortcuts. Claude reads its own past outbound
-// rows on session resume, sees `[sticker:working]` (the placeholder
-// deriveOutboundText synthesises for sendSticker rows), and starts
-// mimicking the format as plain text. Without the new branch the
-// placeholder was rendered verbatim in the chat instead of swapped for
-// the actual sticker.
-const {
-  parseResponse: parseResponseImpl,
-  stripInlineTags: stripInlineTagsImpl,
-} = require('./lib/parse-response');
-function parseResponse(text) {
-  return parseResponseImpl(text, { stickerMap, emojiToSticker });
-}
-// rc.67: pre-processor for the streamer. Strips recognised inline
-// `[sticker:NAME]` and any `[react:EMOJI]` tags BEFORE the chunk is
-// committed to the bubble + DB row, so the user never sees a literal
-// tag even when the turn-end finalize path doesn't manage to clean it
-// (interrupt, error, hung query, edit failure, or the stickerMap-miss
-// no-op branch). parseResponse continues to surface the same tags in
-// `parsed.stickers[]` / `parsed.reactions[]` for outbound dispatch via
-// sendInlineStickers / sendInlineReactions.
-function stripInlineTagsForStreamer(text) {
-  return stripInlineTagsImpl(text, { stickerMap });
-}
-
-// ─── Cron/IPC send ─────────────────────────────────────────────────
-
-// Allowlist of Telegram Bot API methods external callers (cron) may invoke.
-// Broader than sendMessage to cover receipts, error reports, quick replies.
-// Deliberately excludes destructive ops (deleteMessage, banChatMember, etc.);
-// cron has no business calling those.
-const IPC_SEND_ALLOWED_METHODS = new Set([
-  'sendMessage',
-  'sendPhoto',
-  'sendDocument',
-  'sendSticker',
-  'sendChatAction',
-  'editMessageText',
-  'setMessageReaction',
-]);
-
-async function handleSendOverIpc(req) {
-  const { method, params = {}, source } = req || {};
-  if (!method) throw new Error('method required');
-  if (!IPC_SEND_ALLOWED_METHODS.has(method)) {
-    throw new Error(`method not allowed: ${method}`);
-  }
-  if (!bot) throw new Error(`bot process not ready`);
-
-  // Enforce: chat_id must belong to this bot (no cross-bot sends).
-  // After filterConfigToBot, config.chats only contains our chats.
-  const chatId = params.chat_id != null ? String(params.chat_id) : null;
-  if (chatId && !config.chats[chatId]) {
-    throw new Error(`chat not owned by ${BOT_NAME}: ${chatId}`);
-  }
-
-  // rc.58: catch the most common file-upload mistakes before Telegram
-  // rejects with a confusing error. validateIpcFileParam returns a
-  // human-readable error string when the file param is malformed,
-  // null otherwise.
-  const fileParamErr = validateIpcFileParam(method, params);
-  if (fileParamErr) throw new Error(fileParamErr);
-
-  const sendRes = await tg(bot, method, params, {
-    source: source || 'ipc',
-    botName: BOT_NAME,
-  });
-  return { result: sendRes };
-}
-
-// ─── Approvals ─────────────────────────────────────────────────────
-// rc.20: pure UI builders moved to lib/approval-ui.js for testability.
-// Imported above (buildApprovalKeyboard, buildApprovalKeyboardWithAlways,
-// approvalCardText, formatToolInputForCard).
-
-// /model and /effort inline keyboard. `show` controls which row(s) appear:
-// 'model', 'effort', or 'all'. The current value gets a ✓ marker so the
-// user can see at a glance what's selected.
-const MODEL_OPTIONS = ['opus', 'sonnet', 'haiku'];
-const EFFORT_OPTIONS = ['low', 'medium', 'high', 'xhigh', 'max'];
-
-function buildConfigKeyboard(chatConfig, show = 'all') {
-  const rows = [];
-  if (show === 'model' || show === 'all') {
-    rows.push(MODEL_OPTIONS.map((m) => ({
-      text: m === chatConfig.model ? `✓ ${m}` : m,
-      callback_data: `cfg:model:${m}`,
-    })));
-  }
-  if (show === 'effort' || show === 'all') {
-    rows.push(EFFORT_OPTIONS.map((e) => ({
-      text: e === chatConfig.effort ? `✓ ${e}` : e,
-      callback_data: `cfg:effort:${e}`,
-    })));
-  }
-  return { inline_keyboard: rows };
-}
-
-// Card text shown above the inline keyboard. Includes plain-language
-// guidance on when to pick which model / effort, since most users
-// (especially in shared groups) don't know which option to tap.
-//
-// Model versions: polygram passes the alias ("opus", "sonnet", "haiku")
-// to claude, which resolves it to the latest snapshot. We mirror those
-// snapshots here for display only, and verify them on each release with
-// `claude --model <alias>` (probing the system:init event's `model`
-// field). Bumping is a manual step — when claude releases a new
-// snapshot the alias maps to, update this map and ship.
-const MODEL_VERSIONS_DESC = {
-  opus: 'claude-opus-4-7',
-  sonnet: 'claude-sonnet-4-6',
-  haiku: 'claude-haiku-4-5',
-};
-
-function formatConfigInfoText(chatConfig, show, sessionKey) {
-  const alive = pm.has(sessionKey) && !pm.get(sessionKey).closed;
-  const ver = MODEL_VERSIONS_DESC[chatConfig.model] || chatConfig.model;
-  const head = `Model: ${chatConfig.model} (${ver})\nEffort: ${chatConfig.effort}\nAgent: ${chatConfig.agent}\nProcess: ${alive ? 'warm' : 'cold'}\nSession: ${getClaudeSessionId(db, sessionKey)?.slice(0, 8) || 'new'}`;
-
-  const modelHelp = [
-    '',
-    '**Models**',
-    '🧠 **opus** — deep analysis, code refactor, multi-source reconciliation. ~5× sonnet cost.',
-    '🤖 **sonnet** — default. Most ops, code review, document summary.',
-    '⚡ **haiku** — quick simple tasks, classification, lookup.',
-  ].join('\n');
-
-  const effortHelp = [
-    '',
-    '**Effort** — ceiling on how much Claude can think. Simple questions get fast replies; hard ones spend more tokens. Safe to set higher — Claude scales down automatically when it doesn\'t need to think.',
-    '• **low** — fast replies, minimum reasoning. Casual chat, simple lookups.',
-    '• **medium** — balanced default. Fits most use cases.',
-    '• **high** — multi-step tasks. Audit, debug, multi-source analysis.',
-    '• **xhigh** / **max** — heaviest. Hard reasoning, edge cases.',
-  ].join('\n');
-
-  let body = head;
-  if (show === 'model' || show === 'all') body += '\n' + modelHelp;
-  if (show === 'effort' || show === 'all') body += '\n' + effortHelp;
-  return body;
-}
-
-// rc.20: approvalCardText + safeParse moved to lib/approval-ui.js.
-
-// 0.8.0-rc.18+: canonicalizeToolInput moved to lib/canonical-json.js
-// for testability. Same function, no behavior change.
-
-/**
- * 0.8.0 Phase 2 step 6: SDK canUseTool callback. Hands back to the
- * SDK an async PermissionResult per `@anthropic-ai/claude-agent-sdk`
- * sdk.d.ts:146-188.
- *
- * Flow (per v4 plan §4.2):
- *   1. If no approval config → allow.
- *   2. Look up chat_tool_decisions for short-circuit (always-allow/
- *      always-deny by exact / prefix / regex match). If found,
- *      return that decision.
- *   3. Match against config.bot.approvals.gatedTools; if not gated,
- *      allow.
- *   4. Issue pending_approvals row (with tool_use_id dedup); post
- *      4-button card to admin chat; park resolver in
- *      approvalWaiters Map; race against opts.signal + timeout.
- *   5. Return PermissionResult; the SDK lets the tool run or denies.
- *
- * Reuses the existing approvals store + approvalWaiters Map (same
- * shape as today's IPC flow). Both paths can coexist on the same
- * daemon — IPC for CLI pm chats, canUseTool for SDK pm chats.
- */
-function makeCanUseTool(sessionKey) {
-  const chatId = getChatIdFromKey(sessionKey);
-  const threadId = sessionKey.includes(':') ? sessionKey.split(':')[1] : null;
-  return async function canUseTool(toolName, input, opts) {
-    const apprCfg = config.bot?.approvals;
-    if (!apprCfg || !apprCfg.adminChatId) {
-      // Not configured for this bot → allow everything (matches CLI
-      // pm's bypassPermissions today when approvals not set).
-      return { behavior: 'allow' };
-    }
-
-    const canonicalInput = canonicalizeToolInput(input);
-
-    // Step 2: chat_tool_decisions short-circuit.
-    try {
-      const persisted = db.lookupChatToolDecision({
-        bot_name: BOT_NAME, chat_id: chatId, tool_name: toolName,
-        canonical_input: canonicalInput, now: Date.now(),
-      });
-      if (persisted) {
-        logEvent('canusetool-shortcircuit', {
-          chat_id: chatId, tool_name: toolName,
-          decision: persisted.decision, match_type: persisted.match_type,
-          tool_use_id: opts?.toolUseID || null,
-        });
-        if (persisted.decision === 'allow') return { behavior: 'allow' };
-        return { behavior: 'deny', message: 'matched persisted always-deny rule' };
-      }
-    } catch (err) {
-      console.error(`[${sessionKey}] chat_tool_decisions lookup: ${err.message}`);
-      // Non-fatal — fall through to gating + card.
-    }
-
-    // Step 3: gating check.
-    const gated = matchesApprovalPattern(toolName, input, apprCfg.gatedTools || []);
-    if (!gated.matched) return { behavior: 'allow' };
-
-    // Step 4: issue + post + park.
-    const row = approvals.issue({
-      bot_name: BOT_NAME, turn_id: opts?.toolUseID || null,
-      requester_chat_id: chatId,
-      approver_chat_id: String(apprCfg.adminChatId),
-      tool_name: toolName, tool_input: input,
-      timeoutMs: apprCfg.timeoutMs || APPROVAL_DEFAULT_TIMEOUT_MS,
-    });
-    if (opts?.toolUseID) {
-      // Persist the SDK's stable per-call ID so dedup-by-toolUseId
-      // works on retries (same call, same row).
-      try {
-        approvals.setToolUseId?.(row.id, opts.toolUseID);
-      } catch { /* swallow if older approvals store */ }
-    }
-    if (!bot) {
-      approvals.resolve({ id: row.id, status: 'cancelled', reason: 'bot not ready' });
-      return { behavior: 'deny', message: 'bot not ready' };
-    }
-    if (!row.reused || !row.approver_msg_id) {
-      try {
-        const sent = await tg(bot, 'sendMessage', {
-          chat_id: apprCfg.adminChatId,
-          text: approvalCardText(row),
-          reply_markup: buildApprovalKeyboardWithAlways(row.id, row.callback_token),
-        }, { source: 'canusetool-card', botName: BOT_NAME, plainText: true });
-        if (sent?.message_id) approvals.setApproverMsgId(row.id, sent.message_id);
-      } catch (err) {
-        console.error(`[${sessionKey}] failed to post canUseTool card: ${err.message}`);
-        approvals.resolve({ id: row.id, status: 'cancelled', reason: `post failed: ${err.message}` });
-        return { behavior: 'deny', message: `post failed: ${err.message}` };
-      }
-    }
-
-    // Step 5: race signal + timeout + click.
-    return await new Promise((resolve) => {
-      let settled = false;
-      const settle = (decision) => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        if (opts?.signal && sigCleanup) {
-          try { opts.signal.removeEventListener('abort', sigCleanup); }
-          catch { /* swallow */ }
-        }
-        dropWaiter(row.id, wrappedResolve);
-        resolve(decision);
-      };
-      const timer = setTimeout(() => {
-        approvals.resolve({ id: row.id, status: 'timeout' }).catch?.(() => {});
-        settle({ behavior: 'deny', message: 'approval timed out' });
-      }, Math.max(1000, row.timeout_ts - Date.now()));
-      const sigCleanup = opts?.signal
-        ? () => settle({ behavior: 'deny', message: 'aborted' })
-        : null;
-      if (opts?.signal && sigCleanup) {
-        opts.signal.addEventListener('abort', sigCleanup, { once: true });
-      }
-      const wrappedResolve = (decision, reason, extra) => {
-        // decision here is from resolveApprovalWaiter:
-        //   'approved' | 'denied' | 'approved-always' | 'denied-always'
-        // Map to SDK PermissionResult shape. extra carries
-        // updatedPermissions for the always-* variants.
-        if (decision === 'approved' || decision === 'approved-always') {
-          settle({
-            behavior: 'allow',
-            ...(decision === 'approved-always' && extra?.updatedPermissions
-              ? { updatedPermissions: extra.updatedPermissions }
-              : {}),
-          });
-        } else {
-          settle({
-            behavior: 'deny',
-            message: reason || decision || 'denied',
-          });
-        }
-      };
-      const list = approvalWaiters.get(row.id) || [];
-      list.push(wrappedResolve);
-      approvalWaiters.set(row.id, list);
-    });
-  };
-}
-
-async function handleApprovalRequest(req) {
-  const { bot_name, chat_id, turn_id, tool_name, tool_input } = req;
-  if (!chat_id || !tool_name) {
-    throw new Error('chat_id, tool_name required');
-  }
-  // Per-bot process: the caller's bot_name must match ours if provided.
-  if (bot_name && bot_name !== BOT_NAME) {
-    throw new Error(`wrong bot: socket is ${BOT_NAME}, request is for ${bot_name}`);
-  }
-
-  const apprCfg = config.bot?.approvals;
-  if (!apprCfg || !apprCfg.adminChatId) {
-    return { decision: 'not-gated', reason: 'approvals not configured for this bot' };
-  }
-
-  const gated = matchesApprovalPattern(tool_name, tool_input, apprCfg.gatedTools || []);
-  if (!gated.matched) {
-    return { decision: 'not-gated' };
-  }
-
-  // Issue pending row (with dedup). Row persists the bot_name for archive/
-  // audit queries across per-bot DBs.
-  const row = approvals.issue({
-    bot_name: BOT_NAME, turn_id, requester_chat_id: chat_id,
-    approver_chat_id: String(apprCfg.adminChatId),
-    tool_name, tool_input,
-    timeoutMs: apprCfg.timeoutMs || APPROVAL_DEFAULT_TIMEOUT_MS,
-  });
-
-  if (!bot) {
-    approvals.resolve({ id: row.id, status: 'cancelled', reason: 'bot process not ready' });
-    return { decision: 'denied', reason: 'bot process not ready' };
-  }
-
-  if (!row.reused || !row.approver_msg_id) {
-    try {
-      const sent = await tg(bot, 'sendMessage', {
-        chat_id: apprCfg.adminChatId,
-        text: approvalCardText(row),
-        reply_markup: buildApprovalKeyboard(row.id, row.callback_token),
-      }, { source: 'approval-request', botName: BOT_NAME, plainText: true });
-      if (sent?.message_id) {
-        approvals.setApproverMsgId(row.id, sent.message_id);
-      }
-    } catch (err) {
-      console.error(`[${BOT_NAME}] failed to post approval card: ${err.message}`);
-      approvals.resolve({ id: row.id, status: 'cancelled', reason: `post failed: ${err.message}` });
-      return { decision: 'denied', reason: `post failed: ${err.message}` };
-    }
-  }
-
-  // Block until callback resolves us, or timeout fires. Multiple dedup'd
-  // callers can queue on the same id — they all get the same decision.
-  return await new Promise((resolve) => {
-    const timer = setTimeout(() => {
-      dropWaiter(row.id, wrappedResolve);
-      resolve({ decision: 'timeout', reason: 'operator did not respond in time' });
-    }, Math.max(1000, row.timeout_ts - Date.now()));
-
-    const wrappedResolve = (decision, reason) => {
-      clearTimeout(timer);
-      // Translate 'approved-always' / 'denied-always' to plain
-      // approve/deny for the IPC caller — the IPC hook protocol
-      // doesn't carry persistence state, only the bool decision.
-      if (decision === 'approved-always') decision = 'approved';
-      else if (decision === 'denied-always') decision = 'denied';
-      resolve({ decision, reason });
-    };
-
-    const list = approvalWaiters.get(row.id) || [];
-    list.push(wrappedResolve);
-    approvalWaiters.set(row.id, list);
-  });
-}
-
-function dropWaiter(id, fn) {
-  const list = approvalWaiters.get(id);
-  if (!list) return;
-  const i = list.indexOf(fn);
-  if (i !== -1) list.splice(i, 1);
-  if (list.length === 0) approvalWaiters.delete(id);
-}
-
-function resolveApprovalWaiter(id, decision, reason, extra) {
-  // `extra` carries SDK-shape updatedPermissions for always-* clicks.
-  // IPC waiters (CLI pm) ignore it; SDK canUseTool waiters use it
-  // to populate PermissionResult.updatedPermissions so the in-flight
-  // Query picks up the new rule for the rest of the turn.
-  const list = approvalWaiters.get(id);
-  if (!list) return;
-  approvalWaiters.delete(id);
-  for (const fn of list) {
-    try { fn(decision, reason, extra); } catch {}
-  }
-}
-
-async function handleApprovalCallback(ctx) {
-  const data = ctx.callbackQuery?.data || '';
-  // 0.8.0 Phase 2 step 6: extended pattern accepts the 4-button
-  // SDK canUseTool format. `approve-always` / `deny-always`
-  // additionally write a row to chat_tool_decisions so subsequent
-  // calls to the same tool with the same input short-circuit.
-  const m = String(data).match(/^(approve|deny|approve-always|deny-always):(\d+):(\S+)$/);
-  if (!m) return;
-  const decision = m[1];
-  const id = parseInt(m[2], 10);
-  const token = m[3];
-
-  const row = approvals.getById(id);
-  if (!row) {
-    await ctx.answerCallbackQuery({ text: 'Unknown approval.', show_alert: true }).catch(() => {});
-    return;
-  }
-  if (!approvalTokensEqual(row.callback_token, token)) {
-    logEvent('approval-token-mismatch', {
-      id, from_user: ctx.from?.id,
-      // Don't log the sent_token — attackers guessing it don't need to know
-      // which prefix they got close on.
-    });
-    await ctx.answerCallbackQuery({ text: 'Bad token.', show_alert: true }).catch(() => {});
-    return;
-  }
-  if (row.status !== 'pending') {
-    await ctx.answerCallbackQuery({ text: `Already ${row.status}.`, show_alert: true }).catch(() => {});
-    return;
-  }
-
-  // Only the configured approver chat is authoritative. Our process only
-  // serves one bot, so config.bot.approvals is the authoritative source.
-  const apprCfg = config.bot?.approvals;
-  const expectedChat = String(apprCfg?.adminChatId || '');
-  if (String(ctx.chat?.id) !== expectedChat) {
-    logEvent('approval-foreign-chat', {
-      id, from_chat: ctx.chat?.id, expected: expectedChat,
-    });
-    await ctx.answerCallbackQuery({ text: 'Not authorised here.', show_alert: true }).catch(() => {});
-    return;
-  }
-
-  // 0.8.0 Phase 2 step 6: parse always-variants. The base status
-  // ('approved' / 'denied') drives existing logic + card edit;
-  // `isAlways` triggers the chat_tool_decisions persistence
-  // below (after the atomic SQL resolve succeeds, so we don't
-  // write a "always" rule for a stale double-click).
-  const isApprove = decision === 'approve' || decision === 'approve-always';
-  const isAlways = decision === 'approve-always' || decision === 'deny-always';
-  const status = isApprove ? 'approved' : 'denied';
-  const user = ctx.from?.first_name || ctx.from?.username || null;
-  const userId = ctx.from?.id || null;
-  // SQL-level atomic resolve: UPDATE ... WHERE status='pending' — so in a
-  // double-click race only one of the two callers writes. If ours was
-  // second, changes=0 → stale decision; tell the clicker and don't edit
-  // the card a second time (the winner already did).
-  const changes = approvals.resolve({
-    id, status,
-    decided_by_user_id: userId, decided_by_user: user,
-  });
-  if (changes === 0) {
-    const fresh = approvals.getById(id);
-    await ctx.answerCallbackQuery({
-      text: `Already ${fresh?.status || 'resolved'}.`,
-      show_alert: true,
-    }).catch(() => {});
-    return;
-  }
-  logEvent('approval-resolved', {
-    id, status, by: userId, user, bot: BOT_NAME,
-  });
-
-  // Edit the card to show the decision. 0.6.14: routed through tg() so
-  // the edit gets the same write-before-send DB row, plain-text policy
-  // (no parse_mode injection from tool input), and logged failure
-  // surface as every other outbound. Pre-0.6.14 this called
-  // ctx.api.editMessageText directly — same bypass class as the two
-  // already-routed in 0.6.8 (approval-timeout and pair-onboarding).
-  try {
-    const fresh = approvals.getById(id);
-    await tg(bot, 'editMessageText', {
-      chat_id: row.approver_chat_id,
-      message_id: row.approver_msg_id,
-      text: approvalCardText(fresh, {
-        resolvedBy: `${status === 'approved' ? '✅ Approved' : '❌ Denied'} by ${user || userId}`,
-      }),
-    }, { source: 'approval-card-decision', botName: BOT_NAME, plainText: true });
-  } catch (err) {
-    console.error(`[${BOT_NAME}] edit approval card failed: ${err.message}`);
-  }
-  // 0.8.0 Phase 2 step 6: persist always-* clicks to chat_tool_decisions
-  // so subsequent SDK canUseTool calls for the same (bot, chat, tool,
-  // input) short-circuit without prompting. Use prefix match by default
-  // (allows minor argument variations) — the user can hand-edit to
-  // exact / regex via SQL if they want narrower rules.
-  let updatedPermissions = null;
-  if (isAlways) {
-    try {
-      const canonical = canonicalizeToolInput(row.tool_input);
-      db.insertChatToolDecision({
-        bot_name: BOT_NAME,
-        chat_id: row.requester_chat_id,
-        tool_name: row.tool_name,
-        match_type: 'prefix',  // most useful default; exact would be too narrow
-        input_pattern: canonical,
-        decision: status === 'approved' ? 'allow' : 'deny',
-        issued_by_user_id: userId ? String(userId) : null,
-        expires_ts: null,
-      });
-      logEvent('chat-tool-decision-persisted', {
-        chat_id: row.requester_chat_id,
-        tool_name: row.tool_name,
-        decision: status === 'approved' ? 'allow' : 'deny',
-        match_type: 'prefix',
-      });
-      // Build SDK-shape updatedPermissions so the in-flight Query
-      // also picks up the rule for the rest of THIS turn (avoids
-      // re-prompting on the next sibling tool call).
-      updatedPermissions = [{
-        type: 'addRules',
-        rules: [{
-          toolName: row.tool_name,
-          decision: status === 'approved' ? 'allow' : 'deny',
-        }],
-      }];
-    } catch (err) {
-      console.error(`[${BOT_NAME}] chat_tool_decisions persist failed: ${err.message}`);
-      // Non-fatal — the one-time decision still propagates below.
-    }
-  }
-
-  await ctx.answerCallbackQuery({ text: status }).catch(() => {});
-
-  // Pass the original decision token back to the waiter so it can
-  // distinguish 'approved-always' (SDK gets updatedPermissions)
-  // from plain 'approved'. CLI IPC waiters strip back to plain
-  // approve/deny in their wrappedResolve.
-  resolveApprovalWaiter(id, decision === 'approve-always' ? 'approved-always'
-    : decision === 'deny-always' ? 'denied-always'
-    : status, undefined, { updatedPermissions });
-}
-
-// Handles taps on the /model and /effort inline keyboard buttons. Same
-// outcome as the text-typed `/model sonnet` flow: mutate chatConfig,
-// trigger graceful respawn, log config change, edit the message to show
-// the new ✓ marker.
-async function handleConfigCallback(ctx) {
-  const data = ctx.callbackQuery?.data || '';
-  const m = String(data).match(/^cfg:(model|effort):(\S+)$/);
-  if (!m) return;
-  const setting = m[1];
-  const value = m[2];
-
-  const chatId = String(ctx.callbackQuery.message?.chat?.id || '');
-  const chatConfig = config.chats[chatId];
-  if (!chatConfig) {
-    await ctx.answerCallbackQuery({ text: 'Chat not configured', show_alert: true }).catch(() => {});
-    return;
-  }
-  if (!config.bot?.allowConfigCommands) {
-    await ctx.answerCallbackQuery({ text: 'Config commands disabled', show_alert: true }).catch(() => {});
-    return;
-  }
-
-  const validValues = setting === 'model' ? MODEL_OPTIONS : EFFORT_OPTIONS;
-  if (!validValues.includes(value)) {
-    await ctx.answerCallbackQuery({ text: `Invalid ${setting}` }).catch(() => {});
-    return;
-  }
-
-  const oldValue = chatConfig[setting];
-  if (oldValue === value) {
-    await ctx.answerCallbackQuery({ text: `Already ${value}` }).catch(() => {});
-    return;
-  }
-
-  chatConfig[setting] = value;
-  const cmdUserId = ctx.callbackQuery.from?.id || null;
-  const cmdUser = ctx.callbackQuery.from?.first_name || ctx.callbackQuery.from?.username || null;
-  dbWrite(() => db.logConfigChange({
-    chat_id: chatId, thread_id: null, field: setting,
-    old_value: oldValue, new_value: value,
-    user: cmdUser, user_id: cmdUserId, source: 'inline-button',
-  }), `log ${setting} change`);
-
-  // Graceful application of the change to the topic's session. With
-  // isolateTopics=false sessionKey is the chat (one shared session). With
-  // isolateTopics=true sessionKey carries the topic, so other topics'
-  // in-flight turns are not disturbed and the card update + button toast
-  // only affect the user's own context.
-  //
-  // CLI pm: requestRespawn drains pending turns then kills the process;
-  //   the next user message spawns fresh with the updated chatConfig.
-  // SDK pm: applies live to the running Query via setModel /
-  //   applyFlagSettings — no respawn needed, change takes effect for the
-  //   rest of the in-flight turn AND all future ones. Falls back to
-  //   {killed: false} if neither method is available, leaving the new
-  //   chatConfig value to be picked up by the next cold spawn.
-  const callbackThreadId = ctx.callbackQuery.message?.message_thread_id?.toString() || null;
-  const callbackSessionKey = getSessionKey(chatId, callbackThreadId, chatConfig);
-  const reason = setting === 'model' ? 'model-change' : 'effort-change';
-  // Feature-detect on the routed pm for this specific session, not on
-  // the router itself (the router exposes every method as a forwarding
-  // shim so `typeof pm.X` is always 'function').
-  const pmForCb = pm.pickFor(callbackSessionKey);
-  let respawn;
-  if (typeof pmForCb.requestRespawn === 'function') {
-    respawn = pmForCb.requestRespawn(callbackSessionKey, reason);
-  } else if (setting === 'effort' && typeof pmForCb.applyFlagSettings === 'function') {
-    const ok = await pmForCb.applyFlagSettings(callbackSessionKey, { effortLevel: value });
-    respawn = { killed: ok };
-  } else if (setting === 'model' && typeof pmForCb.setModel === 'function') {
-    const ok = await pmForCb.setModel(callbackSessionKey, value);
-    respawn = { killed: ok };
-  } else {
-    respawn = { killed: false };
-  }
-  const anyActive = !respawn.killed;
-
-  // Re-render the card with updated ✓ + the same help text shown initially.
-  // Detect original card type (model-only / effort-only / both) by counting
-  // rows in the existing reply_markup so the user sees the same layout
-  // they tapped into.
-  const existingRows = ctx.callbackQuery.message?.reply_markup?.inline_keyboard?.length || 0;
-  const showRow = existingRows >= 2 ? 'all' : setting;
-  // chatId works as a session-key proxy here for the warm-process check
-  // (isolateTopics chats might have multiple keys but for this card we
-  // just want a representative state).
-  const newInfo = formatConfigInfoText(chatConfig, showRow, chatId);
-  const newKeyboard = buildConfigKeyboard(chatConfig, showRow);
-  try {
-    // Pre-format the markdown→HTML ourselves so editMessageText can be
-    // called with the right parse_mode (the bot.api.editMessageText path
-    // bypasses tg() / applyFormatting in the chat-action approval card,
-    // but here we DO want HTML).
-    const { toTelegramHtml } = require('./lib/telegram-format');
-    const { text: html, parseMode } = toTelegramHtml(newInfo);
-    await ctx.editMessageText(html, {
-      reply_markup: newKeyboard,
-      ...(parseMode && { parse_mode: parseMode }),
-    });
-  } catch (err) {
-    console.error(`[${BOT_NAME}] config-card edit failed: ${err.message}`);
-  }
-
-  const ackText = anyActive
-    ? `${setting} → ${value} — switching when finished`
-    : `${setting} → ${value}`;
-  await ctx.answerCallbackQuery({ text: ackText }).catch(() => {});
+// ─── Response parsing (stickers, reactions) ─────────────────────────
+// Implementation lives in lib/parse-response.js so tests can require it
+// without starting a bot (polygram.js is a top-level script that calls
+// main() at bottom). The wrapper here supplies the runtime stickerMap /
+// emojiToSticker that the parser looks up against.
+//
+// 0.7.5: parser also recognises a literal `[sticker:NAME]` pattern in
+// addition to single-emoji shortcuts. Claude reads its own past outbound
+// rows on session resume, sees `[sticker:working]` (the placeholder
+// deriveOutboundText synthesises for sendSticker rows), and starts
+// mimicking the format as plain text. Without the new branch the
+// placeholder was rendered verbatim in the chat instead of swapped for
+// the actual sticker.
+const {
+  parseResponse: parseResponseImpl,
+  stripInlineTags: stripInlineTagsImpl,
+} = require('./lib/telegram/parse');
+function parseResponse(text) {
+  return parseResponseImpl(text, { stickerMap, emojiToSticker });
 }
-
-function startApprovalSweeper(intervalMs = 30_000) {
-  return setInterval(() => {
-    let rows;
-    try {
-      rows = approvals.sweepTimedOut();
-    } catch (err) {
-      // Silent failure here is invisible death — pending approvals time out
-      // with no operator signal. Log loudly.
-      console.error(`[approvals] sweeper DB error: ${err.message}`);
-      logEvent('approval-sweep-failed', {
-        error: err.message?.slice(0, 300),
-      });
-      return;
-    }
-    for (const row of rows) {
-      approvals.resolve({ id: row.id, status: 'timeout' });
-      logEvent('approval-timeout', {
-        id: row.id, bot: BOT_NAME, tool: row.tool_name,
-      });
-      resolveApprovalWaiter(row.id, 'timeout', 'swept');
-      // Best-effort: edit the card to show the timeout. Routed through
-      // tg() so the edit gets the same plain-text formatting policy as
-      // the original card post (no parse_mode injection from tool input)
-      // AND lands in the transcript like every other outbound. Pre-0.6.8
-      // this called bot.api.editMessageText directly and bypassed both.
-      if (bot && row.approver_msg_id) {
-        tg(bot, 'editMessageText', {
-          chat_id: row.approver_chat_id,
-          message_id: row.approver_msg_id,
-          text: approvalCardText(approvals.getById(row.id), { resolvedBy: '⏰ Timed out' }),
-        }, { source: 'approval-card-timeout', botName: BOT_NAME, plainText: true })
-          .catch((err) => console.error(`[${BOT_NAME}] approval-card-timeout edit: ${err.message}`));
-      }
-    }
-  }, intervalMs);
+// rc.67: pre-processor for the streamer. Strips recognised inline
+// `[sticker:NAME]` and any `[react:EMOJI]` tags BEFORE the chunk is
+// committed to the bubble + DB row, so the user never sees a literal
+// tag even when the turn-end finalize path doesn't manage to clean it
+// (interrupt, error, hung query, edit failure, or the stickerMap-miss
+// no-op branch). parseResponse continues to surface the same tags in
+// `parsed.stickers[]` / `parsed.reactions[]` for outbound dispatch via
+// sendInlineStickers / sendInlineReactions.
+function stripInlineTagsForStreamer(text) {
+  return stripInlineTagsImpl(text, { stickerMap });
 }
 
+// ─── Cron/IPC send — extracted to lib/handlers/ipc-send.js ──────────
+let handleSendOverIpc = null;
+
+// ─── Approvals ─────────────────────────────────────────────────────
+// Pure UI builders live in lib/approval-ui.js for testability.
+// Imported above (buildApprovalKeyboardWithAlways, approvalCardText,
+// formatToolInputForCard).
+
+// Config card UI moved to lib/handlers/config-ui.js. polygram.js
+// keeps a thin formatConfigInfoText wrapper since it needs the
+// runtime pm + db + getClaudeSessionId; buildConfigKeyboard is
+// pure and re-exported.
+const {
+  buildConfigKeyboard,
+  createFormatConfigInfoText,
+  MODEL_OPTIONS,
+  EFFORT_OPTIONS,
+  MODEL_VERSIONS_DESC,
+} = require('./lib/handlers/config-ui');
+let formatConfigInfoText = null;
+// CRITICAL: these placeholders MUST exist or 'use strict' boot fails
+// with ReferenceError. v4 review (commit 39) found 4 missing — restored.
+// Each handler is wired in main() once its deps exist.
+let handleConfigCallback = null;
+let handleAbortIfRequested = null;
+let autosteer = null;
+let dispatchSlashCommand = null;
+
+// rc.20: approvalCardText + safeParse moved to lib/approvals/ui.js.
+// 0.9.0 commit 29: makeCanUseTool / handleApprovalCallback /
+// resolveApprovalWaiter / dropWaiter / startApprovalSweeper extracted
+// to lib/handlers/approvals.js. Wired in main() once db + bot + tg +
+// approvals store are available.
+let makeCanUseTool = null;
+let handleApprovalCallback = null;
+let resolveApprovalWaiter = null;
+let startApprovalSweeper = null;
+let cancelAllWaiters = null;
+
 // Parse /pair-code args: /pair-code [--chat <id>] [--scope user|chat] [--ttl 10m] [--note "..."]
 function parsePairCodeArgs(text) {
   const out = {};
@@ -2142,342 +634,14 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
     await sendReply(info, { params: { reply_markup } });
     return;
   }
-  // 0.8.0 Phase 2 step 7: /new and /reset slash commands. Both close
-  // the current Query (if any), clear the claude_session_id from the
-  // sessions table, and post "✨ Started a fresh session." Next user
-  // message starts a fresh subprocess with no resume.
-  //
-  // Equivalent UX to OpenClaw's /new and /reset handlers
-  // (pi-embedded:40594 BARE_SESSION_RESET_PROMPT). Required by the
-  // 85%-context-full hint (Phase 2 step 4) and by classifier-driven
-  // auto-recovery (step 8) — both reference these commands.
-  // 0.8.0 Phase 2 step 9: /context slash command. On-demand context-
-  // usage report. Only meaningful under SDK pm (CLI pm has no
-  // getContextUsage equivalent); CLI path replies with a hint.
-  if (botAllowsCommands && text === '/context') {
-    if (!pm.isSdkFor(sessionKey)) {
-      await sendReply('📚 /context requires the SDK pm. This chat is on the CLI pm path.');
-      return;
-    }
-    const entry = pm.get(sessionKey);
-    const q = entry?.query;
-    if (!q || typeof q.getContextUsage !== 'function') {
-      await sendReply('📚 No active session yet — send a message first, then /context.');
-      return;
-    }
-    try {
-      const u = await q.getContextUsage();
-      await sendReply(formatContextReply(u));
-    } catch (err) {
-      console.error(`[${label}] /context failed: ${err.message}`);
-      await sendReply(`📚 Couldn't fetch context info: ${err.message}`);
-    }
-    return;
-  }
-  // 0.8.0-rc.22: /compact <preserve text> — manual SDK compaction with
-  // user-supplied preservation instructions. The SDK's CLI binary
-  // recognises "/compact" as a slash command via streamInput.push
-  // (verified by scripts/spikes/compact-via-streaminput.mjs: PreCompact
-  // hook fires with trigger:'manual', compact_boundary event lands).
-  // We push the raw text "/compact <instructions>" through the SDK's
-  // input controller; the SDK handles parsing + compaction internally.
-  if (botAllowsCommands && text.startsWith('/compact')) {
-    if (!pm.isSdkFor(sessionKey)) {
-      await sendReply('🗜️ /compact requires the SDK pm. This chat is on the CLI pm path.');
-      return;
-    }
-    // rc.64: if the in-memory session was evicted (LRU cap pressure)
-    // but there's a saved Claude session_id in DB, auto-spawn the
-    // Query with --resume so /compact has something to work with.
-    // Pre-rc.64 we returned "🗜️ No active session" — confusing
-    // because the user just had a conversation 5 minutes ago, the
-    // session went idle, LRU evicted it, and "No active session"
-    // reads as "I never knew you" instead of "I unloaded your
-    // session, hold on."
-    let entry = pm.get(sessionKey);
-    if (!entry) {
-      const savedSessionId = getClaudeSessionId(db, sessionKey);
-      if (!savedSessionId) {
-        await sendReply('🗜️ No conversation to compact yet. Send a message first, then /compact.');
-        return;
-      }
-      try {
-        entry = await getOrSpawnForChat(sessionKey);
-      } catch (err) {
-        console.error(`[${label}] /compact spawn-resume: ${err.message}`);
-        await sendReply(`🗜️ Couldn't load session for compaction: ${err.message}`);
-        return;
-      }
-      if (!entry) {
-        await sendReply('🗜️ Session not loadable (config missing).');
-        return;
-      }
-      logEvent('compact-spawn-resumed', {
-        chat_id: chatId, thread_id: threadIdStr, session_key: sessionKey,
-        resumed_session_id: savedSessionId,
-      });
-    }
-    if (!entry?.inputController?.push) {
-      await sendReply('🗜️ Session not ready for /compact (no input controller).');
-      return;
-    }
-    // Push the literal "/compact ..." text into the input stream.
-    // The SDK parses leading "/" as a slash command and triggers
-    // manual compaction; user's preserve instructions land in
-    // PreCompactHookInput.custom_instructions.
-    try {
-      entry.inputController.push({
-        type: 'user',
-        message: { role: 'user', content: text },
-        parent_tool_use_id: null,
-      });
-      logEvent('compact-command', {
-        chat_id: chatId, thread_id: threadIdStr, session_key: sessionKey,
-        text_len: text.length,
-        // rc.65: store the full /compact text so boot-time orphan
-        // recovery can silently re-push it after a deploy
-        // interrupted compaction. Agent-supplied hints (e.g.
-        // "/compact keep the Q3 commission decisions") need to be
-        // preserved verbatim for the retry to summarize correctly.
-        text,
-        user: cmdUser, user_id: cmdUserId,
-      });
-      const hasHint = text.length > '/compact'.length + 1;
-      await sendReply(hasHint
-        ? '🗜️ Compacting with your hint…'
-        : '🗜️ Compacting…');
-    } catch (err) {
-      console.error(`[${label}] /compact push: ${err.message}`);
-      await sendReply(`🗜️ Couldn't trigger compact: ${err.message}`);
-    }
-    return;
-  }
-  // 0.8.0-rc.46: /reload — close + respawn the SDK Query while
-  // PRESERVING the persisted claude_session_id. The next user
-  // message resumes the conversation (model has prior context via
-  // SDK resume) but the spawn re-reads agent / skill / plugin files
-  // from disk, so any local edits to ~/.claude/agents/<name>.md or
-  // skill files take effect.
-  //
-  // Difference vs /new:
-  //   /new    → resetSession clears session_id → fresh conversation
-  //   /reload → kill closes Query, session_id preserved → same
-  //              conversation continues with fresh agent/skill code
-  //
-  // Mechanism: pm.kill drains the pending queue (with code 'KILLED')
-  // and closes the SDK Query. Crucially it does NOT call
-  // db.clearSessionId — the contract test
-  // 'pm.kill does NOT call db.clearSessionId' pins this invariant.
-  // The next user message hits getOrSpawn → no warm Query → spawn
-  // fresh with `resume: <session_id>` from sessions table → SDK
-  // restores conversation history → fresh files loaded.
-  if (botAllowsCommands && text === '/reload') {
-    if (pm.has(sessionKey)) {
-      try { await pm.kill(sessionKey); }
-      catch (err) { console.error(`[${label}] kill on /reload: ${err.message}`); }
-    }
-    logEvent('session-reload-command', {
-      chat_id: chatId, command: text,
-      user: cmdUser, user_id: cmdUserId,
-    });
-    await sendReply('🔄 Reloaded. Next message picks up the conversation with fresh skills/agents.');
-    return;
-  }
-
-  if (botAllowsCommands && (text === '/new' || text === '/reset')) {
-    let drained = 0;
-    const target = pm.pickFor(sessionKey);
-    if (typeof target.resetSession === 'function') {
-      try {
-        const r = await target.resetSession(sessionKey, { reason: text.slice(1) });
-        drained = r?.drainedPendings ?? 0;
-      } catch (err) {
-        console.error(`[${label}] resetSession ${text}: ${err.message}`);
-      }
-    } else {
-      // CLI pm fallback: kill the session; sessions table cleared
-      // via clearSessionId in pm's proc.on('close') resume-fail
-      // path (lib/process-manager.js:457). We force the path by
-      // setting the kill rationale so the close handler treats it
-      // as a successful reset.
-      try { await pm.kill(sessionKey); }
-      catch (err) { console.error(`[${label}] kill on ${text}: ${err.message}`); }
-      try { db.clearSessionId(sessionKey); } catch { /* swallow */ }
-    }
-    // rc.59: clear contextHint once-per-cycle gate so a freshly-reset
-    // session can fire its own hint when context fills up again.
-    contextHintShown.delete(sessionKey);
-    logEvent('session-reset-command', {
-      chat_id: chatId, command: text, drained_pendings: drained,
-      user: cmdUser, user_id: cmdUserId,
-    });
-    await sendReply('✨ Started a fresh session.');
-    return;
-  }
-  // 0.8.0-rc.9: /steer command removed. Mid-turn user input is
-  // handled implicitly by autosteer — any follow-up message during
-  // an in-flight SDK turn flows through autosteerBuffer +
-  // PostToolBatch hook. No explicit command needed; matches Claude
-  // Code interactive UX where you just keep typing.
-  // Graceful application of a model/effort change to the user's CURRENT
-  // session only. With isolateTopics=false the sessionKey is just the
-  // chat (one shared session for the whole chat — every topic
-  // respawns implicitly). With isolateTopics=true each topic is a
-  // separate session, and a /model in topic A should NOT disturb
-  // topic B's in-flight turn or post a phantom "✓ Using sonnet now"
-  // in a topic that didn't ask.
-  //
-  // CLI pm: requestRespawn drains pending turns then kills the process;
-  //   the next user message spawns fresh with the updated chatConfig.
-  // SDK pm: applies live to the running Query via setModel /
-  //   applyFlagSettings — no respawn needed, change takes effect for
-  //   the rest of the in-flight turn AND all future ones.
-  const applyConfigChange = async (reason, setting, value) => {
-    const target = pm.pickFor(sessionKey);
-    if (typeof target.requestRespawn === 'function') {
-      const res = target.requestRespawn(sessionKey, reason);
-      return { queued: res.queued, anyActive: !res.killed };
-    }
-    if (setting === 'effort' && typeof target.applyFlagSettings === 'function') {
-      const ok = await target.applyFlagSettings(sessionKey, { effortLevel: value });
-      return { queued: 0, anyActive: !ok };
-    }
-    if (setting === 'model' && typeof target.setModel === 'function') {
-      const ok = await target.setModel(sessionKey, value);
-      return { queued: 0, anyActive: !ok };
-    }
-    return { queued: 0, anyActive: false };
-  };
-
-  if (botAllowsCommands && text.startsWith('/model ')) {
-    const newModel = text.slice(7).trim();
-    if (['opus', 'sonnet', 'haiku'].includes(newModel)) {
-      const oldModel = chatConfig.model;
-      // Ephemeral: in-memory only, reverts to config.json on restart.
-      chatConfig.model = newModel;
-      dbWrite(() => db.logConfigChange({
-        chat_id: chatId, thread_id: threadIdStr, field: 'model',
-        old_value: oldModel, new_value: newModel,
-        user: cmdUser, user_id: cmdUserId, source: 'command',
-      }), 'log model change');
-      const { anyActive } = await applyConfigChange('model-change', 'model', newModel);
-      const ver = MODEL_VERSIONS[newModel] || newModel;
-      const suffix = anyActive ? ` — I'll switch when I finish` : '';
-      await sendReply(`Model → ${newModel} (${ver})${suffix}`);
-    } else {
-      await sendReply(`Unknown model. Use: opus, sonnet, haiku`);
-    }
-    return;
-  }
-  if (botAllowsCommands && text.startsWith('/effort ')) {
-    const newEffort = text.slice(8).trim();
-    if (['low', 'medium', 'high', 'xhigh', 'max'].includes(newEffort)) {
-      const oldEffort = chatConfig.effort;
-      // Ephemeral: in-memory only, reverts to config.json on restart.
-      chatConfig.effort = newEffort;
-      dbWrite(() => db.logConfigChange({
-        chat_id: chatId, thread_id: threadIdStr, field: 'effort',
-        old_value: oldEffort, new_value: newEffort,
-        user: cmdUser, user_id: cmdUserId, source: 'command',
-      }), 'log effort change');
-      const { anyActive } = await applyConfigChange('effort-change', 'effort', newEffort);
-      const suffix = anyActive ? ` — I'll switch when I finish` : '';
-      await sendReply(`Effort → ${newEffort}${suffix}`);
-    } else {
-      await sendReply(`Unknown effort. Use: low, medium, high, xhigh, max`);
-    }
-    return;
-  }
-  // Admin-only pairing commands — chat must match config.bot.adminChatId.
-  // allowConfigCommands alone is NOT sufficient: that flag gates /model and
-  // /effort which only affect the current chat. Pairing issues cross-chat
-  // trust and must be narrowed further.
-  const adminChatId = config.bot?.adminChatId ? String(config.bot.adminChatId) : null;
-  const isAdminChat = adminChatId && String(chatId) === adminChatId;
-
-  if (botAllowsCommands && text.startsWith('/pair-code')) {
-    if (!isAdminChat) { await sendReply('Pairing commands are admin-only; run from the admin chat.'); return; }
-    const issuerId = cmdUserId;
-    if (!issuerId) { await sendReply('No user id on request'); return; }
-    const args = parsePairCodeArgs(text);
-    try {
-      const out = pairings.issueCode({
-        bot_name: BOT_NAME,
-        chat_id: args.chat || null,
-        scope: args.scope || 'user',
-        issued_by_user_id: issuerId,
-        ttlMs: args.ttl ? parsePairingTtl(args.ttl) : undefined,
-        note: args.note || null,
-      });
-      logEvent('pair-code-issued', {
-        bot: BOT_NAME, by: issuerId, scope: out.scope,
-        chat_id: out.chat_id, note: out.note,
-      });
-      const ttlLabel = args.ttl || '10m';
-      const chatLabel = out.chat_id ? `chat ${out.chat_id}` : 'any chat';
-      await sendReply(
-        `Code: ${out.code}\nexpires: ${ttlLabel}\nscope: ${out.scope} (${chatLabel})${out.note ? `\nnote: ${out.note}` : ''}\n\nShare with user:\n/pair ${out.code}`,
-      );
-    } catch (err) {
-      await sendReply(`Could not issue code: ${err.message}`);
-    }
-    return;
-  }
-  if (botAllowsCommands && text.startsWith('/pairings')) {
-    if (!isAdminChat) { await sendReply('Pairing commands are admin-only; run from the admin chat.'); return; }
-    const rows = pairings.listActive(BOT_NAME);
-    if (!rows.length) { await sendReply('No active pairings.'); return; }
-    const lines = rows.map(r => {
-      const chat = r.chat_id ? `chat ${r.chat_id}` : 'any chat';
-      const granted = new Date(r.granted_ts).toISOString().slice(0, 16).replace('T', ' ');
-      const note = r.note ? ` — ${r.note}` : '';
-      return `• user ${r.user_id} — ${chat} — ${granted}${note}`;
-    });
-    await sendReply(`Active pairings (${rows.length}):\n${lines.join('\n')}`);
-    return;
-  }
-  if (botAllowsCommands && text.startsWith('/unpair ')) {
-    if (!isAdminChat) { await sendReply('Pairing commands are admin-only; run from the admin chat.'); return; }
-    const arg = text.slice(8).trim();
-    const targetId = parseInt(arg, 10);
-    if (!Number.isFinite(targetId)) {
-      await sendReply('Usage: /unpair <user_id>'); return;
-    }
-    const n = pairings.revokeByUser({ bot_name: BOT_NAME, user_id: targetId });
-    logEvent('pair-revoked', {
-      bot: BOT_NAME, user_id: targetId, by: cmdUserId, count: n,
-    });
-    await sendReply(n ? `Revoked ${n} pairing(s) for user ${targetId}.` : `No active pairings for user ${targetId}.`);
-    return;
-  }
-  // /pair <CODE> — open to anyone, no admin gate (the code IS the auth)
-  if (text.startsWith('/pair ') && !text.startsWith('/pair-code') && !text.startsWith('/pairings')) {
-    if (!cmdUserId) { await sendReply('No user id on request'); return; }
-    const code = text.slice(6).trim();
-    const res = pairings.claimCode({
-      code, claimer_user_id: cmdUserId,
-      chat_id: chatId, bot_name: BOT_NAME,
-    });
-    logEvent('pair-claim-attempt', {
-      bot: BOT_NAME, user_id: cmdUserId, chat_id: chatId,
-      ok: res.ok, reason: res.reason,
-    });
-    if (res.ok) {
-      const chatLabel = res.chat_id ? `chat ${res.chat_id}` : `every chat ${BOT_NAME} is in`;
-      await sendReply(`Paired. You can use me in ${chatLabel}.${res.note ? `\n(${res.note})` : ''}`);
-    } else {
-      // Collapse specific failure reasons into a single "invalid or expired"
-      // response to prevent enumeration: distinguishing "wrong-chat" from
-      // "not-found" would tell an attacker a valid code prefix. The
-      // pair-claim-attempt event above still logs the precise reason for
-      // operator audit.
-      const userMsg = res.reason === 'rate-limited'
-        ? 'Too many attempts. Try again later.'
-        : 'Invalid or expired code.';
-      await sendReply(userMsg);
-    }
-    return;
-  }
+  // Slash command dispatch — extracted to lib/handlers/slash-commands.js.
+  // Covers /context /compact /reload /new /reset /model /effort
+  // /pair-code /pairings /unpair /pair. Returns true when handled;
+  // caller short-circuits.
+  if (await dispatchSlashCommand({
+    text, sessionKey, chatId, threadIdStr, chatConfig,
+    cmdUser, cmdUserId, label, sendReply,
+  })) return;
 
   const t0 = Date.now();
 
@@ -2759,19 +923,10 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
   // voice transcription, don't overwrite it. Let onFirstStream
   // promote to 🤔 when Claude actually starts work.
   //
-  // rc.32 second guard: skip THINKING if we're going to autosteer
-  // this message. Pre-fix, autosteer messages briefly showed
-  // 🤔 → ✍ (THINKING set here, then AUTOSTEERED set inside the
-  // autosteer block ~50 lines below). The flash was visible to
-  // users. Detect the autosteer pre-condition (SDK pm active AND
-  // session in-flight AND chat hasn't opted out) and skip.
-  const willAutosteer = pm.has(sessionKey)
-    && pm.get(sessionKey)?.inFlight
-    && pm.isSdkFor(sessionKey)
-    && (chatConfig.autosteer != null
-      ? chatConfig.autosteer !== false
-      : config.bot?.autosteer !== false);
-  if (!voiceAck.ackEmitted && !willAutosteer) {
+  // Skip the 🤔 → ✍ flash for messages that are about to be
+  // autosteered. willAutosteer evaluates the same pre-condition
+  // tryAutosteer would.
+  if (!voiceAck.ackEmitted && !autosteer.willAutosteer(sessionKey, chatConfig)) {
     reactor.setState('THINKING');
   }
 
@@ -2781,86 +936,33 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
   // exit paths below (NO_REPLY, streamed-reply preview-becomes-final,
   // discard+redeliver, regular reply at end) call it directly.
 
-  // 0.8.0 Phase 2 step 1 — AUTOSTEER. If SDK pm is active AND there's
-  // already an in-flight turn for this session AND autosteer isn't
-  // disabled in config, route this user message via pm.steer()
-  // instead of pm.send(). Matches OpenClaw's default UX: typing a
-  // follow-up while the bot is mid-reply MERGES into the active
-  // turn rather than queueing as a separate response. Saves a turn,
-  // saves tokens, feels more conversational.
-  //
-  // Opt-out: config.bot.autosteer === false (or per-chat
-  // chatConfig.autosteer === false). CLI pm always falls through
-  // to the queue-FIFO path (no steer primitive on stream-json).
+  // AUTOSTEER. If session is in-flight AND autosteer isn't disabled,
+  // route this user message via pm.injectUserMessage instead of
+  // pm.send (OpenClaw "merge into active" UX). The steered message
+  // gets a ✍ reaction so the user knows it landed; the in-flight
+  // turn's response covers both messages.
   //
-  // The steered message gets a ✍ reaction so the user knows it
-  // landed; no separate reply is generated (the in-flight turn's
-  // response covers both messages, OpenClaw-style).
+  // Mode: chatConfig.autosteerMode = 'merge' (priority='next', default)
+  // | 'queue' (priority='later'). Spike findings in
+  // scripts/spikes/native-queue.mjs.
   //
-  // Reaction emoji must be from Telegram's curated allowlist
-  // (~60 standard emoji per core.telegram.org/bots/api#availablereactions).
-  // 🛞 (steering wheel) is NOT on it — Telegram returns
-  // 400: REACTION_INVALID. ✍ ("writing/noting") is on the list and
-  // conveys "incorporating this".
-  const chatAutosteer = chatConfig.autosteer != null
-    ? chatConfig.autosteer
-    : config.bot?.autosteer;
-  // 0.8.0-rc.42: autosteer is now native — push the user message
-  // directly onto the SDK's input controller with a priority hint.
-  // The SDK manages absorption / queueing per the U7 spike findings
-  // (scripts/spikes/native-queue.mjs, 2026-05-01):
-  //
-  //   priority='next' (default): absorb into current turn at the next
-  //     natural pause (between tool calls / after subagent return).
-  //     ONE result event for the whole chain — same UX as the
-  //     deleted autosteer-buffer + PostToolBatch flow.
-  //   priority='later': queue for after current turn ends. SEPARATE
-  //     result event per absorbed message. Cleaner per-msg lifecycle
-  //     for chats that prefer accurate cost-row attribution.
-  //
-  // Per-chat opt-in via `chatConfig.autosteerMode: 'merge' | 'queue'`.
-  // 'merge' → priority='next' (default). 'queue' → priority='later'.
-  //
-  // Pre-rc.42 this used a custom autosteerBuffer + PostToolBatch hook
-  // returning <channel source="user-followup"> additionalContext. The
-  // SDK at the time rejected priority='now' mid-tool-use (m87 gate);
-  // 'next'/'later' were never tested. The U7 spike confirmed all
-  // three priorities now work cleanly — so the buffer/hook detour is
-  // gone. ~250 LOC + 2 test files deleted.
-  //
-  // CLI pm has no inputController push primitive, so it falls
-  // through to FIFO pm.send (same UX as 0.7.x — queued behind active).
-  const autosteerEnabled = chatAutosteer !== false
-    && pm.isSdkFor(sessionKey);
-  if (autosteerEnabled && pm.has(sessionKey)) {
-    const entry = pm.get(sessionKey);
-    if (entry?.inFlight) {
-      const autosteerMode = chatConfig.autosteerMode != null
-        ? chatConfig.autosteerMode
-        : config.bot?.autosteerMode;
-      const priority = autosteerMode === 'queue' ? 'later' : 'next';
-      const ok = pm.injectUserMessage(sessionKey, {
-        content: prompt,
-        priority,
-      });
-      if (ok) {
-        autosteeredRefs.add(sessionKey, { chatId, msgId: msg.message_id });
-        logEvent('autosteer', {
-          chat_id: chatId, msg_id: msg.message_id,
-          text_len: prompt?.length ?? 0,
-          priority,
-        });
-        stopTyping();
-        // setState('AUTOSTEERED') is terminal — bypasses the throttle,
-        // serializes after any in-flight QUEUED apply via applyChain.
-        await reactor.setState('AUTOSTEERED');
-        // rc.38: AUTOSTEERED is terminal; stop the reactor's STALL /
-        // TIMEOUT timers so they don't pin the closure for up to 30s.
-        reactor.stop();
-        markReplied();
-        return;
-      }
-    }
+  // Reaction emoji must be from Telegram's curated allowlist (~60
+  // standard emoji per core.telegram.org/bots/api#availablereactions).
+  // 🛞 is NOT on it (400: REACTION_INVALID). ✍ ("writing/noting")
+  // is on the list and conveys "incorporating this".
+  const steered = autosteer.tryAutosteer({
+    sessionKey, chatConfig, chatId, msg, prompt,
+  });
+  if (steered.autosteered) {
+    stopTyping();
+    // setState('AUTOSTEERED') is terminal — bypasses throttle,
+    // serializes after any in-flight QUEUED apply via applyChain.
+    await reactor.setState('AUTOSTEERED');
+    // AUTOSTEERED is terminal; stop the reactor's STALL / TIMEOUT
+    // timers so they don't pin the closure for up to 30s.
+    reactor.stop();
+    markReplied();
+    return;
   }
 
   try {
@@ -2914,12 +1016,9 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
       // role_ordering / context_overflow / missing_tool_input),
       // tell pm to reset the session NOW so the user's NEXT
       // message starts fresh — without them having to type /new.
-      // Only fires when pm.resetSession is available (SDK pm
-      // path); CLI pm doesn't have the method.
       const cls = classifyError(result.error);
-      const recoverTarget = pm.pickFor(sessionKey);
-      if (cls.autoRecover === 'reset_session' && typeof recoverTarget.resetSession === 'function') {
-        recoverTarget.resetSession(sessionKey, { reason: cls.kind })
+      if (cls.autoRecover === 'reset_session') {
+        pm.resetSession(sessionKey, { reason: cls.kind })
           .catch((err) => console.error(`[${label}] auto-reset failed: ${err.message}`));
         logEvent('auto-recover', {
           chat_id: chatId, kind: cls.kind, action: 'reset_session',
@@ -2951,14 +1050,12 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
       // result, the followup messages (if any) get their own SDK
       // pause to absorb at, no special handling needed.
 
-      // 0.8.0 Phase 2 step 4: context-full live hint. After a
-      // successful turn, peek at SDK's getContextUsage(); if past
-      // the threshold, post a quiet hint so the user knows /new
-      // will help. SDK pm only — CLI pm has no equivalent (no
-      // Query object, no getContextUsage). OPT-IN per-chat or
-      // per-bot — most chats don't want the noise. Per-chat takes
-      // precedence over per-bot so admins (Ivan DM) can opt in
-      // without forcing it on every other chat.
+      // Context-full live hint. After a successful turn, peek at
+      // SDK's getContextUsage(); if past the threshold, post a
+      // quiet hint so the user knows /new will help. OPT-IN
+      // per-chat or per-bot — most chats don't want the noise.
+      // Per-chat takes precedence over per-bot so admins (Ivan DM)
+      // can opt in without forcing it on every other chat.
       //
       // rc.56: threshold default lowered to 70% (was 85%) because
       // the SDK auto-compacts mid-turn at ~85% — by the time
@@ -2977,7 +1074,7 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
       // session first crosses the threshold, mark the flag, suppress
       // subsequent fires. Cleared on compact-boundary so the next
       // cycle (if it crosses again) will fire fresh.
-      if (pm.isSdkFor(sessionKey) && chatCtxHint === true && !contextHintShown.has(sessionKey)) {
+      if (chatCtxHint === true && !contextHintShown.has(sessionKey)) {
         const entry = pm.get(sessionKey);
         const q = entry?.query;
         if (q && typeof q.getContextUsage === 'function') {
@@ -3443,91 +1540,11 @@ function createBot(token) {
     const rawText = msg.text || '';
     const cleanText = mentionRe ? rawText.replace(mentionRe, '').trim() : rawText.trim();
 
-    // Abort: skip the queue entirely. Matches bilingual natural-language
-    // cues ("stop" / "стоп" / "cancel" / "отмена" / …) and explicit
-    // slash commands (/stop, /abort, /cancel). Kills the active Claude
-    // subprocess and drains queued messages for this chat. Replies so
-    // the user sees the bot heard them — silent abort is worse than
-    // acknowledged abort.
-    if (isAbortRequest(cleanText)) {
-      const threadId = msg.message_thread_id?.toString();
-      const sessionKey = getSessionKey(chatId, threadId, chatConfig);
-      const hadActive = pm.has(sessionKey) && !!pm.get(sessionKey)?.inFlight;
-      // Mark BEFORE killing: the 'close' event fires almost immediately
-      // after SIGTERM, and processQueue's catch needs to see the flag to
-      // skip the generic error-reply. If we marked after, there'd be a
-      // race where the error-reply slips through.
-      if (hadActive) markSessionAborted(sessionKey);
-      // 0.8.0 Phase 2 step 2: under SDK pm, prefer interrupt() +
-      // drainQueue() — keeps the Query alive (cheap to reuse for
-      // the user's next message), no respawn cost. Falls back to
-      // pm.kill() under CLI pm, which is the original behaviour.
-      //
-      // Why both: interrupt() cancels the in-flight turn at SDK
-      // level WITHOUT tearing down the subprocess; drainQueue()
-      // rejects every queued pending with err.code='INTERRUPTED'
-      // so the abort-grace classifier suppresses error replies.
-      //
-      // Kill ONLY the user's own session, not every topic in the
-      // chat. Pre-0.6.5 this was pm.killChat(chatId) which fanned
-      // out across all topics under isolateTopics=true: the user
-      // typed "stop" in topic A and the bot tore down topic B's
-      // in-flight turn, surfacing a 💥 reply to topic B's user
-      // (whose key was never marked aborted, so the abort grace
-      // window didn't apply). With isolateTopics=false the
-      // sessionKey is the chat itself, so killing one session is
-      // the same as killing the chat — behavior unchanged for the
-      // common case.
-      const stopTarget = pm.pickFor(sessionKey);
-      if (typeof stopTarget.interrupt === 'function') {
-        await stopTarget.interrupt(sessionKey).catch((err) =>
-          console.error(`[${BOT_NAME}] interrupt failed: ${err.message}`));
-        if (typeof stopTarget.drainQueue === 'function') {
-          stopTarget.drainQueue(sessionKey, 'INTERRUPTED');
-        }
-      } else {
-        await stopTarget.kill(sessionKey).catch((err) =>
-          console.error(`[${BOT_NAME}] abort kill failed: ${err.message}`));
-      }
-      // rc.42: autosteer buffer is gone (native SDK priority push).
-      // Followups already pushed onto the SDK's input controller will
-      // be drained by drainQueue() / kill() on the entry — no separate
-      // buffer to clear.
-      // Clear ✍ reactions on already-autosteered messages from this
-      // aborted turn — they're now dead context.
-      clearAutosteeredReactions(sessionKey).catch(() => {});
-      logEvent('abort-requested', {
-        chat_id: chatId, user_id: msg.from?.id || null,
-        had_active: hadActive,
-        trigger: cleanText.slice(0, 40),
-      });
-      // Reply in the same language the user aborted in. Cyrillic-detection
-      // is crude but reliable for ru/en (the only two cue sets we ship).
-      // 0.6.12 fix: pre-0.6.5 the message included a "queue cleared (N)"
-      // suffix when N > 0; that came from drainQueuesForChat which always
-      // returned 0 in the concurrent model and was deleted in 0.6.5.
-      // The reference to `dropped` here was missed, so EVERY abort hit
-      // a ReferenceError that the surrounding `catch {}` swallowed —
-      // leaving the user with no ack at all. Reduced to "stopped vs
-      // nothing-to-stop" since the queue-cleared variant was already
-      // dead.
-      const lang = /[а-яё]/i.test(cleanText) ? 'ru' : 'en';
-      const strs = {
-        en: { stopped: 'Stopped.',     nothing: 'Nothing to stop.' },
-        ru: { stopped: 'Остановлено.', nothing: 'Нечего останавливать.' },
-      }[lang];
-      const reply = hadActive ? strs.stopped : strs.nothing;
-      try {
-        await tg(bot, 'sendMessage', {
-          chat_id: chatId, text: reply,
-          reply_parameters: { message_id: msg.message_id, allow_sending_without_reply: true },
-          ...(threadId && { message_thread_id: threadId }),
-        }, { source: 'abort-ack', botName: BOT_NAME });
-      } catch (err) {
-        // Don't swallow silently — if the ack itself fails, the operator
-        // needs to know (the user typed stop and saw nothing).
-        console.error(`[${BOT_NAME}] abort-ack send failed: ${err.message}`);
-      }
+    // Abort: skip the queue entirely. Matches bilingual natural-
+    // language cues + slash variants. handleAbortIfRequested
+    // (lib/handlers/abort.js) returns true when handled — short-
+    // circuit out of dispatch.
+    if (await handleAbortIfRequested(msg, chatId, chatConfig, cleanText)) {
       return;
     }
 
@@ -3645,8 +1662,18 @@ function createBot(token) {
   });
 
   bot.on('callback_query:data', async (ctx) => {
+    if (!isWellFormedCallbackQuery(ctx.callbackQuery)) {
+      logEvent('malformed-update', {
+        bot: BOT_NAME,
+        update_id: ctx.update?.update_id,
+        reason: 'callback_query missing message/from/data or inline-mode',
+      });
+      // Best-effort ack so Telegram stops re-sending. May fail silently.
+      await ctx.answerCallbackQuery({ text: 'Stale or invalid button.' }).catch(() => {});
+      return;
+    }
     try {
-      const data = ctx.callbackQuery?.data || '';
+      const data = ctx.callbackQuery.data;
       if (data.startsWith('cfg:')) {
         await handleConfigCallback(ctx);
       } else {
@@ -3737,117 +1764,9 @@ function createBot(token) {
   return bot;
 }
 
-// ─── Manual polling ─────────────────────────────────────────────────
-
-async function pollBot(bot) {
-  await bot.init();
-  bot._setBotUsername(bot.botInfo.username);
-  console.log(`[${BOT_NAME}] Bot @${bot.botInfo.username} ready`);
-
-  await bot.api.deleteWebhook();
-
-  // Restore polling offset from DB so a restart doesn't re-process the
-  // backlog Telegram has accumulated while we were down. Grammy's in-memory
-  // offset resets to 0 each boot, which makes getUpdates return every
-  // un-confirmed update since the last ack — for an overnight outage that
-  // can mean replaying dozens of stale messages.
-  let offset = 0;
-  try {
-    const saved = db?.getPollingOffset?.(BOT_NAME);
-    if (saved && saved > 0) {
-      offset = saved + 1;
-      console.log(`[${BOT_NAME}] resuming polling from update_id ${saved}`);
-    }
-  } catch (err) {
-    console.error(`[${BOT_NAME}] getPollingOffset failed: ${err.message}`);
-  }
-  let running = true;
-  bot._lastPollTs = Date.now();
-
-  bot._stop = () => { running = false; };
-
-  while (running) {
-    try {
-      const updates = await bot.api.getUpdates({
-        offset,
-        // Long-poll: Telegram holds the connection up to 25s waiting for
-        // updates. When something arrives it returns immediately; empty
-        // windows cost ~0 local CPU. Drops median inbound latency vs the
-        // old short-poll-every-1s.
-        timeout: 25,
-        allowed_updates: ['message', 'edited_message', 'callback_query'],
-      });
-      bot._lastPollTs = Date.now();
-
-      for (const update of updates) {
-        offset = update.update_id + 1;
-        if (update.message && isWellFormedMessage(update.message)) {
-          const m = update.message;
-          const chatId = m.chat.id.toString();
-          const chatConfig = config.chats[chatId];
-          const threadId = m.message_thread_id?.toString();
-          // rc.57: use getTopicName() helper which handles BOTH legacy string
-          // form and rc.48 object form. Pre-rc.57 the direct lookup
-          // `chatConfig.topics[threadId]` template-literal'd into "[object Object]"
-          // because rc.48 topics are objects like {name:"Music",agent:"...",...}.
-          const topicName = threadId
-            ? (chatConfig ? getTopicName(chatConfig, threadId) : threadId)
-            : null;
-          const chatLabel = chatConfig?.name || chatId;
-          const label = topicName ? `${chatLabel}/${topicName}` : chatLabel;
-          console.log(`[${BOT_NAME}] ← ${label}: ${(m.text || m.caption || '(media)').slice(0, 60)}`);
-        }
-        try {
-          await bot.handleUpdate(update);
-        } catch (err) {
-          console.error(`[${BOT_NAME}] Handler error:`, err.message);
-        }
-      }
-      // Persist offset after batch dispatch so a crash mid-batch only risks
-      // re-processing the unacked updates. We write only on non-empty batches
-      // to avoid churning the row on every 25s idle poll.
-      if (updates.length > 0) {
-        dbWrite(() => db.savePollingOffset(BOT_NAME, updates[updates.length - 1].update_id),
-          'save polling offset');
-      }
-      // No sleep on the success path: long-poll already blocks up to 25s
-      // when idle. Sleeping here would add latency with no gain.
-    } catch (err) {
-      if (!running) break;
-      if (err.error_code === 409) {
-        console.log(`[${BOT_NAME}] 409, waiting 3s...`);
-        await new Promise(r => setTimeout(r, 3000));
-      } else {
-        console.error(`[${BOT_NAME}] Poll error:`, err.message);
-        await new Promise(r => setTimeout(r, 3000));
-      }
-    }
-  }
-}
-
-// Watchdog: if the poll loop hasn't ticked in POLL_STALL_MS, log an event
-// so external monitoring (or a human reading `events`) can see it. Launchd
-// restarts the whole process on death, so we don't exit here — a stalled
-// grammy poll is usually transient (network flap, Telegram 5xx).
-const POLL_STALL_MS = 120_000;
-function startPollWatchdog(bot) {
-  let stalled = false;
-  return setInterval(() => {
-    const now = Date.now();
-    const age = now - (bot._lastPollTs || 0);
-    if (age > POLL_STALL_MS) {
-      if (!stalled) {
-        console.error(`[${BOT_NAME}] poll-stalled: no tick in ${Math.round(age / 1000)}s`);
-        logEvent('poll-stalled', { bot: BOT_NAME, stall_ms: age });
-        stalled = true;
-      }
-    } else if (stalled) {
-      console.log(`[${BOT_NAME}] poll-recovered after stall`);
-      logEvent('poll-recovered', { bot: BOT_NAME });
-      stalled = false;
-    }
-  }, 30_000);
-}
+// ─── Manual polling — extracted to lib/handlers/poll.js ────────────
+let pollBot = null;
+let startPollWatchdog = null;
 
 // ─── Main ───────────────────────────────────────────────────────────
 
@@ -3942,281 +1861,126 @@ async function main() {
 
   const cap = config.maxWarmProcesses || DEFAULT_MAX_WARM_PROCS;
 
-  // 0.8.0-rc.6: per-chat pm selection. Three modes:
-  //   1. POLYGRAM_USE_SDK=1 with no POLYGRAM_SDK_CHATS list  → all chats SDK
-  //   2. POLYGRAM_SDK_CHATS=id1,id2,...                       → those chats
-  //      use SDK; everyone else uses CLI (both pms live in the daemon)
-  //   3. neither set                                          → all chats CLI
-  // The per-chat mode lets us soak SDK pm against real traffic in one
-  // chat (Ivan's DM) while keeping partner-facing chats on the
-  // battle-tested CLI path. When both pms run, killChat /shutdown
-  // broadcast to both; everything else routes per-sessionKey via
-  // pickPmFor() based on the chat's set membership.
-  // rc.17: router policy + proxy live in lib/pm-router.js for
-  // testability. Policy parses env config and produces
-  // pickPmKindFor; createPmRouter wraps the cli/sdk pms with the
-  // routed surface.
-  const { sdkActive, sdkAllChats, sdkSomeChats, sdkChatIdSet, pickPmKindFor } = makeRouterPolicy({
-    useSdkAll: USE_SDK,
-    sdkChats: String(process.env.POLYGRAM_SDK_CHATS || '').split(','),
-    getChatIdFromKey,
+  // 0.9.0: single pm. SDK ProcessManager is the only impl after the
+  // CLI pm + dual-pm router were deleted (see lib/pm-router.js
+  // header comment for the migration history).
+  // 0.9.0 commit 19: SDK lifecycle callbacks live in lib/sdk/callbacks.js;
+  // factory threads the runtime context in via DI. onRespawn dropped
+  // earlier — SDK pm applies /model + /effort live so there's no
+  // drain event to hook.
+  const sdkCallbacks = createSdkCallbacks({
+    db, dbWrite, config, bot, botName: BOT_NAME, tg, logEvent,
+    classifyToolName, announce, shouldAnnounce, contextHintShown,
+    extractAssistantText, getChatIdFromKey, getThreadIdFromKey,
+    logger: console,
   });
-
-  // Shared callbacks: identical instance passed to both pms so a
-  // chat's lifecycle events look the same regardless of which pm
-  // is handling it.
   const pmOpts = {
     cap,
     db,
     logger: console,
-    onInit: (sessionKey, event, entry) => {
-      dbWrite(() => db.upsertSession({
-        session_key: sessionKey,
-        chat_id: entry.chatId,
-        thread_id: entry.threadId,
-        claude_session_id: event.session_id,
-        agent: config.chats[entry.chatId]?.agent || null,
-        cwd: config.chats[entry.chatId]?.cwd || null,
-        model: config.chats[entry.chatId]?.model || null,
-        effort: config.chats[entry.chatId]?.effort || null,
-      }), `upsert session ${sessionKey}`);
-    },
-    onClose: (sessionKey, code, entry) => {
-      console.log(`[${entry.label}] Process exited (code ${code})`);
-      logEvent('process-close', { chat_id: entry.chatId, session_key: sessionKey, code });
-    },
-    onStreamChunk: (sessionKey, partial, entry) => {
-      // Route to the head pending's per-turn streamer. In the 0.4.8
-      // concurrent-pending model, there can be N pendings queued — only
-      // the HEAD is the turn Claude is actively emitting events for.
-      const head = entry.pendingQueue?.[0];
-      const s = head?.context?.streamer;
-      if (s) s.onChunk(partial).catch(() => {});
-      // 0.8.0-rc.16: heartbeat the reactor so long text generation
-      // doesn't trip the 10s STALL → 🥱 / 30s TIMEOUT → 😨 promotion.
-      // Pre-rc.16 the reactor only got setState calls at turn start
-      // (THINKING) and per-tool (CODING/TOOL/...); pure text turns
-      // hit STALL within 10s of streaming. heartbeat() re-arms the
-      // stall timers without changing the visible emoji.
-      const r = head?.context?.reactor;
-      if (r && typeof r.heartbeat === 'function') r.heartbeat();
-    },
-    onToolUse: (sessionKey, toolName, entry) => {
-      const head = entry.pendingQueue?.[0];
-      const r = head?.context?.reactor;
-      if (r) r.setState(classifyToolName(toolName));
-      // 0.7.0 (Phase J): opt-in subagent announce. When Claude uses
-      // the Task tool to spawn a subagent, post a brief informational
-      // message to the chat so the user knows a heavier turn is in
-      // progress. ON by default (rc.9+) — set per-chat
-      // `announceSubagents: false` (or per-bot) to silence.
-      // Per-chat debounce 30s prevents announce-storms in tool-heavy
-      // turns.
-      const chatCfg = config.chats[entry.chatId] || {};
-      const optOut = chatCfg.announceSubagents != null
-        ? chatCfg.announceSubagents === false
-        : config.bot?.announceSubagents === false;
-      if (toolName === 'Task' && !optOut) {
-        if (shouldAnnounce(entry.chatId)) {
-          announce({
-            send: (b, method, params, m) => tg(b, method, params, m),
-            bot, chatId: entry.chatId,
-            threadId: head?.context?.threadId ?? null,
-            text: '🤖 Spawning subagent…',
-            meta: { botName: BOT_NAME, source: 'subagent-announce' },
-            logger: { error: (m) => console.error(`[${entry.label}] ${m}`) },
-          });
-        }
-      }
-    },
-    // 0.7.0 (Phase F): each new top-level assistant message gets its
-    // own bubble. When Claude emits text, then tool_use, then more
-    // text in a NEW assistant message (typical of tool-heavy turns),
-    // the previous bubble's content stays visible as a "thinking out
-    // loud" intermediate; the new message starts fresh below.
-    onAssistantMessageStart: (sessionKey, entry) => {
-      const head = entry.pendingQueue?.[0];
-      const s = head?.context?.streamer;
-      if (s) s.forceNewMessage();
-      // rc.25: heartbeat at every assistant-message boundary too. A
-      // long thinking phase (effort=high, 30+ s before first chunk)
-      // doesn't fire onStreamChunk. Without this, the freeze timer
-      // could expire while the model is "still thinking but about
-      // to speak".
-      const r = head?.context?.reactor;
-      if (r && typeof r.heartbeat === 'function') r.heartbeat();
-    },
-    // rc.47: autonomous wakeup forwarding. Fires when an SDK
-    // assistant message arrives with no head pending — typical
-    // ScheduleWakeup case where the agent self-fires without an
-    // inbound user message. We derive chat_id (always) and thread_id
-    // (when isolateTopics) from the sessionKey, then send the text
-    // to that chat/topic. Subagent messages were already filtered
-    // upstream (parent_tool_use_id != null check in pm-sdk).
-    //
-    // Best-effort send: failures are logged but don't propagate —
-    // an autonomous turn that can't be delivered shouldn't crash
-    // the daemon. Telemetry emitted as `autonomous-wakeup-message`
-    // so we can audit how often these fire and whether any get lost.
-    onAutonomousAssistantMessage: (sessionKey, msg /* , entry */) => {
-      try {
-        const text = extractAssistantText(msg);
-        if (!text) return;
-        const chatId = getChatIdFromKey(sessionKey);
-        const threadIdRaw = getThreadIdFromKey(sessionKey);
-        const threadId = threadIdRaw ? parseInt(threadIdRaw, 10) : null;
-        if (!bot) {
-          console.error(`[${BOT_NAME}] autonomous wakeup: bot not ready, dropping ${text.length} chars`);
-          return;
-        }
-        const params = {
-          chat_id: chatId,
-          text,
-          ...(Number.isInteger(threadId) && { message_thread_id: threadId }),
-        };
-        // Don't `await` — keep the pm-sdk event loop unblocked. The
-        // tg() wrapper handles its own retries / chunking.
-        tg(bot, 'sendMessage', params,
-          { source: 'autonomous-wakeup', botName: BOT_NAME }).catch((err) => {
-            console.error(`[${BOT_NAME}] autonomous wakeup send failed: ${err.message}`);
-          });
-        logEvent('autonomous-wakeup-message', {
-          chat_id: chatId,
-          session_key: sessionKey,
-          thread_id: threadIdRaw,
-          text_len: text.length,
-        });
-      } catch (err) {
-        console.error(`[${BOT_NAME}] autonomous wakeup handler: ${err.message}`);
-      }
-    },
-    // rc.29 onThinking removed — replaced by simpler timer-based
-    // approach in handleMessage (post-QUEUED setState). The
-    // SDK-thinking-block detection added complexity (partial-message
-    // bandwidth, thinking config mapping) without solving the actual
-    // user-visible problem ("show me the bot is working"). The lib-
-    // side handler in pm-sdk stays for any future caller; polygram
-    // doesn't wire it.
-    // 0.8.0 Phase 2 step 5: SDK auto-compaction observability. Fires
-    // when SDK emits SDKCompactBoundaryMessage (between turns or
-    // mid-turn — see Phase 0 gate 8.5). Surfaces a quiet system
-    // status note to the chat so the user knows the bot is busy
-    // reorganising context (compaction can take seconds, during
-    // which the bot looks unresponsive). ON by default (rc.12+) —
-    // set per-chat or per-bot `announceCompact: false` to silence.
-    // Only fires under SDK pm — the CLI pm has no equivalent event.
-    //
-    // Wording is intentionally non-technical — the user doesn't
-    // care about "compaction" or "tokens"; they just want to know
-    // the bot didn't hang.
-    onCompactBoundary: async (sessionKey, msg, entry) => {
-      // rc.59: clear the contextHint once-per-cycle gate. After
-      // compaction, context drops below threshold; if it climbs back
-      // up the next cycle should fire a fresh hint. Without this
-      // clear, a session that fired its hint pre-compact would never
-      // fire again for the rest of the daemon's life.
-      contextHintShown.delete(sessionKey);
-
-      const chatCfg = config.chats[entry.chatId] || {};
-      const optOut = chatCfg.announceCompact != null
-        ? chatCfg.announceCompact === false
-        : config.bot?.announceCompact === false;
-      if (optOut) return;
-      const threadId = entry.threadId || undefined;
-
-      // rc.62: word the message based on what actually happened.
-      // Pre-rc.62 we said "💭 Catching up on history, one moment…"
-      // for every compact_boundary — but the event fires AFTER
-      // compaction completed, not during. The "one moment…" wording
-      // implied more work was coming, leaving the user confused
-      // when nothing followed. Now: distinguish manual vs auto and
-      // surface the actual compression ratio.
-      const meta = msg?.compact_metadata || {};
-      const trigger = meta.trigger;        // 'manual' | 'auto'
-      const preTokens = meta.pre_tokens;
-      const postTokens = meta.post_tokens;
-      const durationMs = meta.duration_ms;
-      const fmtTok = (n) => {
-        if (n == null) return null;
-        if (n >= 1000) return `${(n / 1000).toFixed(1)}k`;
-        return String(n);
-      };
-      const ratio = (preTokens && postTokens) ? `${fmtTok(preTokens)} → ${fmtTok(postTokens)}` : null;
-      const duration = durationMs ? `${(durationMs / 1000).toFixed(1)}s` : null;
-      const stats = [ratio, duration].filter(Boolean).join(', ');
-
-      let text;
-      if (trigger === 'manual') {
-        // /compact — the user explicitly asked. Compaction is DONE,
-        // session is idle, ready for next message.
-        text = stats
-          ? `✅ Compacted (${stats}). Ready for your next message.`
-          : `✅ Compacted. Ready for your next message.`;
-      } else {
-        // Auto-compaction (mid-turn). The agent is continuing, this
-        // is just informational — show that something happened
-        // without implying "wait, more is coming."
-        text = stats
-          ? `💭 Auto-compacted (${stats}). Continuing…`
-          : `💭 Auto-compacted. Continuing…`;
-      }
-
-      try {
-        await tg(bot, 'sendMessage', {
-          chat_id: entry.chatId,
-          text,
-          ...(threadId ? { message_thread_id: threadId } : {}),
-        }, { source: 'compact-boundary', botName: BOT_NAME });
-      } catch (err) {
-        console.error(`[${entry.label}] compact-boundary post: ${err.message}`);
-      }
-    },
-    // Fires after a graceful /model or /effort drain has actually
-    // swapped to the new settings. Post a confirmation back to the
-    // chat ONLY when wasDrained=true — the user actively waited for an
-    // in-flight turn to finish before the switch took effect, so the
-    // explicit "switched" message is meaningful. When the kill was
-    // immediate (queue empty), the inline-card update + button toast
-    // already convey "done", and a separate message is just noise.
-    onRespawn: (sessionKey, reason, entry, wasDrained) => {
-      if (!wasDrained) return;
-      const chatId = entry.chatId;
-      if (!chatId) return;
-      const chatConfig = config.chats[chatId];
-      if (!chatConfig) return;
-      const text = reason === 'model-change'
-        ? `✓ Using ${chatConfig.model} now.`
-        : reason === 'effort-change'
-        ? `✓ Effort is ${chatConfig.effort} now.`
-        : `✓ Ready.`;
-      const threadId = entry.threadId || undefined;
-      tg(bot, 'sendMessage', {
-        chat_id: chatId, text,
-        ...(threadId && { message_thread_id: threadId }),
-      }, { source: 'respawn-confirm', botName: BOT_NAME }).catch(() => {});
-    },
+    ...sdkCallbacks,
   };
 
-  // Instantiate the actual pm(s). When sdkActive is false we still
-  // build a CLI pm; SDK pm is null. When sdkActive is true we always
-  // build BOTH so chats outside the SDK list still get the CLI path.
-  const cliPm = new ProcessManager({ ...pmOpts, spawnFn: spawnClaude });
-  const sdkPm = sdkActive
-    ? new ProcessManagerSdk({ ...pmOpts, spawnFn: buildSdkOptions })
-    : null;
-
-  // Routing pm: same surface as a single pm, but per-method routing
-  // through pickPmKindFor(sessionKey). Per-method semantics
-  // documented in lib/pm-router.js.
-  pm = createPmRouter({ cliPm, sdkPm, pickPmKindFor });
-
-  if (sdkAllChats) {
-    console.log('[polygram] using SDK ProcessManager (all chats)');
-  } else if (sdkSomeChats) {
-    console.log(`[polygram] router active: SDK pm for chats {${Array.from(sdkChatIdSet).join(',')}}, CLI pm for everyone else`);
-  } else {
-    console.log('[polygram] using CLI ProcessManager');
-  }
+  // 0.9.0 wiring order matters here. The factories destructure
+  // their `pm` / `bot` deps by value at call time; the closures
+  // they return then reference those CAPTURED references at every
+  // future call. So `pm` and `bot` must be assigned BEFORE the
+  // factory that consumes them runs — late-rebinding the
+  // module-level `let pm` doesn't propagate into the factory's
+  // captured local. v3 architecture review caught this as a
+  // production-blocking bug after commit 29.
+  //
+  // Order encoded below:
+  //   1. bot = createBot(token)              — needed by approvals + abort
+  //   2. createApprovals(...)                — provides makeCanUseTool
+  //   3. createBuildSdkOptions(...)          — uses makeCanUseTool
+  //   4. pm = new ProcessManagerSdk(...)     — uses buildSdkOptions
+  //   5. handler factories that need pm/bot  — see them as live refs
+
+  bot = createBot(config.bot.token);
+
+  ({
+    makeCanUseTool,
+    handleApprovalCallback,
+    resolveApprovalWaiter,
+    startApprovalSweeper,
+    cancelAllWaiters,
+  } = createApprovals({
+    config, db, bot, botName: BOT_NAME, tg, logEvent,
+    approvals, getChatIdFromKey, logger: console,
+  }));
+  buildSdkOptions = createBuildSdkOptions({
+    config,
+    botName: BOT_NAME,
+    childHome: CHILD_HOME,
+    makeCanUseTool,
+    logEvent,
+    logger: console,
+  });
+  transcribeVoiceAttachments = createTranscribeVoiceAttachments({
+    config, db, dbWrite, tg, logEvent,
+    transcribeVoice, isVoiceAttachment,
+    botName: BOT_NAME, logger: console,
+  });
+  downloadAttachments = createDownloadAttachments({
+    config, db, dbWrite, inboxDir: INBOX_DIR, logger: console,
+  });
+  pm = new ProcessManagerSdk({ ...pmOpts, spawnFn: buildSdkOptions });
+  // formatConfigInfoText MUST be wired BEFORE createHandleConfigCallback
+  // — the latter destructures formatConfigInfoText from its deps at
+  // call time and captures the value (closure-by-value). v4 reviewer
+  // caught this as the same class as the v3 BLOCKER.
+  formatConfigInfoText = createFormatConfigInfoText({
+    pm, db, getClaudeSessionId,
+  });
+  handleConfigCallback = createHandleConfigCallback({
+    config, db, dbWrite, pm, getSessionKey,
+    formatConfigInfoText, buildConfigKeyboard,
+    botName: BOT_NAME, logger: console,
+  });
+  handleAbortIfRequested = createHandleAbort({
+    pm, bot, tg, logEvent, isAbortRequest,
+    markSessionAborted, clearAutosteeredReactions, getSessionKey,
+    botName: BOT_NAME, logger: console,
+  });
+  autosteer = createAutosteerHandlers({
+    config, pm, autosteeredRefs, logEvent,
+  });
+  recordInbound = createRecordInbound({
+    db, dbWrite, config, botName: BOT_NAME, extractAttachments,
+  });
+  handleSendOverIpc = createHandleSendOverIpc({
+    config, bot, tg, botName: BOT_NAME,
+  });
+  ({
+    dispatchHandleMessage,
+    attemptAutoResume,
+    errorReplyText,
+    queueWarnThreshold,
+    inFlightHandlers,
+  } = createDispatcher({
+    config, db, dbWrite, tg, botName: BOT_NAME, logEvent,
+    handleMessage, sendToProcess,
+    classifyError, isAutoResumable,
+    abortGrace, autoResumeTracker,
+    chunkMarkdownText, deliverReplies,
+    TG_MAX_LEN,
+    getIsShuttingDown: () => isShuttingDown,
+    logger: console,
+  }));
+  ({ pollBot, startPollWatchdog } = createPollLoop({
+    db, dbWrite, config, botName: BOT_NAME,
+    isWellFormedMessage, getTopicName,
+    logger: console,
+  }));
+  dispatchSlashCommand = createSlashCommands({
+    config, db, dbWrite, pm, pairings, parsePairingTtl,
+    contextHintShown, formatContextReply, getClaudeSessionId,
+    getOrSpawnForChat, parsePairCodeArgs,
+    modelVersionsDesc: MODEL_VERSIONS_DESC,
+    botName: BOT_NAME, logEvent, logger: console,
+  });
+  console.log('[polygram] using SDK ProcessManager');
 
   console.log(`polygram (LRU cap=${cap}, SQLite source of truth)`);
   console.log(`Chats: ${Object.entries(config.chats).map(([id, c]) => `${c.name} (${c.model}/${c.effort})`).join(', ')}`);
@@ -4241,7 +2005,8 @@ async function main() {
     }
   }
 
-  bot = createBot(config.bot.token);
+  // bot was created earlier in main() — see the wiring-order block
+  // around the factory creations.
 
   // Graceful shutdown: stop accepting new inbound, drain in-flight pendings
   // up to SHUTDOWN_DRAIN_MS, then mark anything still unfinished so boot
@@ -4296,10 +2061,12 @@ async function main() {
     if (approvalSweepTimer) clearInterval(approvalSweepTimer);
     if (ipcCloser) ipcCloser.close().catch(() => {});
     try { fs.unlinkSync(ipcServer.secretPathFor(BOT_NAME)); } catch {}
-    for (const list of approvalWaiters.values()) {
-      for (const fn of list) { try { fn('cancelled', 'polygram shutting down'); } catch {} }
-    }
-    approvalWaiters.clear();
+    // Reject every parked canUseTool waiter so the SDK doesn't
+    // hang on a dangling approval Promise. v4 review caught this:
+    // commit 29 moved the Map into lib/handlers/approvals.js; the
+    // old `approvalWaiters` reference here would ReferenceError
+    // mid-shutdown and prevent pm/DB cleanup.
+    if (cancelAllWaiters) cancelAllWaiters('cancelled', 'polygram shutting down');
     if (pm) await pm.shutdown().catch(() => {});
     if (db) {
       try { db.logEvent('polygram-stop'); db.raw.close(); } catch {}
@@ -4335,7 +2102,6 @@ async function main() {
       path: ipcServer.socketPathFor(BOT_NAME),
       secret: ipcSecret,
       handlers: {
-        approval_request: handleApprovalRequest,
         ping: async () => ({ pong: true, bot: BOT_NAME }),
         send: (req) => handleSendOverIpc(req),
       },
@@ -4547,7 +2313,7 @@ async function main() {
     console.error(`[${BOT_NAME}] Fatal:`, err.message);
   });
 
-  const watchdogTimer = startPollWatchdog(bot);
+  const watchdogTimer = startPollWatchdog(bot, { logEvent });
   process.once('exit', () => clearInterval(watchdogTimer));
 
   await pollPromise;