test(protocols): bound the #1428 deadline test so a lost alarm cannot hang the worker (#1889)

[JarryShaw]

Please follow the guide below

• You will be asked some questions, please read them carefully and answer honestly

• Put an x into all the boxes [ ] relevant to your pull request (like that [x])

• Use Preview tab to see how your pull request will actually look like

• Searched for similar pull requests

• Followed the coding style (make pylint, make mypy, make isort)

• make test passes, and a test case covers the change. Narrow runs only, listed below.

• Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible: N/A — centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

What is the purpose of your pull request?

Tick the commit type your subject line carries.

• fix — corrects a defect
• feat — adds a feature
• perf — changes performance, not behaviour
• refactor — changes neither behaviour nor performance
• test — tests only
• docs — documentation only
• ci — workflows or build tooling
• release — bumps the version or rolls up a distribution
• chore — anything else

---

What happened on #1882's job 117297215943. The #1428 deadline test spun until pytest-timeout's 900s backstop ended the xdist worker. The traceback was lost because an xdist worker's stdout is /dev/null. Another test that waits on the tier-guard lock took 882s on the same job, so the spin held that lock the whole time.

Why the alarm can be lost (reproduced locally, not proven on CI). The generator's deadline is a one-shot SIGALRM. If its single TimeoutError is swallowed, nothing fires again. Two things swallow it:

• a finaliser, which routes the raise to sys.unraisablehook, for example after a long garbage collection;
• an except OSError, because TimeoutError is an OSError. Extractor.__del__ catches exactly that.

Fix.

• examples/generators/options.py: _deadline re-arms itself until roundtrip marks the case settled. The option captures regenerate byte-identical.
• The test's spin gives up after 10s, so a lost alarm fails quickly with a clear message rather than hanging a worker.

Tests. New tests cover a swallowed raise (still recorded as 'TIMEOUT'), the repeat stopping once settled, and a cleared alarm. With the generator fix reverted they fail in about 11s instead of hanging. On main, with a finaliser swallowing the first raise, the CI worker crash reproduces exactly. The file passes 20/20 serially and 20/20 under -n 4 on Python 3.12.

Closes #1889

[JarryShaw]

Verdict: NEEDS CHANGES at ccc1e469e. The approach is sound, and two small gaps need closing. A Sonnet cross-review confirmed:

• the lost-raise mechanism hangs on base and is handled on head;
• no stray alarm or handler is left behind on the TIMEOUT, CONSTRUCT and KeyboardInterrupt paths it ran;
• the option captures regenerate byte-identical (sha256 of all five matches base);
• reverting options.py fails the new tests in about 11s rather than hanging;
• the other option-generator tests and test_tier_guard.py pass.

Required:

1. Non-timeout exits. settled is set only in the except TimeoutError clauses and after the last step, not on the CONSTRUCT, PARSE or RECONSTRUCT returns. If the alarm fires just before __exit__ cancels it on one of those paths, expire re-arms and the handler is never restored. Injected with signal.raise_signal at the top of __exit__, that left a recurring alarm raising TimeoutError in unrelated code. Base leaks only the handler. Set limit.settled = True first in those except clauses too, or have __exit__ settle before cancelling.
2. No test pins the settled stores. Removing all of them in roundtrip still passes the suite. Add a deterministic test: fire SIGALRM via signal.raise_signal during exit, check roundtrip still returns its outcome, and check that no alarm or foreign handler is left. Show that it fails without the stores.

[JarryShaw]

Verdict: NEEDS CHANGES at 69ea9b3e6. The amend closes the exit-path window on the CONSTRUCT, PARSE and RECONSTRUCT returns, and the new test pins those stores and the with order. Reordering the with changes no outcome: all 326 outcomes are identical to before, and the option captures are byte-identical.

But a SIGALRM delivered at the very top of _deadline.__exit__, before its first statement, still leaks on two paths:

• The OK path, which is a regression. Dropping the end-of-body store means settled is False until __exit__ runs.
• A BaseException such as KeyboardInterrupt, which was already leaking.

On both, TimeoutError escapes roundtrip, an alarm stays pending and the handler is not restored. The new comment's "before anything else, on every way out" is therefore not quite true.

Required:

• Wrap the with body in try: … finally: limit.settled = True. The reviewer checked this in a scratch copy: all eight ways out come back clean.
• Add a fire point at the very top of __exit__ to the test, covering OK and the BaseException exit.

[JarryShaw]

Verdict: GOOD TO GO at 437e5ad73. The Sonnet reviewer's third pass found nothing left to change.

• A SIGALRM handled at the entry to _deadline.__exit__, before its first statement, now leaves nothing behind on all eight ways out, OK and BaseException included: no pending alarm, the handler restored, and no stray TimeoutError.
• Each guard is pinned. Dropping the finally fails 2 tests, dropping the per-clause stores fails 6, and dropping __exit__'s backstop fails 1.
• Apart from the try/finally and comment rewording, the generator's syntax tree is unchanged. All 326 outcomes are identical, and the option captures are byte-identical to main.
• The test file passed 5/5 runs; the other option-generator tests and test_tier_guard.py pass.

Unverified, as the PR says: that the lost raise is what hung CI. That was reproduced locally only.

[github-actions]

Coverage: 90.06% (unit tier, Python 3.15, 437e5ad73, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	2	20	2	96.77%
pcapkit/const	19595	881	2618	867	92.11%
pcapkit/corekit	2462	69	780	35	96.55%
pcapkit/dumpkit	276	3	100	3	98.40%
pcapkit/foundation	2914	164	1016	34	93.59%
pcapkit/interface	138	7	52	5	93.68%
pcapkit/protocols	17406	224	4580	189	98.10%
pcapkit/toolkit	872	177	298	8	77.18%
pcapkit/utilities	512	2	158	4	99.10%
pcapkit/vendor	4429	2341	1018	156	43.62%

Per-file detail: the coverage-html artifact of this run.