waggle-os/docs/audits/2026-07-11-channels-ux-hardening.md

# Channels UX and Reliability Hardening

**Date:** 2026-07-11
**Branch:** `codex/channels-ux-hardening` from `origin/main` (`89329f99`)
**Scope:** Telegram, Discord, Slack, WhatsApp settings, protected routes, inbound agent turns, pairing, workspace routing, approvals, persistence, responsive UI, clean install, and real local runtime.

## Gate status

The Channels implementation is code-complete and locally release-ready. All hermetic gates pass, the production UI was exercised against a real bearer-protected sidecar, and the real Baileys transport reached QR pairing without writing plaintext authentication state.

External release evidence is still required for real provider credentials and a real WhatsApp device scan. That evidence is intentionally not represented as complete below.

## Defects found and corrected

| Severity | Defect | Correction |
|---|---|---|
| P0 | Settings used raw `fetch`, so protected channel routes returned 401. | Added typed authenticated adapter methods and moved the UI entirely onto them. |
| P0 | Channel-to-agent loopback called protected `/api/chat` without a bearer token. | Threaded the sidecar session token through `ChannelManager` and `runChannelChatTurn`; added a real Fastify auth integration test. |
| P0 | `package-lock.json` did not describe the merged Channels dependency graph; clean install failed. | Regenerated the lock, aligned `tsx`/`esbuild`, added the Testing Library peer, and proved normal `npm ci --legacy-peer-deps`. |
| P0 | Baileys persisted WhatsApp account/session keys as plaintext JSON. | Replaced multi-file auth persistence with one encrypted Vault entry, added one-time legacy migration, removed plaintext only after the encrypted write succeeds, and wipes both stores on logout. Corrupt state now fails closed and is preserved for recovery. |
| P1 | Headless channel turns could wait five minutes for an SSE approval nobody was watching. | Channel turns now use `proposeHeld`; gated actions enter the durable approval queue and the channel receives the app-approval response immediately. |
| P1 | Config writes could partially save secrets before a later field failed validation. | Validate the entire request, secret key set, values, enabled flag, and workspace before any Vault write. |
| P1 | Config changes were not represented in the audit stream. | Added `channel_config_change`; audit payloads contain secret key names only, never values. |
| P1 | Duplicate provider deliveries could execute a turn twice; simultaneous messages in one chat could interleave. | Added bounded 24-hour message-ID deduplication and a per-chat promise queue. |
| P1 | `/workspace` required opaque IDs and `/status` exposed raw IDs. | Resolve names or IDs, persist the stable ID, and show `Name (id)` in status output. |
| P1 | Channel controls were unreadable in narrow windows because the nested Settings rail consumed most of the viewport. | Settings tabs become a horizontal scroller below 640 px; active tabs scroll into view; channel forms, selectors, and actions stack without page overflow. |
| P2 | A deep link to a disclosure-hidden tab stayed on General after the user enabled Standard. | Re-resolve `?tab=channels` when the disclosure tier changes. |
| P2 | Failed saves cleared or obscured useful state and several actions had weak busy/error feedback. | Preserve secret drafts on failure, expose alert/status semantics, and consistently disable busy or prerequisite-blocked actions with visible reasons. |
| P2 | Baileys' default logger printed verbose device-pairing payloads. | Pass a silent internal logger and retain only curated Waggle lifecycle/error messages. |

## Scenario coverage

| Scenario | Evidence | Result |
|---|---|---|
| Unauthenticated management request | Real Fastify security middleware | 401, no state change |
| Authenticated browser bootstrap | Production app + fresh sidecar | Session token fetched; all Channels GET/POST requests 200 with bearer header |
| Atomic invalid config | Route integration | Unknown secret or workspace rejected; earlier fields are not persisted |
| Secret save | Real browser + isolated Vault | Draft clears only after success; masked saved state appears; Start becomes available |
| Bad provider credential | Real Telegram start | Honest `Unauthorized` error, transport remains stoppable |
| Deny-by-default pairing | Manager/pairing tests | Unknown senders receive silence; only valid one-use code pairs |
| Pair expiry/case/reuse | Pairing tests | Ten-minute TTL, case-insensitive entry, single use |
| Workspace name/id routing | Manager tests | Human name resolves to stable ID; per-chat override remains scoped |
| Duplicate inbound delivery | Manager tests | Same provider message ID executes once |
| Concurrent same-chat turns | Manager tests | Replies remain in arrival order |
| Injection rejection | Loopback client test | Scanner 400 becomes a safe user-facing channel error |
| Held tool approval | Chat route + client/manager tests | Durable approval notification; no unwatched five-minute wait |
| Platform send limits/reconnects | Telegram/Discord/Slack/WhatsApp adapter tests | Chunking, recovery, stop, and error states pass |
| WhatsApp encrypted persistence | Auth-state tests | Credentials and signal keys round-trip through Vault; no plaintext files |
| Existing WhatsApp pairing migration | Auth-state test | Multi-file state imported, encrypted, then legacy directory removed |
| Real Baileys startup | Fresh sidecar on port 34292 | Outbound connection succeeds, QR appears, no plaintext auth dir, verbose upstream logs suppressed |
| Desktop UI | Playwright at 1280x720 | No overlap; full workflow remains scannable |
| Narrow-window UI | Playwright at 390x844 | No document overflow; active tab visible; fields/actions stack and remain usable |
| Deep-link disclosure recovery | Real browser | Essential falls back to General; switching to Standard opens requested Channels tab |

## Verification evidence

- `npm ci --legacy-peer-deps`: pass, 1,769 packages installed.
- Backend Channels lane: 9 files, **89/89 tests pass**.
- Web Channels/deep-link lane: 2 files, **12/12 tests pass**.
- `npx tsc --noEmit --project packages/server/tsconfig.json`: pass.
- `npm run build:packages`: pass.
- `npm run build`: pass.
- `git diff --check`: pass.
- Fresh sidecar boot with a new data directory: pass.
- Real browser authenticated Vault save/start/error/stop flow: pass.
- Real Baileys unpaired QR flow: pass.

## Remaining release evidence

These are not code failures, but they must be completed before calling Channels production-proven:

1. Telegram bot: real token, pair from owner account, inbound answer, workspace switch, duplicate-delivery observation, revoke.
2. Discord bot: real app/guild install, Message Content intent, DM and channel message, reconnect, revoke.
3. Slack app: real Socket Mode app/bot tokens, DM and channel message, reconnect, revoke.
4. WhatsApp: scan with a secondary number, restart persistence, inbound/outbound message, unlink/logout wipe, re-pair.
5. Trigger one genuinely gated tool from a real channel and approve it in the desktop Approvals surface.

The founder-approved WhatsApp Terms-of-Service and ban risk remains visible and is not treated as solved by the credential hardening.

## Integration notes outside this branch

- `origin/main` still emits the known Tailwind arbitrary-duration warnings, the shape-selection chunk warning, and a >500 kB bundle warning. The broader UX branch already contains related build-polish work; do not duplicate it here.
- The served page reports a CSP rejection for the inline theme bootstrap script. It did not block Channels, but it remains global browser-console debt and should be resolved in the broader UX integration branch.