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>
2026-08-03 07:23:24 +02:00 · 2026-07-15 05:45:57 +02:00
parent d80dfb8bbe
commit bb3b4b0c6d
35 changed files with 2100 additions and 20 deletions
@@ -0,0 +1,143 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { ReactNode } from "react";
+
+const { getCredentialsStatus, setCredentials } = vi.hoisted(() => ({
+  getCredentialsStatus: vi.fn(async () => ({ has_credentials: false })),
+  setCredentials: vi.fn(async () => ({ has_credentials: true })),
+}));
+
+vi.mock("@/lib/api", () => ({
+  telegramApi: { getCredentialsStatus, setCredentials },
+}));
+
+import { TelegramCredentialsForm } from "../telegram-credentials-card";
+
+function withQueryClient(ui: ReactNode) {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+  return <QueryClientProvider client={client}>{ui}</QueryClientProvider>;
+}
+
+describe("TelegramCredentialsForm", () => {
+  beforeEach(() => {
+    getCredentialsStatus.mockClear();
+    setCredentials.mockClear();
+  });
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("shows 'no credentials configured' by default", async () => {
+    render(withQueryClient(<TelegramCredentialsForm />));
+    expect(
+      await screen.findByText("No credentials configured"),
+    ).toBeInTheDocument();
+  });
+
+  it("disables Save until both fields are filled", async () => {
+    render(withQueryClient(<TelegramCredentialsForm />));
+    await screen.findByText("No credentials configured");
+    const saveButton = screen.getByRole("button", { name: "Save" });
+    expect(saveButton).toBeDisabled();
+
+    fireEvent.change(screen.getByLabelText("Bot token (from @BotFather)"), {
+      target: { value: "123:abc" },
+    });
+    expect(saveButton).toBeDisabled(); // chat id still unfilled
+
+    fireEvent.change(screen.getByLabelText("Chat id (destination)"), {
+      target: { value: "987" },
+    });
+    expect(saveButton).not.toBeDisabled();
+  });
+
+  it("saves both secrets and clears the inputs on success", async () => {
+    render(withQueryClient(<TelegramCredentialsForm />));
+    await screen.findByText("No credentials configured");
+
+    fireEvent.change(screen.getByLabelText("Bot token (from @BotFather)"), {
+      target: { value: "123:abc" },
+    });
+    fireEvent.change(screen.getByLabelText("Chat id (destination)"), {
+      target: { value: "987" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+
+    await waitFor(() =>
+      expect(setCredentials).toHaveBeenCalledWith({
+        bot_token: "123:abc",
+        chat_id: "987",
+      }),
+    );
+    await waitFor(() =>
+      expect(
+        (
+          screen.getByLabelText("Bot token (from @BotFather)") as HTMLInputElement
+        ).value,
+      ).toBe(""),
+    );
+  });
+
+  it("a clear (both blank + has_credentials) opens a confirm dialog and defers the mutation until confirmed", async () => {
+    getCredentialsStatus.mockResolvedValueOnce({ has_credentials: true });
+    render(withQueryClient(<TelegramCredentialsForm />));
+    await screen.findByText("Credentials are set");
+
+    const saveButton = screen.getByRole("button", { name: "Save" });
+    expect(saveButton).not.toBeDisabled();
+
+    fireEvent.click(saveButton);
+
+    const dialog = await screen.findByRole("alertdialog");
+    expect(dialog).toBeInTheDocument();
+    expect(setCredentials).not.toHaveBeenCalled();
+
+    fireEvent.click(screen.getByRole("button", { name: "Clear" }));
+    await waitFor(() =>
+      expect(setCredentials).toHaveBeenCalledWith({
+        bot_token: "",
+        chat_id: "",
+      }),
+    );
+  });
+
+  it("a normal both-filled save fires immediately without a confirm dialog", async () => {
+    render(withQueryClient(<TelegramCredentialsForm />));
+    await screen.findByText("No credentials configured");
+
+    fireEvent.change(screen.getByLabelText("Bot token (from @BotFather)"), {
+      target: { value: "123:abc" },
+    });
+    fireEvent.change(screen.getByLabelText("Chat id (destination)"), {
+      target: { value: "987" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+
+    await waitFor(() =>
+      expect(setCredentials).toHaveBeenCalledWith({
+        bot_token: "123:abc",
+        chat_id: "987",
+      }),
+    );
+    expect(screen.queryByRole("alertdialog")).not.toBeInTheDocument();
+  });
+
+  it("a clear confirm dialog cancel does NOT fire the mutation", async () => {
+    getCredentialsStatus.mockResolvedValueOnce({ has_credentials: true });
+    render(withQueryClient(<TelegramCredentialsForm />));
+    await screen.findByText("Credentials are set");
+
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+    const dialog = await screen.findByRole("alertdialog");
+    expect(dialog).toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole("button", { name: "Cancel" }));
+    await waitFor(() =>
+      expect(screen.queryByRole("alertdialog")).not.toBeInTheDocument(),
+    );
+    expect(setCredentials).not.toHaveBeenCalled();
+  });
+});
@@ -31,6 +31,7 @@ import {
 } from "@/components/ui/collapsible";
 import { XCredentialsForm } from "@/components/settings/x-credentials-card";
 import { TikTokCredentialsForm } from "@/components/settings/tiktok-credentials-card";
+import { TelegramCredentialsForm } from "@/components/settings/telegram-credentials-card";
 import { cn } from "@/lib/utils";
 import { Flag, ChevronDown, ChevronRight } from "lucide-react";
 import { toast } from "sonner";
@@ -93,12 +94,15 @@ const FLAG_DESCRIPTIONS: Record<string, string> = {
    "Materialize a weekly org-report note (velocity, cycle time, rework, cost) in the vault's Reports/ folder and notify you — deterministic numbers, no LLM. Needs the Obsidian vault projection on.",
  vault_kb_enabled:
    "Index your own vault notes (default RoboCo/Notes/) into the knowledge base so the fleet can retrieve what you write — every note is screened for injection attempts before it's indexed. Needs the Obsidian vault projection on.",
+  telegram_enabled:
+    "Best-effort Telegram DMs to you alongside in-app notifications when a task is escalated for your approval or completes. Server-side fan-out — never blocks the in-app notification. Stays inert until you set bot-token + chat-id credentials in the Telegram card below.",
 };

 export function FeatureFlagsCard() {
  const queryClient = useQueryClient();
  const [xCredsOpen, setXCredsOpen] = useState(false);
  const [tiktokCredsOpen, setTiktokCredsOpen] = useState(false);
+  const [telegramCredsOpen, setTelegramCredsOpen] = useState(false);
  // Off-transition awaiting operator confirm. Null = no dialog open.
  const [confirmFlag, setConfirmFlag] = useState<FeatureFlag | null>(null);
  // Every in-flight toggle key — added on mutate, removed on settle. Tracks
@@ -170,12 +174,13 @@ export function FeatureFlagsCard() {
          {flags.map((flag) => {
            const isXEngine = flag.key === "x_engine_enabled";
            const isVideoEngine = flag.key === "video_engine_enabled";
+            const isTelegram = flag.key === "telegram_enabled";
            return (
              <div
                key={flag.key}
                className={cn(
                  "rounded-lg border p-4",
-                  (isXEngine || isVideoEngine) && "md:col-span-2",
+                  (isXEngine || isVideoEngine || isTelegram) && "md:col-span-2",
                )}
              >
                <div className="flex items-start justify-between gap-4">
@@ -251,6 +256,31 @@ export function FeatureFlagsCard() {
                    </CollapsibleContent>
                  </Collapsible>
                )}
+                {isTelegram && (
+                  <Collapsible
+                    open={telegramCredsOpen}
+                    onOpenChange={setTelegramCredsOpen}
+                    className="mt-3"
+                  >
+                    <CollapsibleTrigger asChild>
+                      <Button
+                        variant="ghost"
+                        size="sm"
+                        className="w-full justify-between px-2 text-muted-foreground"
+                      >
+                        <span className="text-sm">Telegram credentials</span>
+                        {telegramCredsOpen ? (
+                          <ChevronDown className="h-4 w-4" />
+                        ) : (
+                          <ChevronRight className="h-4 w-4" />
+                        )}
+                      </Button>
+                    </CollapsibleTrigger>
+                    <CollapsibleContent className="pt-3">
+                      <TelegramCredentialsForm />
+                    </CollapsibleContent>
+                  </Collapsible>
+                )}
              </div>
            );
          })}
@@ -0,0 +1,149 @@
+"use client";
+
+import { useState } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { telegramApi } from "@/lib/api";
+import { Label } from "@/components/ui/label";
+import { Input } from "@/components/ui/input";
+import { Button } from "@/components/ui/button";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
+import { Key, KeyRound, Save } from "lucide-react";
+import { toast } from "sonner";
+
+const FIELDS: Array<{ key: "bot_token" | "chat_id"; label: string }> = [
+  { key: "bot_token", label: "Bot token (from @BotFather)" },
+  { key: "chat_id", label: "Chat id (destination)" },
+];
+
+// The CEO's one-time entry of the Telegram bot token + destination chat id.
+// Write-only — the stored values are never displayed back, only whether
+// they're set (mirrors the X / git-token cards). Both are required together:
+// a token alone can't target a DM. Rendered chrome-less so it can nest inside
+// the Telegram feature-flag row.
+export function TelegramCredentialsForm() {
+  const queryClient = useQueryClient();
+  const [values, setValues] = useState({ bot_token: "", chat_id: "" });
+
+  const { data: status, isLoading } = useQuery({
+    queryKey: ["telegram", "credentials"],
+    queryFn: () => telegramApi.getCredentialsStatus(),
+  });
+
+  const saveMutation = useMutation({
+    mutationFn: () => telegramApi.setCredentials(values),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["telegram", "credentials"] });
+      setValues({ bot_token: "", chat_id: "" });
+      toast.success("Telegram credentials saved");
+    },
+    onError: (error) => {
+      toast.error(
+        `Failed to save: ${error instanceof Error ? error.message : "Unknown error"}`,
+      );
+    },
+  });
+
+  const allFilled = FIELDS.every((f) => values[f.key].trim().length > 0);
+  const noneFilled = FIELDS.every((f) => values[f.key].trim().length === 0);
+  const canSave = allFilled || (noneFilled && !!status?.has_credentials);
+  const isClearing = noneFilled && !!status?.has_credentials;
+  const [confirmClear, setConfirmClear] = useState(false);
+
+  return (
+    <div className="space-y-4">
+      <p className="text-sm text-muted-foreground">
+        The bot token from <span className="font-medium">@BotFather</span> and the
+        chat id to DM (your user/channel id). Stored encrypted server-side; agents
+        never see them and this panel never displays them again once saved.
+      </p>
+
+      <div className="flex items-center gap-2 rounded-md border p-3">
+        {status?.has_credentials ? (
+          <>
+            <Key className="h-4 w-4 text-green-500" />
+            <span className="text-sm text-green-600 dark:text-green-400">
+              Credentials are set
+            </span>
+          </>
+        ) : (
+          <>
+            <KeyRound className="h-4 w-4 text-amber-500" />
+            <span className="text-sm text-amber-600 dark:text-amber-400">
+              {isLoading ? "Checking..." : "No credentials configured"}
+            </span>
+          </>
+        )}
+      </div>
+
+      <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+        {FIELDS.map((field) => (
+          <div key={field.key} className="space-y-2">
+            <Label htmlFor={`tg-cred-${field.key}`}>
+              {status?.has_credentials ? `Replace ${field.label}` : field.label}
+            </Label>
+            <Input
+              id={`tg-cred-${field.key}`}
+              type="password"
+              value={values[field.key]}
+              onChange={(e) =>
+                setValues((prev) => ({ ...prev, [field.key]: e.target.value }))
+              }
+              placeholder="••••••••••••"
+            />
+          </div>
+        ))}
+      </div>
+
+      <p className="text-xs text-muted-foreground">
+        Set both to save (or rotate); leave both blank and save to clear.
+      </p>
+
+      <Button
+        onClick={() =>
+          isClearing ? setConfirmClear(true) : saveMutation.mutate()
+        }
+        disabled={saveMutation.isPending || !canSave}
+      >
+        <Save className="mr-2 h-4 w-4" />
+        {saveMutation.isPending ? "Saving..." : "Save"}
+      </Button>
+
+      <AlertDialog
+        open={confirmClear}
+        onOpenChange={(open) => {
+          if (!open) setConfirmClear(false);
+        }}
+      >
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Clear Telegram credentials?</AlertDialogTitle>
+            <AlertDialogDescription>
+              This will clear the stored bot token and chat id. This cannot be
+              undone.
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>Cancel</AlertDialogCancel>
+            <AlertDialogAction
+              onClick={() => {
+                setConfirmClear(false);
+                saveMutation.mutate();
+              }}
+            >
+              Clear
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </div>
+  );
+}
@@ -11,6 +11,7 @@ export { TabCommits } from "./tab-commits";
 export { TabNotes } from "./tab-notes";
 export { TabDependencies } from "./tab-dependencies";
 export { TabFindings } from "./tab-findings";
+export { TabCollision } from "./tab-collision";
 export { AcceptanceCriteria } from "./acceptance-criteria";
 export { ProgressTimeline } from "./progress-timeline";
 export { CheckpointCard } from "./checkpoint-card";
@@ -0,0 +1,241 @@
+"use client";
+
+import { Task } from "@/types";
+import { useTaskCollisionMap } from "@/hooks/use-tasks";
+import type { CollisionMap, CollisionSibling } from "@/lib/api/tasks";
+import { Card, CardContent } from "@/components/ui/card";
+import { Badge } from "@/components/ui/badge";
+import { Skeleton } from "@/components/ui/skeleton";
+import { GitBranch, AlertTriangle } from "lucide-react";
+
+interface TabCollisionProps {
+  task: Task;
+}
+
+// Status → tailwind badge class (a small inline map; no shared helper exists
+// across the task-detail tabs, so this mirrors tab-findings' inline maps).
+const STATUS_CLASS: Record<string, string> = {
+  pending: "bg-gray-100 text-gray-700 dark:bg-gray-800 dark:text-gray-300",
+  claimed:
+    "bg-blue-100 text-blue-700 dark:bg-blue-900 dark:text-blue-300",
+  in_progress:
+    "bg-indigo-100 text-indigo-700 dark:bg-indigo-900 dark:text-indigo-300",
+  awaiting_qa:
+    "bg-purple-100 text-purple-700 dark:bg-purple-900 dark:text-purple-300",
+  awaiting_documentation:
+    "bg-cyan-100 text-cyan-700 dark:bg-cyan-900 dark:text-cyan-300",
+  awaiting_pr_review:
+    "bg-amber-100 text-amber-700 dark:bg-amber-900 dark:text-amber-300",
+  awaiting_pm_review:
+    "bg-teal-100 text-teal-700 dark:bg-teal-900 dark:text-teal-300",
+  awaiting_ceo_approval:
+    "bg-orange-100 text-orange-700 dark:bg-orange-900 dark:text-orange-300",
+  needs_revision:
+    "bg-red-100 text-red-700 dark:bg-red-900 dark:text-red-300",
+  completed:
+    "bg-green-100 text-green-700 dark:bg-green-900 dark:text-green-300",
+  cancelled:
+    "bg-gray-100 text-gray-500 dark:bg-gray-800 dark:text-gray-500",
+  blocked:
+    "bg-red-100 text-red-700 dark:bg-red-900 dark:text-red-300",
+  paused: "bg-yellow-100 text-yellow-700 dark:bg-yellow-900 dark:text-yellow-300",
+  verifying:
+    "bg-violet-100 text-violet-700 dark:bg-violet-900 dark:text-violet-300",
+  backlog: "bg-gray-100 text-gray-500 dark:bg-gray-800 dark:text-gray-500",
+};
+
+function SiblingCard({ sib }: { sib: CollisionSibling }) {
+  return (
+    <Card>
+      <CardContent className="pt-4 space-y-3">
+        <div className="flex flex-wrap items-center gap-2">
+          <code className="text-xs font-mono text-muted-foreground">
+            {sib.id}
+          </code>
+          {sib.title && (
+            <span className="text-sm font-medium truncate">{sib.title}</span>
+          )}
+          <Badge
+            className={STATUS_CLASS[sib.status] ?? STATUS_CLASS.pending}
+          >
+            {sib.status}
+          </Badge>
+          {sib.branch_name && (
+            <code className="text-xs text-muted-foreground flex items-center gap-1">
+              <GitBranch className="h-3 w-3" />
+              {sib.branch_name}
+            </code>
+          )}
+          {sib.pr_number != null && (
+            <Badge variant="outline">#{sib.pr_number}</Badge>
+          )}
+          {sib.adds_migration && (
+            <Badge variant="outline" className="text-amber-700">
+              +migration
+            </Badge>
+          )}
+          {sib.touches_shared && (
+            <Badge variant="outline" className="text-orange-700">
+              shared
+            </Badge>
+          )}
+          {sib.sequence != null && (
+            <span className="ml-auto text-xs text-muted-foreground">
+              seq {sib.sequence}
+            </span>
+          )}
+        </div>
+
+        {sib.intends_to_touch.length > 0 && (
+          <div className="flex flex-wrap gap-1.5">
+            {sib.intends_to_touch.map((g) => (
+              <code
+                key={g}
+                className={
+                  "text-xs rounded px-1.5 py-0.5 " +
+                  (sib.overlap.includes(g)
+                    ? "bg-red-100 text-red-700 dark:bg-red-900 dark:text-red-300"
+                    : "bg-muted text-muted-foreground")
+                }
+              >
+                {g}
+              </code>
+            ))}
+          </div>
+        )}
+
+        {sib.overlap.length > 0 && (
+          <p className="text-xs text-muted-foreground">
+            <AlertTriangle className="inline h-3 w-3 mr-1" />
+            Overlaps your declared surface on{" "}
+            {sib.overlap.join(", ")}.
+          </p>
+        )}
+
+        {sib.undeclared.length > 0 && (
+          <div className="rounded border border-amber-300 dark:border-amber-800 bg-amber-50 dark:bg-amber-950/40 p-2 text-xs">
+            <span className="text-amber-700 dark:text-amber-300 font-medium">
+              Drift — touched but not declared:
+            </span>
+            <div className="mt-1 flex flex-wrap gap-1">
+              {sib.undeclared.map((f) => (
+                <code
+                  key={f}
+                  className="bg-amber-100 dark:bg-amber-900 text-amber-800 dark:text-amber-200 rounded px-1.5 py-0.5"
+                >
+                  {f}
+                </code>
+              ))}
+            </div>
+          </div>
+        )}
+      </CardContent>
+    </Card>
+  );
+}
+
+export function TabCollision({ task }: TabCollisionProps) {
+  const { data, isLoading } = useTaskCollisionMap(task.id);
+
+  if (isLoading) {
+    return (
+      <div className="space-y-3">
+        <Skeleton className="h-20 w-full" />
+        <Skeleton className="h-24 w-full" />
+      </div>
+    );
+  }
+
+  // No parent = a root; no collision siblings by construction.
+  if (!data || data.parent_task_id == null) {
+    return (
+      <div className="py-12 text-center text-muted-foreground">
+        <GitBranch className="mx-auto mb-4 h-12 w-12 opacity-50" />
+        <p>No collision map — this task has no parent.</p>
+        <p className="mt-2 text-sm">
+          Roots and standalone tasks have no siblings to collide with.
+        </p>
+      </div>
+    );
+  }
+
+  const siblings = data.siblings;
+
+  if (siblings.length === 0) {
+    return (
+      <div className="space-y-4">
+        <DeclaredSurfaceCard data={data} />
+        <div className="py-8 text-center text-muted-foreground">
+          <GitBranch className="mx-auto mb-4 h-12 w-12 opacity-50" />
+          <p>No colliding siblings.</p>
+          <p className="mt-2 text-sm">
+            None of this task&apos;s siblings share its declared surface or
+            migration chain.
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-4">
+      <DeclaredSurfaceCard data={data} />
+      <div>
+        <h3 className="text-sm font-semibold mb-3">
+          {siblings.length} colliding sibling{siblings.length > 1 ? "s" : ""}
+        </h3>
+        <div className="space-y-3">
+          {siblings.map((sib) => (
+            <SiblingCard key={sib.id} sib={sib} />
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function DeclaredSurfaceCard({ data }: { data: CollisionMap }) {
+  const hasSurface =
+    data.intends_to_touch.length > 0 ||
+    data.adds_migration ||
+    data.touches_shared;
+  return (
+    <Card>
+      <CardContent className="pt-4 space-y-2">
+        <h3 className="text-sm font-semibold">Declared surface</h3>
+        {hasSurface ? (
+          <>
+            {data.intends_to_touch.length > 0 && (
+              <div className="flex flex-wrap gap-1.5">
+                {data.intends_to_touch.map((g) => (
+                  <code
+                    key={g}
+                    className="text-xs bg-muted text-muted-foreground rounded px-1.5 py-0.5"
+                  >
+                    {g}
+                  </code>
+                ))}
+              </div>
+            )}
+            <div className="flex flex-wrap gap-2">
+              {data.adds_migration && (
+                <Badge variant="outline" className="text-amber-700">
+                  adds migration
+                </Badge>
+              )}
+              {data.touches_shared && (
+                <Badge variant="outline" className="text-orange-700">
+                  touches shared
+                </Badge>
+              )}
+            </div>
+          </>
+        ) : (
+          <p className="text-sm text-muted-foreground">
+            This task declared no collision surface.
+          </p>
+        )}
+      </CardContent>
+    </Card>
+  );
+}
@@ -17,6 +17,7 @@ import { TabCommits } from "./tab-commits";
 import { TabNotes } from "./tab-notes";
 import { TabDependencies } from "./tab-dependencies";
 import { TabFindings } from "./tab-findings";
+import { TabCollision } from "./tab-collision";
 import {
  FileText,
  Layout,
@@ -25,6 +26,7 @@ import {
  StickyNote,
  Link2,
  ListChecks,
+  GitBranch,
  type LucideIcon,
 } from "lucide-react";

@@ -108,6 +110,12 @@ export function TaskTabs({ task }: TaskTabsProps) {
      hint: "Revision-findings ledger — QA / PR-review / PM / CEO bounce feedback",
      count: findingsCount > 0 ? findingsCount : undefined,
    },
+    {
+      value: "collision",
+      label: "Collision",
+      icon: GitBranch,
+      hint: "Sibling collision surface + declared-vs-actual drift",
+    },
  ];

  // The active tab lives in the URL (?tab=) so it survives reloads,
@@ -128,7 +136,7 @@ export function TaskTabs({ task }: TaskTabsProps) {

  return (
    <Tabs value={activeTab} onValueChange={handleTabChange} className="mt-6">
-      <TabsList className="grid w-full grid-cols-7 lg:w-auto lg:inline-grid">
+      <TabsList className="grid w-full grid-cols-8 lg:w-auto lg:inline-grid">
        {tabs.map((tab) => (
          <Tooltip key={tab.value}>
            <TooltipTrigger asChild>
@@ -169,6 +177,9 @@ export function TaskTabs({ task }: TaskTabsProps) {
        <TabsContent value="findings">
          <TabFindings task={task} />
        </TabsContent>
+        <TabsContent value="collision">
+          <TabCollision task={task} />
+        </TabsContent>
      </div>
    </Tabs>
  );
@@ -1,5 +1,5 @@
 import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
-import { tasksApi, type TaskFilters } from "@/lib/api/tasks";
+import { tasksApi, type TaskFilters, type CollisionMap } from "@/lib/api/tasks";
 import {
  Team,
  TaskStatus,
@@ -29,6 +29,7 @@ export const taskKeys = {
    [...taskKeys.all, "subtasks", parentId] as const,
  boardReview: (id: string) => [...taskKeys.all, "board-review", id] as const,
  findings: (id: string) => [...taskKeys.all, "findings", id] as const,
+  collisionMap: (id: string) => [...taskKeys.all, "collision-map", id] as const,
  stats: () => [...taskKeys.all, "stats"] as const,
  statsByTeam: () => [...taskKeys.all, "stats-by-team"] as const,
 };
@@ -81,6 +82,18 @@ export function useTaskFindings(taskId: string) {
  });
 }

+// The reviewer/PM collision map — surfaced siblings that would collide with
+// the task. Fetched lazily (enabled only on the Collision tab) so it adds no
+// cost to the task-detail load; mirrors useBoardReview's staleTime posture.
+export function useTaskCollisionMap(taskId: string) {
+  return useQuery<CollisionMap>({
+    queryKey: taskKeys.collisionMap(taskId),
+    queryFn: () => tasksApi.getCollisionMap(taskId),
+    enabled: !!taskId,
+    staleTime: 30000,
+  });
+}
+
 export function useSubtasks(parentTaskId: string) {
  return useQuery({
    queryKey: taskKeys.subtasks(parentTaskId),
@@ -31,6 +31,8 @@ export type {
  XPostHistoryEntry,
  XCredentialsStatus,
 } from "./x";
+export { telegramApi } from "./telegram";
+export type { TelegramCredentialsStatus } from "./telegram";
 export { roadmapApi } from "./roadmap";
 export type {
  RoadmapCycle,
@@ -75,6 +75,34 @@ export interface TaskFindingsResponse {
  truncated: boolean;
 }

+// One surfaced sibling that collides with the task under review — matches
+// the backend CollisionSibling schema (roboco/api/schemas/tasks.py).
+export interface CollisionSibling {
+  id: string;
+  title: string | null;
+  status: string;
+  branch_name: string | null;
+  pr_number: number | null;
+  sequence: number | null;
+  intends_to_touch: string[];
+  adds_migration: boolean;
+  touches_shared: boolean;
+  overlap: string[];
+  undeclared: string[];
+}
+
+// The collision map for a task — its own declared surface + the surfaced
+// siblings (same parent) that would collide with it. Matches
+// CollisionMapResponse.
+export interface CollisionMap {
+  task_id: string;
+  parent_task_id: string | null;
+  intends_to_touch: string[];
+  adds_migration: boolean;
+  touches_shared: boolean;
+  siblings: CollisionSibling[];
+}
+
 // Wire shape of GET /tasks/summary (backend TaskSummaryResponse) — exactly
 // the fields list views render; everything fat stays on GET /tasks/{id}.
 interface TaskSummaryWire {
@@ -213,6 +241,26 @@ export const tasksApi = {
    return data;
  },

+  // The reviewer/PM collision map — the task's own declared surface + the
+  // surfaced siblings (same parent) that would collide with it (file-overlap
+  // globs or a shared migration chain). Empty siblings for a root or a task
+  // with no colliding siblings. Feed for the panel's Collision tab.
+  getCollisionMap: async (taskId: string): Promise<CollisionMap> => {
+    if (isMockMode())
+      return {
+        task_id: taskId,
+        parent_task_id: null,
+        intends_to_touch: [],
+        adds_migration: false,
+        touches_shared: false,
+        siblings: [],
+      };
+    const { data } = await api.get<CollisionMap>(
+      "/tasks/" + taskId + "/collision-map",
+    );
+    return data;
+  },
+
  // Create task
  create: async (task: TaskCreate): Promise<Task> => {
    if (isMockMode()) {
@@ -0,0 +1,30 @@
+import api from "./client";
+
+// ---------------------------------------------------------------------------
+// Telegram notifications bridge — the CEO's bot-token + chat-id credentials
+// (write-only; the API never returns the stored secrets). The fan-out itself
+// runs server-side from the CEO-notify producers; this surface is the
+// credentials card only.
+// ---------------------------------------------------------------------------
+
+export interface TelegramCredentialsStatus {
+  has_credentials: boolean;
+}
+
+export const telegramApi = {
+  getCredentialsStatus: async (): Promise<TelegramCredentialsStatus> => {
+    const { data } =
+      await api.get<TelegramCredentialsStatus>("/telegram/credentials");
+    return data;
+  },
+  setCredentials: async (creds: {
+    bot_token: string;
+    chat_id: string;
+  }): Promise<TelegramCredentialsStatus> => {
+    const { data } = await api.post<TelegramCredentialsStatus>(
+      "/telegram/credentials",
+      creds,
+    );
+    return data;
+  },
+};