polygram 0.17.11 → 0.18.0

package/polygram.js

@@ -22,7 +22,7 @@
 const { Bot } = require('grammy');
 const fs = require('fs');
 const path = require('path');
-const processGuard = require('./lib/process-guard');
+const processGuard = require('@shumkov/orchestra').processGuard;
 const dbClient = require('./lib/db');
 const {
   migrateJsonToDb, getClaudeSessionId, resolveSessionForSpawn,
@@ -39,9 +39,10 @@ const { filterAttachments, resolveFileCaps, resolveMaxFileOverride, MAX_TOTAL_BY
 // Process subclasses (SdkProcess now, TmuxProcess in Phase 2) provide
 // per-session mechanics. The pre-0.10.0 monolithic ProcessManagerSdk
 // is deleted; SdkProcess inherits its per-entry guts.
-const { ProcessManager } = require('./lib/process-manager');
-const { createProcessFactory, pickBackend } = require('./lib/process/factory');
-const { extractAssistantText } = require('./lib/process/sdk-process');
+const { ProcessManager } = require('@shumkov/orchestra');
+const { createProcessFactory, pickBackend } = require('@shumkov/orchestra');
+const { checkClaudeAuthHealth } = require('@shumkov/orchestra').claudeBin;
+const { extractAssistantText } = require('@shumkov/orchestra');
 // 0.11.0: channels backend tool dispatcher — adapts CliProcess's reply
 // tool callback into polygram's existing chunkText + deliverReplies primitives.
 // ADV-14: chunkMarkdownText (fence-aware) is imported once below (~line 88)
@@ -49,8 +50,8 @@ const { extractAssistantText } = require('./lib/process/sdk-process');
 // containing code blocks or HTML-style tags aren't split mid-element by the
 // size cap.
 const { createChannelsToolDispatcher } = require('./lib/process/channels-tool-dispatcher');
-const { createTmuxRunner } = require('./lib/tmux/tmux-runner');
-const { sweepTmuxOrphans } = require('./lib/tmux/orphan-sweep');
+const { createTmuxRunner } = require('@shumkov/orchestra');
+const { sweepTmuxOrphans } = require('@shumkov/orchestra').orphanSweep;
 // rc.42: autosteer-buffer module deleted. Native SDK priority push
 // (pm.injectUserMessage) replaces the buffer + PostToolBatch detour.
 const { createAutosteeredRefs } = require('./lib/autosteered-refs');
@@ -68,6 +69,7 @@ const { createAutosteerHandlers } = require('./lib/handlers/autosteer');
 const { createEditCorrectionInjector } = require('./lib/handlers/edit-correction');
 const { createEditRedelivery } = require('./lib/handlers/edit-redelivery');
 const { createGateInbound, ADMIN_CMD_RE, PAIR_CLAIM_RE } = require('./lib/handlers/gate-inbound');
+const { createShouldHandle } = require('./lib/handlers/should-handle');
 const { createRedeliver } = require('./lib/handlers/redeliver');
 const { classifyReplay, executeReplayPlan } = require('./lib/handlers/replay-disposition');
 const { createDropRedeliverer } = require('./lib/handlers/drop-redeliver');
@@ -87,13 +89,18 @@ const { formatContextReply, maybeContextFullHint } = require('./lib/context-form
 const { createAbortGrace } = require('./lib/abort-grace');
 const agentLoader = require('./lib/agents/loader');
 const { createSender } = require('./lib/telegram/api');
-const { createAsyncLock } = require('./lib/async-lock');
+const { createAsyncLock } = require('@shumkov/orchestra');
 const { sweepInbox } = require('./lib/db/inbox');
 const { parseBotArg, parseDbArg, filterConfigToBot, activeBotConfig } = require('./lib/config-scope');
 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 {
+  toTelegramRichBlocks, resolveRichTextEnabled, isRichCapabilityError, isRichContentError,
+} = require('./lib/telegram/rich');
+const { createRichEditor } = require('./lib/telegram/rich-edit');
+const { redactBotToken, stripUrlCredentials } = require('./lib/error/net');
 // F#23: shared agent-reply helper. parseResponse + sanitizer + chunked
 // delivery + inline sticker/react in one place. Wired into both the
 // channels dispatcher (F#1) and the autonomous-wakeup handler (F#23).
@@ -110,6 +117,8 @@ const { createMediaGroupBuffer } = require('./lib/media-group-buffer');
 const { applyReactionToMessages } = require('./lib/telegram/album-reactions');
 const { classify: classifyError, classifyTurnEndError, detectWedgedSessionError, isTransientHttpError } = require('./lib/error/classify');
 const { createAutoResumeTracker, isAutoResumable } = require('./lib/db/auto-resume');
+const { createAuthDisabledGate } = require('./lib/ops/auth-disabled-gate');
+const { createHeartbeat } = require('./lib/ops/heartbeat');
 const { resolveReplayWindowMs } = require('./lib/db/replay-window');
 const { pruneEvents, resolveRetentionPolicy, validatePolicy } = require('./lib/db/events-retention');
 const { sweepSecrets, resolveSecretSweepConfig } = require('./lib/db/secret-sweep');
@@ -169,6 +178,8 @@ let ipcCloser = null;
 // single-valued), we keep them as plain module-level variables — not a map.
 let BOT_NAME = null;  // string, frozen after boot
 let bot = null;       // grammy Bot for BOT_NAME
+let mediaBuffer = null; // media-group coalescing buffer, created in createBot;
+                        // module-level so shutdown can replay-mark buffered albums
 // 0.4.8 note: streamer + reactor are per-turn, not per-session. They live
 // on the pending's `context` object in the pm pendingQueue, keyed to the
 // specific turn (not the session). The old per-session Maps were a bug
@@ -293,6 +304,23 @@ function logEvent(kind, detail) {
   dbWrite(() => db.logEvent(kind, detail), `log ${kind}`);
 }
 
+// One bot runs per process, so rich-message capability can be represented
+// by one process-wide boolean rather than a per-connection map. Set once by
+// isRichCapabilityError (endpoint missing/404) and never cleared for the
+// process lifetime — retrying a permanently-missing endpoint on every
+// future send is wasteful. Transient errors must not set the latch.
+let richKnownUnsupported = false;
+
+// Extracted to lib/telegram/rich-edit.js so the capability/content/
+// transient error-classification + fallback wiring is directly unit-
+// testable. Constructed in main() (like `tg` itself, just below),
+// NOT here at module load time — BOT_NAME/config are `let`s still
+// `null`/`undefined` at this point; capturing them by destructuring now
+// would bake in stale values permanently, unlike `logEvent`, which is
+// safe to reference early because it's a stable function that does its
+// own live lookups internally when called.
+let richEditMessageText;
+
 // 0.15 secret redaction (agent-flagged path): the agent marks a secret it saw
 // in the user's message with `[redact:<secret>]`. parseResponse / stripInlineTags
 // strip the marker so nothing leaks to the user; here we wipe the literal from
@@ -473,7 +501,7 @@ function buildSpawnContext(sessionKey) {
     const resolved = {
       agent: topicConfig.agent || chatConfig.agent || null,
       cwd: topicConfig.cwd || chatConfig.cwd || null,
-      backend: pickBackend({ config, chatId, threadId: threadId || null }),
+      backend: pickBackend({ config, chatId, threadId: threadId || null, pmDefault: 'sdk' }),
     };
     const r = resolveSessionForSpawn(db, sessionKey, resolved);
     existingSessionId = r.existingSessionId;
@@ -502,7 +530,15 @@ function buildSpawnContext(sessionKey) {
     // the inbound filter and the send() choke point use, so CliProcess's
     // pre-check + system-prompt line can't drift from actual enforcement.
     localApi: !!config.bot?.apiRoot,
-    outboundCapOverride: resolveMaxFileOverride(config, chatId, threadId || null),
+    // Pre-resolve through the SAME backend-aware resolver origin's CliProcess used, so
+    // orchestra (which now uses opts.outboundCapOverride verbatim, without its own
+    // resolveFileCaps clamp) gets the backend default (2GB local / 50MB cloud) AND the
+    // ceiling clamp — not a flat 100MB. resolveFileCaps always returns a number, so this
+    // is always non-null and orchestra's injected fallback never fires.
+    outboundCapOverride: resolveFileCaps({
+      localApi: !!config.bot?.apiRoot,
+      override: resolveMaxFileOverride(config, chatId, threadId || null),
+    }).outBytes,
   };
 }
 
@@ -595,6 +631,14 @@ let errorReplyText = null;
 let queueWarnThreshold = null;
 let inFlightHandlers = null;
 
+// AUTH_DISABLED (docs/AUTH_DISABLED_HANDLING_SPEC.md): dedupe/re-arm gate for
+// the operator notification (dispatcher.js) + Netdata-visibility heartbeat
+// counter, both process-scoped like autoResumeTracker/contextHintShown above.
+// heartbeat.start() is called in main() once DATA_DIR is settled; the gate
+// needs no runtime config, so it's constructed here directly.
+const authDisabledGate = createAuthDisabledGate();
+const authDisabledHeartbeat = createHeartbeat({ dataDir: DATA_DIR, authDisabledGate });
+
 // 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
@@ -797,8 +841,9 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
     // showed "Agent: shumabit" instead of music-curation:music-curator
     // (2026-06-03). getTopicConfig returns {} when there's no active topic.
     const _cardTopicCfg = getTopicConfig(chatConfig, threadIdStr || null);
-    const info = formatConfigInfoText(chatConfig, show, sessionKey, _cardTopicCfg);
-    const reply_markup = buildConfigKeyboard(chatConfig, show, _cardTopicCfg);
+    const effectiveRichText = resolveRichTextEnabled(config, chatId, threadIdStr || null);
+    const info = formatConfigInfoText(chatConfig, show, sessionKey, _cardTopicCfg, effectiveRichText);
+    const reply_markup = buildConfigKeyboard(chatConfig, show, _cardTopicCfg, effectiveRichText);
     await sendReply(info, { params: { reply_markup } });
     return;
   }
@@ -811,6 +856,37 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
     cmdUser, cmdUserId, label, sendReply,
   })) return;
 
+  // Claude-auth gate: if the CLI login has expired, every claude turn wedges
+  // INVISIBLY — the 401 fires inside the subprocess, never reaches the
+  // classifier, and the turn degrades to a silent "⏱ went quiet" across every
+  // topic. Refuse up-front with a clear message + a loud log instead of
+  // spawning a doomed turn. Slash commands above don't need claude, so they
+  // still work. Free check (reads the credentials file, no API call). Guarded
+  // (fail-open to 'unknown' on throw): this sits on every turn's hot path, so
+  // a broken health check must never itself become the silent wedge this gate
+  // exists to catch. Applies to replays/redeliveries too (boot-replay,
+  // drop-redeliver, edit-redelivery) — the check is a cheap stateless file
+  // read, and a token can expire between an original dispatch and its later
+  // redelivery, so skipping it there would silently re-wedge exactly the
+  // messages most likely to hit an expired-auth window (post-restart backlog).
+  let auth;
+  try {
+    auth = checkClaudeAuthHealth();
+  } catch (err) {
+    console.error(`[auth] health check failed: ${err.message}`);
+    auth = { state: 'unknown' };
+  }
+  if (auth.state === 'expired') {
+    const expIso = new Date(auth.refreshTokenExpiresAt).toISOString();
+    console.error(`[auth] Claude login EXPIRED (refresh token ${expIso}) — refusing turn for ${label}; re-login on the host.`);
+    logEvent('auth-expired', {
+      session_key: sessionKey, chat_id: chatId, source: 'dispatch-gate',
+      refresh_token_expires_at: auth.refreshTokenExpiresAt,
+    });
+    await sendReply('🔑 Claude login has expired and needs to be re-authenticated. Messages can\'t be processed until the login is refreshed on the host.');
+    return;
+  }
+
   const t0 = Date.now();
 
   const sessionCtx = !pm.has(sessionKey) ? await readSessionContext(sessionKey, chatConfig.cwd) : '';
@@ -928,11 +1004,35 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
   // eliminates the "stuck at 15min typing" complaint from the non-streaming
   // code path. For short responses the streamer stays idle and we fall
   // through to the normal send path via finalize() returning streamed=false.
+  // Gate rich delivery on the per-chat/topic opt-in and the process-wide
+  // capability latch. Returning null forces the streamer's plain-text
+  // path — same contract for "not opted in", "capability known
+  // unsupported", and "content doesn't need it" (needsRichRendering
+  // inside toTelegramRichBlocks handles the last one).
+  // Rich delivery is limited to this interactive streamer instance.
+  // A reply that never crosses minChars (stays idle → delivered via
+  // deliverReplies) and any non-streaming send path — autonomous-wakeup/
+  // auto-resume/autosteer via lib/telegram/process-agent-reply.js, cron/
+  // IPC sends — never render rich even when richText is on and the
+  // content qualifies. Those delivery paths intentionally remain plain.
+  // Re-read both controls for every flush so a config change or a
+  // capability result applies to the turn already in progress.
+  const toRichPayload = (text, opts) => {
+    if (richKnownUnsupported || !resolveRichTextEnabled(config, chatId, threadId)) return null;
+    return toTelegramRichBlocks(text, opts);
+  };
+
   const streamer = createStreamer({
     // rc.67: pre-process every chunk to strip recognised
     // [sticker:NAME] / [react:EMOJI] tags BEFORE the bubble or DB row
     // captures them. See stripInlineTagsForStreamer above.
     transformText: stripInlineTagsForStreamer,
+    toRichPayload,
+    onRichUpgrade: () => {
+      // Record the visible transition when an existing plain bubble
+      // becomes rich during streaming.
+      logEvent('rich-streaming-upgrade', { chat_id: chatId, thread_id: threadId, bot: BOT_NAME });
+    },
     send: async (text) => {
       const params = {
         chat_id: chatId, text,
@@ -948,7 +1048,17 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
       }
       return tg(bot, 'sendMessage', params, outMetaBase);
     },
-    edit: async (messageId, text) => {
+    edit: async (messageId, payload) => {
+      // The streamer emits either a plain string or a rich payload with
+      // blocks and their source Markdown. Rich error classification and
+      // fallback live in rich-edit.js so this wiring stays focused.
+      if (payload && typeof payload === 'object' && payload.rich) {
+        return richEditMessageText({
+          bot, chatId, threadId, messageId,
+          blocks: payload.blocks, sourceText: payload.sourceText,
+        });
+      }
+      const text = payload;
       try {
         // Route edits through tg() so applyFormatting runs (MarkdownV2
         // + escape). Going direct to bot.api.editMessageText would
@@ -1307,6 +1417,12 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
       const chatCtxHint = chatConfig.contextHint != null
         ? chatConfig.contextHint
         : config.bot?.contextHint;
+      // AUTH_DISABLED re-arm (docs/AUTH_DISABLED_HANDLING_SPEC.md): only a
+      // genuine, non-error turn result counts as "recovered" — slash
+      // commands and other early-returns in handleMessage never reach this
+      // branch, so they can't falsely clear an ongoing outage and cause the
+      // operator to be re-paged before it's actually fixed.
+      try { authDisabledGate.noteSuccess(); } catch (e) { console.error(`[auth] authDisabledGate.noteSuccess failed: ${e.message}`); }
       // rc.59: gate the hint to once-per-cycle. Pre-rc.59 the hint
       // fired on EVERY turn that landed over threshold — so a user
       // saw "📚 70% full…" then "71% full…" then "72% full…"
@@ -1753,34 +1869,11 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
 
 // ─── Bot setup ──────────────────────────────────────────────────────
 
-function shouldHandle(msg, chatConfig, botUsername) {
-  const hasAttachment = !!(msg.document || msg.photo || msg.voice || msg.audio || msg.video);
-  if (!msg.text && !msg.caption && !hasAttachment) return false;
-  const chatId = msg.chat.id.toString();
-  if (!config.chats[chatId]) return false;
-
-  if (chatConfig.requireMention && msg.chat.type !== 'private') {
-    const text = msg.text || msg.caption || '';
-    const isReplyToBot = msg.reply_to_message?.from?.username === botUsername;
-    const hasMention = text.includes(`@${botUsername}`);
-    // A reply targeting some other user (not the bot) is a strong signal
-    // "this message is for that person, not me". Paired users normally
-    // bypass requireMention, but not in this case — without the guard a
-    // paired user saying "Gotcha!" to a teammate gets processed by the
-    // bot just because the user is paired, which is what bit us in
-    // UMI Group on 0.5.9 (bot leaked reasoning as a reply to "Gotcha!").
-    const repliesToOtherUser = !!msg.reply_to_message
-      && msg.reply_to_message.from?.username !== botUsername;
-    // Paired users bypass requireMention — operator-trusted, no @ needed
-    // every time. Skipped when they're replying to a non-bot user (above).
-    const paired = !repliesToOtherUser && pairings && msg.from?.id
-      ? pairings.hasLivePairing({ bot_name: BOT_NAME, user_id: msg.from.id, chat_id: chatId })
-      : false;
-    if (!isReplyToBot && !hasMention && !paired) return false;
-  }
-
-  return true;
-}
+const shouldHandle = createShouldHandle({
+  getConfig: () => config,
+  getPairings: () => pairings,
+  getBotName: () => BOT_NAME,
+});
 
 function createBot(token) {
   // Optional self-hosted Telegram Bot API server. When config.bot.apiRoot is
@@ -1945,7 +2038,7 @@ function createBot(token) {
   // a single synthetic turn with all attachments merged. Timer resets on
   // every new sibling, so as long as messages arrive faster than the
   // DEFAULT_FLUSH_MS window apart they stay in the same bundle.
-  const mediaBuffer = createMediaGroupBuffer({
+  mediaBuffer = createMediaGroupBuffer({
     onFlush: (messages) => {
       if (!messages || messages.length === 0) return;
       // Primary = the (usually first) message with text/caption; that's
@@ -2224,7 +2317,14 @@ async function main() {
   // TmuxProcess.start() hits EEXIST on session spawn for any chat
   // routed to pm:'tmux'. See lib/tmux/orphan-sweep.js for rationale.
   try {
-    const sweep = await sweepTmuxOrphans({ botName: BOT_NAME, logger: console });
+    // Sweep must look for polygram's session prefix — orchestra's default runner
+    // filters 'orchestra-<bot>-', which would never match our 'polygram-<bot>-'
+    // sessions (dead safety net + EEXIST on cli respawn of a leaked session).
+    const sweep = await sweepTmuxOrphans({
+      botName: BOT_NAME,
+      runner: createTmuxRunner({ logger: console, sessionPrefix: 'polygram' }),
+      logger: console,
+    });
     if (sweep.swept.length > 0) {
       console.log(`[orphan-sweep] killed ${sweep.swept.length} stale tmux session(s)`);
     }
@@ -2236,6 +2336,18 @@ async function main() {
     db = dbClient.open(DB_PATH);
     console.log(`[db] opened ${DB_PATH}`);
     tg = createSender(db, console, config);
+    richEditMessageText = createRichEditor({
+      tg,
+      botName: BOT_NAME,
+      logEvent,
+      redactBotToken,
+      isRichCapabilityError,
+      isRichContentError,
+      getRichKnownUnsupported: () => richKnownUnsupported,
+      setRichKnownUnsupported: () => { richKnownUnsupported = true; },
+      getApiRoot: () => config.bot?.apiRoot || null,
+      stripUrlCreds: stripUrlCredentials,
+    });
     pairings = createPairingsStore(db.raw);
     approvals = createApprovalsStore(db.raw);
     const migration = migrateJsonToDb(db, SESSIONS_JSON_PATH, config.chats);
@@ -2324,6 +2436,38 @@ async function main() {
     setInterval(() => runSecretSweep('interval'), secretSweepCfg.intervalMs).unref?.();
   }
 
+  // Claude-auth health monitor — a FREE credentials-file check (no API call, no
+  // model spawn). An expired refresh token makes the CLI 401 silently and wedges
+  // every channels turn; the handleMessage gate refuses turns + tells the user,
+  // and this surfaces the same state loudly in the operator logs at boot + every
+  // 30 min, warning a few days ahead so re-login happens before it breaks.
+  const runAuthCheck = (trigger) => {
+    try {
+      const auth = checkClaudeAuthHealth();
+      const expIso = auth.refreshTokenExpiresAt ? new Date(auth.refreshTokenExpiresAt).toISOString() : 'n/a';
+      if (auth.state === 'expired') {
+        console.error(`[auth] (${trigger}) Claude login EXPIRED (refresh token ${expIso}) — turns are being refused; re-login on the host.`);
+        logEvent('auth-expired', { source: 'monitor', trigger, refresh_token_expires_at: auth.refreshTokenExpiresAt });
+      } else if (auth.state === 'expiring') {
+        console.warn(`[auth] (${trigger}) Claude login expires in ${auth.daysLeft}d (${expIso}) — re-login soon.`);
+        logEvent('auth-expiring', { source: 'monitor', trigger, days_left: auth.daysLeft, refresh_token_expires_at: auth.refreshTokenExpiresAt });
+      } else if (auth.state === 'unknown') {
+        console.warn(`[auth] (${trigger}) Claude credentials check inconclusive: ${auth.reason}`);
+      }
+    } catch (err) {
+      console.error(`[auth] health check failed (${trigger}): ${err.message}`);
+    }
+  };
+  runAuthCheck('boot');
+  setInterval(() => runAuthCheck('interval'), 30 * 60_000).unref?.();
+
+  // AUTH_DISABLED Netdata-visibility heartbeat (docs/AUTH_DISABLED_HANDLING_SPEC.md,
+  // Layer 3.3) — writes <DATA_DIR>/heartbeat.json every 60s with the
+  // authDisabledGate's occurrence counter. File-only (no HTTP server in this
+  // repo to hang a /healthz route on); wiring the file into an actual Netdata
+  // alert is a separate VPS-side ops change, out of scope here.
+  authDisabledHeartbeat.start();
+
   // 0.8.0 Phase 1 step 11 + rc.50: defensive uncaughtException +
   // unhandledRejection handlers. The new pm wraps every Query
   // iteration in try/catch so SDK throws never leak — but if a
@@ -2482,7 +2626,7 @@ async function main() {
   // tmux backend runner — one per daemon, shared across all TmuxProcess
   // instances. Construction is cheap (no system call until first
   // spawn/send). Only used if any chat in config has pm:'tmux'.
-  const tmuxRunner = createTmuxRunner({ logger: console });
+  const tmuxRunner = createTmuxRunner({ logger: console, sessionPrefix: 'polygram' });
   // Verify the pinned claude CLI binary is present. The tmux
   // backend spawns this exact binary by absolute path (see
   // lib/claude-bin.js + TmuxProcess.start) — it never resolves
@@ -2498,7 +2642,13 @@ async function main() {
     // auto-pruner (keeps only ~3 newest, deletes the rest) can't take cli chats
     // down. Spawns from ~/.local/share/polygram/claude-bin/<version>, immune to
     // pruning. Self-heals on boot (copy from the system install, else install).
-    const { CLAUDE_CLI_PINNED_VERSION, ensureVendoredClaudeBin } = require('./lib/claude-bin');
+    // orchestra's claude-bin defaults its vendor dir to ~/.local/share/orchestra;
+    // point it at polygram's EXISTING vendored dir so boot reuses the pinned binary
+    // that's already there (no 223 MB re-vendor / `claude install` network call).
+    if (!process.env.ORCHESTRA_CLAUDE_VENDOR_DIR) {
+      process.env.ORCHESTRA_CLAUDE_VENDOR_DIR = require('node:path').join(require('node:os').homedir(), '.local', 'share', 'polygram', 'claude-bin');
+    }
+    const { CLAUDE_CLI_PINNED_VERSION, ensureVendoredClaudeBin } = require('@shumkov/orchestra').claudeBin;
     const binCheck = ensureVendoredClaudeBin(CLAUDE_CLI_PINNED_VERSION, { logger: console });
     if (binCheck.ok) {
       console.log(
@@ -2542,6 +2692,23 @@ async function main() {
     // channels backend
     toolDispatcher: channelsToolDispatcher,
     channelsClaudeBin,
+    // orchestra identity — polygram's names so behavior is byte-identical to the
+    // copied engine. bridge/tmux/hook/attachment prefixes, product/surface prose,
+    // the SDK backend (injected), and the default backend all match polygram's.
+    sessionPrefix: 'polygram',
+    bridgeServerName: 'polygram-bridge',
+    appDataDir: require('node:path').join(require('node:os').homedir(), '.polygram'),
+    attachmentBase: require('node:path').join(require('node:os').tmpdir(), 'polygram-attachments'),
+    productName: 'polygram',
+    surfaceName: 'Telegram',
+    pmDefault: 'sdk',
+    // The CLI append-system-prompt's FIRST block — origin hard-required this into every
+    // CliProcess. Without it, cli chats lose the Telegram table/markdown display rules.
+    displayHint: require('./lib/telegram/display-hint').POLYGRAM_DISPLAY_HINT,
+    // Backend-default outbound cap fallback (per-spawn buildSpawnContext override
+    // normally supersedes this; kept so any context-less spawn still gets the backend
+    // default rather than orchestra's neutral 100MB).
+    maxOutboundFileBytes: resolveFileCaps({ localApi: !!config.bot?.apiRoot }).outBytes,
   });
   // Route in-process approval prompts through the SAME canUseTool plumbing
   // that SDK chats use:
@@ -2633,6 +2800,7 @@ async function main() {
     chunkMarkdownText, deliverReplies,
     chunkBudget: TG_CHUNK_BUDGET,
     getIsShuttingDown: () => isShuttingDown,
+    authDisabledGate,
     logger: console,
   }));
   // 0.12.0 post-turn edit re-delivery: constructed AFTER dispatchHandleMessage is assigned (above).
@@ -2737,6 +2905,53 @@ async function main() {
       console.error(`[shutdown] question expiry failed: ${err.message}`);
     }
 
+    // 1.6 Album siblings still buffered (arrived <flushMs before shutdown,
+    //     never dispatched) sit at handler_status NULL — invisible to both
+    //     the drain below (not in inFlightHandlers) and recordCleanShutdown
+    //     (only re-marks dispatched/processing). Mark them replay-pending so
+    //     boot treats them like any interrupted turn: crash → recovered,
+    //     deliberate restart → the visible skip notice.
+    //
+    //     takeAllForShutdown() (not peekAll()) atomically cancels each
+    //     group's pending flush timer as it reads it (review: adversarial)
+    //     — a live timer firing during the drain below could otherwise
+    //     self-flush a group already marked replay-pending here, double-
+    //     processing it. Each group is coalesced onto ONE primary row,
+    //     mirroring onFlush's own primary-selection + attachment-reassign
+    //     logic above (review: correctness) — marking every sibling
+    //     individually meant a crash recovered an album as N fragmented
+    //     single-photo turns instead of the one multi-photo turn the live
+    //     path guarantees.
+    try {
+      const groups = mediaBuffer?.takeAllForShutdown() || [];
+      let markedCount = 0;
+      for (const { messages } of groups) {
+        if (!messages || messages.length === 0) continue;
+        const primary = messages.find((m) => m.text || m.caption) || messages[0];
+        const chatId = String(primary.chat.id);
+        const siblingMsgIds = messages
+          .filter((m) => m.message_id !== primary.message_id)
+          .map((m) => m.message_id);
+        if (siblingMsgIds.length) {
+          const primaryDbId = db.getInboundMessageId({ chat_id: chatId, msg_id: primary.message_id });
+          if (primaryDbId) {
+            dbWrite(() => db.reassignAttachmentsToMessage({
+              chat_id: chatId, msg_ids: siblingMsgIds, target_message_id: primaryDbId,
+            }), 'shutdown-media-buffer-reassign');
+          }
+        }
+        dbWrite(() => db.setInboundHandlerStatus({
+          chat_id: chatId, msg_id: primary.message_id, status: 'replay-pending',
+        }), 'shutdown-media-buffer');
+        markedCount += 1;
+      }
+      if (markedCount) {
+        logEvent('shutdown-media-buffer-marked', { count: markedCount });
+      }
+    } catch (err) {
+      console.error(`[shutdown] media-buffer replay-mark failed: ${err.message}`);
+    }
+
     // 2. Drain in-flight handlers. Wait for inFlightHandlers to empty or
     //    SHUTDOWN_DRAIN_MS to elapse. pm handlers resolve naturally when
     //    result events arrive; the dispatcher's .finally decrements.
@@ -2777,6 +2992,7 @@ async function main() {
     // 4. Remaining shutdown: approvals sweeper, IPC, resolve hook waiters,
     //    kill pm subprocesses, close DB.
     if (approvalSweepTimer) clearInterval(approvalSweepTimer);
+    authDisabledHeartbeat.stop();
     if (ipcCloser) ipcCloser.close().catch(() => {});
     try { fs.unlinkSync(ipcServer.secretPathFor(BOT_NAME)); } catch {}
     // Reject every parked canUseTool waiter so the SDK doesn't

package/lib/async-lock.js

@@ -1,49 +0,0 @@
-/**
- * Per-key chain lock. Each acquire() returns a release function; the next
- * acquire() awaits the previous one's release.
- *
- * Used by polygram to serialise stdin writes per session. Pre-work
- * (attachment download, voice transcription, prompt formatting) runs
- * concurrently; only the stdin write itself is serialised so Claude
- * reads messages in arrival order and replies come out in the same
- * order.
- *
- * Deliberately minimal — no timeouts, no cancellation, no fairness
- * guarantees beyond FIFO. Callers are expected to ALWAYS call release,
- * even on error paths, or the lock leaks (blocks all future acquires
- * for that key forever).
- */
-
-function createAsyncLock() {
-  const chains = new Map(); // key → Promise of last release
-
-  return {
-    async acquire(key) {
-      const prev = chains.get(key) || Promise.resolve();
-      let release;
-      const next = new Promise((resolve) => { release = resolve; });
-      // Save the chain-entry promise so the cleanup branch can compare
-      // against the SAME reference. Pre-fix this re-evaluated
-      // `prev.then(() => next)` (a fresh promise each call), so the
-      // === compare was always false and the Map leaked one entry per
-      // unique key.
-      const myEntry = prev.then(() => next);
-      chains.set(key, myEntry);
-      await prev;
-      // Return a wrapper that also clears the chain entry when this is
-      // the last holder — avoids the Map growing unbounded across the
-      // lifetime of the process. Idempotent: a double-release call is
-      // harmless (release() is a Promise resolver; calling resolve
-      // twice is a no-op).
-      return () => {
-        if (chains.get(key) === myEntry) {
-          chains.delete(key);
-        }
-        release();
-      };
-    },
-    get size() { return chains.size; },
-  };
-}
-
-module.exports = { createAsyncLock };