[chubes4]

Fixes #572

What changed

Deletes the two one-release back-compat fallbacks that #567/#574 shipped for exactly one release (v0.12.1), per #572's "do this once" trigger (Automattic/intelligence#1082 merged and deployed; v0.12.1 shipped with the fallbacks present).

1. Dispatch (agents_run_workflow_dispatch())

Removed the wp_agent_workflow_handler first-callable-wins fallback and register_workflow_handler().

New unattributed-dispatch rule — applies when no runtime is identifiable (no explicit runtime input, no registered spec meta.runtime):

• exactly one runtime handler registered in wp_agent_workflow_runtime_handlers → dispatch to it
• zero registered → existing agents_run_workflow_no_handler WP_Error
• more than one registered → new agents_run_workflow_ambiguous_runtime WP_Error, listing the registered keys

An attributed runtime (explicit runtime input or spec meta.runtime) with no matching handler is no_handler — no fallback to any other registered handler, attributed or not.

agents_run_workflow_dispatch_failed still fires on every error path.

2. Step types

Removed the legacy wp_agent_workflow_known_step_types (validator) and wp_agent_workflow_step_handlers (runner constructor, runner default_step_handlers(), and register-reconcile-workflow-branch.php's agents_workflow_resolve_step_handlers()) filters. WP_Agent_Workflow_Step_Type_Registry is now the sole source for known step types and their handlers — no more filter layered on top. Caller-supplied constructor $step_handlers still merge on top of registry defaults (unchanged).

WP_Agent_Workflow_Spec_Validator::KNOWN_STEP_TYPES is also removed — confirmed via git grep that nothing in src/ read it (only a doc comment and the docs file referenced it).

3. Recorder — NOT touched (per #572, this is the scoped seam, not a fallback)

wp_agent_workflow_run_recorder( $recorder, $runtime, $run_id ) is unchanged. Only removed the BACK-COMPAT paragraph in agents_workflow_resolve_recorder()'s docblock, which documented that WordPress's own "only pass declared args" mechanic lets an old zero-argument hook keep resolving every run on the site — that mechanic isn't going away (it's not something agents-api's code implements or can delete), so the paragraph read as a stale promise to remove something that was never actually a code fallback. workflow-scoped-seams-smoke.php's "LEGACY BACK-COMPAT" recorder section still passes unchanged since the underlying behavior wasn't removed.

4. Docs

docs/channels-workflows-operations.md rewritten to the final (no back-compat) contract at all three back-compat call-outs (step-type filters/constant, dispatch fallback, recorder zero-arg note).

5. Tests

Migrated every test that exercised the deleted filters/helper to register_workflow_step_type() / register_workflow_runtime_handler():

• agents-workflow-ability-smoke.php — rewrote the dispatch section for the new unattributed rule (single/zero/two runtimes, explicit unknown runtime)
• workflow-scoped-seams-smoke.php — section 3 rewritten the same way; section 2 (recorder legacy zero-arg contract) untouched since that behavior is intentionally kept
• workflow-runner-smoke.php — throwing/custom_nested step types now registered via register_workflow_step_type(); the "unknown step type, no handler" scenario now constructs the WP_Agent_Workflow_Spec directly (bypassing the validator), since the unified registry makes "validates but has no handler" unreachable through normal registration
• workflow-spec-validator-smoke.php, workflow-await-smoke.php, workflow-cancel-fencing-smoke.php — same register_workflow_step_type() migration for their fixture step types
• workflow-step-type-registry-smoke.php — deleted the "Legacy two-filter registration still validates and runs" section entirely (it only asserted the deleted back-compat path)

BREAKING CHANGE

• wp_agent_workflow_handler filter and register_workflow_handler() are removed — register via register_workflow_runtime_handler( string $runtime, callable $handler ) instead.
• wp_agent_workflow_known_step_types and wp_agent_workflow_step_handlers filters are removed — register via WP_Agent_Workflow_Step_Type_Registry::register() or register_workflow_step_type() instead.
• WP_Agent_Workflow_Spec_Validator::KNOWN_STEP_TYPES is removed — use WP_Agent_Workflow_Step_Type_Registry::types().

Grep evidence

$ git grep -nE "wp_agent_workflow_handler'|register_workflow_handler|wp_agent_workflow_known_step_types|wp_agent_workflow_step_handlers" -- src docs tests
(no output — exit 1)

Verification

$ composer smoke
... 4803 assertions passed, 0 failed, exit 0

$ composer phpstan
[OK] No errors

⚠️ Merge gate

Do not merge until Automattic/intelligence#1085 is deployed. That PR migrates Intelligence's remaining zero-argument recorder claim / unscoped dispatch usage; merging this before it deploys removes the unattributed-dispatch fallback Intelligence currently relies on.

AI disclosure

AI assistance: Yes / Tool: OpenCode / Used for: implementation and tests.