Feature: Emit task flow lifecycle hook events for plugin observability

Summary

Plugins currently have no way to observe task flow lifecycle transitions. The TaskFlowRegistryObserverEvent system exists internally but is not exposed through the hook system or the plugin SDK. This makes it impossible for plugins to implement custom metrics, logging, or side-effects based on task flow state changes (created, started, completed, failed, etc.).

Motivation

Plugin authors building observability integrations need visibility into the task flow lifecycle — specifically when flows are declared (created), started (transition to running), and completed (transition to succeeded/failed/cancelled). Custom tags/metadata per flow would enable rich dimensional metrics (e.g., by owner, goal, sync mode, step).

Today the only paths are:

• configureTaskFlowRegistryRuntime({ observers }) — internal to src/tasks/, not exported via the plugin SDK, and single-slot (replaces any existing observer).
• BoundTaskFlowRuntime — purely imperative CRUD; no callback/listener registration.
• internalDiagnostics.onEvent — gated to trusted bundled diagnostics exporters; unavailable to regular plugins.
• registerHook(...) — the hook system exists, but no task:flow:* events are emitted anywhere.

Proposal

Emit hook events from the task flow registry on lifecycle transitions so plugins can subscribe via registerHook():

New hook events

Plugin usage

ctx.registerHook(["task:flow:created", "task:flow:transition"], (event) => {
  if (event.name === "task:flow:transition" && event.payload.flow.status === "succeeded") {
    myMetrics.counter("task.flow.completed", {
      ownerKey: event.payload.flow.ownerKey,
      goal: event.payload.flow.goal,
      syncMode: event.payload.flow.syncMode,
      durationMs: (event.payload.flow.endedAt ?? Date.now()) - event.payload.flow.createdAt,
    });
  }
});

Implementation sketch

The existing emitFlowRegistryObserverEvent() call site in src/tasks/task-flow-registry.ts already fires on every mutation. The change would:

1. Import the hooks emitter into task-flow-registry.ts.
2. In the existing observer emit path, also emit the corresponding hook event:
   • On "upserted" with no previous → emit task:flow:created
   • On "upserted" where previous.status !== flow.status → emit task:flow:transition
   • On "deleted" → emit task:flow:deleted
3. Register the new event names in the hook type system.

No changes to TaskFlowRecord schema are needed. Plugins that want custom tags can use the existing stateJson field to carry tag metadata.

Bonus: diagnostic event bus bridge

Separately (or as part of this), the same lifecycle events could be bridged into DiagnosticEventPayload so the bundled OTel and Prometheus exporters automatically produce openclaw.task.flow.* metrics and spans. This would be additive — new DiagnosticTaskFlowCreatedEvent / DiagnosticTaskFlowTransitionEvent types in src/infra/diagnostic-events.ts.

Affected files