[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>

tests/unit/services/test_notification.py

@@ -412,4 +412,108 @@ async def test_create_notification_requires_ack_derives_from_type(
     assert (
         rows[0].requires_ack is ACK_REQUIRED_BY_TYPE[NotificationType.KNOWLEDGE_SHARE]
     )
-    assert rows[0].requires_ack is False
+
+
+# ---------------------------------------------------------------------------
+# Coordination-event producers (reassignment / collision / unblock /
+# dependency-revival / stale-claim-reaped)
+# ---------------------------------------------------------------------------
+
+# previous_assignee + new_assignee + ceo, resolved to UUIDs pre-insert.
+_REASSIGN_RECIPIENT_COUNT = 3
+# {task-owner, ceo} for the other four coordination producers.
+_TWO_RECIPIENT_COUNT = 2
+
+
+@pytest.mark.asyncio
+async def test_send_reassignment_notification(svc: NotificationService) -> None:
+    aid = uuid4()
+    db = _FakeDb(agent_uuid=aid)
+    with _patch_db_context(db):
+        await svc.send_reassignment_notification(
+            task_id="t1", previous_assignee="be-dev-1", new_assignee="be-dev-2"
+        )
+    rows = [r for r in db.added if r.related_task_id == "t1"]
+    assert rows
+    assert all(len(r.to_agents) == _REASSIGN_RECIPIENT_COUNT for r in rows)
+    assert any("reassigned" in r.subject for r in rows)
+
+
+@pytest.mark.asyncio
+async def test_send_reassignment_notification_no_recipients_is_noop(
+    svc: NotificationService,
+) -> None:
+    """All three recipients falsy ⇒ nothing is created (no crash)."""
+    db = _FakeDb()
+    with _patch_db_context(db):
+        await svc.send_reassignment_notification(
+            task_id="t1",
+            previous_assignee=None,
+            new_assignee=None,
+            to_ceo="",
+        )
+    assert db.added == []
+
+
+@pytest.mark.asyncio
+async def test_send_collision_sequencing_notification(
+    svc: NotificationService,
+) -> None:
+    aid = uuid4()
+    db = _FakeDb(agent_uuid=aid)
+    with _patch_db_context(db):
+        await svc.send_collision_sequencing_notification(
+            held_back_task_id="t2",
+            blocking_task_id="t1",
+            held_back_assignee="be-dev-1",
+        )
+    rows = [r for r in db.added if r.related_task_id == "t2"]
+    assert rows
+    assert all(len(r.to_agents) == _TWO_RECIPIENT_COUNT for r in rows)
+    assert any("sequenced behind" in r.subject for r in rows)
+
+
+@pytest.mark.asyncio
+async def test_send_unblock_notification(svc: NotificationService) -> None:
+    aid = uuid4()
+    db = _FakeDb(agent_uuid=aid)
+    with _patch_db_context(db):
+        await svc.send_unblock_notification(task_id="t1", restored_owner="be-dev-1")
+    rows = [r for r in db.added if r.related_task_id == "t1"]
+    assert rows
+    assert all(len(r.to_agents) == _TWO_RECIPIENT_COUNT for r in rows)
+    assert any("unblocked" in r.subject for r in rows)
+
+
+@pytest.mark.asyncio
+async def test_send_dependency_revival_notification(
+    svc: NotificationService,
+) -> None:
+    aid = uuid4()
+    db = _FakeDb(agent_uuid=aid)
+    with _patch_db_context(db):
+        await svc.send_dependency_revival_notification(
+            task_id="t1", assignee="be-dev-1", completed_dependency_id="dep1"
+        )
+    rows = [r for r in db.added if r.related_task_id == "t1"]
+    assert rows
+    assert all(len(r.to_agents) == _TWO_RECIPIENT_COUNT for r in rows)
+    assert any("revived" in r.subject for r in rows)
+    assert any("dep1" in r.body for r in rows)
+
+
+@pytest.mark.asyncio
+async def test_send_stale_claim_reaped_notification(
+    svc: NotificationService,
+) -> None:
+    aid = uuid4()
+    db = _FakeDb(agent_uuid=aid)
+    with _patch_db_context(db):
+        await svc.send_stale_claim_reaped_notification(
+            task_id="t1", reaped_agent="be-dev-1", last_heartbeat="2026-07-11T00:00:00"
+        )
+    rows = [r for r in db.added if r.related_task_id == "t1"]
+    assert rows
+    assert all(len(r.to_agents) == _TWO_RECIPIENT_COUNT for r in rows)
+    assert any(r.priority == NotificationPriority.HIGH for r in rows)
+    assert any("stale claim reaped" in r.subject for r in rows)

tests/unit/services/test_task.py

@@ -461,6 +461,93 @@ async def test_reassign_returns_none_when_task_missing() -> None:
     assert out is None
 
 
+@pytest.mark.asyncio
+async def test_reassign_notifies_once_not_twice_for_same_target() -> None:
+    """Repeated reassign to the SAME target must not double-fire.
+
+    `reassign` runs every time it's called (even a no-op redirect); the
+    coordination notification is guarded separately by comparing the new
+    assignee against the assignee captured before the mutation, so a second
+    call with an already-current target must skip the notification.
+    """
+    task = _build_task(assigned_to=None, claimed_by=None)
+    svc = TaskService(MagicMock(flush=AsyncMock()))
+    _bind(svc, "get", AsyncMock(return_value=task))
+    new_assignee = uuid4()
+    mock_ns = MagicMock()
+    mock_ns.send_reassignment_notification = AsyncMock()
+    with patch(
+        "roboco.services.notification.NotificationService", return_value=mock_ns
+    ):
+        await svc.reassign(task.id, new_assignee)
+        await svc.reassign(task.id, new_assignee)
+    mock_ns.send_reassignment_notification.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_unblock_notifies_once_not_twice_on_repeated_call() -> None:
+    """Repeated unblock() against the same task must not double-fire.
+
+    `unblock` only mutates + notifies a task whose status is currently
+    BLOCKED; the first call flips it to IN_PROGRESS/PENDING, so a second
+    call against the same task_id short-circuits on the status guard and
+    must not send a second notification.
+    """
+    raiser = uuid4()
+    task = _build_task(
+        status=TaskStatus.BLOCKED, branch_name=None, blocker_raised_by=raiser
+    )
+    svc = TaskService(MagicMock(flush=AsyncMock()))
+    _bind(svc, "get", AsyncMock(return_value=task))
+    _bind(svc, "_index_lifecycle_event_background", AsyncMock())
+    mock_ns = MagicMock()
+    mock_ns.send_unblock_notification = AsyncMock()
+    with patch(
+        "roboco.services.notification.NotificationService", return_value=mock_ns
+    ):
+        first = await svc.unblock(task.id)
+        second = await svc.unblock(task.id)
+    assert first is task
+    assert second is None
+    mock_ns.send_unblock_notification.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_wire_sibling_collision_dag_notifies_only_for_new_edges() -> None:
+    """Collision-sequencing notification fires only for freshly-added edges.
+
+    `add_dependency` returns True only on a new edge; a subsequent wiring
+    pass over the same pair returns False and must skip the notification,
+    so the coordination ALERT cannot double-fire.
+    """
+    parent_id = uuid4()
+    held_back_id = uuid4()
+    blocking_id = uuid4()
+    held_back = _build_task(id=held_back_id, assigned_to=uuid4())
+    blocking = _build_task(id=blocking_id)
+    svc = TaskService(MagicMock(flush=AsyncMock()))
+    _bind(svc, "get_subtasks", AsyncMock(return_value=[held_back, blocking]))
+    add_dep_mock = AsyncMock(side_effect=[True, False])
+    _bind(svc, "add_dependency", add_dep_mock)
+    mock_ns = MagicMock()
+    mock_ns.send_collision_sequencing_notification = AsyncMock()
+    wiring_passes = 2
+    with (
+        patch(
+            "roboco.services.sequencing.dev_task_collision_edges",
+            return_value=[(blocking_id, held_back_id)],
+        ),
+        patch(
+            "roboco.services.notification.NotificationService",
+            return_value=mock_ns,
+        ),
+    ):
+        for _ in range(wiring_passes):
+            await svc.wire_sibling_collision_dag(parent_id)
+    mock_ns.send_collision_sequencing_notification.assert_awaited_once()
+    assert add_dep_mock.await_count == wiring_passes
+
+
 @pytest.mark.asyncio
 async def test_mark_agent_idle_sets_status_idle() -> None:
     agent = MagicMock(id=uuid4(), status=AgentStatus.ACTIVE)