[JarryShaw]

• 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
• Added a changelog entry — 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?

• test — adding missing tests or correcting existing tests

---

Description of your pull request and other information

Part of #2082. It fixes the deadlock that ate 600 s of GraalPy's last shard in 3 of the last 4 full runs. #2083, #2084 and #2085 hold the leg's other failures.

• What happens:
  • test_module_isolation holds the tier-guard lock shared while its nested pytest runs.
  • Since test: the tier guard's blocking flock deadlocks GraalPy's xdist session #1977's writer gate, a queued writer (ProbeWriteLockTests) blocks new shared holds.
  • So the nested run's tests queue behind the writer, while the writer waits on the outer hold.
  • Only the nested run's 600 s timeout breaks the cycle. In job 120240454095, three tests finished together at 05:10:33 after a silent stretch at load 0.22.
• It isn't GraalPy-specific: GraalPy's slow startup just gives the writer time to queue.
• The fix: tests/conftest.py's shared hold now sets PCAPKIT_TEST_TIER_GUARD_HELD to the lock path while it lasts. A child process that inherits it for the same lock skips its own request, because the parent's hold already keeps the writer out. The out-of-date "nothing here triggers it" comment is corrected.
• Tests: ProbeLockNestedRunTests recreates the deadlock with a real child process and a writer queued at the gate. With the fix disabled it times out; with it, it passes in 0.24 s. It also checks that the variable lasts only for the hold and that another lock's path is ignored.
• Results: the tier-guard, isolation, support-helper and docs tests give 237 passed.

[JarryShaw]

GOOD TO GO at e20ee37e5 (Sonnet cross-review).

• The cycle: job 120240454095 stalls from 05:00:53 to 05:10:33, and the nested pytest had finished one test ([b'.']) before blocking. The gate code at 7f7c7cf8b and on main explains why. A reader takes the gate shared and then the lock. A writer holds the gate while it waits for the lock, and the outer shared hold waits on its subprocess.
• Skipping is sound: the parent's hold spans the whole subprocess.run, and the variable must name the exact lock path. A finally restores or removes it. xdist workers start before any hold, so they still lock. A writer in a child still waits, exactly as before.
• The new test: with the fix removed it times out after about 120 s, and with it restored it passes in 0.24 s.
• One residual, judged negligible: a child left behind by a parent killed without cleanup would run unlocked. subprocess.run kills the child on timeout.

[github-actions]

Coverage: 91.54% (unit tier, Python 3.15, e20ee37e5, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	4	20	2	95.16%
pcapkit/const	19599	880	2618	866	92.12%
pcapkit/corekit	2565	71	812	37	96.56%
pcapkit/dumpkit	282	3	102	3	98.44%
pcapkit/foundation	2930	23	1022	25	98.79%
pcapkit/interface	138	4	52	3	96.32%
pcapkit/protocols	17414	219	4574	185	98.14%
pcapkit/toolkit	869	36	298	10	95.20%
pcapkit/utilities	473	7	136	5	98.03%
pcapkit/vendor	4432	1988	1018	167	51.87%

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

[JarryShaw]

Ready to merge at e20ee37e5: the review is GOOD TO GO and CI is complete (56 passed, 0 failed). The ordering leg ran 2041 tests with 0 failures, and the 3.8–3.10 KTLO legs show 0 failing tests. The branch is one test-only commit behind main (b561d0f), so no rebase is needed.