feat(escalations): unify /escalate through HandoffManager

Replaces the legacy flowpilot_engine.escalate_session orchestration with
a single canonical path through HandoffManager. Every escalation now
creates a SessionHandoff row, fans out via the SSE bus, persists
AppNotification rows for the bell icon, dispatches to external channels
(Slack/Teams) via notify(), and emails per-user — regardless of whether
the call entered through /escalate (legacy URL) or /handoff (new URL).
The senior-pickup magic-moment screen now works end-to-end from the
EscalateModal bell-icon path the user just tested.

Backend
- HandoffCreateRequest gains optional target_user_id (the equivalent of
  the legacy escalated_to_id field). Self-targeting rejected.
- HandoffManager.create_handoff handles intent='escalate' end-to-end:
  sets escalation_reason + escalated_to_id, builds the legacy enhanced
  AI escalation_package (Sonnet, lazy-imported from flowpilot_engine,
  graceful fallback on failure), and merges handoff metadata into it.
  Eager-loads session.steps and session.user via selectinload — required
  by both the enhanced-package builder and notify() to avoid
  MissingGreenlet on async lazy access.
- HandoffManager.finalize_escalation generates SessionDocumentation,
  pushes documentation to PSA, and runs notify() — pre-commit so the
  AppNotification rows persist atomically with the handoff.
- HandoffManager.dispatch_escalation_notifications keeps only the
  fire-and-forget IO (bus publish, per-user emails) — runs post-commit.
  Pulls engineer name via a separate User query rather than relying on
  session.user lazy access.
- /handoff endpoint passes target_user_id through and calls
  finalize_escalation pre-commit.
- /escalate endpoint is now a thin shim: owner-only session lookup,
  HandoffManager.create_handoff(intent='escalate'), finalize_escalation,
  commit, dispatch_escalation_notifications, return SessionCloseResponse
  built from documentation + psa_result. flowpilot_engine.escalate_session
  is no longer called by any endpoint.
- pickup_session accepts both 'requesting_escalation' (legacy in-flight
  sessions) and 'escalated' (new canonical) so the migration is seamless
  for sessions already in the queue.
- Escalation queue list and sidebar count now match either status.

Frontend
- useFlowPilotSession optimistic update flips status to 'escalated'
  instead of 'requesting_escalation' so the page state matches the
  unified backend response.

Verified end-to-end live: a fresh /escalate call from the junior produces
status='escalated', a SessionHandoff row, a SessionDocumentation, PSA
push attempted (no_psa for this test session), AND a bell-icon
AppNotification for the team admin with link
/pilot/{session_id}?pickup=true. Backend test suite: 1103 passed.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

backend/app/api/endpoints/ai_sessions.py

@@ -452,6 +452,13 @@ async def resolve_session(
 
 
 # ── Escalate ──
+#
+# Thin shim over HandoffManager. The legacy `flowpilot_engine.escalate_session`
+# is no longer the source of truth — every escalation now creates a
+# SessionHandoff row, fans out via the SSE bus, dispatches AppNotification +
+# external channels via notify(), and emails per-user. EscalateModal and the
+# /handoff endpoint both funnel through here / through HandoffManager so the
+# senior-pickup magic-moment screen works regardless of entry point.
 
 @router.post("/{session_id}/escalate", response_model=SessionCloseResponse)
 @limiter.limit("15/minute")
@@ -463,21 +470,49 @@ async def escalate_session(
     db: Annotated[AsyncSession, Depends(get_db)],
     _: None = Depends(require_engineer_or_admin),
 ):
-    """Escalate a FlowPilot session to another engineer."""
+    """Escalate a FlowPilot session — unified through HandoffManager."""
+    from app.services.handoff_manager import HandoffManager
+
+    # Owner-only — matches the original constraint on flowpilot_engine.escalate_session.
+    session_result = await db.execute(
+        select(AISession).where(
+            AISession.id == session_id,
+            AISession.user_id == current_user.id,
+        )
+    )
+    session = session_result.scalar_one_or_none()
+    if not session:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Session not found"
+        )
+
+    manager = HandoffManager(db)
     try:
-        result = await flowpilot_engine.escalate_session(
+        handoff = await manager.create_handoff(
             session_id=session_id,
-            request=data,
+            intent="escalate",
+            engineer_notes=data.escalation_reason,
             user_id=current_user.id,
-            db=db,
+            priority="normal",
+            target_user_id=data.escalated_to_id,
         )
     except ValueError as e:
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
-    except PermissionError as e:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(e))
+
+    documentation, psa_result = await manager.finalize_escalation(
+        handoff, session, current_user.id
+    )
 
     await db.commit()
-    return result
+
+    await manager.dispatch_escalation_notifications(handoff)
+
+    return SessionCloseResponse(
+        session_id=session.id,
+        status=session.status,
+        documentation=documentation,
+        **psa_result,
+    )
 
 
 # ── Pause ──
@@ -644,7 +679,7 @@ async def get_escalation_queue(
         select(AISession)
         .where(
             scope_filter,
-            AISession.status == "requesting_escalation",
+            AISession.status.in_(("requesting_escalation", "escalated")),
         )
         .order_by(AISession.created_at.desc())
     )

backend/app/api/endpoints/session_handoffs.py

@@ -63,10 +63,16 @@ async def create_handoff(
             engineer_notes=body.engineer_notes,
             user_id=current_user.id,
             priority=body.priority,
+            target_user_id=body.target_user_id,
         )
     except ValueError as e:
         raise HTTPException(status_code=400, detail=str(e))
 
+    # For escalate: generate documentation + push to PSA before commit so
+    # the handoff and the PSA-state changes land atomically.
+    if handoff.intent == "escalate":
+        await manager.finalize_escalation(handoff, session, current_user.id)
+
     await db.commit()
 
     # Best-effort notification dispatch AFTER commit so we never email about

backend/app/api/endpoints/sidebar.py

@@ -161,7 +161,7 @@ async def get_sidebar_stats(
             select(func.count()).where(
                 and_(
                     esc_scope,
-                    AISession.status == "requesting_escalation",
+                    AISession.status.in_(("requesting_escalation", "escalated")),
                 )
             )
         )