queue:work --timeout has no effect when used with --once

[matthieu-mabillard]

Hello 👋,

Description

The documentation currently implies that the --timeout option on queue:work works globally for the queue worker. However, when combining --once with --timeout, the timeout restriction is silently ignored.

I understand the design choice, but we had to debug this exact issue in production today, and to save other developers time, this PR aims to clarify this behavior in the official documentation. Note that this specifically applies to running individual workers via --once, and we are not using queue:listen (which handles timeouts differently).

Technical Proof

This is because the logic for sending the SIGTERM comes from the registerTimeoutHandler method, which is called exclusively in daemon mode.

Proposed solution

Add a warning note in the queue documentation under the --timeout section to clarify this behavior.