…5317)

* feat(channels)!: migrate signal from in-process adapter to sidecar

Replaces the 975-line in-process `librefang-channels::signal` (polling
loop against signal-cli-rest-api with SSRF guard rejecting
loopback/RFC-1918/link-local/CGNAT/IPv6-ULA, `POST /v2/send` outbound,
optional Bearer API key, optional base64 attachments) with an
out-of-process Python sidecar at
`sdk/python/librefang/sidecar/adapters/signal.py` (stdlib-only —
`urllib.request` for REST, `socket` + `ipaddress` for the SSRF
classifier).

Same pattern as line #5312 / zulip #5310 / mattermost #5315.

Behaviour parity (each citation against the pre-migration tree):

- SSRF guard: scheme + DNS-resolved address validation matches
  signal.rs:27-98. Default-deny on private/loopback unless
  `SIGNAL_ALLOW_LOCAL=1` is set explicitly.
- `GET /v1/receive/{phone}` polling with default 2 s cadence
  (signal.rs:171, 332).
- Self / allowlist / empty-text filters (signal.rs:361-376).
- Slash-command routing `/cmd args` → Command (signal.rs:383-396).
- `POST /v2/send` with `{message, number, recipients}`
  (signal.rs:204-244).
- Multi-bot `account_id` injection (#5003, signal.rs:417-422).
- Optional Bearer auth via `SIGNAL_API_KEY`.

Improvements over the Rust adapter:

1. Inbound dedupe on `envelope.timestamp` with
   `SEEN_MESSAGES_MAX=10000`/`EVICT=5000` — Rust emit at
   signal.rs:398-415 was unconditional, so a retry redelivered
   duplicates.
2. 429 `Retry-After` honoured on both poll and send paths
   (Rust had no 429 handling at all).
3. Explicit 15 s `urlopen` timeouts on every REST call.
4. 1–60 s exponential backoff on transport / non-2xx errors —
   Rust just `continue`-d on every error and spun at
   `poll_interval` against a wedged daemon.

Known gap: the Rust adapter's inline base64 attachment support
(`Image`/`Voice`/`Video`/`Audio`/`Animation`/`File`/`FileData`/
`MediaGroup`) is not wired through the sidecar yet — non-text content
falls back to a `(Unsupported content type)` placeholder. Follow-up
will restore the base64 round-trip end-to-end.

Cascade removal:

- `src/signal.rs` deleted; `lib.rs` mod, `channels-allowlist.txt`
  entry, both `Cargo.toml` features (incl. `all-channels` /
  `all-channels-no-email` / `mini`)
- `SignalConfig` struct + Default + `ChannelsConfig.signal` field +
  `default_signal_poll_interval_secs` helper + 3 unit tests
- `channel_bridge.rs` import / spawn block / `find_channel_info!` /
  `check_channel!` / default-empty assertion
- `routes/channels.rs` `ChannelMeta` entry + 4 match arms;
  `SIDECAR_CATALOG` entry added
- `routes/config.rs` `ch!(signal)` removed
- `channel_sender.rs` macro entry + EXPECTED list entry
- CLI TUI `ChannelDef`
- `librefang-channels` README / AGENTS sentence
- `librefang-migrate` openclaw importer (both JSON-block and
  YAML-file paths) — Signal now records a `report.skipped` entry
  (mirrors IRC / Mattermost)
- Docs EN + ZH (6 files)

Test plan:

- [x] `cargo check -p librefang-types -p librefang-channels -p librefang-api -p librefang-kernel -p librefang-cli -p librefang-migrate --lib` — clean
- [x] `cargo xtask channel-policy` — passed (`signal` removed)
- [x] `pytest sdk/python/tests/test_signal_adapter.py` — 61 passed
- [ ] Live signal-cli-rest-api smoke test (operator)

* fix(channels): make signal SSRF guard fail-closed on unparseable addr

`_is_private_or_loopback` returned `False` (= "public, allow") when
`ipaddress.ip_address` rejected the input string. In production
`socket.getaddrinfo` always hands back a well-formed IPv4/IPv6
literal so the path was unreachable, but the SSRF guard's contract
is default-deny — a future change that lets a scoped IPv6 literal
(`fe80::1%eth0`) through `getaddrinfo` would have silently allowed
link-local addresses.

Fail-CLOSED: any address the classifier cannot interpret is treated
as private. Tests cover the contract directly + the scoped-literal
case.

Tests: 61 → 62 (1 new for fail-closed on garbage inputs).

* docs(channels): correct Signal sidecar override + attachment notes

The two Signal-specific sections in the channels overview were
authored against the in-process Rust adapter and still claimed:

1. `Signal Plain-Text Default` — that you can override
   `output_format` via `[channels.signal.overrides]`. The
   `[channels.signal]` block was deleted in this migration, and
   `SidecarChannelConfig` does not expose an `overrides` field, so
   the snippet was inaccurate. The PlainText default itself still
   applies because it keys off the sidecar entry's
   `channel_type = "signal"` (`default_output_format_for_channel`
   in `crates/librefang-channels/src/formatter.rs`); only the
   *override mechanism* is currently absent on sidecar channels.

2. `Signal Media Attachments` — that base64 attachment delivery
   for `Image / Voice / Video / Audio / Animation / File /
   FileData / MediaGroup` works. The sidecar currently routes
   anything other than text to `(Unsupported content type)`; the
   PR description already lists base64 attachment parity as a
   known follow-up.

Updates EN + ZH overview pages plus the two cross-reference
sentences in EN + ZH `core/page.mdx` that pointed at these
anchors.

* fix(channels): drop stale signal refs missed by sidecar migration

Two leftovers from the in-process Signal removal broke 4 CI lanes
(Quality, Workspace coverage, Test/Windows shard 1, Test/macOS),
all with the same compile error:

    error[E0609]: no field `signal` on type `ChannelsConfig`

1. `librefang-migrate/src/openclaw.rs` — the
   `test_roundtrip_migrate_output_into_real_structs` test was still
   reading `cfg.channels.signal` even though the field is gone. The
   migrator now records the legacy `signal:` JSON block as a
   `report.skipped` entry (already covered by
   `test_signal_block_records_skipped_after_sidecar_migration`), so
   the inline read-back has no struct to land on. Replaced with a
   pointer to the dedicated skipped-channel test.

2. `librefang-cli/src/main.rs` — `cmd_channel_setup("signal")` still
   wrote a `[channels.signal]` block with `phone_env`, `socket_path`,
   `default_agent` fields the kernel would refuse to deserialize, and
   the `cmd_channel_list` summary still listed `signal` as a
   configurable in-process channel. Dropped the `"signal"` match arm
   and removed `signal` from both the list-view vector and the
   interactive picker — same shape the previous discord / slack /
   telegram migrations used.

Orphan i18n keys `section-setup-signal` in `locales/{en,zh-CN}/main.ftl`
are left in place to match the precedent set by discord/slack
(`section-setup-discord`, `section-setup-slack` also kept as orphans);
a single sweep across migrated channels is a separate cleanup.

---------

Co-authored-by: Evan <[email protected]>

Replaces the 758-line in-process `librefang-channels::qq`
adapter (token mint + WebSocket gateway + HELLO/IDENTIFY/READY
handshake + heartbeat + DISPATCH for 4 event types + REST send
with markdown stripping) with an out-of-process Python sidecar
at `sdk/python/librefang/sidecar/adapters/qq.py`. Same pattern as
ntfy #5224, telegram #5241, gotify #5263, mastodon #5264, bluesky
#5277, reddit #5281, twitch #5297, rocketchat #5298, discord
#5299, nextcloud #5301, slack #5302, webex #5309, line #5312,
zulip #5310, mattermost #5315, signal #5317.

Behaviour parity (every claim cited against the pre-migration
tree):

- Token fetch: POST bots.qq.com/app/getAppAccessToken (qq.rs:542-557).
- Gateway: GET /gateway with Bearer auth (qq.rs:559-573).
- WS handshake: HELLO(op=10) → IDENTIFY(op=2) with token =
  "QQBot <access_token>", intents bitmask, shard=[0,1] → READY
  dispatch (qq.rs:413-433).
- Heartbeat: op=1 frame at the server-supplied interval, carrying
  last seen `s` from dispatch frames (qq.rs:359-368).
- 4 dispatch event types: MESSAGE_CREATE / AT_MESSAGE_CREATE →
  /channels/{channel_id}/messages, DIRECT_MESSAGE_CREATE →
  /dms/{guild_id}/messages, GROUP_AT_MESSAGE_CREATE →
  /v2/groups/{group_openid}/messages, C2C_MESSAGE_CREATE →
  /v2/users/{user_openid}/messages (qq.rs:194-224).
- Bot-mention `/` strip + slash-command routing (qq.rs:227).
- User allowlist + multi-bot account_id metadata (#5003,
  qq.rs:400-405).
- Outbound markdown stripping pipeline preserves order:
  think tags → code blocks → inline code → bold → italic →
  headings → table separators → links → blockquotes → HRs →
  triple-newline collapse (qq.rs:137-180).
- 2000-char chunking (qq.rs:26), 1–60 s exponential reconnect
  backoff (qq.rs:282).

Improvements over the Rust adapter
==================================

1. **Reply context actually round-trips.** The Rust
   `parse_dispatch_event` (qq.rs:182-246) computed
   `reply_endpoint` and `msg_id` but the dispatch loop bound them
   to `_endpoint` / `_msg_id` (qq.rs:399) and dropped them on the
   floor; `send` (qq.rs:497-498) then expected
   `user.platform_id` to be encoded as `"<endpoint>|<msg_id>"`
   and silently no-op'd when the delimiter wasn't there. The
   Rust adapter therefore failed every real outbound — only the
   synthetic wiremock tests at qq.rs:686-712 exercised the
   working shape. The sidecar surfaces the reply endpoint as
   `channel_id` and the QQ `msg_id` as `thread_id` on the
   inbound event so the bridge round-trips them through to
   `on_send`, which posts to `{api_base}{channel_id}` with the
   correct passive-reply `msg_id`.

2. **Inbound dedupe on `msg.id`.** Rust emitted every parsed
   event unconditionally (qq.rs:399-410); WS reconnect could
   replay. Bounded local set, SEEN_MAX=10000 / EVICT=5000.

3. **429 Retry-After honoured on every REST path.** Token,
   gateway, and outbound send all sleep + retry once; second
   429 logs-and-continues (matches webex / line / mattermost /
   signal #5303).

4. **Explicit 15s urlopen timeouts on every REST call.** Rust
   pre-configured reqwest's 30s default at qq.rs:71; sidecar
   passes `timeout=SEND_TIMEOUT_SECS` (15 s) so a misbehaving
   endpoint trips an explicit error.

Cascade removal
================

- `src/qq.rs` deleted; `lib.rs` mod, `channels-allowlist.txt`
  entry, both `Cargo.toml` features removed.
- `QqConfig` struct + Default + `ChannelsConfig.qq` field gone.
- `channel_bridge.rs` import / spawn block / `check_channel!`
  / find_channel_info!(qq) (none existed) removed.
- `routes/channels.rs` `ChannelMeta` entry + 4 match arms
  (`is_some` / serialize / `len` / `ser`) removed; SIDECAR_CATALOG
  `qq` entry added.
- `routes/config.rs` `ch!(qq)` removed.
- `channel_sender.rs` `for_each_channel_field!` macro entry +
  `EXPECTED` name-list entry removed.
- CLI / TUI had no QQ wizard arm to remove.
- librefang-migrate had no QQ block to handle (QQ wasn't in the
  OpenClaw schema).
- Docs EN + ZH (6 files): `[channels.qq]` blocks replaced with
  `[[sidecar_channels]]` redirects; integrations tutorial
  rewritten for the sidecar.

New env-var knobs (`[sidecar_channels.env]`)
=============================================

- `QQ_APP_ID` (required)
- `QQ_ALLOWED_USERS` (optional, CSV)
- `QQ_ACCOUNT_ID` (optional)
- `QQ_INTENTS` (optional, decimal/hex bitmask override)

Secret (`~/.librefang/secrets.env`)
====================================

- `QQ_APP_SECRET` (required)

Operator action required
========================

An existing `[channels.qq]` block is no longer recognised —
re-declare as `[[sidecar_channels]]` running
`python3 -m librefang.sidecar.adapters.qq`. See
`sdk/python/librefang/sidecar/adapters/qq.py` header for the
exact config. `ChannelType::Custom("qq")` is preserved via
`channel_type = "qq"` on the sidecar entry so existing routing
and `channel_role_mapping` keys continue to resolve.

Verification
============

- `cargo check -p librefang-types -p librefang-channels -p librefang-api -p librefang-kernel -p librefang-cli --lib` — clean
- `cargo xtask channel-policy` — passed (`qq` removed from allowlist)
- `pytest sdk/python/tests/test_qq_adapter.py -q` — **77 passed**
  (covers env parsing, markdown stripping, parse_qq_event for all
  4 event types + edge cases, _mark_seen LRU eviction,
  _fetch_token + _fetch_gateway happy path / 429 / non-200 /
  missing field, _post_message chunking + 429 retry-once +
  persistent-429 fail-open + 5xx fail-open, on_send wiring with
  markdown stripping at the outbound boundary, WS gateway flow
  via mock _WebSocketClient — HELLO → IDENTIFY token+intents+
  shard, DISPATCH emission, msg.id dedupe, RECONNECT/INVALID_SESSION,
  heartbeat after interval, --describe schema, capabilities
  contract).

Co-authored-by: Evan <[email protected]>

…migration (closes #5316)

Four `librefang-migrate::openclaw::tests` cases used mattermost as their
in-process channel witness, but #5315 migrated mattermost to a sidecar
and the production migrate code now pushes a SkippedItem instead of
emitting [channels.mattermost]. With no other in-process channel in the
small fixtures, migrate_channels_from_json returned None, the report
had zero ItemKind::Channel imports, and the JSON5 full-migration
imported-count fell from 7 to 6 — turning main red.

- create_legacy_yaml_workspace: add messaging/whatsapp.yaml as the new
  in-process witness (telegram/discord/slack/mattermost are all
  sidecar-skipped). test_scan_workspace now asserts channels.len() == 5
  with whatsapp membership.
- test_json5_channel_extraction: add whatsapp to the inline JSON5;
  mattermost joins the sidecar-skip loop; ch_table.contains_key flips
  to whatsapp; secret-count stays at 5 (MATTERMOST_TOKEN still extracted
  via the sidecar-skipped path) and the new MATTERMOST_TOKEN=mm-token
  assertion against secrets.env makes that explicit.
- test_json5_full_migration: assertion 7 -> 6; count-comment rewritten to
  enumerate the 7 skips (telegram, discord, slack, irc, mattermost,
  imessage, bluebubbles) and the 6 in-process imports (whatsapp,
  signal, matrix, feishu, google_chat, msteams).
- test_policy_migration: replace mattermost witness with signal (still
  in-process, also accepts dm_policy); mattermost added to the
  sidecar-skip loop alongside discord/slack.

Verified: 36 openclaw::tests + 51 lib tests + 6 idempotency integration
tests green; `cargo clippy -p librefang-migrate --all-targets -- -D
warnings` clean.