M4.4 — Lifespan integration

[zestones]

Note

Milestone: M4 — Sentinel + Investigator
Planning doc: docs/planning/M4-sentinel-investigator/issues.md

Scope. Modifier backend/main.py lifespan pour :

• Démarrer sentinel_task au startup
• L'annuler au shutdown
• Logger les exceptions du sentinel_loop sans laisser la task mourir silencieusement
  (wrapper try/except avec re-raise contrôlé)

Acceptance.

• docker compose up → log "Sentinel started" visible
• docker compose down → log "Sentinel cancelled"

---

[zestones]

Audit follow-up — implementation context

From docs/audits/M4-M5-issue-context-pass.md §2.4 and M4-M5-sentinel-investigator-workorder-qa-audit.md §5 (M4.4).

Drifts from main

• Current backend/main.py:34-43 wraps mcp_http_app.lifespan(mcp_http_app). Sentinel calls MCPClient which connects to http://localhost:8000/mcp/ (loopback) — Sentinel must start inside the MCP lifespan wrapper, not outside it.
• Issue body is very thin. Context below makes it implementable cold.

Exact placement in backend/main.py

@asynccontextmanager
async def lifespan(app: FastAPI):
    await db.connect()
    app.state.db = db
    log.info("ARIA backend ready")
    async with mcp_http_app.lifespan(mcp_http_app):
        log.info("MCP server ready at /mcp")
        from agents.sentinel import sentinel_loop
        sentinel_task = asyncio.create_task(sentinel_loop(), name="sentinel")
        log.info("Sentinel started")
        try:
            yield
        finally:
            sentinel_task.cancel()
            try:
                await sentinel_task
            except asyncio.CancelledError:
                pass
            log.info("Sentinel cancelled")
            await db.disconnect()

Warning

If Sentinel starts outside the mcp_http_app.lifespan wrapper, its first mcp_client.call_tool() hits a 404 because the MCP HTTP app has not yet been mounted.

Investigator is NOT started here

run_investigator is spawned per-anomaly by Sentinel via asyncio.create_task(...). Do not start it from lifespan.

Cross-references

• Upstream: M2.1 — FastMCP server + mount #8 (M2.1 MCP mount), M4.2 — Sentinel asyncio loop #24 (M4.2 loop body)
• Blocks: nothing (last M4 backend infra issue)

[zestones]

Cross-ref from M4.1 (#23) — current_turn_id ContextVar contract

Note

M4.1 added core.ws_manager.current_turn_id: ContextVar[str | None]. The orchestrator (this issue / M4.4 lifespan) is the only place that should set() it. Agents downstream just call ws_manager.broadcast(...) and the field is auto-injected.

Contract

from contextvars import ContextVar
import uuid
from core.ws_manager import current_turn_id, ws_manager

# Per agentic turn, in the orchestrator's entry point (chat WS handler /
# Sentinel-triggered Investigator turn / etc.):
turn_id = uuid.uuid4().hex
token = current_turn_id.set(turn_id)
try:
    await ws_manager.broadcast("agent_start", {"agent": agent_name, "turn_id": turn_id})
    # ... agent loop. Any nested ws_manager.broadcast() inside this scope
    # picks up the ContextVar automatically — agents do not need to know
    # about turn_id ...
    await ws_manager.broadcast("agent_end", {"agent": agent_name, "finish_reason": "stop"})
finally:
    current_turn_id.reset(token)

Why ContextVar (not a kwarg)

• Asyncio-safe: each task has its own copy, so two parallel turns do not bleed.
• Agents stay oblivious: kb_builder, investigator, qa, wo_gen only need to await ws_manager.broadcast(event_type, payload).
• Callers that explicitly pass turn_id in the payload win over the ContextVar (test test_broadcast_explicit_turn_id_is_preserved).

What is NOT in the orchestrator's job

• Sentinel anomalies are not part of an agent turn — leave the ContextVar unset for those, turn_id will simply be omitted from the frame. See cross-ref on M4.2 — Sentinel asyncio loop #24.
• The 5-phase KB upload broadcasts (M3.6 — UI tools pour KB Builder onboarding #22) currently fire outside any turn (they are HTTP-driven). Once the chat-driven onboarding flow exists, wrap each submit_onboarding_message call in a turn scope.

Lifespan touchpoints

• No new app.state entry needed — ws_manager is a module-level singleton.
• No teardown either — sockets are GC'd on disconnect via WSManager.disconnect().