test/hil, docs: move the containment history into the design doc

The modules were 21% comment, much of it review-cycle argument rather than
guidance -- _kill_kids stated 'descendant by construction, no argv check needed'
twice, eight lines apart. Deleting such comments outright makes maintenance
worse: the next reader simplifies the thing the comment was defending. So the
history moves to the 2026-07-30 fleet-wedge design doc, which gains a trim
addendum recording what was removed, what was deliberately kept, and the rule
that decided each -- the CI ceiling bounds how long a run burns, and does nothing
about state that outlives it.

One comment was not merely long but WRONG: the report wipe carried 'The unlink is
DEFERRED to inside the pool try/except below', which is the opposite of what the
code does -- it sits before Manager() with its own comment explaining why. That
is the failure mode this pass is about, so it is deleted rather than reworded.

Kept everywhere: citations that refute a plausible wrong reading. That
usb_lock_device_interruptible is why the readers are killable, that usblp_mutex
is driver-global, that rawmidi honours O_NONBLOCK where usblp does not.

Two follow-ups are retired with them: pr3803-hil-blindness-reporting.md (there
is no blindness to report any more) and pr3803-usbtest-recovery-reserve.md (the
reserve is derived now). Kept: pr3803-flasher-recover.md, which PR #3832
implements, plus pr3803-pci-rebind-stranding.md and pr3803-hil-iar-rerun-spec.md,
both independent of this work.

2 files changed, 5 insertions, 7 deletions

diff --git a/test/hil/helper/hil_health.py b/test/hil/helper/hil_health.py
index b9c05c236..d78d0f220 100644
--- a/test/hil/helper/hil_health.py
+++ b/test/hil/helper/hil_health.py
@@ -246,10 +246,8 @@ def _kill_kids(kids: dict, seen: set) -> int:
     if denied:
         _p(f'warning: could not kill {sorted(denied)}; they still hold whatever they '
               f'had open (probe, usbfs node) into the next job', flush=True)
-    # SURVIVORS, not the signalled-child count: the caller needs to know the rig is dirty
-    # for the next job, and a count of what we successfully signalled cannot tell it that.
-    # (They are different units anyway -- a killpg is counted once per child sharing the
-    # group -- so the old return was never comparable to anything.)
+    # SURVIVORS, not the count we signalled: the caller needs to know the rig is dirty for
+    # the next job, and a killpg is counted once per child sharing the group anyway.
     return len(denied)
 
 
diff --git a/test/hil/helper/hil_util.py b/test/hil/helper/hil_util.py
index b2c233cf3..6f84c143d 100644
--- a/test/hil/helper/hil_util.py
+++ b/test/hil/helper/hil_util.py
@@ -343,9 +343,9 @@ def usb_scan(vid_pid=None, serial=None, vid=None, timeout=SYSFS_READ_GRACE) -> l
     """
     out = []
     for d in glob.glob('/sys/bus/usb/devices/*-*'):
-        # Interfaces are '<busport>:<cfg>.<ifnum>' (e.g. 2-4:1.0) -- they CONTAIN the
-        # colon, they do not end with it, so the original endswith() never fired and every
-        # scan opened idVendor/idProduct on all of them (measured: 31 of 44 matches).
+        # `in`, not endswith: an interface is '<busport>:<cfg>.<ifnum>' (2-4:1.0), which
+        # CONTAINS the colon rather than ending with it. Screening them out here is worth
+        # real time -- they were 31 of 44 matches on this rig.
         if ':' in os.path.basename(d):
             continue
         try: