Telegram channel plugin: --channels flag stalls SSH terminal session

Environment

• Claude Code version: 2.1.81
• OS: Ubuntu Linux (headless server, SSH access only)
• SSH clients tested: Termius (macOS + iOS), plain OpenSSH
• Bun version: 1.3.11
• Plugin version: telegram@claude-plugins-official 0.0.4
• Auth: claude.ai OAuth (not API key)
• Feature flags: tengu_harbor: true, telegram in tengu_harbor_ledger

Problem

Launching Claude Code with --channels plugin:telegram@claude-plugins-official causes the terminal session to stall indefinitely. The SSH client (Termius) shows continuous "connecting" state and never renders the Claude Code TUI. This requires opening a separate plain SSH session to kill the process or revert changes.

The Telegram MCP server itself works fine — when Claude Code is launched without --channels, the plugin's bun process still starts (auto-loaded via enabledPlugins in settings.json), the bot connects to Telegram, and the MCP tools (reply, react, edit_message) are available. The issue is specifically with the --channels flag and inbound message delivery.

Issues encountered (chronological)

1. Variadic --channels flag swallows positional arguments

--channels is defined as <servers...> (variadic). When used with a startup prompt:

# BROKEN: /pickup is parsed as a second channel name
claude --channels plugin:telegram@claude-plugins-official /pickup

# WORKS: -- separates variadic args from positional
claude --channels plugin:telegram@claude-plugins-official -- /pickup

This isn't documented anywhere. The README example only shows --channels with no other arguments:

claude --channels plugin:telegram@claude-plugins-official

2. Terminal session stalls on startup

Even with correct syntax, the session stalls during startup when --channels is present. The terminal never renders the TUI — it appears to hang during MCP channel registration or the startup banner rendering.

Reproducer:

cd ~/docs && claude --channels plugin:telegram@claude-plugins-official -- /pickup

Expected: Claude Code starts with Telegram channel listening
Actual: Terminal hangs, SSH client shows perpetual "connecting" state

3. --channels is hidden from --help

The flag is defined with .hideHelp() so claude --help doesn't show it. This makes troubleshooting difficult — users can't verify the correct syntax without reading the plugin README or reverse-engineering the binary.

4. Plugin auto-loads without --channels

When telegram@claude-plugins-official is in enabledPlugins, the bun MCP server process starts in every Claude Code session regardless of whether --channels is passed. This means:

• Multiple sessions = multiple bun processes competing for the same bot token
• ~50% message loss when two sessions are open
• No way to have the plugin installed but only active in specific sessions

Setup details (all verified working)

• Token configured in ~/.claude/channels/telegram/.env
• access.json has dmPolicy: allowlist with user ID in allowFrom
• ackReaction: "👀" configured
• bun dependencies installed and working
• Bot responds to DMs when MCP tools are called manually

What I'd like

1. Fix or document the --channels + positional argument interaction (the -- requirement)
2. Investigate why --channels causes terminal session stalls (possibly related to TUI rendering or MCP channel registration blocking)
3. Consider showing --channels in --help output since it's documented in plugin READMEs
4. Consider making plugin auto-load respect --channels (only start the bot polling when --channels is explicitly passed)

Workaround

Currently running without --channels — the MCP tools work for outbound messages but inbound Telegram messages don't reach the conversation.