Integrate ergebnis/phpunit-agent-reporter into agent-aware PHPUnit runs

[coisa]

Problem

Agent-driven runs of dev-tools tests still consume too much context from the default PHPUnit output stream. Even small failures can produce long terminal payloads with repeated progress, summary, and diagnostic lines, forcing agents to spend unnecessary context just to understand what failed.

This is especially visible in interactive agent sessions and agent-triggered workflows where the goal is to extract actionable PHPUnit results with minimal noise. The broader structured-output direction is already tracked in #248, but PHPUnit has a package-built path that can improve this problem sooner.

Proposal

Integrate ergebnis/phpunit-agent-reporter into the PHPUnit execution path used by DevTools so agent contexts can consume compact, agent-oriented PHPUnit output instead of the default verbose stream.

The integration should reuse DevTools runtime-environment detection so the reporter is enabled only when appropriate, while preserving the current human-readable PHPUnit behavior for regular CLI and CI usage.

Goals

• Reduce context consumption for agent-driven PHPUnit runs.
• Preserve the current PHPUnit output contract for maintainers running the command manually.
• Keep the tests command deterministic across agent and non-agent execution contexts.

Expected Behavior

When dev-tools tests runs in a detected agent environment, PHPUnit uses ergebnis/phpunit-agent-reporter (or an equivalent supported integration path) so failures, counts, and summaries are emitted in a compact format that is easier for agents to consume.

When the same command runs in a normal terminal or standard CI context, DevTools preserves the current PHPUnit output behavior unless an explicit opt-in mode is introduced.

Implementation Strategy

• Evaluate the supported integration path for ergebnis/phpunit-agent-reporter in the currently supported PHPUnit version range.
• Isolate the decision of whether agent reporting is enabled behind runtime-environment aware collaborators instead of inlining package-specific checks into the command flow.
• Keep TestsCommand focused on orchestration while delegating agent-reporter resolution/configuration to a dedicated collaborator if the logic becomes non-trivial.
• Verify compatibility with coverage, cache, bootstrap, filter, progress, and output-mode behavior already supported by the tests command.
• Treat this as a focused follow-up to Support colored pretty JSON and structured tool result payloads #248 rather than a redesign of all structured tool output.

Requirements

• Agent-detected PHPUnit runs MUST integrate ergebnis/phpunit-agent-reporter through a supported path for the active PHPUnit version.
• Non-agent PHPUnit runs MUST preserve the current default output behavior unless a separate explicit opt-in mode is intentionally introduced.
• Existing tests command features such as coverage, cache, bootstrap, filter, and exit-code handling MUST remain compatible.
• The integration MUST work for direct tests command usage and for workflows that execute PHPUnit through DevTools.
• Focused tests MUST cover agent and non-agent execution paths.
• Command documentation SHOULD explain when agent reporting is active and what behavior remains unchanged.

Non-goals

• Do not redesign all DevTools JSON or tool-result payloads in this issue; broader structured-output work remains in Support colored pretty JSON and structured tool result payloads #248.
• Do not expand this issue to Rector, ECS, phpDocumentor, PhpMetrics, or other non-PHPUnit tools.
• Do not change human-readable PHPUnit output for normal terminal usage unless that behavior is explicitly guarded and documented.

Benefits

This gives agent-driven PHPUnit runs a smaller and more actionable output surface, reduces wasted context in interactive and automated agent sessions, and delivers a focused improvement without waiting for the full structured-output initiative in #248.

Acceptance Criteria

Functional Criteria

• Agent-detected PHPUnit runs use ergebnis/phpunit-agent-reporter or an equivalent supported integration path.
• Non-agent PHPUnit runs preserve the current default PHPUnit output behavior.
• Coverage, cache, bootstrap, filter, progress, and exit-code behavior remain compatible with the current tests command.
• Focused tests cover agent and non-agent execution paths.
• Documentation is updated when command behavior or runtime expectations become user-visible.

Architectural / Isolation Criteria

• MUST: The core logic MUST be isolated into dedicated classes or services instead of living inside command or controller entrypoints.
• MUST: Responsibilities MUST be separated across input resolution, domain logic, processing or transformation, and output rendering when the change is non-trivial.
• MUST: The command or controller layer MUST act only as an orchestrator.
• MUST: The implementation MUST avoid tight coupling between core behavior and CLI or framework-specific I/O.
• MUST: The design MUST allow future extraction or reuse with minimal changes.
• MUST: The solution MUST remain extensible without requiring major refactoring for adjacent use cases.
• MUST: Argument and option resolution MUST be validated separately from command execution logic.
• MUST: Console formatting and rendering MUST stay separate from domain processing.
• MUST: Exit behavior, error messaging, and generated output MUST remain deterministic and testable.