feat: native WhatsApp Web channel via wa-rs

AGENTS.md

@@ -10,7 +10,7 @@ Project-level guidance for coding agents working in this repository.
 - Benchmarks: `benches/message_bus.rs`
 - Integration tests: `tests/integration.rs`
 - Codebase: ~106,000+ lines of Rust
-- Channels: 9 (Telegram, Slack, Discord, WhatsApp, WhatsApp Cloud, Lark, Email, Webhook, Serial)
+- Channels: 10 (Telegram, Slack, Discord, WhatsApp, WhatsApp Web, WhatsApp Cloud, Lark, Email, Webhook, Serial)
 - Runtimes: 6 (Native, Docker, Apple Container, Landlock, Firejail, Bubblewrap)
 - Peripherals: 4 boards (ESP32, RPi, Arduino, Nucleo) with GPIO, I2C, NVS, Serial
 - Skills: OpenClaw-compatible (reads `metadata.zeptoclaw` > `metadata.openclaw` > raw)
@@ -20,7 +20,7 @@ Project-level guidance for coding agents working in this repository.
 - Provider introspection CLI: `zeptoclaw provider status` prints resolved providers, wrapper config (retry/fallback), and quota usage snapshot
 - Channel dispatch: avoids holding the channels map `RwLock` across async `send()` awaits
 - Channel supervisor: polling (15s) detects dead channels, restarts with 60s cooldown, max 5 restarts
-- Channel panic isolation: Slack/Discord/Webhook/WhatsApp/WhatsApp Cloud/Lark/Email/MQTT/Serial spawned tasks are wrapped with `catch_unwind` and panic logging
+- Channel panic isolation: Slack/Discord/Webhook/WhatsApp/WhatsApp Web/WhatsApp Cloud/Lark/Email/MQTT/Serial spawned tasks are wrapped with `catch_unwind` and panic logging
 - Telegram outbound formatting: sends HTML parse mode with `||spoiler||` → `<tg-spoiler>` conversion
 - Discord outbound delivery: supports reply references and thread-create metadata (`discord_thread_*`) in `OutboundMessage`
 - Cron scheduling hardening: dispatch timeout + exponential error backoff + one-shot delete-after-run only on success
@@ -39,7 +39,7 @@ Project-level guidance for coding agents working in this repository.
 - MCP transport: supports both HTTP and stdio MCP servers (`url` or `command` + args/env) with tool registration during `create_agent()`
 - Hands-lite: `HAND.toml` + bundled hands (`researcher`, `coder`, `monitor`) + `hand` CLI
 - Process exit codes: explicit `main` mapping for success (0) and error (1); uncaught panic/crash remains Rust default (101)
-- Tests: 2956 lib + 92 main + 23 cli_smoke + 13 e2e + 70 integration + 126 doc (27 ignored)
+- Tests: default build runs 2956 lib + 92 main + 23 cli_smoke + 13 e2e + 70 integration + 126 doc (27 ignored); optional features such as `whatsapp-web` add feature-gated coverage
 
 ## Task Tracking Protocol
 

CLAUDE.md

@@ -24,7 +24,7 @@ cargo clippy -- -D warnings
 cargo fmt
 
 # Test counts (cargo test)
-# lib: 2956, main: 92, cli_smoke: 23, e2e: 13, integration: 70, doc: 126 passed (27 ignored)
+# default build: lib 2956, main 92, cli_smoke 23, e2e 13, integration 70, doc 126 passed (27 ignored); optional features such as whatsapp-web add feature-gated coverage
 
 # Version
 ./target/release/zeptoclaw --version
@@ -98,8 +98,8 @@ cargo fmt
 
 # Channel management
 ./target/release/zeptoclaw channel list
-./target/release/zeptoclaw channel setup whatsapp
-./target/release/zeptoclaw channel test whatsapp
+./target/release/zeptoclaw channel setup whatsapp_web
+./target/release/zeptoclaw channel test whatsapp_web
 
 # Onboard (express setup by default)
 ./target/release/zeptoclaw onboard
@@ -249,7 +249,7 @@ src/
 │   ├── slack.rs    # Slack outbound channel
 │   ├── discord.rs  # Discord Gateway WebSocket + REST (reply + thread create)
 │   ├── webhook.rs  # Generic HTTP webhook inbound
-│   ├── whatsapp.rs # WhatsApp via whatsmeow-rs bridge (WebSocket)
+│   ├── whatsapp_web.rs # WhatsApp Web via wa-rs native (feature: whatsapp-web)
 │   ├── whatsapp_cloud.rs # WhatsApp Cloud API (official webhook + REST)
 │   ├── lark.rs     # Lark/Feishu messaging (WS long-connection)
 │   ├── email_channel.rs # Email channel (IMAP IDLE + SMTP)
@@ -407,8 +407,6 @@ Containerized agent proxy for full request isolation:
 - Stdin/stdout IPC with containerized agent
 - Semaphore-based concurrency limiting (`max_concurrent` config)
 - Mount allowlist validation, docker binary verification
-- **Auto-installs channel dependencies** (e.g., whatsmeow-bridge for WhatsApp)
-- Dependencies installed at gateway startup via DepManager
 - Warn-and-continue on dependency failures (non-blocking)
 
 ### Providers (`src/providers/`)
@@ -433,7 +431,7 @@ Message input channels via `Channel` trait:
 - `SlackChannel` - Slack outbound messaging
 - `DiscordChannel` - Discord Gateway WebSocket + REST API messaging (replies + thread creation)
 - `WebhookChannel` - Generic HTTP POST inbound with optional Bearer auth
-- `WhatsAppChannel` - WhatsApp via whatsmeow-rs bridge (WebSocket JSON protocol)
+- `WhatsAppWebChannel` - WhatsApp Web via wa-rs native client (QR pairing, feature: whatsapp-web)
 - `WhatsAppCloudChannel` - WhatsApp Cloud API (webhook inbound + REST outbound, no bridge)
 - `MqttChannel` - MQTT messaging for IoT devices over WiFi/network (rumqttc, feature: mqtt)
 - `SerialChannel` - UART serial messaging (line-delimited JSON, feature: hardware)
@@ -631,12 +629,15 @@ Environment variables override config:
 - `ZEPTOCLAW_TOOLS_WEB_SEARCH_PROVIDER` — search provider: "brave", "searxng", "ddg" (default: auto-detect)
 - `ZEPTOCLAW_TOOLS_WEB_SEARCH_API_URL` — SearXNG instance URL (required when provider is "searxng")
 - `ZEPTOCLAW_TOOLS_CODING_TOOLS` — enable coding-specific tools: grep, find (default: false; auto-enabled by coder template)
+- `ZEPTOCLAW_CHANNELS_WHATSAPP_WEB_ENABLED` — enable WhatsApp Web channel (default: false)
+- `ZEPTOCLAW_CHANNELS_WHATSAPP_WEB_AUTH_DIR` — session persistence directory (default: ~/.zeptoclaw/state/whatsapp_web)
 
 ### Cargo Features
 
 - `android` — Enable Android device control tool via ADB
 - `google` — Enable Google Workspace tools (Gmail + Calendar) via gogcli-rs
 - `mqtt` — Enable MQTT channel for IoT device communication (rumqttc async client)
+- `whatsapp-web` — Enable native WhatsApp Web channel via wa-rs (QR code pairing)
 - `memory-bm25` — Enable BM25 keyword scoring for memory search
 - `peripheral-esp32` — Enable ESP32 peripheral with I2C + NVS tools (implies `hardware`)
 - `peripheral-rpi` — Enable Raspberry Pi GPIO + native I2C tools via rppal (Linux only)
@@ -647,6 +648,9 @@ Environment variables override config:
 ```bash
 cargo build --release --features android
 
+# Native WhatsApp Web channel
+cargo build --release --features whatsapp-web
+
 # Linux sandbox runtimes
 cargo build --release --features sandbox-landlock
 cargo build --release --features sandbox-firejail