[77719d3f] A2A team telemetry: coordination event notifications for 5 event types (#477)

* [13d03d5c] Add 5 coordination-event notification producers + wire at chokepoints (#472) (#474)

* [13d03d5c] Add 5 coordination-event notification producer methods

* [13d03d5c] Wire reassignment/collision/unblock/dependency-revival notifications

* [13d03d5c] Wire stale-claim-reaped notification into orchestrator reaper

* [13d03d5c] fix(runtime): guard reaper's UUID annotation + defensive attr access

The stale-claim-reaped notification hook added a runtime-unquoted
`UUID` type annotation (only imported under TYPE_CHECKING, so the
module raised NameError on import) and a direct `t.assigned_to`
attribute access that crashes against the minimal test doubles the
existing reaper test suite uses. Quote the annotation and switch to
getattr-defensive access, matching `_assignee_is_provider_parked`'s
existing convention in the same file.

* [13d03d5c] test(notification): unit coverage for 5 coordination-event producers

One test per new send_* method (reassignment, collision-sequencing,
unblock, dependency-revival, stale-claim-reaped) following the
existing _FakeDb/_patch_db_context pattern, asserting subject/body/
related_task_id/priority/recipient-count, plus a no-recipients no-op
case for reassignment.

* [13d03d5c] test(task): prove reassign + unblock don't double-fire notifications

Two chokepoint-level tests mocking NotificationService at its defining
module: a repeated reassign() to the same already-current target skips
the notification (guarded by comparing against the pre-mutation
assignee), and a repeated unblock() on the same task only notifies
once since the second call short-circuits on the status!=BLOCKED
guard.

* [13d03d5c] style(task): ruff format the collision-sequencing wiring block

No behavior change — reflows the newly-added _notify_collision_sequencing
call site to satisfy ruff format's line-length rules.

* [13d03d5c] docs(backend): add coordination-event notification producers guide

Documented the 5 new NotificationService producers (reassignment, collision-sequencing,
unblock, dependency-revival, stale-claim-reaped) with fire conditions, double-fire
prevention mechanisms, and implementation patterns. Updated backend README to link the
new services guide for developers integrating new coordination events.

---------

Co-authored-by: Backend Developer 1 <be-dev-1@roboco.tech>
Co-authored-by: Backend Documenter <be-doc@roboco.tech>

* [3ee8150b] Frontend: render coordination-event notifications + e2e smoke coverage (#475)

* [69777c3a] test(e2e-smoke): add coverage for soft-block + unblock coordination notifications (#471)

Co-authored-by: Frontend Developer 2 <fe-dev-2@roboco.tech>

* [8eb82639] Render 5 coordination-event notification types with task deep-links (#470)

* [8eb82639] feat(notifications): add APPROVAL type icon and deep-link component test

Add missing APPROVAL member to the frontend NotificationType enum to
match backend roboco/models/base.py, wire its icon into the existing
typeIcons Record in the notifications page, and add a component test
covering type rendering and the task deep-link.

* [8eb82639] docs(notifications): document 5 coordination-event types and APPROVAL enum addition

Added comprehensive reference guide explaining the 5 notification types
(TASK_ASSIGNMENT, BLOCKER_ESCALATION, REVIEW_REQUEST, DOCUMENTATION_REQUEST,
APPROVAL), their visual identities (icon + color), use cases, and
deep-linking behavior to related tasks. Updated panel README with quick
reference table. TypeScript Record pattern ensures exhaustive type coverage
at build time.

---------

Co-authored-by: Frontend Developer 1 <fe-dev-1@roboco.tech>
Co-authored-by: Frontend Documenter <fe-doc@roboco.tech>

---------

Co-authored-by: Frontend Developer 2 <fe-dev-2@roboco.tech>
Co-authored-by: Frontend Developer 1 <fe-dev-1@roboco.tech>
Co-authored-by: Frontend Documenter <fe-doc@roboco.tech>

* [a27de2a8] fix(docs): reflow hard-wrapped notification-types.md to pass markdown gate (#479) (#481)

The Python quality gate on assembled PR #477 was red because the newly
added docs/frontend/components/notification-types.md (introduced by the
frontend coordination-event rendering commit) had manually wrapped prose
paragraphs, which scripts/reflow_md.py --check rejects as part of make
quality. Reflowed the file with scripts/reflow_md.py --apply (whitespace
only, no content change) so the check passes. ruff format/check, mypy,
xenon, vulture, bandit, and the full pytest suite (10284 passed) all
confirmed green on this commit; notification.py, task.py, and
orchestrator.py are untouched.

Co-authored-by: Backend Developer 1 <be-dev-1@roboco.tech>

* [705419d5] Remove duplicate unblock notification and fix its dependent tests (#485) (#488)

* [705419d5] fix(notifications): remove duplicate unblock notification, fix its tests

The /unblock route was still calling delivery.notify_assignee_of_unblock()
(TASK_ASSIGNMENT) after TaskService.unblock() already sent the
send_unblock_notification() ALERT wired in by an earlier task — a real
duplicate notification on every unblock. Delete the route-layer call and
the now-dead NotificationDeliveryService.notify_assignee_of_unblock
method, fix the integration test that mocked it, and fix/extend the e2e
notification-coordination-events test to assert the persisted ALERT rows
(exact subjects) for both the direct-unblock and dependency-revival
producers instead of the old TASK_ASSIGNMENT assertion.

* [705419d5] docs(backend): update coordination-events doc for unblock duplicate removal

---------

Co-authored-by: Backend Developer 1 <be-dev-1@roboco.tech>
Co-authored-by: Backend Documenter <be-doc@roboco.tech>

* [6c142a73] docs(changelog): document restored coordination-event notification producers and add collision-sequencing double-fire test (#489) (#490)

Co-authored-by: Backend Developer 2 <be-dev-2@roboco.tech>

* [77719d3f] Seed system agent in e2e harness to fix unblock/dependency-revival notifications

The e2e harness's seed_company omitted the system sentinel agent that
production seeds via initial_data.py. The unblock and dependency-revival
notification producers default to from_agent="system", which
_resolve_agent_uuid looks up by slug in the DB. With no system row the
resolver returns None and _create_notification silently skips the
notification, so the two ALERT assertions got 0 rows instead of 1.

The soft-block test passed because it uses NotificationDeliveryService
which creates the notification directly with a real agent UUID as
from_agent, bypassing the slug resolution path entirely.

* [77719d3f] Use foundation UUID for system agent to avoid slug collision

The first attempt seeded the system agent with a random UUID. Other
tests (_seed_system_and_secretary, _seed_video_agents) check by the
fixed foundation UUID via session.get(AgentTable, uuid); not finding
it they INSERT their own system row, hitting ix_agents_slug. Using the
foundation UUID makes their check find the seed_company row and skip.

* [77719d3f] Fix dependency-revival notification event loop mismatch

The dependency-revival test calls _unblock_dependents directly via
stack.run_db, which creates a new asyncio event loop. Inside,
_notify_dependency_revival -> NotificationService._create_notification
opened its own session via get_db_context(), which reuses the singleton
_DbHolder engine — bound to the FastAPI server's event loop. The
asyncpg connection raised 'Future attached to a different loop' and the
exception was silently caught + logged as a warning, so the notification
never persisted and the test saw 0 rows.

Fix: add an optional db_session parameter to _create_notification and
the two send methods. When provided, use the caller's session directly
and skip the internal commit (the caller owns the transaction). The
TaskService's _notify_unblock and _notify_dependency_revival now pass
self.session, keeping the notification in the same event loop + session
as the task transition.

* [77719d3f] Scope system-agent seeding to notification tests only

Seeding the system sentinel in seed_company (commits 3bba7b32/617b7890)
fixed the 0-notification bug but caused 3 i_documented gateway_timeout
failures: every e2e test now paid notification-creation latency for
system-origin notifications that were previously silently skipped,
pushing the already-slow i_documented verb past its 120s timeout.

Move system-agent seeding out of seed_company and into a scoped
_seed_system_agent helper called only by the two coordination-event
tests that exercise send_unblock_notification /
send_dependency_revival_notification (both resolve from_agent='system'
via DB lookup). dev_lifecycle and state_machine tests revert to the
pre-fix behavior (system-origin notifications silently skipped, no extra
latency).

The event-loop fix (commit 7b95d77d: pass db_session=self.session to
_create_notification) is unchanged — dependency_revival still needs it
because stack.run_db creates a new event loop while _DbHolder.engine is
bound to the FastAPI server loop.

* [77719d3f] Fix reassignment notification deadlock + suppressed-notification commit regression

Two fixes in notification.py / task.py:

1. Cross-session self-deadlock in send_reassignment_notification:
   TaskService.reassign() flushes an uncommitted row lock on the task,
   then calls _notify_reassignment -> send_reassignment_notification ->
   _create_notification(db_session=None) which opens a SEPARATE session
   via get_db_context() and INSERTs a notification with related_task_id
   FK -> tasks.id. The FK key-share lock blocks on the request session's
   uncommitted exclusive lock, but the request can't commit until the
   notify returns -> 120s verb hard-cut. Fix: pass db_session=self.session
   so the notification joins the verb's own transaction, same pattern as
   the unblock/dependency-revival fix in 7b95d77d.

2. Suppressed-notification commit regression: the 7b95d77d refactor moved
   await db.commit() out of _create_notification_with_session into
   _create_notification's db_session=None branch, where it ran
   unconditionally — even when _create_notification_with_session returned
   early (suppressed: unresolvable from_agent / no recipients /
   refire-guard / dedup-hit). Fix: _create_notification_with_session now
   returns bool (False at each early return, True after delivery);
   _create_notification commits only when created is True.

---------

Co-authored-by: Backend Developer 1 <be-dev-1@roboco.tech>
Co-authored-by: Backend Documenter <be-doc@roboco.tech>
Co-authored-by: Frontend Developer 2 <fe-dev-2@roboco.tech>
Co-authored-by: Frontend Developer 1 <fe-dev-1@roboco.tech>
Co-authored-by: Frontend Documenter <fe-doc@roboco.tech>
Co-authored-by: Backend Developer 2 <be-dev-2@roboco.tech>
Co-authored-by: Renn F <rennf93@users.noreply.github.com>

panel/README.md

@@ -50,8 +50,9 @@ That gives you Next dev-server on `localhost:3000`, but you still need the orche
 - `src/components/` — React components (organized by feature: tasks, agents, channels, …)
 - `src/lib/api/` — typed API client (thin wrappers over `fetch`)
 - `src/lib/` — constants, utilities, WebSocket hooks
-- `src/types/` — shared TypeScript types mirroring backend schemas
+- `src/types/` — shared TypeScript types mirroring backend schemas (includes `NotificationType` enum)
 - `src/hooks/` — reusable React hooks (see [Frontend hooks](../docs/frontend/hooks.md))
+- `src/app/(dashboard)/notifications/` — notifications inbox page and components
 
 ## Hooks
 
@@ -73,6 +74,20 @@ const { register, unregister, refresh, loading, disabled } = usePageRefresh();
 
 Wrap your page or layout in `PageRefreshProvider` from `@/components/providers` before consuming the hook. Dashboard pages should register their refetch callbacks and avoid adding inline "Refresh" buttons; see [`docs/frontend/components/page-refresh-provider.md`](../docs/frontend/components/page-refresh-provider.md) for the full wiring list and examples.
 
+## Notifications
+
+The panel renders five core **coordination-event notification types** that signal task lifecycle transitions between agents:
+
+| Type | Icon | Color | Meaning |
+|------|------|-------|---------|
+| `TASK_ASSIGNMENT` | ListTodo | green | A task has been assigned to you |
+| `BLOCKER_ESCALATION` | AlertTriangle | red | A developer is blocked and escalated |
+| `REVIEW_REQUEST` | Check | purple | Your review is needed |
+| `DOCUMENTATION_REQUEST` | Info | blue | Documentation is needed |
+| `APPROVAL` | ShieldCheck | emerald | Board-level approval requested |
+
+Each notification optionally carries a `related_task_id` rendered as a deep-link to `/tasks/{id}`. For full details on types, icons, and adding new types, see [`docs/frontend/components/notification-types.md`](../docs/frontend/components/notification-types.md).
+
 ## Dependency Management
 
 ### Version Alignment

panel/src/app/(dashboard)/notifications/__tests__/page.test.tsx

@@ -0,0 +1,129 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { PageRefreshProvider } from "@/components/providers";
+import { NotificationType, NotificationPriority, type Notification } from "@/types";
+
+const {
+  useNotifications,
+  useMarkNotificationRead,
+  useAcknowledgeNotification,
+  useMarkAllNotificationsRead,
+} = vi.hoisted(() => ({
+  useNotifications: vi.fn(),
+  useMarkNotificationRead: vi.fn(),
+  useAcknowledgeNotification: vi.fn(),
+  useMarkAllNotificationsRead: vi.fn(),
+}));
+
+vi.mock("next/navigation", () => ({
+  useRouter: () => ({ push: vi.fn() }),
+  useSearchParams: () => new URLSearchParams("tab=all"),
+}));
+
+vi.mock("@/hooks/use-notifications", () => ({
+  useNotifications,
+  useMarkNotificationRead,
+  useAcknowledgeNotification,
+  useMarkAllNotificationsRead,
+}));
+
+vi.mock("@/components/ui/markdown", () => ({
+  Markdown: ({ children }: { children: string }) => <div>{children}</div>,
+}));
+
+vi.mock("sonner", () => ({
+  toast: { success: vi.fn(), error: vi.fn() },
+}));
+
+import NotificationsPage from "../page";
+
+function withPageRefresh(ui: ReactNode) {
+  return <PageRefreshProvider>{ui}</PageRefreshProvider>;
+}
+
+function buildNotification(overrides: Partial<Notification> = {}): Notification {
+  return {
+    id: "notif-1",
+    type: NotificationType.TASK_ASSIGNMENT,
+    priority: NotificationPriority.NORMAL,
+    from_agent: "fe-pm-00000000",
+    to_agents: ["fe-dev-1"],
+    subject: "New task assigned",
+    body: "You have been assigned a new task.",
+    requires_ack: false,
+    is_acknowledged: false,
+    is_fully_acknowledged: false,
+    is_read: false,
+    related_task_id: "11111111-2222-3333-4444-555555555555",
+    related_message_ids: [],
+    timestamp: "2026-07-11T09:00:00Z",
+    expires_at: null,
+    acked_by: [],
+    acked_at: {},
+    ...overrides,
+  };
+}
+
+describe("NotificationsPage", () => {
+  beforeEach(() => {
+    useMarkNotificationRead.mockReturnValue({ mutateAsync: vi.fn() });
+    useAcknowledgeNotification.mockReturnValue({ mutateAsync: vi.fn() });
+    useMarkAllNotificationsRead.mockReturnValue({ mutateAsync: vi.fn() });
+  });
+
+  it("renders a TASK_ASSIGNMENT notification with a working deep-link to its task", () => {
+    useNotifications.mockReturnValue({
+      data: {
+        items: [buildNotification()],
+        total: 1,
+        unread_count: 1,
+        pending_ack_count: 0,
+      },
+      isLoading: false,
+      error: null,
+      refetch: vi.fn(),
+    });
+
+    render(withPageRefresh(<NotificationsPage />));
+
+    expect(screen.getByText("New task assigned")).toBeInTheDocument();
+
+    const taskLink = screen.getByRole("link", { name: /Task #11111111/i });
+    expect(taskLink).toHaveAttribute(
+      "href",
+      "/tasks/11111111-2222-3333-4444-555555555555",
+    );
+  });
+
+  it("renders each of the 5 coordination-event notification types with a distinguishing icon", () => {
+    const types = [
+      NotificationType.TASK_ASSIGNMENT,
+      NotificationType.BLOCKER_ESCALATION,
+      NotificationType.REVIEW_REQUEST,
+      NotificationType.DOCUMENTATION_REQUEST,
+      NotificationType.APPROVAL,
+    ];
+    const items = types.map((type, idx) =>
+      buildNotification({
+        id: `notif-${idx}`,
+        type,
+        subject: `Subject for ${type}`,
+        related_task_id: null,
+      }),
+    );
+
+    useNotifications.mockReturnValue({
+      data: { items, total: items.length, unread_count: 0, pending_ack_count: 0 },
+      isLoading: false,
+      error: null,
+      refetch: vi.fn(),
+    });
+
+    render(withPageRefresh(<NotificationsPage />));
+
+    for (const type of types) {
+      expect(screen.getByText(`Subject for ${type}`)).toBeInTheDocument();
+    }
+  });
+});

panel/src/app/(dashboard)/notifications/page.tsx

@@ -29,6 +29,7 @@ import {
   MailOpen,
   BookOpen,
   AtSign,
+  ShieldCheck,
 } from "lucide-react";
 import { formatDistanceToNow } from "date-fns";
 import { toast } from "sonner";
@@ -50,6 +51,9 @@ const typeIcons: Record<NotificationType, React.ReactNode> = {
   [NotificationType.DOCUMENTATION_REQUEST]: (
     <Info className="h-4 w-4 text-blue-500" />
   ),
+  [NotificationType.APPROVAL]: (
+    <ShieldCheck className="h-4 w-4 text-emerald-500" />
+  ),
   [NotificationType.ALERT]: (
     <AlertTriangle className="h-4 w-4 text-yellow-500" />
   ),

panel/src/types/index.ts

@@ -120,6 +120,7 @@ export enum NotificationType {
   BLOCKER_ESCALATION = "blocker_escalation",
   REVIEW_REQUEST = "review_request",
   DOCUMENTATION_REQUEST = "documentation_request",
+  APPROVAL = "approval", // Board-level approval requests (PO/HM/Main PM)
   ALERT = "alert",
   BROADCAST = "broadcast",
   KNOWLEDGE_SHARE = "knowledge_share", // Cross-agent learning notification