polygram 0.12.0-rc.3 → 0.12.0-rc.30

package/config.example.json

@@ -4,6 +4,7 @@
   "bots": {
     "admin-bot": {
       "token": "REPLACE_WITH_BOT_TOKEN_FROM_BOTFATHER",
+      "_comment_apiRoot": "Optional. Point grammy at a self-hosted Telegram Bot API server (e.g. 'http://localhost:8082' from a local `telegram-bot-api --local` process) to raise file send/receive limits from cloud's 50MB-out / 20MB-in to 2GB both ways. Omit for cloud Telegram (default, unchanged). The server is a separate localhost-only companion daemon — see docs/0.12.0-file-send.md.",
       "allowConfigCommands": true,
       "_comment_adminChatId": "Required when allowConfigCommands is true for pairing commands (/pair-code, /pairings, /unpair) to work. These grant cross-chat trust and are gated to the admin chat only.",
       "adminChatId": "123456789",
@@ -70,7 +71,10 @@
       "model": "opus",
       "effort": "medium",
       "cwd": "/Users/you/admin-agent",
-      "timeout": 600
+      "timeout": 600,
+      "_comment_maxFileBytes": "OPTIONAL per-chat (or per-topic; topic wins) file-size cap in BYTES. There is NO fixed default — the default is backend-derived: cloud Telegram = 50MB send / 20MB receive; with a local Bot API server (bot.apiRoot set) = 2GB both ways. This key only LOWERS that ceiling for this chat (Telegram rejects anything above the backend limit regardless); omit it to use the full backend default. To set one, add e.g. \"maxFileBytes\": 104857600 (=100MB) — only meaningful when apiRoot is set, since cloud already clamps to 50/20MB.",
+      "_comment_compactionWarnings": "OPTIONAL per-chat (or per-topic; topic wins). CLI/channels backend (pm:'cli') only. Default OFF. When ON, polygram warns the chat as Claude's context fills so you can /compact on your terms BEFORE an auto-compaction interrupts a turn (auto-compaction detaches the channels MCP bridge mid-turn — see docs/0.12.0-compaction-warnings.md). Two forms: `true` (enable at the 75% default threshold) or `{ \"enabled\": true, \"thresholdPct\": 80 }` (custom 1-99 threshold). Proactive: at the threshold it posts 'context ~N% full, run /compact or /new at a break'. Reactive backstop: when claude auto-compacts anyway it posts 'compacting now, resend if quiet'. Manual /compact never warns. Requires the bot to allow /compact + /new commands.",
+      "compactionWarnings": true
     },
 
     "-1000000000001": {

package/lib/attachments.js

@@ -22,8 +22,48 @@
  *     extension — the fallback only kicks in when MIME is unhelpful.
  */
 
-const MAX_FILE_BYTES = 10 * 1024 * 1024;
-const MAX_TOTAL_BYTES = 20 * 1024 * 1024;
+// Inbound (user → bot) per-file cap. Telegram's cloud Bot API hard-caps
+// bot file DOWNLOADS (getFile) at 20 MB, so 20 MB is the real ceiling on
+// cloud — raised from 10 MB so users can send larger tracks/docs. With a
+// self-hosted Bot API server (config.bot.apiRoot) the Telegram limit rises
+// to 2 GB; resolveFileCaps() raises the default accordingly.
+const MAX_FILE_BYTES = 20 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 50 * 1024 * 1024;
+
+// ─── Backend-derived file-size caps (cloud vs local Bot API server) ──
+//
+// These are the HARD ceilings Telegram itself enforces — a per-chat
+// override can lower them but never exceed them (Telegram rejects beyond
+// regardless). NOT "adaptive": there is no intermediate tier. Cloud is a
+// flat 20 in / 50 out; a local `telegram-bot-api --local` server is a flat
+// 2 GB both ways.
+const CLOUD_MAX_IN_BYTES  = 20 * 1024 * 1024;          // getFile download limit
+const CLOUD_MAX_OUT_BYTES = 50 * 1024 * 1024;          // sendDocument upload limit
+const LOCAL_MAX_BYTES     = 2000 * 1024 * 1024;        // --local server, both ways
+
+/**
+ * Resolve the effective per-file caps for a chat/topic.
+ *
+ * @param {object} opts
+ * @param {boolean} opts.localApi   — true when config.bot.apiRoot is set
+ *   (a local Bot API server is in use → 2 GB ceiling).
+ * @param {...number} opts.override  — per-chat/topic maxFileBytes (bytes).
+ *   Resolved by the caller from topic → chat → undefined; clamped to the
+ *   backend ceiling.
+ * @returns {{ inBytes:number, outBytes:number, ceiling:number, localApi:boolean }}
+ */
+function resolveFileCaps({ localApi = false, override = null } = {}) {
+  const ceiling = localApi ? LOCAL_MAX_BYTES : null;
+  const defIn  = localApi ? LOCAL_MAX_BYTES : CLOUD_MAX_IN_BYTES;
+  const defOut = localApi ? LOCAL_MAX_BYTES : CLOUD_MAX_OUT_BYTES;
+  // A numeric override sets BOTH directions to the same value, clamped to
+  // the backend hard ceiling (cloud uses the per-direction default as the
+  // clamp so an override can't push past Telegram's own limit).
+  const ovr = (typeof override === 'number' && override > 0) ? override : null;
+  const inBytes  = ovr ? (localApi ? Math.min(ovr, ceiling) : Math.min(ovr, CLOUD_MAX_IN_BYTES))  : defIn;
+  const outBytes = ovr ? (localApi ? Math.min(ovr, ceiling) : Math.min(ovr, CLOUD_MAX_OUT_BYTES)) : defOut;
+  return { inBytes, outBytes, ceiling: ceiling ?? CLOUD_MAX_OUT_BYTES, localApi };
+}
 const MIME_ALLOW = [
   /^image\//, /^audio\//, /^video\//,
   /^application\/pdf$/, /^text\/plain$/,
@@ -109,8 +149,12 @@ function filterAttachments(attachments, opts = {}) {
 
 module.exports = {
   filterAttachments,
+  resolveFileCaps,
   MAX_FILE_BYTES,
   MAX_TOTAL_BYTES,
+  CLOUD_MAX_IN_BYTES,
+  CLOUD_MAX_OUT_BYTES,
+  LOCAL_MAX_BYTES,
   MIME_ALLOW,
   EXTENSION_ALLOW,
   FALLBACK_MIMES,

package/lib/claude-bin.js

@@ -7,7 +7,14 @@ const fs = require('fs');
 // 0.12 Phase 4: moved from lib/process/tmux-process.js into the helper module
 // that consumes it, so the constant survives TmuxProcess deletion. CliProcess
 // + spike scripts + polygram boot all import from here now.
-const CLAUDE_CLI_PINNED_VERSION = '2.1.142';
+// 0.12.0-rc.18: bumped 2.1.142 → 2.1.158 (latest installed). The dev-channels
+// inbound-message delivery has an intermittent channel-bind race (the bridge
+// pushes user_msg before claude's channel subscription is active → message
+// silently dropped → stuck turn; see docs/0.12.0-known-issues.md). Trying a
+// newer claude to see if the research-preview channels reliability improved,
+// before building polygram-side recovery. Re-validate the channel flow on each
+// bump via tests/e2e-channels-real-claude.test.js.
+const CLAUDE_CLI_PINNED_VERSION = '2.1.158';
 
 /**
  * Resolve + verify the pinned claude CLI binary.

package/lib/compaction-warn.js

@@ -0,0 +1,59 @@
+/**
+ * compaction-warn — per-chat config resolution + warn-once state for the
+ * compaction warning (0.12.0-rc.13).
+ *
+ * The warning is OFF by default. A chat (or topic) opts in via
+ * `compactionWarnings`:
+ *   true                                   → enabled, default threshold
+ *   { enabled: true, thresholdPct: 80 }    → enabled, custom threshold
+ *   false / absent / object w/o enabled    → off
+ *
+ * `thresholdPct` is the context-fill % at which the PROACTIVE warning fires
+ * (propose /compact before claude auto-compacts mid-turn). Default 75 — below
+ * claude's own auto-compact threshold so the user gets a window to act.
+ */
+
+'use strict';
+
+const DEFAULT_THRESHOLD_PCT = 75;
+
+/**
+ * @param {object|undefined} cfg  resolved topic/chat config (getTopicConfig result)
+ * @returns {{enabled: boolean, thresholdPct: number}}
+ */
+function resolveCompactionWarnConfig(cfg) {
+  const raw = cfg?.compactionWarnings;
+  const off = { enabled: false, thresholdPct: DEFAULT_THRESHOLD_PCT };
+
+  if (raw === true) return { enabled: true, thresholdPct: DEFAULT_THRESHOLD_PCT };
+  if (raw && typeof raw === 'object' && raw.enabled === true) {
+    const t = Number(raw.thresholdPct);
+    const thresholdPct = (Number.isFinite(t) && t > 0 && t < 100) ? t : DEFAULT_THRESHOLD_PCT;
+    return { enabled: true, thresholdPct };
+  }
+  return off;
+}
+
+/**
+ * Per-session "have we already warned on this climb?" state. Warn ONCE per
+ * session until reset — without this the proactive warning would re-fire on
+ * every turn-end while the context stays high. Reset on a successful
+ * compaction (PostCompact → context dropped) or a fresh session so the next
+ * climb can warn again. Mirrors the autoResumeTracker shape.
+ */
+function createCompactionWarnTracker() {
+  const warned = new Set();
+  return {
+    shouldWarn(sessionKey) { return !warned.has(sessionKey); },
+    markWarned(sessionKey) { warned.add(sessionKey); },
+    reset(sessionKey) { warned.delete(sessionKey); },
+    resetAll() { warned.clear(); },
+    _size() { return warned.size; },
+  };
+}
+
+module.exports = {
+  resolveCompactionWarnConfig,
+  createCompactionWarnTracker,
+  DEFAULT_THRESHOLD_PCT,
+};

package/lib/context-usage.js

@@ -0,0 +1,93 @@
+/**
+ * context-usage — read live context occupancy from a Claude Code session
+ * transcript (JSONL).
+ *
+ * Used by the per-chat compaction warning (0.12.0-rc.13). polygram has no
+ * usage payload on the channels/CLI backend (hook events carry none — see
+ * the rc.13 spike), so the only source of "how full is the context" is the
+ * transcript itself. We read it ONCE per turn-end (Stop hook), not on a
+ * poll loop, so a single streamed pass is fine.
+ *
+ * What "occupancy" means: Claude's own context-% / auto-compact threshold is
+ * measured against what's fed INTO the model each turn —
+ *   input_tokens + cache_read_input_tokens + cache_creation_input_tokens
+ * (cache_read dominates once the conversation is warm). output_tokens is the
+ * reply, not context, so it's excluded.
+ *
+ * We take the LAST main-thread (non-sidechain) assistant frame with a usage
+ * block. Subagents write to their own agent_transcript_path so sidechain
+ * frames don't normally appear here, but we skip them defensively: a format
+ * change that inlined a subagent's large usage would otherwise spike the
+ * parent's apparent context and trigger a false "you're full" warning.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const readline = require('node:readline');
+
+// Standard Claude context window (sonnet/opus, non-beta). The warning is a
+// heuristic ("you're getting full"), so an approximate denominator is fine;
+// callers can pass a different window for 1M-beta sessions.
+const DEFAULT_WINDOW_TOKENS = 200_000;
+
+/**
+ * @param {string} transcriptPath
+ * @returns {Promise<{inputTokens:number, cacheReadTokens:number, cacheCreationTokens:number, total:number} | null>}
+ *   null when the path is falsy/unreadable or no usable usage frame exists.
+ */
+async function readContextTokens(transcriptPath) {
+  if (!transcriptPath) return null;
+
+  let stream;
+  try {
+    stream = fs.createReadStream(transcriptPath, { encoding: 'utf8' });
+  } catch {
+    return null;
+  }
+
+  return new Promise((resolve) => {
+    let last = null;
+    // Resolve only once — error and close can both fire.
+    let done = false;
+    const finish = (v) => { if (!done) { done = true; resolve(v); } };
+
+    stream.on('error', () => finish(null));
+
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    // readline forwards the input stream's 'error' (e.g. ENOENT on open) to
+    // the interface; without this handler that re-emit is unhandled and
+    // crashes the process even though we resolved null on the stream error.
+    rl.on('error', () => finish(null));
+    rl.on('line', (line) => {
+      if (!line) return;
+      let o;
+      try { o = JSON.parse(line); } catch { return; }  // skip partial/non-JSON lines
+      if (!o || o.type !== 'assistant' || o.isSidechain === true) return;
+      const u = o.message?.usage;
+      if (!u) return;
+      const inputTokens = Number(u.input_tokens) || 0;
+      const cacheReadTokens = Number(u.cache_read_input_tokens) || 0;
+      const cacheCreationTokens = Number(u.cache_creation_input_tokens) || 0;
+      const total = inputTokens + cacheReadTokens + cacheCreationTokens;
+      if (total > 0) last = { inputTokens, cacheReadTokens, cacheCreationTokens, total };
+    });
+    rl.on('close', () => finish(last));
+  });
+}
+
+/**
+ * Fraction (0..1) of the context window currently occupied. Clamps to 0 on
+ * non-positive / non-finite inputs so callers never see NaN/Infinity.
+ *
+ * @param {number} totalTokens
+ * @param {number} [windowTokens=DEFAULT_WINDOW_TOKENS]
+ * @returns {number}
+ */
+function contextPct(totalTokens, windowTokens = DEFAULT_WINDOW_TOKENS) {
+  if (!Number.isFinite(totalTokens) || totalTokens <= 0) return 0;
+  if (!Number.isFinite(windowTokens) || windowTokens <= 0) return 0;
+  return totalTokens / windowTokens;
+}
+
+module.exports = { readContextTokens, contextPct, DEFAULT_WINDOW_TOKENS };

package/lib/db.js

@@ -19,7 +19,7 @@ const Database = require('better-sqlite3');
 // SCHEMA_VERSION; the early-return on line ~42 then skipped the
 // migration loop on any DB already at user_version=8 → turn_metrics
 // table never created → INSERT prepare at startup crashed polygram.
-const SCHEMA_VERSION = 11;
+const SCHEMA_VERSION = 12;
 
 // Sentinel `error` value for outbound rows whose API call may or may not
 // have reached Telegram. markStalePending writes it; hasOutboundReplyTo

package/lib/error/classify.js

@@ -195,6 +195,18 @@ const CODES = {
     isTransient: false,
     autoRecover: null,
   },
+  // TMUX_SESSION_GONE: claude exited during spawn so the tmux session vanished
+  // before the channel went live (the startup-gate's captureWide hit "can't
+  // find pane"). Usual cause: an unresumable aged session whose "Resume from
+  // summary?" /compact exits code 0. The dispatcher poison-clears the session
+  // on this code, so a resend genuinely starts fresh and works — hence the
+  // calm "send it again" copy instead of the old raw "[startup-gate]…" leak.
+  TMUX_SESSION_GONE: {
+    kind: 'tmuxSessionGone',
+    userMessage: '🔄 That chat got stuck starting up, so I reset it. Send your message again and I\'ll pick it up fresh.',
+    isTransient: false,
+    autoRecover: null,
+  },
   // TURN_TIMEOUT: 10-min wall-clock cap on a single channels turn. Mirror
   // of the tmux wall-clock ceiling — typically a runaway, not a wedge.
   // Not transient (auto-retry would just runaway again).

package/lib/handlers/abort.js

@@ -42,13 +42,37 @@ function createHandleAbort({
     const threadId = msg.message_thread_id?.toString();
     const sessionKey = getSessionKey(chatId, threadId, chatConfig);
     const proc = pm.has(sessionKey) ? pm.get(sessionKey) : null;
-    const hadActive = !!proc?.inFlight;
+    let hadActive = !!proc?.inFlight;
 
     // Mark BEFORE killing: the 'close' event fires almost immediately
     // after interrupt, and the surrounding handleMessage's catch
     // needs to see the flag to skip the generic error-reply.
     if (hadActive) markSessionAborted(sessionKey);
 
+    // "Stop" incident (shumorobot Music, 2026-05-31 13:08): on the
+    // CliProcess/channels backend a turn resolves on the quiet-window
+    // after claude's last reply tool call (inFlight → false), but claude
+    // can still be working (subagent, long Bash). Keying the ack on
+    // inFlight alone made "Stop" say "Nothing to stop" while a subagent
+    // download churned. probeBusyState() reads the TUI "esc to interrupt"
+    // hint — the truthful signal — so detection, the abort mark, and the
+    // ack all agree. The probe result is logged below (forensics) so the
+    // heuristic can be refined against real states later. Channels analog
+    // of the (deleted) tmux hasBackgroundShell branch; typeof-guarded so
+    // it's a no-op on backends without it.
+    let busyProbe = null;
+    if (!hadActive && proc && typeof proc.probeBusyState === 'function') {
+      try {
+        busyProbe = await proc.probeBusyState();
+        if (busyProbe?.busy) {
+          hadActive = true;
+          markSessionAborted(sessionKey);
+        }
+      } catch (err) {
+        logger.error?.(`[${botName}] busy-probe failed: ${err.message}`);
+      }
+    }
+
     // Bug 1 (incident 2026-05-18): "Stop" was turn-scoped — it only
     // looked at an in-flight TURN. But the agent can leave a DETACHED
     // background shell running (a `run_in_background:true` Bash) that
@@ -72,21 +96,47 @@ function createHandleAbort({
       }
     }
 
-    // SDK abort: interrupt() + drainQueue(). interrupt() cancels
-    // the in-flight turn at SDK level WITHOUT tearing down the
-    // Query (cheap to reuse for the user's next message);
-    // drainQueue() rejects every queued pending with
-    // err.code='INTERRUPTED' so the abort-grace classifier
-    // suppresses error replies.
-    await pm.interrupt(sessionKey).catch((err) =>
-      logger.error?.(`[${botName}] interrupt failed: ${err.message}`));
+    // Reject queued pendings first (err.code='INTERRUPTED' → the abort-grace
+    // classifier suppresses their error replies AND each turn's finally clears
+    // its reactor + typing), THEN stop the live work.
     pm.drainQueue(sessionKey, 'INTERRUPTED');
+    if (hadActive && proc && proc.backend === 'cli') {
+      // Channels HARD stop (user decision 2026-06-04: "/stop should stop
+      // everything including background, like the SDK backend"). A soft C-c
+      // interrupt leaves detached background shells + subagents running and
+      // can't clear a ghost (no-pending-turn) busy state — the symptom was
+      // "Stopped." with the reaction + typing still going. Kill the session: the
+      // whole process tree (claude + every subagent + all background shells)
+      // dies at once, the close drains the in-flight turn (clearing its
+      // reactor/typing), and the next message respawns fresh (--resume restores
+      // the conversation). This is what makes channels /stop "stop everything".
+      await pm.kill(sessionKey, 'abort').catch((err) =>
+        logger.error?.(`[${botName}] abort kill failed: ${err.message}`));
+    } else {
+      // SDK (or nothing active): non-destructive interrupt cancels the in-flight
+      // Query turn WITHOUT tearing down the Query (cheap to reuse next message).
+      await pm.interrupt(sessionKey).catch((err) =>
+        logger.error?.(`[${botName}] interrupt failed: ${err.message}`));
+    }
 
     clearAutosteeredReactions(sessionKey).catch(() => {});
     logEvent('abort-requested', {
       chat_id: chatId, user_id: msg.from?.id || null,
       had_active: hadActive,
       killed_background_shell: killedBackgroundShell,
+      // "Stop" incident forensics: the raw busy-probe signals at decision
+      // time. Lets us query, across real aborts, where the esc-hint /
+      // inFlight / pending-turn signals agreed vs diverged and refine the
+      // heuristic later. null when no probe ran (turn was already inFlight,
+      // or the backend has no probeBusyState).
+      busy_probe: busyProbe ? {
+        busy: busyProbe.busy,
+        streaming: busyProbe.streaming,
+        in_flight: busyProbe.inFlight,
+        pending_turns: busyProbe.pendingTurns,
+        captured: busyProbe.captured,
+        pane_tail: busyProbe.paneTail,
+      } : null,
       trigger: cleanText.slice(0, 40),
     });
 

package/lib/handlers/config-callback.js

@@ -17,6 +17,7 @@
 'use strict';
 
 const { toTelegramHtml } = require('../telegram/format');
+const { getTopicConfig } = require('../session-key');
 
 const MODEL_OPTIONS = ['opus', 'sonnet', 'haiku'];
 const EFFORT_OPTIONS = ['low', 'medium', 'high', 'xhigh', 'max'];
@@ -92,8 +93,13 @@ function createHandleConfigCallback({
     // tapped into.
     const existingRows = ctx.callbackQuery.message?.reply_markup?.inline_keyboard?.length || 0;
     const showRow = existingRows >= 2 ? 'all' : setting;
-    const newInfo = formatConfigInfoText(chatConfig, showRow, chatId);
-    const newKeyboard = buildConfigKeyboard(chatConfig, showRow);
+    // Re-render with per-topic overrides resolved (topic > chat), so the agent
+    // line doesn't flip back to the chat-level default after a button tap —
+    // mirrors the /model command card (polygram.js). getTopicConfig returns {}
+    // for the chat-level card.
+    const _cbTopicCfg = getTopicConfig(chatConfig, callbackThreadId);
+    const newInfo = formatConfigInfoText(chatConfig, showRow, chatId, _cbTopicCfg);
+    const newKeyboard = buildConfigKeyboard(chatConfig, showRow, _cbTopicCfg);
     try {
       const { text: html, parseMode } = toTelegramHtml(newInfo);
       await ctx.editMessageText(html, {

package/lib/handlers/config-ui.js

@@ -31,19 +31,23 @@ const MODEL_VERSIONS_DESC = {
 /**
  * Build the inline keyboard for /model + /effort.
  *   show = 'model' | 'effort' | 'all'
- * The current value gets a ✓ prefix.
+ * The current value gets a ✓ prefix. `topicConfig` (per-topic overrides, or
+ * null for the chat-level card) wins over chatConfig so the ✓ matches what a
+ * topic actually runs — mirrors the spawn-path precedence (topic > chat).
  */
-function buildConfigKeyboard(chatConfig, show = 'all') {
+function buildConfigKeyboard(chatConfig, show = 'all', topicConfig = null) {
+  const model = (topicConfig && topicConfig.model) || chatConfig.model;
+  const effort = (topicConfig && topicConfig.effort) || chatConfig.effort;
   const rows = [];
   if (show === 'model' || show === 'all') {
     rows.push(MODEL_OPTIONS.map((m) => ({
-      text: m === chatConfig.model ? `✓ ${m}` : m,
+      text: m === 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,
+      text: e === effort ? `✓ ${e}` : e,
       callback_data: `cfg:effort:${e}`,
     })));
   }
@@ -60,14 +64,24 @@ function buildConfigKeyboard(chatConfig, show = 'all') {
  * @param {(db, sessionKey) => string|null} deps.getClaudeSessionId
  */
 function createFormatConfigInfoText({ pm, db, getClaudeSessionId } = {}) {
-  return function formatConfigInfoText(chatConfig, show, sessionKey) {
+  return function formatConfigInfoText(chatConfig, show, sessionKey, topicConfig = null) {
     const alive = pm.has(sessionKey) && !pm.get(sessionKey).closed;
-    const ver = MODEL_VERSIONS_DESC[chatConfig.model] || chatConfig.model;
+    // Per-topic overrides win over chat-level for the displayed values,
+    // mirroring the spawn path (polygram.js: topicConfig.agent ||
+    // chatConfig.agent). Pre-fix the card always read chat-level, so a topic's
+    // /model showed the WRONG agent — shumorobot Music topic (thread 3) showed
+    // "Agent: shumabit" instead of its music-curation:music-curator override
+    // (2026-06-03). topicConfig defaults to null (chat-level) for callers with
+    // no active topic.
+    const model = (topicConfig && topicConfig.model) || chatConfig.model;
+    const effort = (topicConfig && topicConfig.effort) || chatConfig.effort;
+    const agent = (topicConfig && topicConfig.agent) || chatConfig.agent;
+    const ver = MODEL_VERSIONS_DESC[model] || model;
     const sess = getClaudeSessionId(db, sessionKey)?.slice(0, 8) || 'new';
     const head =
-      `Model: ${chatConfig.model} (${ver})\n` +
-      `Effort: ${chatConfig.effort}\n` +
-      `Agent: ${chatConfig.agent}\n` +
+      `Model: ${model} (${ver})\n` +
+      `Effort: ${effort}\n` +
+      `Agent: ${agent}\n` +
       `Process: ${alive ? 'warm' : 'cold'}\n` +
       `Session: ${sess}`;
 

package/lib/handlers/dispatcher.js

@@ -24,6 +24,13 @@
 
 const CONCURRENT_WARN_THRESHOLD_DEFAULT = 20;
 
+// Startup auto-retry (option a, 2026-06-04): a short breath before silently
+// re-dispatching a message whose first attempt died in the dev-channels startup
+// gate (TMUX_SESSION_GONE). Long enough that a host under momentary load isn't
+// hammered with a back-to-back respawn, short enough that a transient flake
+// still recovers fast enough to feel instant to the user.
+const STARTUP_RETRY_DELAY_MS = 1500;
+
 function createDispatcher({
   config,
   db,
@@ -48,6 +55,9 @@ function createDispatcher({
   // the historic 4096 for back-compat in synthetic test runs that pass
   // pre-formatted text.
   chunkBudget = 4096,
+  // Delay before a silent startup auto-retry re-dispatches (TMUX_SESSION_GONE).
+  // Injected so tests can drive it to 0; production uses STARTUP_RETRY_DELAY_MS.
+  startupRetryDelayMs = STARTUP_RETRY_DELAY_MS,
   // State accessors (need late binding because polygram.js mutates):
   getIsShuttingDown,              // () → boolean
   logger = console,
@@ -178,6 +188,26 @@ function createDispatcher({
         aborted: wasAborted || undefined,
         replay: isReplay || undefined,
       });
+      // Startup-gate death (claude exited during spawn / the dialog gate timed
+      // out) of a likely-aged RESUMED session — the persisted claude_session_id
+      // can't be resumed cleanly (shumorobot general chat 2026-06-01→03: a
+      // week-old session renders claude's "Resume from summary?" dialog whose
+      // /compact resume exits code 0 → TMUX_SESSION_GONE → the chat re-resumes
+      // the same dead id on every message, stuck for days). Poison-clear so the
+      // NEXT message spawns a FRESH session — same recovery the auto-resume path
+      // does for BRIDGE_DISCONNECTED below. clearSessionId is a no-op DELETE when
+      // there's no row (a genuine fresh-spawn failure), so this is safe; and
+      // unlike an in-process recursive retry it never reuses a closed instance.
+      if ((err.code === 'TMUX_SESSION_GONE' || err.code === 'CHANNELS_DIALOG_TIMEOUT')
+          && typeof db.clearSessionId === 'function') {
+        dbWrite(
+          () => db.clearSessionId(sessionKey),
+          `clearSessionId: poisoned by ${err.code} on startup`,
+        );
+        logEvent('session-reset-after-startup-gate', {
+          chat_id: chatId, session_key: sessionKey, msg_id: msg?.message_id, code: err.code,
+        });
+      }
       // 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 rc.51-onward boot-replay path is
@@ -197,6 +227,35 @@ function createDispatcher({
       //   - shutting down ("Process killed" isn't a real error),
       //   - user just /stop'd (already saw their abort ack).
       if (!wasAborted && !isReplay && !isShuttingDown) {
+        // Startup auto-retry (option a, 2026-06-04). TMUX_SESSION_GONE = claude
+        // exited INSIDE the startup gate, before the dev-channels channel went
+        // live — so the user's message was NEVER delivered to claude. That makes
+        // a re-send idempotent BY CONSTRUCTION (unlike a mid-turn drop, where
+        // claude might still be slowly processing). The session_id was just
+        // poison-cleared above, so re-dispatching the SAME message spawns a FRESH
+        // session and delivers it. Silent: a transient startup flake (recurs
+        // ~once/9h on the channels backend) never reaches the user — instead of
+        // the "🔄 reset it, resend" papercut, polygram just retries. One-shot
+        // (_startupRetried) so a host that genuinely can't start claude surfaces
+        // the friendly reset reply (below) after EXACTLY one retry, never a loop.
+        // Scoped to TMUX_SESSION_GONE only: CHANNELS_DIALOG_TIMEOUT is a real
+        // blocking dialog (usage-limit / permission) a retry would just re-hit,
+        // so it keeps its "please resend" copy.
+        if (err.code === 'TMUX_SESSION_GONE' && !msg._startupRetried) {
+          logEvent('startup-auto-retry', {
+            chat_id: chatId, session_key: sessionKey, msg_id: msg?.message_id,
+          });
+          // Re-dispatch a COPY carrying the one-shot marker — never mutate the
+          // caller's msg (the boot-replay path shares/re-reads it). unref the
+          // best-effort timer so a pending retry can't pin the daemon alive
+          // (the Telegram long-poll already keeps the loop running).
+          const retryMsg = { ...msg, _startupRetried: true };
+          setTimeout(
+            () => dispatchHandleMessage(sessionKey, chatId, retryMsg, bot),
+            startupRetryDelayMs,
+          ).unref?.();
+          return;
+        }
         // rc.54: auto-resume on 300s no-activity timeout. The
         // resume turn itself runs through sendToProcess directly
         // (not handleMessage), so its errors don't re-enter this
@@ -224,6 +283,29 @@ function createDispatcher({
                 chat_id: chatId, session_key: sessionKey, msg_id: msg.message_id,
                 error: resumeErr?.message?.slice(0, 200),
               });
+              // Music topic incident (2026-06-01): a channels session whose
+              // context grew large enough to auto-/compact on resume loses its
+              // MCP bridge binding on EVERY resume ("no MCP server configured"),
+              // so the resumed turn re-detaches (BRIDGE_DISCONNECTED) and lands
+              // here. The persisted claude_session_id is then poisoned — every
+              // future message (manual resend OR post-cooldown auto-resume)
+              // re-resumes it and re-detaches, an endless "🔌 please resend"
+              // loop. Break it: drop the session row so the NEXT message spawns
+              // a FRESH session (no --resume). Gated on the ORIGINAL error being
+              // a bridge-detach AND auto-resume having failed — a one-off bridge
+              // crash that resumes cleanly takes the .then() path above and
+              // keeps its context; only a session that re-detaches on resume is
+              // treated as poison. We lose the poisoned conversation's history,
+              // but that session can't complete a turn anyway.
+              if (err.code === 'BRIDGE_DISCONNECTED' && typeof db.clearSessionId === 'function') {
+                dbWrite(
+                  () => db.clearSessionId(sessionKey),
+                  'clearSessionId: poisoned by bridge-detach on resume',
+                );
+                logEvent('session-reset-after-bridge-detach', {
+                  chat_id: chatId, session_key: sessionKey, msg_id: msg.message_id,
+                });
+              }
               const fallbackText = errorReplyText(err);
               if (fallbackText) {
                 tg(bot, 'sendMessage', {
@@ -266,4 +348,5 @@ function createDispatcher({
 module.exports = {
   createDispatcher,
   CONCURRENT_WARN_THRESHOLD_DEFAULT,
+  STARTUP_RETRY_DELAY_MS,
 };