Merge remote-tracking branch 'origin/kenneth/telegram-all-file-types' into kenneth/channels-rollup

# Conflicts:
#	external_plugins/telegram/server.ts

external_plugins/discord/README.md

@@ -55,7 +55,9 @@ Install the plugin:
 /discord:configure MTIz...
 ```
 
-Writes `DISCORD_BOT_TOKEN=...` to `.claude/channels/discord/.env` in your project. You can also write that file by hand, or set the variable in your shell environment — shell takes precedence.
+Writes `DISCORD_BOT_TOKEN=...` to `~/.claude/channels/discord/.env`. You can also write that file by hand, or set the variable in your shell environment — shell takes precedence.
+
+> To run multiple bots on one machine (different tokens, separate allowlists), point `DISCORD_STATE_DIR` at a different directory per instance.
 
 **6. Relaunch with the channel flag.**
 

external_plugins/discord/server.ts

@@ -25,11 +25,11 @@ import {
   type Attachment,
 } from 'discord.js'
 import { randomBytes } from 'crypto'
-import { readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, statSync, renameSync, realpathSync } from 'fs'
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, statSync, renameSync, realpathSync, chmodSync } from 'fs'
 import { homedir } from 'os'
 import { join, sep } from 'path'
 
-const STATE_DIR = join(homedir(), '.claude', 'channels', 'discord')
+const STATE_DIR = process.env.DISCORD_STATE_DIR ?? join(homedir(), '.claude', 'channels', 'discord')
 const ACCESS_FILE = join(STATE_DIR, 'access.json')
 const APPROVED_DIR = join(STATE_DIR, 'approved')
 const ENV_FILE = join(STATE_DIR, '.env')
@@ -37,6 +37,8 @@ const ENV_FILE = join(STATE_DIR, '.env')
 // Load ~/.claude/channels/discord/.env into process.env. Real env wins.
 // Plugin-spawned servers don't get an env block — this is where the token lives.
 try {
+  // Token is a credential — lock to owner. No-op on Windows (would need ACLs).
+  chmodSync(ENV_FILE, 0o600)
   for (const line of readFileSync(ENV_FILE, 'utf8').split('\n')) {
     const m = line.match(/^(\w+)=(.*)$/)
     if (m && process.env[m[1]] === undefined) process.env[m[1]] = m[2]
@@ -56,6 +58,15 @@ if (!TOKEN) {
 }
 const INBOX_DIR = join(STATE_DIR, 'inbox')
 
+// Last-resort safety net — without these the process dies silently on any
+// unhandled promise rejection. With them it logs and keeps serving tools.
+process.on('unhandledRejection', err => {
+  process.stderr.write(`discord channel: unhandled rejection: ${err}\n`)
+})
+process.on('uncaughtException', err => {
+  process.stderr.write(`discord channel: uncaught exception: ${err}\n`)
+})
+
 const client = new Client({
   intents: [
     GatewayIntentBits.DirectMessages,
@@ -340,7 +351,7 @@ function checkApprovals(): void {
   }
 }
 
-if (!STATIC) setInterval(checkApprovals, 5000)
+if (!STATIC) setInterval(checkApprovals, 5000).unref()
 
 // Discord caps messages at 2000 chars (hard limit — larger sends reject).
 // Split long replies, preferring paragraph boundaries when chunkMode is
@@ -421,7 +432,7 @@ const mcp = new Server(
       '',
       'Messages from Discord arrive as <channel source="discord" chat_id="..." message_id="..." user="..." ts="...">. If the tag has attachment_count, the attachments attribute lists name/type/size — call download_attachment(chat_id, message_id) to fetch them. Reply with the reply tool — pass chat_id back. Use reply_to (set to a message_id) only when replying to an earlier message; the latest message doesn\'t need a quote-reply, omit reply_to for normal responses.',
       '',
-      'reply accepts file paths (files: ["/abs/path.png"]) for attachments. Use react to add emoji reactions, and edit_message to update a message you previously sent (e.g. progress → result).',
+      'reply accepts file paths (files: ["/abs/path.png"]) for attachments. Use react to add emoji reactions, and edit_message for interim progress updates. Edits don\'t trigger push notifications — when a long task completes, send a new reply so the user\'s device pings.',
       '',
       "fetch_messages pulls real Discord history. Discord's search API isn't available to bots — if the user asks you to find an old message, fetch more history or ask them roughly when it was.",
       '',
@@ -469,7 +480,7 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'edit_message',
-      description: 'Edit a message the bot previously sent. Useful for progress updates (send "working…" then edit to the result).',
+      description: 'Edit a message the bot previously sent. Useful for interim progress updates. Edits don\'t trigger push notifications — send a new reply when a long task completes so the user\'s device pings.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -635,6 +646,25 @@ mcp.setRequestHandler(CallToolRequestSchema, async req => {
 
 await mcp.connect(new StdioServerTransport())
 
+// When Claude Code closes the MCP connection, stdin gets EOF. Without this
+// the gateway stays connected as a zombie holding resources.
+let shuttingDown = false
+function shutdown(): void {
+  if (shuttingDown) return
+  shuttingDown = true
+  process.stderr.write('discord channel: shutting down\n')
+  setTimeout(() => process.exit(0), 2000)
+  void Promise.resolve(client.destroy()).finally(() => process.exit(0))
+}
+process.stdin.on('end', shutdown)
+process.stdin.on('close', shutdown)
+process.on('SIGTERM', shutdown)
+process.on('SIGINT', shutdown)
+
+client.on('error', err => {
+  process.stderr.write(`discord channel: client error: ${err}\n`)
+})
+
 client.on('messageCreate', msg => {
   if (msg.author.bot) return
   handleInbound(msg).catch(e => process.stderr.write(`discord: handleInbound failed: ${e}\n`))
@@ -683,7 +713,7 @@ async function handleInbound(msg: Message): Promise<void> {
   // forgeable by any allowlisted sender typing that string.
   const content = msg.content || (atts.length > 0 ? '(attachment)' : '')
 
-  void mcp.notification({
+  mcp.notification({
     method: 'notifications/claude/channel',
     params: {
       content,
@@ -696,6 +726,8 @@ async function handleInbound(msg: Message): Promise<void> {
         ...(atts.length > 0 ? { attachment_count: String(atts.length), attachments: atts.join('; ') } : {}),
       },
     },
+  }).catch(err => {
+    process.stderr.write(`discord channel: failed to deliver inbound to Claude: ${err}\n`)
   })
 }
 
@@ -703,4 +735,7 @@ client.once('ready', c => {
   process.stderr.write(`discord channel: gateway connected as ${c.user.tag}\n`)
 })
 
-await client.login(TOKEN)
+client.login(TOKEN).catch(err => {
+  process.stderr.write(`discord channel: login failed: ${err}\n`)
+  process.exit(1)
+})

external_plugins/discord/skills/configure/SKILL.md

@@ -80,7 +80,8 @@ as the correct long-term choice. Don't skip the lockdown offer.
 2. `mkdir -p ~/.claude/channels/discord`
 3. Read existing `.env` if present; update/add the `DISCORD_BOT_TOKEN=` line,
    preserve other keys. Write back, no quotes around the value.
-4. Confirm, then show the no-args status so the user sees where they stand.
+4. `chmod 600 ~/.claude/channels/discord/.env` — the token is a credential.
+5. Confirm, then show the no-args status so the user sees where they stand.
 
 ### `clear` — remove the token
 

external_plugins/telegram/README.md

@@ -35,7 +35,9 @@ Install the plugin:
 /telegram:configure 123456789:AAHfiqksKZ8...
 ```
 
-Writes `TELEGRAM_BOT_TOKEN=...` to `.claude/channels/telegram/.env` in your project. You can also write that file by hand, or set the variable in your shell environment — shell takes precedence.
+Writes `TELEGRAM_BOT_TOKEN=...` to `~/.claude/channels/telegram/.env`. You can also write that file by hand, or set the variable in your shell environment — shell takes precedence.
+
+> To run multiple bots on one machine (different tokens, separate allowlists), point `TELEGRAM_STATE_DIR` at a different directory per instance.
 
 **4. Relaunch with the channel flag.**
 

external_plugins/telegram/server.ts

@@ -15,14 +15,14 @@ import {
   ListToolsRequestSchema,
   CallToolRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js'
-import { Bot, InputFile, type Context } from 'grammy'
+import { Bot, GrammyError, InputFile, type Context } from 'grammy'
 import type { ReactionTypeEmoji } from 'grammy/types'
 import { randomBytes } from 'crypto'
-import { readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, statSync, renameSync, realpathSync } from 'fs'
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, statSync, renameSync, realpathSync, chmodSync } from 'fs'
 import { homedir } from 'os'
 import { join, extname, sep } from 'path'
 
-const STATE_DIR = join(homedir(), '.claude', 'channels', 'telegram')
+const STATE_DIR = process.env.TELEGRAM_STATE_DIR ?? join(homedir(), '.claude', 'channels', 'telegram')
 const ACCESS_FILE = join(STATE_DIR, 'access.json')
 const APPROVED_DIR = join(STATE_DIR, 'approved')
 const ENV_FILE = join(STATE_DIR, '.env')
@@ -30,6 +30,8 @@ const ENV_FILE = join(STATE_DIR, '.env')
 // Load ~/.claude/channels/telegram/.env into process.env. Real env wins.
 // Plugin-spawned servers don't get an env block — this is where the token lives.
 try {
+  // Token is a credential — lock to owner. No-op on Windows (would need ACLs).
+  chmodSync(ENV_FILE, 0o600)
   for (const line of readFileSync(ENV_FILE, 'utf8').split('\n')) {
     const m = line.match(/^(\w+)=(.*)$/)
     if (m && process.env[m[1]] === undefined) process.env[m[1]] = m[2]
@@ -49,6 +51,15 @@ if (!TOKEN) {
 }
 const INBOX_DIR = join(STATE_DIR, 'inbox')
 
+// Last-resort safety net — without these the process dies silently on any
+// unhandled promise rejection. With them it logs and keeps serving tools.
+process.on('unhandledRejection', err => {
+  process.stderr.write(`telegram channel: unhandled rejection: ${err}\n`)
+})
+process.on('uncaughtException', err => {
+  process.stderr.write(`telegram channel: uncaught exception: ${err}\n`)
+})
+
 const bot = new Bot(TOKEN)
 let botUsername = ''
 
@@ -302,7 +313,7 @@ function checkApprovals(): void {
   }
 }
 
-if (!STATIC) setInterval(checkApprovals, 5000)
+if (!STATIC) setInterval(checkApprovals, 5000).unref()
 
 // Telegram caps messages at 4096 chars. Split long replies, preferring
 // paragraph boundaries when chunkMode is 'newline'.
@@ -339,9 +350,9 @@ const mcp = new Server(
     instructions: [
       'The sender reads Telegram, not this session. Anything you want them to see must go through the reply tool — your transcript output never reaches their chat.',
       '',
-      'Messages from Telegram arrive as <channel source="telegram" chat_id="..." message_id="..." user="..." ts="...">. If the tag has an image_path attribute, Read that file — it is a photo the sender attached. Reply with the reply tool — pass chat_id back. Use reply_to (set to a message_id) only when replying to an earlier message; the latest message doesn\'t need a quote-reply, omit reply_to for normal responses.',
+      'Messages from Telegram arrive as <channel source="telegram" chat_id="..." message_id="..." user="..." ts="...">. If the tag has an image_path attribute, Read that file — it is a photo the sender attached. If the tag has attachment_file_id, call download_attachment with that file_id to fetch the file, then Read the returned path. Reply with the reply tool — pass chat_id back. Use reply_to (set to a message_id) only when replying to an earlier message; the latest message doesn\'t need a quote-reply, omit reply_to for normal responses.',
       '',
-      'reply accepts file paths (files: ["/abs/path.png"]) for attachments. Use react to add emoji reactions, and edit_message to update a message you previously sent (e.g. progress → result).',
+      'reply accepts file paths (files: ["/abs/path.png"]) for attachments. Use react to add emoji reactions, and edit_message for interim progress updates. Edits don\'t trigger push notifications — when a long task completes, send a new reply so the user\'s device pings.',
       '',
       "Telegram's Bot API exposes no history or search — you only see messages as they arrive. If you need earlier context, ask the user to paste it or summarize.",
       '',
@@ -370,6 +381,11 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
             items: { type: 'string' },
             description: 'Absolute file paths to attach. Images send as photos (inline preview); other types as documents. Max 50MB each.',
           },
+          format: {
+            type: 'string',
+            enum: ['text', 'markdownv2'],
+            description: "Rendering mode. 'markdownv2' enables Telegram formatting (bold, italic, code, links). Caller must escape special chars per MarkdownV2 rules. Default: 'text' (plain, no escaping needed).",
+          },
         },
         required: ['chat_id', 'text'],
       },
@@ -387,15 +403,31 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ['chat_id', 'message_id', 'emoji'],
       },
     },
+    {
+      name: 'download_attachment',
+      description: 'Download a file attachment from a Telegram message to the local inbox. Use when the inbound <channel> meta shows attachment_file_id. Returns the local file path ready to Read. Telegram caps bot downloads at 20MB.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          file_id: { type: 'string', description: 'The attachment_file_id from inbound meta' },
+        },
+        required: ['file_id'],
+      },
+    },
     {
       name: 'edit_message',
-      description: 'Edit a message the bot previously sent. Useful for progress updates (send "working…" then edit to the result).',
+      description: 'Edit a message the bot previously sent. Useful for interim progress updates. Edits don\'t trigger push notifications — send a new reply when a long task completes so the user\'s device pings.',
       inputSchema: {
         type: 'object',
         properties: {
           chat_id: { type: 'string' },
           message_id: { type: 'string' },
           text: { type: 'string' },
+          format: {
+            type: 'string',
+            enum: ['text', 'markdownv2'],
+            description: "Rendering mode. 'markdownv2' enables Telegram formatting (bold, italic, code, links). Caller must escape special chars per MarkdownV2 rules. Default: 'text' (plain, no escaping needed).",
+          },
         },
         required: ['chat_id', 'message_id', 'text'],
       },
@@ -412,6 +444,8 @@ mcp.setRequestHandler(CallToolRequestSchema, async req => {
         const text = args.text as string
         const reply_to = args.reply_to != null ? Number(args.reply_to) : undefined
         const files = (args.files as string[] | undefined) ?? []
+        const format = (args.format as string | undefined) ?? 'text'
+        const parseMode = format === 'markdownv2' ? 'MarkdownV2' as const : undefined
 
         assertAllowedChat(chat_id)
 
@@ -438,6 +472,7 @@ mcp.setRequestHandler(CallToolRequestSchema, async req => {
               (replyMode === 'all' || i === 0)
             const sent = await bot.api.sendMessage(chat_id, chunks[i], {
               ...(shouldReplyTo ? { reply_parameters: { message_id: reply_to } } : {}),
+              ...(parseMode ? { parse_mode: parseMode } : {}),
             })
             sentIds.push(sent.message_id)
           }
@@ -478,12 +513,33 @@ mcp.setRequestHandler(CallToolRequestSchema, async req => {
         ])
         return { content: [{ type: 'text', text: 'reacted' }] }
       }
+      case 'download_attachment': {
+        const file_id = args.file_id as string
+        const file = await bot.api.getFile(file_id)
+        if (!file.file_path) throw new Error('Telegram returned no file_path — file may have expired')
+        const url = `https://api.telegram.org/file/bot${TOKEN}/${file.file_path}`
+        const res = await fetch(url)
+        if (!res.ok) throw new Error(`download failed: HTTP ${res.status}`)
+        const buf = Buffer.from(await res.arrayBuffer())
+        // file_path is from Telegram (trusted), but strip to safe chars anyway
+        // so nothing downstream can be tricked by an unexpected extension.
+        const rawExt = file.file_path.includes('.') ? file.file_path.split('.').pop()! : 'bin'
+        const ext = rawExt.replace(/[^a-zA-Z0-9]/g, '') || 'bin'
+        const uniqueId = (file.file_unique_id ?? '').replace(/[^a-zA-Z0-9_-]/g, '') || 'dl'
+        const path = join(INBOX_DIR, `${Date.now()}-${uniqueId}.${ext}`)
+        mkdirSync(INBOX_DIR, { recursive: true })
+        writeFileSync(path, buf)
+        return { content: [{ type: 'text', text: path }] }
+      }
       case 'edit_message': {
         assertAllowedChat(args.chat_id as string)
+        const editFormat = (args.format as string | undefined) ?? 'text'
+        const editParseMode = editFormat === 'markdownv2' ? 'MarkdownV2' as const : undefined
         const edited = await bot.api.editMessageText(
           args.chat_id as string,
           Number(args.message_id),
           args.text as string,
+          ...(editParseMode ? [{ parse_mode: editParseMode }] : []),
         )
         const id = typeof edited === 'object' ? edited.message_id : args.message_id
         return { content: [{ type: 'text', text: `edited (id: ${id})` }] }
@@ -505,6 +561,80 @@ mcp.setRequestHandler(CallToolRequestSchema, async req => {
 
 await mcp.connect(new StdioServerTransport())
 
+// When Claude Code closes the MCP connection, stdin gets EOF. Without this
+// the bot keeps polling forever as a zombie, holding the token and blocking
+// the next session with 409 Conflict.
+let shuttingDown = false
+function shutdown(): void {
+  if (shuttingDown) return
+  shuttingDown = true
+  process.stderr.write('telegram channel: shutting down\n')
+  // bot.stop() signals the poll loop to end; the current getUpdates request
+  // may take up to its long-poll timeout to return. Force-exit after 2s.
+  setTimeout(() => process.exit(0), 2000)
+  void Promise.resolve(bot.stop()).finally(() => process.exit(0))
+}
+process.stdin.on('end', shutdown)
+process.stdin.on('close', shutdown)
+process.on('SIGTERM', shutdown)
+process.on('SIGINT', shutdown)
+
+// Commands are DM-only. Responding in groups would: (1) leak pairing codes via
+// /status to other group members, (2) confirm bot presence in non-allowlisted
+// groups, (3) spam channels the operator never approved. Silent drop matches
+// the gate's behavior for unrecognized groups.
+
+bot.command('start', async ctx => {
+  if (ctx.chat?.type !== 'private') return
+  const access = loadAccess()
+  if (access.dmPolicy === 'disabled') {
+    await ctx.reply(`This bot isn't accepting new connections.`)
+    return
+  }
+  await ctx.reply(
+    `This bot bridges Telegram to a Claude Code session.\n\n` +
+    `To pair:\n` +
+    `1. DM me anything — you'll get a 6-char code\n` +
+    `2. In Claude Code: /telegram:access pair <code>\n\n` +
+    `After that, DMs here reach that session.`
+  )
+})
+
+bot.command('help', async ctx => {
+  if (ctx.chat?.type !== 'private') return
+  await ctx.reply(
+    `Messages you send here route to a paired Claude Code session. ` +
+    `Text and photos are forwarded; replies and reactions come back.\n\n` +
+    `/start — pairing instructions\n` +
+    `/status — check your pairing state`
+  )
+})
+
+bot.command('status', async ctx => {
+  if (ctx.chat?.type !== 'private') return
+  const from = ctx.from
+  if (!from) return
+  const senderId = String(from.id)
+  const access = loadAccess()
+
+  if (access.allowFrom.includes(senderId)) {
+    const name = from.username ? `@${from.username}` : senderId
+    await ctx.reply(`Paired as ${name}.`)
+    return
+  }
+
+  for (const [code, p] of Object.entries(access.pending)) {
+    if (p.senderId === senderId) {
+      await ctx.reply(
+        `Pending pairing — run in Claude Code:\n\n/telegram:access pair ${code}`
+      )
+      return
+    }
+  }
+
+  await ctx.reply(`Not paired. Send me a message to get a pairing code.`)
+})
+
 bot.on('message:text', async ctx => {
   await handleInbound(ctx, ctx.message.text, undefined)
 })
@@ -535,10 +665,94 @@ bot.on('message:photo', async ctx => {
   })
 })
 
+bot.on('message:document', async ctx => {
+  const doc = ctx.message.document
+  const name = safeName(doc.file_name)
+  const text = ctx.message.caption ?? `(document: ${name ?? 'file'})`
+  await handleInbound(ctx, text, undefined, {
+    kind: 'document',
+    file_id: doc.file_id,
+    size: doc.file_size,
+    mime: doc.mime_type,
+    name,
+  })
+})
+
+bot.on('message:voice', async ctx => {
+  const voice = ctx.message.voice
+  const text = ctx.message.caption ?? '(voice message)'
+  await handleInbound(ctx, text, undefined, {
+    kind: 'voice',
+    file_id: voice.file_id,
+    size: voice.file_size,
+    mime: voice.mime_type,
+  })
+})
+
+bot.on('message:audio', async ctx => {
+  const audio = ctx.message.audio
+  const name = safeName(audio.file_name)
+  const text = ctx.message.caption ?? `(audio: ${safeName(audio.title) ?? name ?? 'audio'})`
+  await handleInbound(ctx, text, undefined, {
+    kind: 'audio',
+    file_id: audio.file_id,
+    size: audio.file_size,
+    mime: audio.mime_type,
+    name,
+  })
+})
+
+bot.on('message:video', async ctx => {
+  const video = ctx.message.video
+  const text = ctx.message.caption ?? '(video)'
+  await handleInbound(ctx, text, undefined, {
+    kind: 'video',
+    file_id: video.file_id,
+    size: video.file_size,
+    mime: video.mime_type,
+    name: safeName(video.file_name),
+  })
+})
+
+bot.on('message:video_note', async ctx => {
+  const vn = ctx.message.video_note
+  await handleInbound(ctx, '(video note)', undefined, {
+    kind: 'video_note',
+    file_id: vn.file_id,
+    size: vn.file_size,
+  })
+})
+
+bot.on('message:sticker', async ctx => {
+  const sticker = ctx.message.sticker
+  const emoji = sticker.emoji ? ` ${sticker.emoji}` : ''
+  await handleInbound(ctx, `(sticker${emoji})`, undefined, {
+    kind: 'sticker',
+    file_id: sticker.file_id,
+    size: sticker.file_size,
+  })
+})
+
+type AttachmentMeta = {
+  kind: string
+  file_id: string
+  size?: number
+  mime?: string
+  name?: string
+}
+
+// Filenames and titles are uploader-controlled. They land inside the <channel>
+// notification — delimiter chars would let the uploader break out of the tag
+// or forge a second meta entry.
+function safeName(s: string | undefined): string | undefined {
+  return s?.replace(/[<>\[\]\r\n;]/g, '_')
+}
+
 async function handleInbound(
   ctx: Context,
   text: string,
   downloadImage: (() => Promise<string | undefined>) | undefined,
+  attachment?: AttachmentMeta,
 ): Promise<void> {
   const result = gate(ctx)
 
@@ -575,7 +789,7 @@ async function handleInbound(
 
   // image_path goes in meta only — an in-content "[image attached — read: PATH]"
   // annotation is forgeable by any allowlisted sender typing that string.
-  void mcp.notification({
+  mcp.notification({
     method: 'notifications/claude/channel',
     params: {
       content: text,
@@ -586,14 +800,63 @@ async function handleInbound(
         user_id: String(from.id),
         ts: new Date((ctx.message?.date ?? 0) * 1000).toISOString(),
         ...(imagePath ? { image_path: imagePath } : {}),
+        ...(attachment ? {
+          attachment_kind: attachment.kind,
+          attachment_file_id: attachment.file_id,
+          ...(attachment.size != null ? { attachment_size: String(attachment.size) } : {}),
+          ...(attachment.mime ? { attachment_mime: attachment.mime } : {}),
+          ...(attachment.name ? { attachment_name: attachment.name } : {}),
+        } : {}),
       },
     },
+  }).catch(err => {
+    process.stderr.write(`telegram channel: failed to deliver inbound to Claude: ${err}\n`)
   })
 }
 
-void bot.start({
-  onStart: info => {
-    botUsername = info.username
-    process.stderr.write(`telegram channel: polling as @${info.username}\n`)
-  },
+// Without this, any throw in a message handler stops polling permanently
+// (grammy's default error handler calls bot.stop() and rethrows).
+bot.catch(err => {
+  process.stderr.write(`telegram channel: handler error (polling continues): ${err.error}\n`)
 })
+
+// 409 Conflict = another getUpdates consumer is still active (zombie from a
+// previous session, or a second Claude Code instance). Retry with backoff
+// until the slot frees up instead of crashing on the first rejection.
+void (async () => {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      await bot.start({
+        onStart: info => {
+          botUsername = info.username
+          process.stderr.write(`telegram channel: polling as @${info.username}\n`)
+          void bot.api.setMyCommands(
+            [
+              { command: 'start', description: 'Welcome and setup guide' },
+              { command: 'help', description: 'What this bot can do' },
+              { command: 'status', description: 'Check your pairing status' },
+            ],
+            { scope: { type: 'all_private_chats' } },
+          ).catch(() => {})
+        },
+      })
+      return // bot.stop() was called — clean exit from the loop
+    } catch (err) {
+      if (err instanceof GrammyError && err.error_code === 409) {
+        const delay = Math.min(1000 * attempt, 15000)
+        const detail = attempt === 1
+          ? ' — another instance is polling (zombie session, or a second Claude Code running?)'
+          : ''
+        process.stderr.write(
+          `telegram channel: 409 Conflict${detail}, retrying in ${delay / 1000}s\n`,
+        )
+        await new Promise(r => setTimeout(r, delay))
+        continue
+      }
+      // bot.stop() mid-setup rejects with grammy's "Aborted delay" — expected, not an error.
+      if (err instanceof Error && err.message === 'Aborted delay') return
+      process.stderr.write(`telegram channel: polling failed: ${err}\n`)
+      return
+    }
+  }
+})()

external_plugins/telegram/skills/configure/SKILL.md

@@ -77,7 +77,8 @@ offer.
 2. `mkdir -p ~/.claude/channels/telegram`
 3. Read existing `.env` if present; update/add the `TELEGRAM_BOT_TOKEN=` line,
    preserve other keys. Write back, no quotes around the value.
-4. Confirm, then show the no-args status so the user sees where they stand.
+4. `chmod 600 ~/.claude/channels/telegram/.env` — the token is a credential.
+5. Confirm, then show the no-args status so the user sees where they stand.
 
 ### `clear` — remove the token
 

plugins/mcp-server-dev/skills/build-mcp-app/SKILL.md

@@ -350,4 +350,3 @@ The `sleep` keeps stdin open long enough to collect all responses. Parse the jso
 - `references/iframe-sandbox.md` — CSP/sandbox constraints, the bundle-inlining pattern, image handling
 - `references/widget-templates.md` — reusable HTML scaffolds for picker / confirm / progress / display
 - `references/apps-sdk-messages.md` — the `App` class API: widget ↔ host ↔ server messaging
-- `references/app-architecture-patterns.md` — multi-view app patterns: action dispatch, model context, build pipeline, dual transport

plugins/mcp-server-dev/skills/build-mcp-app/references/app-architecture-patterns.md

@@ -1,381 +0,0 @@
-# Multi-View App Architecture
-
-When a single-purpose widget isn't enough — when you have 5+ UI tools that share styling, state patterns, or a data model — consider building a **multi-view MCP app**: one React (or framework) SPA that dispatches to the right view based on which tool was called.
-
-This doc covers the production patterns for that architecture. It assumes you've read the main `build-mcp-app` skill and the `widget-templates.md` reference.
-
-> **Reference implementation:** [`nashville-charts-app`](https://github.com/bryankthompson/nashville-charts-app) on GitHub / npm demonstrates every pattern below. Install with `npx nashville-charts-app --stdio`.
-
----
-
-## Single resource, action-dispatched views
-
-Instead of one HTML file per tool, register **one shared resource** and point all UI tools at it. Each tool returns JSON with an `action` field that tells the app which view to render.
-
-**Server side:**
-
-```typescript
-const RESOURCE_URI = "ui://my-app/app.html";
-
-// Tool A — returns action + data
-registerAppTool(server, "show_dashboard", {
-  description: "Show the analytics dashboard",
-  inputSchema: { range: z.enum(["week", "month"]) },
-  _meta: { ui: { resourceUri: RESOURCE_URI } },
-}, async ({ range }) => {
-  const stats = await fetchStats(range);
-  return {
-    content: [{ type: "text", text: JSON.stringify({ action: "dashboard", stats }) }],
-  };
-});
-
-// Tool B — same resource, different action
-registerAppTool(server, "show_details", {
-  description: "Show detail view for a specific item",
-  inputSchema: { id: z.string() },
-  _meta: { ui: { resourceUri: RESOURCE_URI } },
-}, async ({ id }) => {
-  const item = await fetchItem(id);
-  return {
-    content: [{ type: "text", text: JSON.stringify({ action: "detail", item }) }],
-  };
-});
-
-// One resource serves all views
-registerAppResource(server, "App", RESOURCE_URI, {},
-  async () => ({
-    contents: [{ uri: RESOURCE_URI, mimeType: RESOURCE_MIME_TYPE, text: appHtml }],
-  }),
-);
-```
-
-**Widget side (React):**
-
-```tsx
-function App() {
-  const [view, setView] = useState(null);
-  const { app } = useApp({
-    appInfo: { name: "MyApp", version: "1.0.0" },
-    onAppCreated: (app) => {
-      app.ontoolresult = async (result) => {
-        const data = JSON.parse(result.content[0].text);
-        if (data.action) setView(data);
-      };
-    },
-  });
-
-  if (!view) return <div>Waiting for tool call...</div>;
-
-  switch (view.action) {
-    case "dashboard": return <Dashboard stats={view.stats} app={app} />;
-    case "detail":    return <DetailView item={view.item} app={app} />;
-    default:          return <div>Unknown view</div>;
-  }
-}
-```
-
-**Why this beats multiple HTML files:**
-- Shared CSS, shared components, shared state (theme, loading indicators)
-- One build artifact to deploy and cache
-- Consistent UX across all views — users don't see a flash between different iframes
-- The dispatch is just a `switch` on a string — trivial to extend
-
----
-
-## Model context updates
-
-`updateModelContext()` tells the LLM what the user is currently looking at — without adding a visible message to the chat. This is critical for multi-step workflows where Claude needs to reason about the current UI state.
-
-**What to send:** Structured state, not a prose description. YAML or JSON works well.
-
-```tsx
-useEffect(() => {
-  if (!view || !app) return;
-
-  const ctx = {
-    view: view.action,
-    ...(view.action === "dashboard" && {
-      range: view.stats.range,
-      itemCount: view.stats.items.length,
-    }),
-    ...(view.action === "detail" && {
-      itemId: view.item.id,
-      itemName: view.item.name,
-    }),
-  };
-
-  app.updateModelContext({
-    content: [{ type: "text", text: JSON.stringify(ctx) }],
-  }).catch(() => {
-    // Host may not support updateModelContext — degrade silently
-  });
-}, [app, view]);
-```
-
-**When to send:** On every view change. Don't send on every keystroke or scroll — just when the semantic state changes (new view, new data, user selection).
-
-**Always catch:** Not all hosts support `updateModelContext()`. Wrap in `.catch()` so the app doesn't break in hosts that don't implement it.
-
----
-
-## Teardown guards
-
-After the host calls `onteardown`, other callbacks (`ontoolresult`, `onhostcontextchanged`) may still fire. Without a guard, these late callbacks can cause React state updates on an unmounted component.
-
-```tsx
-const tornDown = useRef(false);
-
-app.onteardown = async () => {
-  tornDown.current = true;
-  setView(null);
-  return {};
-};
-
-app.ontoolresult = async (result) => {
-  if (tornDown.current) return;  // Guard
-  const data = JSON.parse(result.content[0].text);
-  if (data.action) setView(data);
-};
-
-app.onhostcontextchanged = () => {
-  if (tornDown.current) return;  // Guard
-  setHostContext(app.getHostContext());
-};
-```
-
-Use a `useRef` (not `useState`) — refs update synchronously and don't trigger re-renders.
-
----
-
-## Bidirectional tool calls from components
-
-When a UI component needs to call a server tool (e.g., a "Transpose" button, a "Load More" link), use `app.callServerTool()` and flow the result back through the parent's dispatch.
-
-```tsx
-// Parent holds the dispatch
-function App() {
-  const handleToolResult = useCallback((result) => {
-    const data = JSON.parse(result.content[0].text);
-    if (data.action) setView(data);
-  }, []);
-
-  return <DetailView item={view.item} app={app} onToolResult={handleToolResult} />;
-}
-
-// Child calls tools, parent re-dispatches
-function DetailView({ item, app, onToolResult }) {
-  const [loading, setLoading] = useState(false);
-
-  const handleRefresh = async () => {
-    setLoading(true);
-    try {
-      const result = await app.callServerTool({
-        name: "show_details",
-        arguments: { id: item.id },
-      });
-      onToolResult(result);
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  return (
-    <div>
-      <h1>{item.name}</h1>
-      <button onClick={handleRefresh} disabled={loading}>
-        {loading ? "Loading..." : "Refresh"}
-      </button>
-    </div>
-  );
-}
-```
-
-**Pattern:** Components don't set the view directly — they call tools and the parent handles the result. This keeps the data flow unidirectional: tool result -> parent dispatch -> child render.
-
-**App-only tools:** For tools that should only be callable from the widget (not by the LLM), use `server.registerTool` (not `registerAppTool` — these tools don't render a UI resource) with `visibility: ["app"]`:
-
-```typescript
-server.registerTool("internal_action", {
-  description: "...",
-  inputSchema: { ... },
-  _meta: { ui: { visibility: ["app"] } },
-}, handler);
-```
-
----
-
-## Build pipeline: Vite + esbuild
-
-A multi-view app needs a framework build (React, Vue, etc.) bundled into a single HTML file, plus a separate server bundle. Two-step build:
-
-**Step 1 — Vite bundles the SPA into one HTML file:**
-
-```typescript
-// vite.config.ts
-import { defineConfig } from "vite";
-import react from "@vitejs/plugin-react";
-import { viteSingleFile } from "vite-plugin-singlefile";
-
-export default defineConfig({
-  plugins: [react(), viteSingleFile()],
-  build: {
-    rollupOptions: { input: process.env.INPUT },  // e.g., INPUT=app.html
-    outDir: "dist",
-    emptyOutDir: false,  // Don't delete dist — esbuild writes here too
-  },
-});
-```
-
-`vite-plugin-singlefile` inlines all JS and CSS into the HTML. The output is a self-contained `dist/app.html` — no external chunks, no asset files.
-
-**Step 2 — esbuild bundles the server:**
-
-```bash
-# Server module
-npx esbuild server/server.ts --bundle --platform=node --format=esm \
-  --outfile=dist/server.js --packages=external
-
-# CLI entry point (with shebang for npx)
-npx esbuild main.ts --bundle --platform=node --format=esm \
-  --outfile=dist/index.js --packages=external \
-  --banner:js='#!/usr/bin/env node'
-```
-
-`--packages=external` keeps npm dependencies as imports (not bundled). The shebang banner makes `dist/index.js` directly executable.
-
-**Combined build script:**
-
-```json
-{
-  "build": "cross-env INPUT=app.html vite build && npx esbuild server/server.ts --bundle --platform=node --format=esm --outfile=dist/server.js --packages=external && npx esbuild main.ts --bundle --platform=node --format=esm --outfile=dist/index.js --packages=external --banner:js='#!/usr/bin/env node'"
-}
-```
-
-**Path resolution (dev vs. prod):**
-
-```typescript
-// Works in both TypeScript (dev) and compiled JS (prod)
-const DIST_DIR = import.meta.filename.endsWith(".ts")
-  ? path.join(import.meta.dirname, "..", "dist")   // Running .ts directly
-  : import.meta.dirname;                             // Running compiled .js
-
-const appHtml = await fs.promises.readFile(
-  path.join(DIST_DIR, "app.html"), "utf-8"
-);
-```
-
----
-
-## Dual transport: HTTP + stdio
-
-Support both transports from one codebase. Use a server factory function and a CLI flag.
-
-```typescript
-// main.ts
-import { createServer } from "./server/server.js";
-
-const useStdio = process.argv.includes("--stdio");
-
-if (useStdio) {
-  startStdio(createServer);
-} else {
-  startHTTP(createServer);
-}
-```
-
-**HTTP (stateless, one server per request):**
-
-```typescript
-async function startHTTP(createServer) {
-  const app = express();
-  app.use(express.json());
-
-  app.all("/mcp", async (req, res) => {
-    const server = createServer();  // Fresh per request
-    const transport = new StreamableHTTPServerTransport({
-      sessionIdGenerator: undefined,  // Stateless
-    });
-    res.on("close", () => {
-      transport.close();
-      server.close();
-    });
-    await server.connect(transport);
-    await transport.handleRequest(req, res, req.body);
-  });
-
-  app.listen(process.env.PORT ?? 3001);
-}
-```
-
-**stdio (persistent, one server for the session):**
-
-```typescript
-async function startStdio(createServer) {
-  const server = createServer();
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-  // Server stays alive until the process exits
-}
-```
-
-**Graceful shutdown** for HTTP:
-
-```typescript
-const shutdown = () => {
-  httpServer.close(() => process.exit(0));
-};
-process.on("SIGINT", shutdown);
-process.on("SIGTERM", shutdown);
-```
-
----
-
-## Debugging tips
-
-**Keep stdout clean.** In stdio mode, stdout IS the MCP protocol. All debug output must go to stderr:
-
-```typescript
-console.error("[DEBUG] Tool called:", toolName);  // stderr — safe
-console.log("...");                                // stdout — breaks protocol
-```
-
-**Extension detection.** The MCP SDK's Zod schema strips unknown fields from `capabilities` — including `extensions`, which signals UI support. To check if the client supports your widgets, intercept raw messages before SDK parsing:
-
-```typescript
-transport.onmessage = (msg) => {
-  if (msg?.method === "initialize") {
-    const extensions = msg.params?.capabilities?.extensions;
-    if (extensions) {
-      console.error("[DEBUG] Client supports extensions:", JSON.stringify(extensions));
-    }
-  }
-};
-```
-
-Compare raw messages with SDK-parsed `server.getClientCapabilities()` to diagnose stripping.
-
-**Resource caching in Claude Desktop.** After editing widget HTML, fully quit (Cmd+Q) and relaunch. Window-close doesn't clear the resource cache.
-
----
-
-## Prompt templates as workflow orchestration
-
-MCP prompts can guide the LLM through multi-tool workflows — acting as lightweight choreography:
-
-```typescript
-server.registerPrompt("analyze_pipeline", {
-  title: "Run Full Analysis",
-  description: "Fetch data, visualize, and summarize",
-}, () => ({
-  messages: [{
-    role: "user",
-    content: {
-      type: "text",
-      text: "Run a full analysis: use fetch-data to pull the latest numbers, " +
-            "show-dashboard to visualize them, then summarize the key insights.",
-    },
-  }],
-}));
-```
-
-The prompt tells the LLM which tools to call in which order. No dynamic data — just instructions. This surfaces as a slash-command in hosts that support prompts, giving users a one-click workflow trigger.