W6: Telegram notifications bridge (V1) (#524)

* feat(gateway): reviewer/PM collision map (W5)

The collision surface (intends_to_touch / adds_migration / touches_shared)
is authored at delegate time, consumed once by SequencingService to wire
dependency edges, then never shown to a reviewer again. This surfaces it:

- Pure builder (services/gateway/choreographer/collision.py): for a task
  under review, the surfaced siblings (same parent) that would collide —
  file-overlap globs or a shared migration chain (both adds_migration) —
  with the overlapping globs and a declared-vs-actual drift check. No
  DB/IO; callers fetch siblings (one indexed get_subtasks query, mig 069)
  + actual files (git). Caps: 10 siblings, 5 globs.

- Evidence envelopes: collision_context block injected into QA
  claim_review, PR-gate claim_gate_review (both carry real touched files
  so drift is populated), and the PM i_will_plan briefing (no actual
  files at plan time, drift omitted). Best-effort — a failure omits the
  block, never breaks the verb/briefing. Empty block omitted (zero token
  cost via _EVIDENCE_OMIT_WHEN_EMPTY).

- Panel: GET /api/tasks/{id}/collision-map (declared surface + sibling
  overlap; no drift — the panel route resolves no workspace) + a Collision
  tab on the task detail (8th tab). Mock-mode returns an empty map.

- docs/map added to the RAG auto-index dirs so the collision-map concept
  is fleet-retrievable; skipped gracefully if the dir is absent.

19 new tests (15 unit on the pure builder + 4 integration on the route).
Gate green: ruff/mypy/xenon (module rank A)/pytest 13000/coverage 94.81%,
panel typecheck/lint/516 tests.

* [w6-telegram] Add Telegram notifications bridge (V1)

CEO-facing Telegram DM bridge, flag-gated off by default
(ROBOCO_TELEGRAM_ENABLED). Mirrors the X-credentials / X-client pattern:

- TelegramCredentialsTable (migration 073) — singleton Fernet-encrypted
  bot_token + chat_id, all-or-nothing set/clear; API never returns plaintext.
- TelegramClient ABC / NullTelegramClient (no-op, configured->False, never
  raises) / LiveTelegramClient (httpx POST sendMessage) / build_telegram_client
  factory (Null when creds unset).
- /telegram/credentials CEO-only routes (write-only, guard-decorated).
- Best-effort _notify_telegram fan-out from the two CEO-notify producers
  (notify_ceo_of_escalation, notify_ceo_of_completion) — guarded by the flag,
  never raises into the producer, carries a panel deep-link when
  panel_base_url is set.
- panel credentials card (2 fields) nested in the Telegram feature-flag row.
- panel_base_url + telegram_timeout_seconds config fields.

V1 scope only: credentials + flag + panel card + client + one-line fan-out.
Out of scope (V2): inbound commands, a TelegramEngine background loop, a
dedup ledger, a bus subscription.

* [w6-telegram] fix: slave mypy/xenon regression (product tests + helper extract)

Pre-existing on slave from prior session's merges — no PR's CI caught them
(squash merges don't re-CI the result; each branch was based on older slave).

- test_product: _product helper returned MagicMock -> list invariant error;
  cast to ProductTable, move import under TYPE_CHECKING.
- test_usage: svc.session.execute (AsyncSession) has no call_args_list;
  cast to MagicMock at the two call sites.
- product.progress_for_products: xenon rank C -> extract module-level
  _project_to_products_map helper (repo pattern: helper-extract).

---------

Co-authored-by: Renn F <rennf93@users.noreply.github.com>

tests/unit/services/test_product.py

@@ -7,12 +7,16 @@ dedup of the same project across a product's cells).
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING, cast
 from unittest.mock import AsyncMock, MagicMock
 from uuid import UUID
 
 import pytest
 from roboco.services.product import ProductService
 
+if TYPE_CHECKING:
+    from roboco.db.tables import ProductTable
+
 _PRODUCT_A = UUID("11111111-1111-1111-1111-111111111111")
 _PRODUCT_B = UUID("22222222-2222-2222-2222-222222222222")
 _PROJECT_1 = UUID("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")
@@ -25,11 +29,11 @@ def _cell(project_id: UUID) -> MagicMock:
     return cell
 
 
-def _product(pid: UUID, project_ids: list[UUID]) -> MagicMock:
+def _product(pid: UUID, project_ids: list[UUID]) -> ProductTable:
     p = MagicMock()
     p.id = pid
     p.cells = [_cell(pid_proj) for pid_proj in project_ids]
-    return p
+    return cast("ProductTable", p)
 
 
 def _result_fetchall(rows: list[MagicMock]) -> MagicMock:

tests/unit/services/test_telegram_client.py

@@ -0,0 +1,66 @@
+"""TelegramClient coverage: NullTelegramClient no-op, LiveTelegramClient calls."""
+
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+from roboco.services.telegram_client import (
+    LiveTelegramClient,
+    NullTelegramClient,
+    build_telegram_client,
+)
+from roboco.services.telegram_credentials import TelegramCredentialsData
+
+_CREDS = TelegramCredentialsData(bot_token="123456:ABC", chat_id="987654321")
+
+
+def test_null_client_is_unconfigured() -> None:
+    client = build_telegram_client(None, timeout=5.0)
+    assert isinstance(client, NullTelegramClient)
+    assert client.configured is False
+
+
+@pytest.mark.asyncio
+async def test_null_client_send_message_is_a_noop() -> None:
+    client: NullTelegramClient = NullTelegramClient()
+    result = await client.send_message("hello")
+    assert result.sent is False
+    assert result.detail  # non-empty reason
+
+
+def test_build_telegram_client_with_creds_returns_live_client() -> None:
+    client = build_telegram_client(_CREDS, timeout=5.0)
+    assert isinstance(client, LiveTelegramClient)
+    assert client.configured is True
+
+
+@pytest.mark.asyncio
+async def test_live_client_send_message_success() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url.path == "/bot123456:ABC/sendMessage"
+        body = json.loads(request.content.decode())
+        assert body == {"chat_id": _CREDS.chat_id, "text": "hi"}
+        return httpx.Response(200, json={"ok": True, "result": {"message_id": 1}})
+
+    transport = httpx.MockTransport(handler)
+    http_client = httpx.AsyncClient(transport=transport)
+    client = LiveTelegramClient(_CREDS, timeout=5.0, client=http_client)
+    result = await client.send_message("hi")
+    assert result.sent is True
+    await client.close()
+
+
+@pytest.mark.asyncio
+async def test_live_client_send_message_http_error_is_graceful() -> None:
+    def handler(_request: httpx.Request) -> httpx.Response:
+        return httpx.Response(401, text="unauthorized")
+
+    transport = httpx.MockTransport(handler)
+    http_client = httpx.AsyncClient(transport=transport)
+    client = LiveTelegramClient(_CREDS, timeout=5.0, client=http_client)
+    result = await client.send_message("hi")
+    assert result.sent is False
+    assert "401" in result.detail
+    await client.close()

tests/unit/services/test_usage.py

@@ -13,6 +13,7 @@ verify the arithmetic / logic of each analytics method:
 from __future__ import annotations
 
 import datetime
+from typing import cast
 from unittest.mock import AsyncMock, MagicMock
 from uuid import UUID
 
@@ -349,7 +350,7 @@ class TestGetTimeSeries:
         )
         svc = _service_with_execute(_result_fetchall([row]))
         await svc.get_time_series("7d", agent_slug="be-dev-1")
-        stmt = svc.session.execute.call_args_list[0][0][0]
+        stmt = cast("MagicMock", svc.session.execute).call_args_list[0][0][0]
         sql = str(stmt.compile(compile_kwargs={"literal_binds": True}))
         assert "be-dev-1" in sql
 
@@ -366,7 +367,7 @@ class TestGetTimeSeries:
         )
         svc = _service_with_execute(_result_fetchall([row]))
         await svc.get_time_series("7d")
-        stmt = svc.session.execute.call_args_list[0][0][0]
+        stmt = cast("MagicMock", svc.session.execute).call_args_list[0][0][0]
         sql = str(stmt.compile(compile_kwargs={"literal_binds": True}))
         assert "agent_slug" not in sql