feat(channel/mattermost): add optional WebSocket listener mode

Summary

Add an optional Mattermost WebSocket listener mode on top of the current Mattermost channel implementation.

Problem statement

The current Mattermost channel uses REST API polling. Current master already supports multi-channel Mattermost operation, auto-discovery, DM/group-DM discovery, per-channel polling cursors, and password login through login_id + password. That covers most of the old #5162 / #5902 scope.

The remaining useful capability from those older PRs is WebSocket event delivery. Polling works, but it adds latency and periodic API load even when no messages are arriving. A WebSocket mode would let Mattermost deployments receive inbound events in near-real time while keeping REST for outbound replies.

Related:

• #5162
• #5902

Proposed solution

Add an opt-in Mattermost WebSocket listener mode against the current channel/config shape.

The first implementation should:

• keep polling as the default behavior;
• add a current-schema config knob such as listen_mode = "websocket" or the equivalent current convention;
• use the existing Mattermost auth model: bot_token, or login_id + password when bot_token is unset;
• connect to Mattermost's /api/v4/websocket endpoint using the existing proxy-aware WebSocket helper where possible;
• handle the Mattermost WebSocket authentication challenge;
• include ping/pong keepalive, timeout detection, and reconnect/backoff behavior;
• parse posted events into the same ChannelMessage semantics as polling;
• preserve current authorization, peer-group, mention_only, DM/group-DM bypass, threading, media/transcription, and per-channel behavior;
• update current docs and tests.

Non-goals / out of scope

Do not port the old #5902 branch wholesale. That branch predates the current config schema, docs book structure, quickstart/TUI work, gateway API shape, and Mattermost channel implementation.

This issue also does not require reviving the old bot_id / bot_password names. Current master already has password login through login_id + password.

Alternatives considered

Keep REST polling only. That is simpler and remains a valid fallback, but it leaves avoidable latency and API churn for deployments that can use Mattermost's native WebSocket events.

Acceptance criteria

• Mattermost polling remains the default and existing configs continue to work.
• Operators can opt into WebSocket listening through a documented config setting.
• WebSocket mode authenticates with either bot_token or the current password-login fields.
• WebSocket posted events produce the same authorization and routing outcomes as polling.
• Reconnect/backoff and ping/pong behavior are covered by tests or clear local validation.
• Docs explain when to use polling versus WebSocket mode.
• The PR body clearly explains compatibility, validation, and rollback.

Architecture impact

Affected area: crates/zeroclaw-channels/src/mattermost.rs, Mattermost config schema/docs, and tests. This should not require gateway or onboarding rewrites unless the current quickstart/config surfaces need a small generated-doc/schema update.

Risk and rollback

Risk is medium. This touches a channel listener and external network behavior, but the feature can be opt-in and polling can remain the default rollback path.

Rollback should be straightforward: set the channel back to polling mode or revert the WebSocket listener change.

Breaking change?

No.

Data hygiene checks

• I removed personal/sensitive data from examples, payloads, and logs.
• I used neutral, project-focused wording and placeholders.