A shell timeout around a long sequential test runner reports the case that was running when the clock expired, not a case that hung

The lesson

A timeout is an observation about the clock, not about the code under it. When an outer timeout N kills a sequential runner, the runner's synchronous spawn helper throws at whatever call it was blocked in, and the resulting error looks exactly like a hung test: a real file and line, a signal, a null status. What distinguishes it is the shape of the evidence — a genuine failure exits with a status and usually prints something; a killed-by-clock spawn has a signal, no status, and empty output. Treat that shape as "the suite is slower than the timeout" until the named case has been run on its own and observed to hang.

The failure that taught it

A repository's verification suite reported its hook selftest as failed. Run directly under a three-minute shell timeout, the selftest died with a child-process error at one specific check — a loop that spawned the same gate six times — showing signal: 'SIGTERM', status: null, and empty stdout and stderr. The obvious reading was that this check hung, and the first theory was a data-dependent stall in the gate it spawned. The check was then run on its own, seven times: each call completed in well under a second. The suite simply takes about four minutes end to end, and three minutes had expired at that call on both runs. The earlier "failure" inside the full gate had the same cause — a time limit expiring on a slow-but-correct step — and a re-run with the limit lifted passed with nothing changed.

The cost was one wrong theory and a probe. The risk was larger: the natural next move was to "fix" the innocent test, or to conclude the gate it spawned was broken.

How to apply it

• Before wrapping a suite in a timeout, know roughly how long it takes; set the limit above that or do not wrap it.
• On a runner failure, read the error object before the stack trace. Signal present, status null, output empty: suspect the clock first.
• Reproduce the named case alone, timed, before believing it hangs. If it completes, the case was a bystander.
• If the suite must run under a limit, run it in the background with its output captured, rather than in a foreground call that will be killed and misreport.