ci: test ZDebug on the PHP 8.6 beta via z-engine 8.6.x-dev

[lisachenko]

What

z-engine's master supports PHP 8.6 (branch-aliased 8.6.x-dev, with linux and darwin x64/arm64 definitions committed — lisachenko/z-engine#58, lisachenko/z-engine#278), so ZDebug is tested on the 8.6 beta the same way it rides the 8.4 and 8.5 lines.

• composer.json — z-engine constraint widened to 8.4.x-dev || 8.5.x-dev || 8.6.x-dev. The platform php requirement of each z-engine line still makes Composer resolve the matching branch per running PHP minor (verified with dry runs on 8.4 and 8.5 — they keep picking 8.4.x-dev / 8.5.x-dev).
• CI — PHP 8.6 legs added to the tests matrix on ubuntu-latest, macos-latest (arm64) and macos-15-intel (x64), and to the PHPStan matrix. All legs required — no experimental escapes.
• docs — README badge/requirements and AGENTS.md branch model extended to 8.4 / 8.5 / 8.6 (beta).

History: the macOS arm64 + PHP 8.6 corruption

The first arm64+8.6 runs crashed every instrumented debuggee: Apple Silicon clang builds of PHP 8.6 selected the new tail-call VM (ZEND_VM_KIND_TAILCALL), under which user opcode handlers mis-resumed execution (reproduced with pure ext-ffi code, no zdebug/z-engine involved). Diagnosed in lisachenko/z-engine#280, filed upstream as php/php-src#24081, fixed by php/php-src#24109 (merged into PHP-8.6). The leg ran as continue-on-error during the ~6 weeks the bug was live and is required again since the fix.

Verification

Local (PHP 8.6 NTS linux-x64, z-engine 8.6.x-dev):

• composer test — OK, 291 tests, 1916 assertions
• composer test:integration (--fail-on-skipped) — OK, 41 tests, 782 assertions, none skipped
• composer phpstan (level max) — no errors
• composer cs:check — clean

CI: full matrix across ubuntu / macOS x64 / macOS arm64 on 8.4, 8.5 and 8.6.

[lisachenko]

Root cause of the Tests (PHP 8.6, macos-latest) failure — upstream, not this PR's. The first run failed only on macOS arm64 + 8.6 (Ubuntu, macOS x64 and PHPStan were green on the same PHP build). A temporary layered diagnostic job (commits db23e9c/a1e7404, removed again in d8ec2f3) isolated it to z-engine itself, with no zdebug code involved:

• Core::init() alone ✅, COMPILE_EXTENDED_STMT alone ✅
• adding a bare OpCode::setHandler(EXT_STMT, …) ❌ — the handler closure's own by-ref counter reads back as a ZEngine\Core object on the first dispatch (Cannot increment ZEngine\Core), and a full zdebug boot segfaults in ZEND_DO_UCALL_SPEC_RETVAL_USED_TAILCALL_HANDLER (KERN_INVALID_ADDRESS at 0x10)
• the identical probes on PHP 8.5 on the same arm64 runner all pass

The TAILCALL handler names are the tell: Apple Silicon clang builds of PHP 8.6 select the new tail-call VM (ZEND_VM_KIND_TAILCALL, new in 8.6), while x64 clang and gcc keep the hybrid VM — which is exactly the failing-platform boundary. Filed upstream with a minimal repro as lisachenko/z-engine#280.

Since no fix exists yet, this PR now runs the arm64+8.6 leg as continue-on-error: true with a comment pointing at #280 (so it stays visible and flips back to required once upstream is fixed), and README/AGENTS note the platform exception. Everything else — linux-x64 and macOS x64 on 8.6, plus the full 8.4/8.5 matrix — is green and required.

---

Generated by Claude Code

[lisachenko]

Cleanup verification on ec393d2: 12 of 13 legs are green. The one red leg — Tests (PHP 8.6, macos-15-intel) — is not a zdebug regression:

• setup-php's current intel 8.6 nightly is php-src eefe4db (built Oct 8), which predates the upstream fix Zend: user opcode DISPATCH runs on a stale frame in the TAILCALL VM. php/php-src#24109 (merged into PHP-8.6 on Oct 9).
• That intel build selects the tail-call VM (vm_kind=5), unlike the arm64 build of the same commit, which came out as the CALL VM — that's why the arm64 and ubuntu 8.6 legs pass while intel fails with the User opcode handlers corrupt VM state under PHP 8.6's tail-call VM (macOS arm64) z-engine#280 corruption signatures (wrong-scope calls, debuggee SIGSEGV mid-session).
• Independently confirmed: z-engine's diagnostics ran this morning on the same intel build and segfaulted at the first-statement probe (EXC_BAD_ACCESS, KERN_INVALID_ADDRESS) — the exact #280 reproduction, now on x64.

No code change needed here. The leg will go green once setup-php ships an intel 8.6 nightly built from PHP-8.6 at or after Oct 9; I'll re-run it then. Upside: that run will be the first real binary validation of the upstream fix under an actually-selected TAILCALL VM.

---

Generated by Claude Code