feat(manager): WhatsApp pilot packaging and operations (WA-06)

[Asaf-prog]

Final planned stage of the WhatsApp integration plan: an administrator runbook, a deployable pilot example, operational monitoring, and a fake-provider restart rehearsal (task 0021).

Stacked on #149, which is stacked on #148. GitHub retargets each PR when its base merges.

Commits

1. feat(manager): log channel status and webhook rejections.
   • The worker logs one channel status: line per EXTRA_WHATSAPP_STATUS_LOG_SECONDS (default 60). It reports queue counts, the oldest unfinished and unsent ages, and unknown, failed, and blocked reply counts.
   • Each read is bounded to five seconds, so monitoring cannot stall scheduling or a graceful drain.
   • Every rejected webhook request logs whatsapp webhook rejected: reason=<fixed reason>.
   • No line contains message text, sender IDs, tokens, or provider message IDs.
2. feat(examples): add the WhatsApp pilot example, runbook, and rehearsal.
   • docs/WHATSAPP_RUNBOOK.md covers preflight, deployment, staged enablement and pause states, health and monitoring, restart recovery, rollback, retention, and the smoke-test checklist.
   • examples/whatsapp-pilot/ contains a tool-free assistant, an allowlist identity resolver for a closed pilot, .env.example with every stage off, and a compose file that runs agent-manager on a durable volume.
   • The rehearsal test proves that a message accepted while the worker is paused survives restarts and is answered and sent exactly once, that a signed delivered callback is projected, and that nothing is resent after a further restart.

The user chose structured log lines for monitoring, so there is no new HTTP endpoint, CLI, dependency, or migration.

Review corrections included

• Exposure: the example binds port 8100 to loopback. The manager's web conversation API is anonymous by default, so publishing the port would bypass the WhatsApp identity check. The runbook requires a proxy that forwards only the webhook path.
• Storage settings: EXTRA_DB_URL in .env now overrides the compose default, so a PostgreSQL configuration is no longer silently replaced by SQLite.
• Rollback in Docker: the rollback runs through docker compose run --entrypoint sh, because the image entrypoint passes other commands to agentctl.
• Allowlist entries: a malformed entry, such as roles given as a string, denies access instead of granting the wrong roles.

Each code correction has a regression test that fails without it.

Validation

• make check passes: 1441 tests, plus ruff and mypy. The first commit was also checked alone in a worktree: 1438 tests.
• agentctl validate passes on the example. docker compose config was checked with and without a PostgreSQL .env.
• The rollback downgrade to 0006 was rehearsed on a temporary database: the channel tables are removed and conversations are kept.
• Not run: the example has not been started in Docker (no local daemon), and nothing was tested against a real Meta account.

Still pending

• Automatic retention for channel data. There is none yet, and the runbook says so.
• Organization account linking (Google/JWT).
• The explicitly authorized real-number smoke test.

🤖 Generated with Claude Code