fix: user opcode handlers under PHP 8.6's tail-call VM (macOS arm64)

[lisachenko]

What

Fixes #280 on z-engine's side: on PHP 8.6 builds using the new tail-call VM (ZEND_VM_KIND_TAILCALL — clang without global-register support, notably Apple Silicon macOS), user opcode handlers mis-resume execution inside the engine and corrupt the process. The diagnostics on this branch reduced it to a php-src bug (pure ext-ffi repro, no z-engine code — see the upstream-ready report on #280): the generated ZEND_USER_OPCODE_SPEC_TAILCALL_HANDLER returns the single-step dispatch result up the musttail chain and execute_ex() resumes it against its stale entry frame.

Until php-src resolves it, z-engine fails fast instead of corrupting the debuggee:

• Core::vmKind() — reports zend_vm_kind() through a dedicated one-symbol FFI binding (usable before init(), no generated-header changes), with VM_KIND_* constants mirroring Zend/zend_vm_opcodes.h
• OpCodeHook::install() throws OpCodeHookException::tailCallVmUnsupported() on VM_KIND_TAILCALL, naming the issue
• OpCodeHookVmKindGuardTest runs in every CI leg (deliberately not in the internal group — the existing opcode-hook tests are internal-only, which is why the macOS legs never caught this): on tail-call builds it asserts the refusal, elsewhere the unchanged install/uninstall lifecycle
• README/AGENTS document the platform caveat

Diagnostics kept as the upstream repro harness

tools/diagnostics/issue-280/ (probe ladder + pure-ffi-repro.php) and the now dispatch-only Diagnose issue 280 workflow stay in-tree: re-dispatching it against a newer PHP build answers "is the php-src bug fixed yet"; both go away with the guard once upstream resolves it.

Verification

• macOS arm64 (tail-call VM): full CI green with the guard test taking the refusal branch; the pure-FFI repro crashes there (vm_kind=5, SIGSEGV) proving the underlying bug is engine-level — run 33257997984
• macOS x64 / linux (hybrid VM): all probes and the repro pass; full suite, PHPStan level max, cs — green
• Probe evidence for the mechanism (stage-marked ladder, lldb, crash reports): run 33256998594

Downstream: lisachenko/zdebug#24 keeps its macOS arm64 + 8.6 leg experimental until upstream is fixed; with this guard, consumers get a clear OpCodeHookException instead of corrupted debuggees.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01U4cKi87mVQ896uSrw592fG

[lisachenko]

@claude Look for the relevant bug report for PHP at https://github.com/php/php-src/ (issues + PRs) and link it here if you will find anything relevant

[lisachenko]

Searched php/php-src issues and PRs (queries: zend_set_user_opcode_handler, ZEND_USER_OPCODE_DISPATCH, USER_OPCODE, "user opcode handler" + tailcall/tail-call, plus web search) — no existing report covers this bug. Nobody has filed the user-opcode-handler mis-resume under the tail-call VM yet, so the report drafted on #280 is still worth submitting upstream.

Closest related upstream items (same bug class — the tail-call VM returning a next-opline/tagged value that the caller mishandles — but all about vm_interrupt, not user opcode handlers):

• php/php-src#17849 — "Tail call VM" by arnaud-lb: the PR that introduced the tail-call VM (handlers return the next opline up the musttail chain), useful context and the right people to CC (arnaud-lb, morrisonlevi).
• php/php-src#21922 — "Fix tailcall helper dispatch after VM interrupt" (merged, PHP-8.5): ZEND_VM_DISPATCH_TO_HELPER() dereferenced an opline tagged with ZEND_VM_ENTER_BIT returned by a helper during an interrupt — precisely the same tagged/next-opline mishandled by the resuming code pattern our diagnosis found in ZEND_USER_OPCODE_SPEC_TAILCALL_HANDLER's ZEND_USER_OPCODE_DISPATCH path.
• php/php-src#22265 — "Fix another vm_interrupt bug for tailcall VM" (merged, PHP-8.5): a follow-up crash in the same area (missing SAVE_OPLINE before ZEND_VM_LOOP_INTERRUPT).

Those two merged fixes show the pattern is a known weak spot, which should make the upstream report easy to triage — it can reference them, the pure-FFI repro (tools/diagnostics/issue-280/pure-ffi-repro.php, no z-engine code involved), and the analysis in the #280 comment. I can't file it from this session (no access to php/php-src), so that comment is ready to copy-paste as the issue body.

---

Generated by Claude Code

[lisachenko]

let's recheck if php has fixed this or not?

[lisachenko]

Re-checked against the current php-src build (run 36771134832, dispatched on this branch): not fixed yet.

Tested: PHP 8.6.0-dev @ dc1145e (built Sep 29, 2026, NTS) on macos-latest / arm64 — vm_kind=5 (ZEND_VM_KIND_TAILCALL), and the failure signatures are byte-for-byte the ones from the original diagnosis:

• install-only passes; every mode that actually dispatches an opcode still corrupts the frame: the probe's next statement executes as the outer frame's cached call — Uncaught TypeError: unlink(): Argument #2 ($context) must be of type resource or null, string given at probe.php:17 (exit 255) in noop/log-const/globals/use-ref/diag
• add-baseline: SIGSEGV right after STAGE payload-first-statement (exit 139)
• pure-FFI repro (no z-engine): vm_kind=5 then SIGSEGV, EXC_BAD_ACCESS / KERN_INVALID_ADDRESS at 0xffffffffffffffe8 (exit 139)

I also checked the php-src side directly: no commit touching ZEND_USER_OPCODE/tailcall dispatch has landed on the PHP-8.6 branch since the diagnosis (the recent zend_vm_execute.h changes are unrelated — GH-23980 include/eval assert and 8.4/8.5 merges), and there's still no upstream issue covering this — only the merged vm_interrupt fixes in the same area (php/php-src#21922, php/php-src#22265). So the upstream-ready report on #280 remains unfiled and worth submitting.

(The macos-15-intel control leg was still compiling PHP from source when I read the results; it's only the hybrid-VM control and doesn't affect the verdict. Re-dispatching this workflow stays the way to re-test future builds.)

---

Generated by Claude Code

[lisachenko]

The Probes (x64) failure on the re-dispatched diagnostics run is not a diagnostic signal — it's setup-php infrastructure: on macos-15-intel the Set up PHP step gives up after ~25 minutes with "Could not setup PHP 8.6" (no 8.6 build currently available for Intel macOS there), reproducibly on both attempts of run 36771134832. The probes never ran against 8.6 on that leg; the always() repro step fell through to the runner's stock PHP 8.5.9 (vm_kind=1, prints OK — the expected control result). The arm64 verdict above is unaffected.

Pushed d88d693 marking the x64 leg continue-on-error in the dispatch-only Diagnose issue 280 workflow: it's only the hybrid-VM control, and a control leg that can't obtain PHP shouldn't paint the run (and this PR) red. It starts failing loudly again the moment it gets a real 8.6 result to report — and can be flipped back to required once setup-php ships 8.6 for Intel macOS.

---

Generated by Claude Code

[lisachenko]

Recovery complete — CI on 0b80ea6 is green everywhere except two upstream-dependent groups (details below). What happened and what was pushed:

php-src's 8.6 branch moved under this branch in two ways today, and PHPStan released 2.2.16 (no lockfile, so CI resolves fresh):

• 837c2b6 — PHPStan 2.2.16 now infers empty new ArrayObject() as ArrayObject<*NEVER*, *NEVER*>; typed the log container in ErrorCallbackHookTest and replaced the inline @var with a real assertNotNull() narrowing.
• 542d13a / f8cd6bf — PHP 8.6 grew four zend_executor_globals vm_stack page-cache fields (API 20250926→20260924), so the committed 8.6 headers were stale. Refreshed linux from the generator's own CI diff (docker unavailable in my environment; the check re-derives and confirms) and darwin arm64 from the artifacts the dispatched Generate darwin headers run produced — its commit job was skipped because the Intel legs can't obtain PHP 8.6, so the arm64 artifacts were committed directly.
• 0b80ea6 — phpstan.dist.neon phpVersion 80500→80600, resolving the in-tree TODO (2.2.16 accepts it; level max clean).
• d88d693 — the dispatch-only diagnose-280 workflow's x64 control leg no longer fails the run while setup-php lacks Intel 8.6.

Remaining red, both outside this PR's control:

1. Tests (macOS x64, nts/zts) + Generated darwin headers up to date (x64, nts/zts) — setup-php currently has no PHP 8.6 build for macos-15-intel (every attempt dies after ~27 min with "Could not setup PHP 8.6"). Clears when setup-php ships Intel 8.6 builds again.
2. Generated headers up to date (linux) — a moving-target race: this check compiles php-src from source at check time, and 8.6 HEAD gained the NTS/ZTS module-ABI unification fields (max_execution_timer_timer/pid/oldact, copied_functions_count, globals_ptr→globals_id_ptr) between today's 21:12 and 22:17 check runs. The committed headers deliberately match setup-php's dc1145e build — the PHP the test legs actually run — because regenerating to HEAD would instead trip the test legs' ZENGINE_STRICT_LAYOUT_CHECK. Once setup-php picks up a build with the new ABI, one composer gen-headers / darwin-workflow rerun re-syncs everything.

If you'd like, these two groups can be made non-blocking (same continue-on-error treatment as the diagnose workflow) while upstream catches up — your call as it changes what the CI matrix enforces.

---

Generated by Claude Code

[lisachenko]

Reported the bug to PHP itself: php/php-src#24081

[lisachenko]

Should be resolved once php/php-src#24109 will be merged into the main branches