feat(pipeline): unified EventHandler protocol (#245 layer 1B)

[miguelgfierro]

Completes layer 1 of the unification (#245) by collapsing `PipelineEventHandler` and `StatePipelineEventHandler` into a single `EventHandler` protocol. Stacked on top of #246 (the checkpoint/audit/resume PR) which is already merged into `issue-147-pipeline-evolution`.

What this lands

New: `EventHandler` protocol

One protocol that covers the full pipeline lifecycle across both modes:

```python
class EventHandler(Protocol):
async def on_pipeline_start(self, pipeline_name: str, run_id: str) -> None: ...
async def on_node_start(self, pipeline_name: str, run_id: str, node_id: str, visit: int) -> None: ...
async def on_node_complete(self, pipeline_name: str, run_id: str, node_id: str, latency_ms: float) -> None: ...
async def on_node_error(self, pipeline_name: str, run_id: str, node_id: str, error: str) -> None: ...
async def on_node_skip(self, pipeline_name: str, run_id: str, node_id: str, reason: str) -> None: ...
async def on_node_pause(self, pipeline_name: str, run_id: str, node_id: str, reason: str) -> None: ...
async def on_pipeline_complete(self, pipeline_name: str, run_id: str, success: bool, duration_ms: float) -> None: ...
```

Every callback carries `run_id` (for correlating across resumes and parallel runs) and `on_node_start` carries `visit` (re-entry counter — ready for cycles in a later layer).

Signature-inspection dispatch

`PipelineEngine._dispatch(method_name, **kwargs)` inspects each handler method's signature once (cached) and only passes parameters the method declares. This makes the unification non-breaking:

Handler type	Engine behavior
`EventHandler` (rich)	Receives all kwargs including `run_id`, `visit`.
Legacy `PipelineEventHandler`	Receives only `node_id`, `pipeline_name`, etc — engine drops `run_id`/`visit`.
Partial / mixed	Each method dispatches according to its own signature; missing methods are no-ops.

All engine event-emission paths now go through `_dispatch` — the previous direct `hasattr` + try/except scaffolding is gone.

Other engine changes

• `on_pipeline_start` is now emitted at `run()` start (previously state-side only).
• `_execute_node` accepts `run_id` so `on_node_start` callbacks can correlate.
• `_emit_node_result` refactored to use `_dispatch`.
• Handler exceptions are swallowed inside `_dispatch` — observability never breaks the pipeline.

Backward compatibility

`PipelineEventHandler` and `StatePipelineEventHandler` stay in place with docstrings marking them legacy. Existing implementations (port-based with 2-arg `on_node_start`, state-based with 4-arg, etc.) keep working without modification. New code should implement `EventHandler`.

Public exports

`EventHandler` is re-exported from `fireflyframework_agentic.pipeline`.

Tests

7 new tests in `tests/unit/pipeline/test_pipeline_engine_event_dispatch.py`:

• Unified handler receives `on_pipeline_start` with `run_id`
• Unified handler receives `visit` on `on_node_start`
• Unified handler receives `on_pipeline_complete` with `run_id`
• Legacy handler still works without `run_id` (dispatch drops it)
• Legacy handler without `on_pipeline_start` is fine (no-op)
• Mixed handler (some methods rich, some legacy) dispatches each correctly
• Handler exceptions don't break the pipeline

Existing `tests/unit/pipeline/test_event_handler.py` (which uses the legacy port-based shape) passes unchanged.

Full unit suite: 1551 passed, 21 warnings, 0 failures.

What's NOT in this PR

• Renaming or removing `PipelineEventHandler` / `StatePipelineEventHandler` aliases — that's the layer 8 cleanup.
• Adding a `DeprecationWarning` at import time — keeping noise low; docstring-only deprecation for now.
• Touching `StatePipeline`'s own `_emit` (still calls its handler directly; layer 7 will collapse it into the unified path).

Refs

• feat(pipeline): unify port-based and state-based pipelines into one DAG + engine #245 — unification design (layer 1B of 8)
• feat(pipeline): PipelineEngine checkpoint, audit, and resume (#245 layer 1) #246 — layer 1A (checkpoint + audit + resume) — already merged into base
• feat(pipeline): state-based PipelineBuilder — full #147 stack (phase 1+2+3a+3b+3c) #232 — umbrella PR carrying everything to main
• Mejorar pipelines / DAG de los agentes #147 — original pipeline evolution issue