Concurrent parallel branch fan-out + terminal-completion hook

[chubes4]

What

Make parallel workflow fan-out complete-able and concurrent as a property of the substrate, so every consumer (Site Forge, wp-codebox, Data Machine) gets it for free instead of hand-rolling it.

Two changes:

1. Terminal-completion hook. do_action( 'wp_agent_workflow_run_completed', $result, $run_id ) fires at the single terminal funnel in the runner's step loop — whether a run completes straight through (run()) or via an async resume after its parallel branches reconcile (resume()). This lets an async consumer finalize on completion WITHOUT block-polling the recorder: dispatch a fan-out, return from the worker immediately (releasing the AS claim), and finalize from the hook — instead of holding a claim while waiting on the very branches it dispatched (which self-deadlocks a cooperative queue).

2. Concurrent branch execution on Action Scheduler. The branch executor enqueued N branches but left them to drain through AS's default runner (one batch of 25 in one worker), so a fan-out's branches ran serially in one PHP process. Now:

   • dispatch() triggers the async queue runner itself after enqueuing, opening N loopback connections concurrently (Requests::request_multiple / curl_multi) so N distinct workers each claim one branch. Bounded by MAX_BRANCH_CONCURRENCY (8); serial fallback where the parallel Requests API is absent.
   • A loopback dispatch-URL rewrite points the trigger at 127.0.0.1 (real host in a Host header) — curl_multi bypasses WordPress's http_api_curl hook, so a .local custom domain would otherwise pay a ~5s multicast-DNS timeout per handle and serialize the concurrent handles.
   • A persistent AS concurrency policy: concurrent_batches raised to the pending branch count (capped), batch_size pinned to 1, only while this executor's own branches are pending (gated live on pending_branch_count() over BRANCH_HOOK). Together they turn N running workers into N distinct branches.

Not a bypass of Action Scheduler

Branches stay ordinary AS actions — enqueued, claimed, run, and reconciled through AS. This only triggers AS's async runner concurrently and tunes AS's own concurrency filters.

Blast radius

The concurrency filters are process-global (AS has no per-group knob), but both gate on this executor's pending branches: with none pending they pass their incoming value through unchanged, so other Action Scheduler workloads keep stock behavior (concurrent=1, batch=25). The concurrent_batches raise only ever raises (max of incoming and target), never lowers another plugin's ceiling.

Verification

Verified on a live native-PHP runtime backed by MySQL: a multi-page Site Forge fan-out completes end to end, the policy resolves correctly (idle concurrent=1 batch=25; with N branches pending concurrent=min(N,8) batch=1), and branches run under the shared substrate with the consumer holding no concurrency code of its own. The change is backend-agnostic — it functions on any Action Scheduler store; concurrent claims are simply more effective on MySQL's FOR UPDATE SKIP LOCKED than on SQLite's single-writer model.

AI assistance

• AI assistance: Yes
• Tool(s): Claude Opus 4.8 via Claude Code
• Used for: Diagnosing the serial-drain and self-deadlock root causes from source and live runtime behavior, implementing the completion hook and the concurrency substrate, and verifying end to end.