@@ -84,6 +84,7 @@ runs:
         echo "key=${prefix}${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" >> "${GITHUB_OUTPUT}"
 
     - name: Restore successful link checks
+      id: cache-restore
       # Refresh mode deliberately skips earlier URL results.
       if: ${{ inputs.refresh != 'true' }}
       uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v6.1.0
@@ -93,6 +94,25 @@ runs:
         restore-keys: ${{ steps.cache.outputs.prefix }}
         enableCrossOsArchive: true
 
+    - name: Explain a missing shared Lychee cache
+      # Prefix restores are normal; cache-hit only identifies exact key matches.
+      if: ${{ inputs.refresh != 'true' && steps.cache-restore.outputs.cache-matched-key == '' }}
+      shell: bash --noprofile --norc -euo pipefail {0}
+      env:
+        KIND: ${{ inputs.kind }}
+        DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        WORKFLOW_URL: ${{ github.server_url }}/${{ github.repository }}/actions/workflows/lychee.yml
+      run: |
+        message="No shared Lychee ${KIND} cache was restored for this checker configuration. Checking links without this baseline may take longer and make more network requests."
+        context="This is expected after checker changes in a PR; a refresh on ${DEFAULT_BRANCH} cannot seed settings that exist only in a PR."
+        hint="For an unexpected miss on ${DEFAULT_BRANCH}, maintainers can run CI: Lychee checks and caches (lychee.yml) on ${DEFAULT_BRANCH} with refresh-cache enabled."
+        echo "::notice title=Lychee ${KIND} cache::${message} ${context} ${hint} ${WORKFLOW_URL}"
+        {
+          printf '### Lychee %s cache\n\n' "$KIND"
+          printf '%s\n\n%s\n\n%s\n\n' "$message" "$context" "$hint"
+          printf '[Open the cache refresh workflow](%s).\n' "$WORKFLOW_URL"
+        } >> "$GITHUB_STEP_SUMMARY"
+
     - name: Check links through the configured pre-commit hook
       shell: bash --noprofile --norc -euo pipefail {0}
       env:
@@ -107,7 +127,7 @@ runs:
           --report "${RUNNER_TEMP}/lychee-reports/lychee-${KIND}.json"
 
     - name: Publish fresh successful link checks
-      # Only nightly refreshes publish, so every pull request restores the same
+      # Only refresh runs publish, so every pull request restores the same
       # baseline. Saving keeps original timestamps and never caches failures.
       if: ${{ !cancelled() && inputs.refresh == 'true' }}
       uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v6.1.0
 
@@ -4,10 +4,10 @@
 
 # Warm authored and rendered link caches through the configured pre-commit
 # hooks. Ordinary PRs reuse authored results; full docs CI reuses rendered
-# results. Nightly starts afresh, reports unresolved links as warnings, and is
-# the only producer of both shared baselines.
+# results. Nightly and manual dispatches with refresh-cache=true start afresh,
+# report unresolved links as warnings, and can produce both shared baselines.
 
-name: "CI: Documentation links"
+name: "CI: Lychee checks and caches"
 
 on:
   workflow_call:
 
@@ -88,9 +88,9 @@ existing allowance for at most ten distinct HTTP 429 URLs.
 
 ### Shared URL Caches
 
-Nightly is the only producer. It skips restoring, checks afresh, and publishes
-successful results; every other job restores the newest baseline and never
-publishes. Failed URLs and filesystem targets are never cached. Successes keep
+Nightly and manual refreshes skip restoring, check afresh, and publish
+successful results; ordinary checks restore the newest baseline and never
+publish. Failed URLs and filesystem targets are never cached. Successes keep
 their original timestamps and expire after three days, so a missed nightly
 refresh does not break reuse, but a link that breaks after a nightly success
 can stay unnoticed for up to 72 hours.
@@ -104,6 +104,21 @@ fragments and Lychee's cache does not record which validation ran. URL results
 are shared across operating systems; pre-commit's installed environments keep
 their OS- and Python-specific caches.
 
+#### Refreshing Shared Caches
+
+To rebuild both shared caches manually, open
+[CI: Lychee checks and caches](https://github.com/NVIDIA/cuda-python/actions/workflows/lychee.yml)
+(`.github/workflows/lychee.yml`), select the default branch, and enable
+`refresh-cache` before choosing **Run workflow**. This runs the cache refresh
+without the rest of nightly CI.
+
+Checks that restore no matching baseline add a notice and a job-summary hint.
+They still check links, with potentially more runtime and network traffic.
+Checker changes in a PR intentionally start with a cold cache; refreshing the
+default branch cannot seed a cache for settings that exist only in that PR.
+Refreshing rebuilds cached successes; broken links and upstream rate limits
+still need their usual investigation.
+
 ### Repository Links
 
 Documentation can link to a path added or moved in the same PR using its
 
@@ -96,6 +96,15 @@ Follow these rules when adding or moving shared test code:
   `tests/helpers/` instead.
 - Import helpers explicitly from the test root, for example:
   `from helpers.memory import create_managed_memory_resource_or_skip`.
+- Reuse `run_child` and `noop` from `helpers.child_processes` for synchronous
+  child-process tests. The runner applies the sanitizer-aware timeout, kills
+  surviving children before asserting success, and closes process handles.
+  Before measuring file-descriptor counts around spawned processes, call
+  `warmup_multiprocessing` from the same module to start the persistent
+  resource-tracker pipe outside the baseline. Keep explicit process management
+  when the test needs to communicate with a running child or inspect its lifetime;
+  use `kill_subprocesses` before assertions and `track_child_processes` for
+  fixture cleanup so a stuck child cannot block IPC resource teardown.
 - Search `tests/helpers/` and `cuda_python_test_helpers/` for prior art
   before adding a new helper; consolidate duplicates across
 
 
@@ -11,6 +11,8 @@
 """
 
 import contextlib
+import functools
+import multiprocessing as mp
 import multiprocessing.process
 import weakref
 
@@ -64,6 +66,36 @@ def kill_subprocesses(*processes):
     return killed
 
 
+def run_child(target, *args):
+    """Run ``target(*args)`` in a child, killing it on timeout or interrupted join.
+
+    Fail unless the child exits successfully. Close the Process object before
+    returning so its handles cannot affect file-descriptor leak checks.
+    """
+    with contextlib.closing(mp.Process(target=target, args=args)) as process:
+        try:
+            process.start()
+            process.join(timeout=child_timeout_sec())
+        finally:
+            survivors = kill_subprocesses(process)
+        assert not survivors, "child did not exit within timeout"
+        assert process.exitcode == 0, f"child exited with {process.exitcode}"
+
+
+def noop(*args):
+    """A picklable child target that accepts and discards any arguments."""
+
+
+@functools.cache
+def warmup_multiprocessing():
+    """Start spawn's persistent resource-tracker pipe before counting open FDs.
+
+    Cache only a successful warmup; the pipe outlives individual Process objects.
+    """
+    assert mp.get_start_method() == "spawn"
+    run_child(noop)
+
+
 @contextlib.contextmanager
 def track_child_processes():
     """Context manager that kills any ``multiprocessing.Process`` children still
 
@@ -13,7 +13,7 @@
 else:
     HAVE_PSUTIL = True
 import pytest
-from helpers.child_processes import child_timeout_sec, kill_subprocesses
+from helpers.child_processes import child_timeout_sec, kill_subprocesses, noop, run_child, warmup_multiprocessing
 
 CHILD_TIMEOUT_SEC = child_timeout_sec()
 NBYTES = 64
@@ -40,16 +40,7 @@ def test_alloc_handle(ipc_memory_resource):
 def exec_success(obj, number=1):
     """Successfully run a child process."""
     for _ in range(number):
-        process = mp.Process(target=child_main, args=(obj,))
-        process.start()
-        process.join(timeout=CHILD_TIMEOUT_SEC)
-        survivors = kill_subprocesses(process)
-        assert not survivors, "child did not exit within timeout"
-        assert process.exitcode == 0
-
-
-def child_main(obj, *args):
-    pass
+        run_child(noop, obj)
 
 
 def exec_launch_failure(obj, number=1):
@@ -78,7 +69,7 @@ def exec_reduce_failure(obj, number=1):
     for _ in range(number):
         fails_to_reduce = Irreducible()
         with contextlib.suppress(RuntimeError):
-            mp.Process(target=child_main, args=(obj, fails_to_reduce)).start()
+            mp.Process(target=noop, args=(obj, fails_to_reduce)).start()
 
 
 class Irreducible:
@@ -137,7 +128,7 @@ def __init__(self):
         self.process = psutil.Process()
 
     def __enter__(self):
-        prime()
+        warmup_multiprocessing()
         gc.collect()
         self.initial_fds = self.process.num_fds()
         return self
@@ -150,20 +141,3 @@ def __exit__(self, exc_type, exc_val, exc_tb):
             final_fds = self.process.num_fds()
             assert final_fds == self.initial_fds, f"file descriptors leaked: {self.initial_fds} -> {final_fds}"
         return False
-
-
-prime_was_run = False
-
-
-def prime():
-    """Multiprocessing consumes a file descriptor on first launch."""
-    assert mp.get_start_method() == "spawn"
-    global prime_was_run
-    if not prime_was_run:
-        process = mp.Process()
-        process.start()
-        process.join(timeout=CHILD_TIMEOUT_SEC)
-        survivors = kill_subprocesses(process)
-        assert not survivors, "child did not exit within timeout"
-        assert process.exitcode == 0
-        prime_was_run = True
@@ -22,7 +22,7 @@
 import threading
 
 import pytest
-from helpers.child_processes import child_timeout_sec, kill_subprocesses
+from helpers.child_processes import child_timeout_sec, kill_subprocesses, noop, run_child, warmup_multiprocessing
 from helpers.contexts import assert_no_cuda_warning
 
 from cuda.bindings import driver
@@ -149,20 +149,6 @@ class _CustomResource(VirtualMemoryResource):
     """A subclass, to check that pickling preserves the type."""
 
 
-def _run_child(target, *args):
-    """Run ``target(*args)`` in a spawned child and fail if it does not exit cleanly."""
-    process = mp.Process(target=target, args=args)
-    process.start()
-    process.join(timeout=CHILD_TIMEOUT_SEC)
-    survivors = kill_subprocesses(process)
-    assert not survivors, "child did not exit within timeout"
-    assert process.exitcode == 0, f"child exited with {process.exitcode}"
-
-
-def _noop(*args):
-    pass
-
-
 def _close_argument(buffer):
     buffer.close()
 
@@ -260,7 +246,7 @@ def test_main(self, vmm_ipc_device):
             assert _open_fds() == fds_before + 3
             fds = [int(handle) for handle in desc._handles]
 
-            _run_child(self.child_main, device.device_id, desc, gran, queue)
+            run_child(self.child_main, device.device_id, desc, gran, queue)
             result = queue.get(timeout=CHILD_TIMEOUT_SEC)
             assert result["chunks"] == [bytes([value]) * 16 for value in values]
             assert result["released"] is True
@@ -311,7 +297,7 @@ def test_main(self, vmm_ipc_device_x2):
 
         peers_possible = dev1.can_access_peer(dev0)
         queue = mp.Queue()
-        _run_child(self.child_main, dev0.device_id, dev1.device_id, desc, peers_possible, queue)
+        run_child(self.child_main, dev0.device_id, dev1.device_id, desc, peers_possible, queue)
         result = queue.get(timeout=CHILD_TIMEOUT_SEC)
         assert f"device {dev0.device_id}" in result["wrong_device"]
         assert result["device_id"] == dev1.device_id
@@ -495,7 +481,7 @@ def test_export_and_pickling_raise_before_any_driver_call(self, vmm_ipc_device):
             with parent_conn, child_conn, pytest.raises(RuntimeError, match=_REEXPORT_MESSAGE):
                 parent_conn.send(imported)
             with pytest.raises(RuntimeError, match=_REEXPORT_MESSAGE):
-                mp.Process(target=_noop, args=(imported,)).start()
+                mp.Process(target=noop, args=(imported,)).start()
             # The original descriptor still serves new importers, and the data is intact.
             _fill(buf, 0x3C)
             alias = Buffer.from_ipc_descriptor(mr, desc, stream=stream)
@@ -589,9 +575,7 @@ def test_exporter_holds_none_without_a_descriptor(self, vmm_ipc_device):
     @pytest.mark.thread_unsafe(reason="counts process-global file descriptors")
     def test_process_argument_releases_with_the_process_object(self, vmm_ipc_device):
         """A buffer passed to a spawned Process imports there; its descriptor goes when the Process object does."""
-        # The first spawn opens a process-wide resource-tracker pipe, which
-        # outlives Process objects. Start it before taking the descriptor baseline.
-        _run_child(_noop)
+        warmup_multiprocessing()
         device = vmm_ipc_device
         mr = _resource(device)
         with mr.allocate(1) as buf:
@@ -926,7 +910,7 @@ def test_round_trip(self, vmm_ipc_device):
         assert alias.is_mapped
         alias.close()
         queue = mp.Queue()
-        _run_child(self.child_main, device.device_id, desc, queue)
+        run_child(self.child_main, device.device_id, desc, queue)
         assert queue.get(timeout=CHILD_TIMEOUT_SEC) == {"size": 0, "is_mapped": True}
         empty.close()
 
@@ -948,7 +932,7 @@ def test_imported_buffer_feeds_a_consumer(self, vmm_ipc_device):
         buf = mr.allocate(1)
         _fill(buf, 0x7E)
         queue = mp.Queue()
-        _run_child(self.child_main, device.device_id, buf, queue)
+        run_child(self.child_main, device.device_id, buf, queue)
         result = queue.get(timeout=CHILD_TIMEOUT_SEC)
         assert result["dl_device"] == (int(DLDeviceType.kDLCUDA), device.device_id)
         assert result["shape"] == (buf.size,)