fix(exc[CommandTimeoutError]) Render duration instead of "code None"

why: ``CommandTimeoutError`` inherited the bare ``CommandError`` template
``"Command failed with code {returncode}: {cmd}"``. When the SIGKILL bail
fires, ``proc.returncode`` is still ``None`` and users saw the misleading
``"Command failed with code None: <cmd>"`` rather than learning the
deadline was exceeded or by how much.
what:
- Add a ``timeout`` keyword to ``CommandTimeoutError`` carrying the
  wall-clock deadline that was breached.
- Override ``__str__`` to render ``"Command timed out after Xs: <cmd>"``
  (or ``"Command timed out: <cmd>"`` when ``timeout`` is unset), with
  partial output appended on a new line.
- Plumb ``timeout`` through ``_wait_with_deadline`` so the exception
  always carries the duration that fired.
- Add a doctest on ``CommandTimeoutError`` and run-level tests covering
  rendered duration and the ``timeout`` attribute.

Author: tony

src/libvcs/_internal/run.py

@@ -265,6 +265,7 @@ def progress_cb(output: t.AnyStr, timestamp: datetime.datetime) -> None:
         code, timeout_stdout, timeout_stderr = _wait_with_deadline(
             proc,
             deadline=time.monotonic() + timeout,
+            timeout=timeout,
             callback=callback,
             cmd=_stringify_command(normalized_args),
         )
@@ -316,6 +317,7 @@ def _wait_with_deadline(
     proc: subprocess.Popen[bytes],
     *,
     deadline: float,
+    timeout: float,
     callback: ProgressCallbackProtocol | None,
     cmd: str | list[str],
 ) -> tuple[int, bytes | None, bytes | None]:
@@ -398,6 +400,7 @@ def _wait_with_deadline(
                     output=message,
                     returncode=proc.returncode,
                     cmd=cmd,
+                    timeout=timeout,
                 )
 
             wait = min(_TIMEOUT_POLL_INTERVAL_SECONDS, remaining)

src/libvcs/exc.py

@@ -34,7 +34,47 @@ def __str__(self) -> str:
 
 
 class CommandTimeoutError(CommandError):
-    """CommandError which gets raised when a subprocess exceeds its timeout."""
+    r"""CommandError raised when a subprocess exceeds its wall-clock timeout.
+
+    Carries the deadline used when the timeout fired so callers and human
+    readers see the duration in the rendered message rather than the
+    misleading ``"Command failed with code None: ..."`` produced by the
+    bare :class:`CommandError` template (the child is not necessarily reaped
+    before the exception is raised, leaving ``returncode`` ``None``).
+
+    Examples
+    --------
+    >>> err = CommandTimeoutError(
+    ...     output='partial output',
+    ...     cmd='git fetch',
+    ...     timeout=2.5,
+    ... )
+    >>> print(str(err))
+    Command timed out after 2.5s: git fetch
+    partial output
+    """
+
+    def __init__(
+        self,
+        output: str,
+        returncode: int | None = None,
+        cmd: str | list[str] | None = None,
+        timeout: float | None = None,
+    ) -> None:
+        super().__init__(output=output, returncode=returncode, cmd=cmd)
+        #: Wall-clock deadline (seconds) the subprocess exceeded, if known.
+        self.timeout = timeout
+
+    def __str__(self) -> str:
+        """Render the timeout duration alongside the command and partial output."""
+        cmd = getattr(self, "cmd", "")
+        if self.timeout is not None:
+            message = f"Command timed out after {self.timeout:g}s: {cmd}"
+        else:
+            message = f"Command timed out: {cmd}"
+        if self.output.strip():
+            message += f"\n{self.output}"
+        return message
 
 
 class InvalidVCS(LibVCSException):

tests/_internal/test_run.py

@@ -125,6 +125,44 @@ def test_run_timeout_none_is_the_default() -> None:
     assert "default" in output
 
 
+def test_command_timeout_error_renders_duration() -> None:
+    """Direct ``CommandTimeoutError`` construction surfaces the duration."""
+    err = exc.CommandTimeoutError(
+        output="",
+        returncode=None,
+        cmd="git fetch origin",
+        timeout=2.5,
+    )
+
+    rendered = str(err)
+    assert "timed out after 2.5s" in rendered
+    assert "git fetch origin" in rendered
+    # Regression guard: the bare ``CommandError`` template would have produced
+    # ``"Command failed with code None: ..."`` when ``returncode`` is ``None``.
+    assert "code None" not in rendered
+
+
+def test_command_timeout_error_without_timeout_falls_back() -> None:
+    """Omitting ``timeout=`` still produces a readable timeout message."""
+    err = exc.CommandTimeoutError(output="partial", cmd="git fetch")
+
+    rendered = str(err)
+    assert "timed out" in rendered
+    assert "git fetch" in rendered
+    assert "partial" in rendered
+
+
+def test_run_timeout_message_includes_duration() -> None:
+    """``run(..., timeout=X)`` raises an exception whose ``str()`` shows X."""
+    with pytest.raises(exc.CommandTimeoutError) as excinfo:
+        run([sys.executable, "-c", "import time; time.sleep(10)"], timeout=0.3)
+
+    assert excinfo.value.timeout == 0.3
+    rendered = str(excinfo.value)
+    assert "timed out after" in rendered
+    assert "0.3" in rendered
+
+
 def test_run_timeout_does_not_deadlock_on_chatty_stdout() -> None:
     """A child filling its stdout pipe must not deadlock the deadline loop.