bug: WP_Agent_Package_Artifact_Hasher not found — fatal in AgentBundleArtifactHasher

[chubes4]

Symptom

Fatal error when the bundle artifact hasher runs — the global WP_Agent_Package_Artifact_Hasher class (from the vendored agents-api substrate) is not loaded at the point AgentBundleArtifactHasher references it.

Evidence (production debug.log, extrachill.com)

PHP Fatal error: Uncaught Error: Class "WP_Agent_Package_Artifact_Hasher" not found in /var/www/extrachill.com/wp-content/plugins/data-machine/inc/Engine/Bundle/AgentBundleArtifactHasher.php:24

Occurred 03-Jun-2026 (16:33, 16:34, 16:39 UTC). Tied to agent bundle operations (agent export).

Known context (from EC agent MEMORY)

• Data Machine now depends on automattic/agents-api (composer dev-main, vendored at vendor/automattic/agents-api/). The bundle/package primitives are now GLOBAL-namespace WP_Agent_* classes from that substrate.
• DM's inc/Engine/Bundle/* classes (e.g. AgentBundleArtifactHasher) are thin namespaced delegators to those WP_Agent_* globals.
• agents-api.php is loaded two ways: composer autoload_files AND an explicit require in data-machine.php line ~28 guarded by ! defined('AGENTS_API_LOADED'). It require_once's all Packages/ class files (hasher at line ~36).
• MEMORY explicitly notes: "agent export is ALSO fatally broken on main (WP_Agent_Package_Artifact_Hasher not found)" and that this blocks the planned private extrachill-event-bundles repo (full-fidelity event flow/pipeline bundles).

Likely root cause

A load-order / autoload race: AgentBundleArtifactHasher (namespaced, line 24) references the global WP_Agent_Package_Artifact_Hasher before agents-api's Packages/ class files have been required. Either:

• the AGENTS_API_LOADED guard short-circuits the explicit require when composer's autoload_files ran first but DIDN'T require the Packages/ files, or
• the hasher delegator is invoked during a code path that runs before data-machine.php's explicit agents-api bootstrap.

Investigation steps

1. Read inc/Engine/Bundle/AgentBundleArtifactHasher.php:24 and confirm exactly how it references the global class.
2. Read data-machine.php around line 28 (the AGENTS_API_LOADED-guarded require) and vendor/automattic/agents-api/agents-api.php — confirm whether the Packages/ class files are unconditionally required and whether the guard can skip them.
3. Check composer autoload_files — does it load agents-api.php in a way that defines AGENTS_API_LOADED WITHOUT requiring the Packages/ files? If so the explicit require is being short-circuited.
4. Determine the trigger code path (agent export / bundle hashing) and whether it can run before bootstrap.
5. Confirm whether this is fixed by ensuring the Packages/ class files are required when the hasher delegator loads (e.g. a class_exists guard + lazy require in the delegator).

Acceptance criteria

• agent export and any bundle-hashing path no longer fatals.
• WP_Agent_Package_Artifact_Hasher is guaranteed loaded before any delegator references it.
• Root cause documented (which load path was skipping the Packages/ requires).

Constraints

• Fix in a worktree + PR; never edit wp-content/plugins on prod directly.
• Conventional commits. Never edit CHANGELOG.md or hand-bump versions (homeboy owns both).
• Layer purity: the fix lives in DM's bundle layer or the agents-api bootstrap, not a higher layer.

[chubes4]

Root-cause fix opened in #2503. The agents-api bootstrap only loads its WP_Agent_* classes inside an AGENTS_API_LOADED-guarded block that early-returns; any path that defines the constant without completing the require block leaves the hasher class missing → bare 'Class not found' fatal. The PR makes the bundled-substrate top-up run unconditionally (idempotent require_once), closing the whole 'constant defined, classes missing' fatal class, with a smoke test reproducing this exact regression.