@@ -27,6 +27,9 @@ jobs:
 
   tests-and-type-check:
     runs-on: ubuntu-latest
+    # A wedged runner must fail in bounded time: with every kernel start
+    # timing out, the session tests alone would otherwise grind for hours.
+    timeout-minutes: 45
     name: tests-and-type-check (${{ matrix.python-version }}, shard ${{ matrix.shard }})
     strategy:
       matrix:
@@ -53,6 +56,15 @@ jobs:
       # Coverage tracing only where the report is uploaded (3.11); the other
       # versions run the plain suite.
       - name: Run tests
+        env:
+          # A kernel start on this runner (2 vCPUs, two xdist workers each
+          # spawning kernels, coverage tracing on 3.11) can take well over the
+          # 30 s library default. Doubling covers that; going higher only
+          # multiplies the wall time of a broken runner, where every start in
+          # the module times out in sequence. A start that needs more than
+          # this should fail loudly — the error explains which phase timed
+          # out — rather than be retried.
+          DOCX_EDITOR_SESSION_START_TIMEOUT: "60"
         run: >-
           uv run python -m pytest tests -n auto
           --splits 2 --group ${{ matrix.shard }}
 
@@ -12,6 +12,7 @@
 import argparse
 import ast
 import json
+import math
 import os
 import re
 import signal
@@ -31,6 +32,21 @@
 
 DEFAULT_CONNECTION_FILE = Path.home() / ".cache" / "docx-editor" / "kernel.json"
 
+# start_session's default budget, and the environment variable that overrides
+# it. A kernel start is a fresh interpreter importing ipykernel + IPython; on a
+# loaded machine (a 2-vCPU CI runner with parallel test workers, coverage
+# tracing on) that import alone can take longer than the unloaded 30 s default.
+DEFAULT_START_TIMEOUT = 30.0
+START_TIMEOUT_ENV = "DOCX_EDITOR_SESSION_START_TIMEOUT"
+
+# How the kernel is launched. Tests substitute a stand-in kernel here to
+# exercise the start-failure paths deterministically; the "-f <file>" argument
+# is appended by start_session.
+_KERNEL_COMMAND = (sys.executable, "-m", "ipykernel_launcher")
+
+# Bytes of kernel stderr kept in a start-failure diagnostic.
+_STDERR_TAIL_BYTES = 4096
+
 _EXTRA_HINT = "Session mode requires extra dependencies: pip install 'docx-editor[session]'"
 
 
@@ -131,29 +147,116 @@ def _read_pid(connection_file: Path) -> int | None:
         return None
 
 
-def start_session(connection_file: Path = DEFAULT_CONNECTION_FILE, timeout: float = 30.0) -> int:
+def _start_timeout() -> float:
+    """start_session's budget: DOCX_EDITOR_SESSION_START_TIMEOUT, else the 30 s default.
+
+    Raises:
+        SessionError: If the variable is set to anything but a positive number.
+    """
+    raw = os.environ.get(START_TIMEOUT_ENV, "").strip()
+    if not raw:
+        return DEFAULT_START_TIMEOUT
+    try:
+        value = float(raw)
+        if not (math.isfinite(value) and value > 0):  # rejects nan and inf too
+            raise ValueError
+    except ValueError:
+        raise SessionError(f"{START_TIMEOUT_ENV} must be a positive number of seconds, got {raw!r}") from None
+    return value
+
+
+def _drain_stderr(proc: subprocess.Popen[bytes]) -> str:
+    """Tail of what a (killed and reaped) kernel wrote to stderr, without blocking.
+
+    Invariant: nothing may read ``proc.stderr`` before this runs — the raw-fd
+    read below bypasses the ``BufferedReader``, so any bytes already buffered
+    there would be silently dropped. (Today the only other reader, the
+    exited-during-startup path, always raises without reaching ``_abort``.)
+
+    The pipe is switched to non-blocking first: every writer is dead, so the
+    read hits EOF at once — but if a grandchild ever inherited the write end,
+    EAGAIN ends the loop instead of hanging a diagnostic that exists to explain
+    a hang.
+    """
+    if proc.stderr is None:
+        return ""
+    fd = proc.stderr.fileno()
+    if os.name == "posix":
+        os.set_blocking(fd, False)
+    chunks: list[bytes] = []
+    while True:
+        try:
+            chunk = os.read(fd, 65536)
+        except OSError:  # EAGAIN: a writer still holds the pipe open
+            break
+        if not chunk:
+            break
+        chunks.append(chunk)
+    return b"".join(chunks)[-_STDERR_TAIL_BYTES:].decode(errors="replace").strip()
+
+
+def _describe_connection_file(connection_file: Path) -> str:
+    """One line on what the kernel managed to write before the budget ran out."""
+    try:
+        size = connection_file.stat().st_size
+    except OSError:
+        return "Connection file: absent."
+    try:
+        info = json.loads(connection_file.read_text(encoding="utf-8"))
+        return (
+            f"Connection file: {size} bytes, {info['transport']} {info['ip']}, "
+            f"shell={info['shell_port']} control={info['control_port']}."
+        )
+    except (OSError, ValueError, KeyError, TypeError) as e:
+        return f"Connection file: {size} bytes, unreadable: {e}."
+
+
+def _load_average() -> str:
+    """Suffix "; load average N.NN" where the platform reports one, else ""."""
+    if not hasattr(os, "getloadavg"):  # Windows
+        return ""
+    try:
+        return f"; load average {os.getloadavg()[0]:.2f}"
+    except OSError:
+        return ""
+
+
+def start_session(connection_file: Path = DEFAULT_CONNECTION_FILE, timeout: float | None = None) -> int:
     """Start a detached IPython kernel and wait until it answers.
 
     Args:
         connection_file: Where to write the kernel connection file
-        timeout: Seconds to wait for the kernel to become ready
+        timeout: Seconds to wait for the kernel to become ready. ``None`` (the
+            default) reads ``DOCX_EDITOR_SESSION_START_TIMEOUT`` and falls back to
+            30 s when it is unset or blank; an explicit argument always wins.
+            The variable exists for loaded machines — CI runners, parallel
+            test workers — where a fresh interpreter importing IPython takes
+            far longer than it does interactively. ``docx-session start``
+            has no flag for it and reaches the variable through this default.
 
     Returns:
         PID of the kernel process.
 
     Raises:
         SessionError: If a session is already running, the kernel fails to
-            start, or the connection file it wrote is unreadable.
+            start, the connection file it wrote is unreadable, or
+            ``DOCX_EDITOR_SESSION_START_TIMEOUT`` is not a positive number.
+            A start that runs out of budget explains itself: which phase
+            timed out (connection file vs. control-channel reply), whether
+            the kernel was still alive, the load average, what it wrote to
+            stderr, and the variable to raise.
         ImportError: If the [session] extra is not installed.
     """
+    if timeout is None:
+        timeout = _start_timeout()
     if is_session_running(connection_file):
         raise SessionError(f"Session already running (connection file: {connection_file})")
 
     connection_file.parent.mkdir(parents=True, exist_ok=True)
     connection_file.unlink(missing_ok=True)
 
     proc = subprocess.Popen(
-        [sys.executable, "-m", "ipykernel_launcher", "-f", str(connection_file)],
+        [*_KERNEL_COMMAND, "-f", str(connection_file)],
         stdout=subprocess.DEVNULL,
         # Keep stderr so a failed start (e.g. missing ipykernel) can explain itself.
         stderr=subprocess.PIPE,
@@ -162,14 +265,32 @@ def start_session(connection_file: Path = DEFAULT_CONNECTION_FILE, timeout: floa
     )
     _pid_file(connection_file).write_text(str(proc.pid), encoding="utf-8")
 
-    def _abort(message: str) -> SessionError:
+    def _abort(summary: str) -> SessionError:
+        # Sampled before the kill so the report says what the kernel was doing
+        # at the timeout, not what the kill did to it.
+        exit_code = proc.poll()
         proc.kill()
         proc.wait()
+        kernel = "was still alive at the timeout" if exit_code is None else f"had exited with code {exit_code}"
+        stderr = _drain_stderr(proc)
+        report = "\n".join([
+            summary,
+            f"Kernel pid {proc.pid} {kernel}{_load_average()}.",
+            _describe_connection_file(connection_file),
+            "Kernel stderr:",
+            "\n".join(f"  {line}" for line in stderr.splitlines()) if stderr else "  (empty)",
+            f"Set {START_TIMEOUT_ENV} to raise the budget on a loaded machine.",
+        ])
         connection_file.unlink(missing_ok=True)
         _pid_file(connection_file).unlink(missing_ok=True)
-        return SessionError(message)
-
-    deadline = time.monotonic() + timeout
+        return SessionError(report)
+
+    # Two phases share one budget. The connection file is written as soon as
+    # the sockets are bound — *before* ipykernel imports IPython and wires the
+    # control channel — so its appearance is an early signal, and the second
+    # phase gets whatever is left (floored at 1 s).
+    t0 = time.monotonic()
+    deadline = t0 + timeout
     while not (connection_file.exists() and connection_file.stat().st_size > 0):
         if proc.poll() is not None:
             stderr = proc.stderr.read().decode(errors="replace").strip() if proc.stderr else ""
@@ -178,8 +299,11 @@ def _abort(message: str) -> SessionError:
             detail = f"\n{stderr}" if stderr else ""
             raise SessionError(f"Kernel process exited during startup (code {proc.returncode}). {hint}{detail}".strip())
         if time.monotonic() > deadline:
-            raise _abort(f"Kernel did not start within {timeout}s")
+            raise _abort(
+                f"Kernel did not start within {timeout}s: no connection file after {time.monotonic() - t0:.1f}s."
+            )
         time.sleep(0.1)
+    t_file = time.monotonic() - t0
 
     kc = None
     try:
@@ -190,8 +314,12 @@ def _abort(message: str) -> SessionError:
             kc = _client(connection_file)
         except (ValueError, OSError) as e:
             raise SessionError(f"Kernel wrote an unreadable connection file ({connection_file}): {e}") from e
-        if not _kernel_alive(kc, timeout=max(1.0, deadline - time.monotonic())):
-            raise SessionError(f"Kernel did not become ready within {timeout}s")
+        remaining = max(1.0, deadline - time.monotonic())
+        if not _kernel_alive(kc, timeout=remaining):
+            raise _abort(
+                f"Kernel did not become ready within {timeout}s: kernel.json appeared after {t_file:.1f}s, "
+                f"then no kernel_info reply on the control channel in the remaining {remaining:.1f}s."
+            )
     except BaseException:
         # Never leave a half-started kernel behind with no way to reach it.
         if proc.poll() is None:
 
@@ -1176,6 +1176,8 @@ scripts. The document (and all your variables) stays open between commands:
 ```bash
 # Requires: pip install "docx-editor[session]"
 docx-session start
+# On a loaded machine (CI, parallel workers) set DOCX_EDITOR_SESSION_START_TIMEOUT=60
+# to raise the 30 s budget `start` gives the kernel to answer.
 
 # Use ABSOLUTE paths: the kernel keeps the cwd it was started in, which is not
 # necessarily the cwd of a later exec. `start` prints the cwd it captured.
 
@@ -180,10 +180,12 @@ def counting(root, tags, **kwargs):
 def _connection_file_from_argv(args) -> Path | None:
     """Return the ``-f <path>`` of an ipykernel_launcher command line, else None.
 
-    ``start_session`` always spawns the kernel as
+    ``start_session`` spawns the kernel as
     ``[python, "-m", "ipykernel_launcher", "-f", <connection file>]``, so the
     connection file can be recovered from the argv alone — no cooperation from
-    the code under test required.
+    the code under test required. Tests that substitute a stand-in kernel (via
+    ``session_mod._KERNEL_COMMAND`` or a fake ``subprocess``) are invisible to
+    this reaper and must reap their own processes.
 
     The path is resolved eagerly: cwd is correct now, but two tests chdir
     (``test_workspace.py``, ``test_document.py``), so a relative path stored