refactor: make handler_configs/handler_slugs single source of truth (#233)

[saraichinwag]

Summary

Eliminates duplication between singular (handler_slug/handler_config) and plural (handler_slugs/handler_configs) fields. Plural fields are now the only source of truth for flow step handler configuration.

The Problem

PRs #247-249 added handler_slugs and handler_configs for multi-handler support but kept writing to the singular fields too. This created two sources of truth, and updateHandler() only wrote to singular — so editing a handler on a multi-handler step left handler_configs stale.

The Fix

New utilities in FlowStepHelpers:

• normalizeHandlerFields() — converts legacy singular fields to plural format on read. Called whenever step config is loaded from DB.
• getPrimaryHandlerSlug() / getPrimaryHandlerConfig() — convenience getters that read from plural fields with legacy fallback.

All writes go to plural only:

• updateHandler() — writes to handler_configs[$slug] and handler_slugs, never handler_slug/handler_config
• addHandler() — normalizes first, writes plural only
• removeHandler() — normalizes first, writes plural only

Backward compatibility maintained:

• API responses (FlowFormatter) derive handler_slug and handler_config from plural fields for consumers that read singular
• Ability input schemas still accept singular for ergonomics (AI agents send singular when configuring one handler)
• Legacy DB data (only has singular fields) auto-migrated on read via normalization

Files Changed (16)

Core write path: FlowStepHelpers, UpdateFlowStepAbility
Abilities: ConfigureFlowStepsAbility, ValidateFlowStepsConfigAbility, FlowHelpers, ExecuteWorkflowAbility
API: FlowSteps REST, FlowFormatter, CreatePipeline chat tool
Engine: Step.php runtime, PipelineSystemPromptDirective, ImportExport
Display: SettingsDisplayService
Frontend: FlowStepCard.jsx, ModalManager.jsx
Tests: FlowAbilitiesTest fixtures

[saraichinwag]

Self-audit complete. Found and fixed 3 additional gaps the sub-agent missed:

• FlowsCommand.php extractHandlers() — was reading handler_slug from flow config, now reads handler_slugs with fallback
• FlowsCommand.php extractPrompt() — was reading handler_config['prompt'] from flow config, now reads from handler_configs via primary slug with fallback
• FlowsCommand.php handler step detection — was checking handler_slug, now checks handler_slugs with fallback
• ChatPipelinesDirective.php — was reading handler_slug from flow config, now reads handler_slugs with fallback

All remaining handler_slug/handler_config references are either:

• Inside normalization/getter methods (FlowStepHelpers)
• Ability INPUT parameters (not stored config)
• Handler identity operations (HandlerAbilities, Auth)
• Runtime tool definitions (tool_def, not flow config)
• Derived API response values (FlowFormatter)
• Legacy fallbacks after checking plural first (ToolExecutor, filterByHandlerSlug)

Total: 18 files changed, 268 additions, 107 deletions.