From 5c8441137ad4e4b565646ca36bc847d265cefce9 Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <blooop@gmail.com>
Date: Sun, 9 Aug 2026 07:55:55 +0100
Subject: [PATCH 01/13] Emit an env-gated timing summary at the end of every dl
 command

DEVLAUNCH_TIMING=1 makes main() end with a dl-timing total line on
stderr; unset means no output and no recording. Ticket #140 slice 1.
---
 devlaunch/dl.py     |   8 ++-
 devlaunch/timing.py | 116 ++++++++++++++++++++++++++++++++++++++++++++
 test/test_timing.py |  36 ++++++++++++++
 3 files changed, 159 insertions(+), 1 deletion(-)
 create mode 100644 devlaunch/timing.py
 create mode 100644 test/test_timing.py

diff --git a/devlaunch/dl.py b/devlaunch/dl.py
index 991cd159..d65b1482 100644
--- a/devlaunch/dl.py
+++ b/devlaunch/dl.py
@@ -36,7 +36,7 @@
 from urllib.parse import urlparse
 from urllib.request import url2pathname
 
-from . import devpod_ssh, disk_usage, gh_auth, tools, tty_session, workspace_state
+from . import devpod_ssh, disk_usage, gh_auth, timing, tools, tty_session, workspace_state
 from .completion import install_completions
 from .workspace_id import TARGET_LENGTH, WorkspaceId, slug, source_workspace_id, validate_ref_name
 from .worktree.config import get_worktree_config
@@ -2361,6 +2361,10 @@ def main(argv: Optional[List[str]] = None) -> int:
     # a caller that drives main() twice (a test, a shell wrapper) must not have
     # the first command's view of devpod answer the second command's questions.
     invalidate_workspace_list_cache()
+    # Timing is per-command, like the workspace-list snapshot: begin() here so
+    # a second main() in the same process starts a fresh summary, emit() in the
+    # finally so the summary lands on stderr however the command ended.
+    timing.begin()
     try:
         return _run_cli(argv)
     except MissingBinary as e:
@@ -2369,6 +2373,8 @@ def main(argv: Optional[List[str]] = None) -> int:
     except UnreadableWorkspaceList as e:
         print(f"error: {e}", file=sys.stderr)
         return UNREADABLE_WORKSPACE_LIST_EXIT_CODE
+    finally:
+        timing.emit()
 
 
 def _run_cli(argv: Optional[List[str]] = None) -> int:
diff --git a/devlaunch/timing.py b/devlaunch/timing.py
new file mode 100644
index 00000000..7085d994
--- /dev/null
+++ b/devlaunch/timing.py
@@ -0,0 +1,116 @@
+"""Env-gated wall-clock timing for dl's subprocess round trips.
+
+Set ``DEVLAUNCH_TIMING=1`` and every dl process ends with one summary on
+stderr: one ``dl-timing: <label> <seconds>s`` line per recorded subprocess
+call, then a ``total`` line for the whole command. With the variable unset
+(or ``0``) nothing is recorded and nothing is printed — the hot path must not
+pay for its own thermometer, so the off state is a single ``None`` check.
+
+stderr because stdout is parsed by the completion machinery, and one summary
+per process (rather than a line per event as it happens) so the output
+composes with one-shot commands: the numbers arrive after the command's own
+output, not interleaved with it.
+
+The on/off state is one optional recorder, not a flag plus fields that must
+agree with it: when timing is off there is nothing to hold, and every code
+path that records goes through the same ``span`` gate.
+"""
+
+import os
+import sys
+import time
+from dataclasses import dataclass, field
+from typing import List, Optional, TextIO, Tuple
+
+ENV_VAR = "DEVLAUNCH_TIMING"
+
+
+@dataclass
+class _Recorder:
+    """Wall-clock records for one dl process: a start instant and spans."""
+
+    started: float
+    entries: List[Tuple[str, float]] = field(default_factory=list)
+
+
+_recorder: Optional[_Recorder] = None
+
+
+class _Span:
+    """Times one ``with`` block and records it, exceptions included.
+
+    A spawn that failed still took time, and a summary that silently dropped
+    it would make the remaining numbers add up to less than the total.
+    """
+
+    __slots__ = ("_recorder", "_label", "_start")
+
+    def __init__(self, recorder: _Recorder, label: str):
+        self._recorder = recorder
+        self._label = label
+        self._start = 0.0
+
+    def __enter__(self) -> "_Span":
+        self._start = time.perf_counter()
+        return self
+
+    def __exit__(self, *_exc) -> bool:
+        self._recorder.entries.append((self._label, time.perf_counter() - self._start))
+        return False
+
+
+class _NoSpan:
+    """The span handed out when timing is off: enter, exit, remember nothing."""
+
+    def __enter__(self) -> "_NoSpan":
+        return self
+
+    def __exit__(self, *_exc) -> bool:
+        return False
+
+
+_NOOP_SPAN = _NoSpan()
+
+
+def begin() -> None:
+    """Start recording for this process iff DEVLAUNCH_TIMING asks for it.
+
+    Called once at the top of main(). Replaces any recorder left over from an
+    earlier main() call in the same process (a test, a shell wrapper), so one
+    command's spans never leak into the next command's summary.
+    """
+    global _recorder  # pylint: disable=global-statement
+    if os.environ.get(ENV_VAR, "").strip() in ("", "0"):
+        _recorder = None
+        return
+    _recorder = _Recorder(started=time.perf_counter())
+
+
+def span(label: str):
+    """A context manager timing one subprocess round trip as *label*.
+
+    Free when timing is off: no allocation, no clock read, just the shared
+    no-op span.
+    """
+    recorder = _recorder
+    if recorder is None:
+        return _NOOP_SPAN
+    return _Span(recorder, label)
+
+
+def emit(stream: Optional[TextIO] = None) -> None:
+    """Write the summary and stop recording; silent when recording never began.
+
+    *stream* defaults to sys.stderr resolved now, not at import, so capture
+    fixtures and redirections see the output.
+    """
+    global _recorder  # pylint: disable=global-statement
+    recorder = _recorder
+    _recorder = None
+    if recorder is None:
+        return
+    out = stream if stream is not None else sys.stderr
+    total = time.perf_counter() - recorder.started
+    for label, seconds in recorder.entries:
+        print(f"dl-timing: {label} {seconds:.3f}s", file=out)
+    print(f"dl-timing: total {total:.3f}s", file=out)
diff --git a/test/test_timing.py b/test/test_timing.py
new file mode 100644
index 00000000..90e09b2b
--- /dev/null
+++ b/test/test_timing.py
@@ -0,0 +1,36 @@
+# pylint: disable=redefined-outer-name
+"""Pin the env-gated wall-clock timing summary (ticket #140).
+
+`DEVLAUNCH_TIMING=1` makes every dl process end with one stderr summary naming
+each subprocess round trip and the total wall time, so a perf change can land
+with before/after numbers. With the variable unset, dl must write no timing
+output at all: the hot path must not pay for its own thermometer.
+
+These tests pin behavior at the same boundaries as test_devpod_spawn_counts:
+the CLI entry point on one side, the subprocess module on the other.
+"""
+
+import re
+
+from devlaunch.dl import main
+
+TIMING_LINE = re.compile(r"^dl-timing: (.+) \d+\.\d{3}s$", re.MULTILINE)
+
+
+def timing_labels(stderr: str):
+    """The labels of every timing line in *stderr*, in order."""
+    return TIMING_LINE.findall(stderr)
+
+
+class TestSummaryGate:
+    """Timing lines appear iff DEVLAUNCH_TIMING is set."""
+
+    def test_no_timing_output_when_env_unset(self, monkeypatch, capsys):
+        monkeypatch.delenv("DEVLAUNCH_TIMING", raising=False)
+        assert main(["--version"]) == 0
+        assert "dl-timing:" not in capsys.readouterr().err
+
+    def test_summary_ends_with_total_when_env_set(self, monkeypatch, capsys):
+        monkeypatch.setenv("DEVLAUNCH_TIMING", "1")
+        assert main(["--version"]) == 0
+        assert timing_labels(capsys.readouterr().err) == ["total"]

From 22bd588ed248cde06cf60b532b2c1cbea2ea06a8 Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <blooop@gmail.com>
Date: Sun, 9 Aug 2026 07:57:08 +0100
Subject: [PATCH 02/13] Name each devpod round trip in the timing summary

run_devpod and run_devpod_session time their spawn by subcommand
(devpod status/ssh/list...), so the summary shows where a launch's
wall time went. Ticket #140 slice 2.
---
 devlaunch/dl.py     | 50 +++++++++++++++++++++++++--------------------
 test/test_timing.py | 35 +++++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+), 22 deletions(-)

diff --git a/devlaunch/dl.py b/devlaunch/dl.py
index d65b1482..1c32bc02 100644
--- a/devlaunch/dl.py
+++ b/devlaunch/dl.py
@@ -1533,13 +1533,16 @@ def run_devpod(
     cmd = ["devpod"] + args
     logging.debug("Running: %s", " ".join(cmd))
     try:
-        if capture:
+        # Timed by subcommand, not full argv: the summary should name each
+        # round trip (status, ssh, up...) without leaking workspace ids into it.
+        with timing.span(" ".join(cmd[:2])):
+            if capture:
+                # nosec B603 - using list form, not shell=True; no command injection risk
+                return subprocess.run(
+                    cmd, capture_output=True, text=True, check=False, env=env, stdin=stdin_file
+                )
             # nosec B603 - using list form, not shell=True; no command injection risk
-            return subprocess.run(
-                cmd, capture_output=True, text=True, check=False, env=env, stdin=stdin_file
-            )
-        # nosec B603 - using list form, not shell=True; no command injection risk
-        return subprocess.run(cmd, check=False, env=env, stdin=stdin_file)
+            return subprocess.run(cmd, check=False, env=env, stdin=stdin_file)
     except FileNotFoundError as e:
         raise DevpodNotInstalled(DEVPOD_MISSING_MESSAGE) from e
 
@@ -1557,22 +1560,25 @@ def run_devpod_session(
     """
     cmd = ["devpod"] + args
     logging.debug("Running: %s", " ".join(cmd))
-    # nosec B603 - using list form, not shell=True; no command injection risk
-    with subprocess.Popen(
-        cmd,
-        stderr=subprocess.PIPE,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-        env=env,
-    ) as proc:
-        # proc.stderr is a pipe because PIPE was asked for, but Popen's type
-        # cannot express that, so the narrowing happens here rather than by
-        # widening filter_devpod_stderr to a None it would have no answer for.
-        pipe = proc.stderr
-        remote_status = (
-            devpod_ssh.filter_devpod_stderr(pipe, sys.stderr) if pipe is not None else None
-        )
+    # The span covers the whole session: what the summary names is the round
+    # trip the user waited on, not just the process spawn.
+    with timing.span(" ".join(cmd[:2])):
+        # nosec B603 - using list form, not shell=True; no command injection risk
+        with subprocess.Popen(
+            cmd,
+            stderr=subprocess.PIPE,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            env=env,
+        ) as proc:
+            # proc.stderr is a pipe because PIPE was asked for, but Popen's type
+            # cannot express that, so the narrowing happens here rather than by
+            # widening filter_devpod_stderr to a None it would have no answer for.
+            pipe = proc.stderr
+            remote_status = (
+                devpod_ssh.filter_devpod_stderr(pipe, sys.stderr) if pipe is not None else None
+            )
     return devpod_ssh.interpret(proc.returncode, remote_status)
 
 
diff --git a/test/test_timing.py b/test/test_timing.py
index 90e09b2b..135af5f3 100644
--- a/test/test_timing.py
+++ b/test/test_timing.py
@@ -11,8 +11,12 @@
 """
 
 import re
+from unittest.mock import patch
+
+import pytest
 
 from devlaunch.dl import main
+from test_devpod_spawn_counts import DevpodSpawns
 
 TIMING_LINE = re.compile(r"^dl-timing: (.+) \d+\.\d{3}s$", re.MULTILINE)
 
@@ -34,3 +38,34 @@ def test_summary_ends_with_total_when_env_set(self, monkeypatch, capsys):
         monkeypatch.setenv("DEVLAUNCH_TIMING", "1")
         assert main(["--version"]) == 0
         assert timing_labels(capsys.readouterr().err) == ["total"]
+
+
+@pytest.fixture
+def spawns():
+    """A devpod stub at the subprocess boundary, background updater disabled."""
+    recorder = DevpodSpawns(["myws"])
+    with patch("devlaunch.dl.subprocess.run", side_effect=recorder):
+        with patch("devlaunch.dl.subprocess.Popen", side_effect=recorder.popen):
+            with patch("devlaunch.dl.update_cache_background"):
+                yield recorder
+
+
+class TestDevpodRoundTripsAreNamed:
+    """The summary names each devpod round trip, in the order it happened."""
+
+    def test_ls_names_its_single_list_round_trip(self, spawns, monkeypatch, capsys):
+        monkeypatch.setenv("DEVLAUNCH_TIMING", "1")
+        assert main(["--ls"]) == 0
+        assert timing_labels(capsys.readouterr().err) == ["devpod list", "total"]
+
+    def test_attach_names_every_round_trip_in_order(self, spawns, monkeypatch, capsys):
+        """The attach chain from the spawn-count tests, seen as named timings:
+        one status, the hostname ssh, then the session ssh."""
+        monkeypatch.setenv("DEVLAUNCH_TIMING", "1")
+        assert main(["myws"]) == 0
+        assert timing_labels(capsys.readouterr().err) == [
+            "devpod status",
+            "devpod ssh",
+            "devpod ssh",
+            "total",
+        ]

From c057623f7e674fe3a677db97fbbd8920bcea8ca2 Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <blooop@gmail.com>
Date: Sun, 9 Aug 2026 07:59:07 +0100
Subject: [PATCH 03/13] Name ssh, gh, and git round trips in the timing summary

The OpenSSH transport, the gh auth token read, clone-state git reads
and the ls-remote branch probe each time their spawn, so a launch
summary accounts for every chokepoint the launch waits on.
Ticket #140 slice 3.
---
 devlaunch/dl.py              | 20 ++++++-----
 devlaunch/gh_auth.py         | 24 +++++++------
 devlaunch/workspace_state.py | 19 ++++++-----
 test/test_timing.py          | 65 +++++++++++++++++++++++++++++++++++-
 4 files changed, 99 insertions(+), 29 deletions(-)

diff --git a/devlaunch/dl.py b/devlaunch/dl.py
index 1c32bc02..a5e5085b 100644
--- a/devlaunch/dl.py
+++ b/devlaunch/dl.py
@@ -1394,13 +1394,14 @@ def _git_ls_remote(owner_repo: str, *args: str) -> Optional[str]:
     """
     url = f"git@github.com:{owner_repo}.git"
     try:
-        result = subprocess.run(
-            ["git", "ls-remote", url, *args],
-            capture_output=True,
-            text=True,
-            check=False,
-            timeout=5,
-        )
+        with timing.span("git ls-remote"):
+            result = subprocess.run(
+                ["git", "ls-remote", url, *args],
+                capture_output=True,
+                text=True,
+                check=False,
+                timeout=5,
+            )
         if result.returncode == 0 and result.stdout.strip():
             return result.stdout
     except (OSError, subprocess.SubprocessError, subprocess.TimeoutExpired):
@@ -2025,8 +2026,9 @@ def run_ssh(args: List[str], env: Optional[Dict[str, str]] = None) -> subprocess
     """
     logging.debug("Running: %s", " ".join(args))
     try:
-        # nosec B603 B607 - list form, not shell=True; no command injection risk
-        return subprocess.run(list(args), check=False, env=env)
+        with timing.span("ssh"):
+            # nosec B603 B607 - list form, not shell=True; no command injection risk
+            return subprocess.run(list(args), check=False, env=env)
     except FileNotFoundError as e:
         raise SshNotInstalled(SSH_MISSING_MESSAGE) from e
 
diff --git a/devlaunch/gh_auth.py b/devlaunch/gh_auth.py
index 85cd3f27..f234bbf5 100644
--- a/devlaunch/gh_auth.py
+++ b/devlaunch/gh_auth.py
@@ -27,6 +27,7 @@
 import tempfile
 from typing import Dict, Iterator, List, Optional, Tuple
 
+from devlaunch import timing
 from devlaunch.xdg import config_home
 
 # The variable set inside the container. gh consults it before its config file.
@@ -64,17 +65,18 @@ def _token_from_gh_cli() -> Optional[str]:
     if not shutil.which("gh"):
         return None
     try:
-        # nosec B603 B607 - list form, not shell=True; no command injection risk
-        result = subprocess.run(
-            ["gh", "auth", "token"],
-            capture_output=True,
-            text=True,
-            check=False,
-            # gh must not eat stdin that belongs to the command `dl` was asked
-            # to run, and must not leave the terminal in a state of its own.
-            stdin=subprocess.DEVNULL,
-            timeout=_GH_TIMEOUT_SECONDS,
-        )
+        with timing.span("gh auth token"):
+            # nosec B603 B607 - list form, not shell=True; no command injection risk
+            result = subprocess.run(
+                ["gh", "auth", "token"],
+                capture_output=True,
+                text=True,
+                check=False,
+                # gh must not eat stdin that belongs to the command `dl` was asked
+                # to run, and must not leave the terminal in a state of its own.
+                stdin=subprocess.DEVNULL,
+                timeout=_GH_TIMEOUT_SECONDS,
+            )
     except (OSError, subprocess.SubprocessError) as e:
         logging.warning(
             "Could not read a GitHub token from gh (%s), so this workspace opens "
diff --git a/devlaunch/workspace_state.py b/devlaunch/workspace_state.py
index 0e992dcd..8f09f6f1 100644
--- a/devlaunch/workspace_state.py
+++ b/devlaunch/workspace_state.py
@@ -59,6 +59,8 @@
 from pathlib import Path
 from typing import Any, Dict, List, NoReturn, Optional, Union
 
+from devlaunch import timing
+
 logger = logging.getLogger(__name__)
 
 
@@ -274,14 +276,15 @@ class reached by a second route, and it is the fail-*open* one.
     """
     root = repo.resolve()
     try:
-        result = subprocess.run(
-            ["git", f"--git-dir={root / '.git'}", f"--work-tree={root}", *args],
-            cwd=repo,
-            capture_output=True,
-            text=True,
-            check=False,
-            timeout=30,
-        )
+        with timing.span(f"git {args[0]}" if args else "git"):
+            result = subprocess.run(
+                ["git", f"--git-dir={root / '.git'}", f"--work-tree={root}", *args],
+                cwd=repo,
+                capture_output=True,
+                text=True,
+                check=False,
+                timeout=30,
+            )
     except (OSError, subprocess.SubprocessError) as e:
         logger.debug(f"git {' '.join(args)} in {repo}: {e}")
         return GitRefused(str(e))
diff --git a/test/test_timing.py b/test/test_timing.py
index 135af5f3..6e0dbad0 100644
--- a/test/test_timing.py
+++ b/test/test_timing.py
@@ -10,12 +10,15 @@
 the CLI entry point on one side, the subprocess module on the other.
 """
 
+import io
 import re
+import subprocess
 from unittest.mock import patch
 
 import pytest
 
-from devlaunch.dl import main
+from devlaunch import gh_auth, timing, workspace_state
+from devlaunch.dl import main, remote_branch_exists, run_ssh
 from test_devpod_spawn_counts import DevpodSpawns
 
 TIMING_LINE = re.compile(r"^dl-timing: (.+) \d+\.\d{3}s$", re.MULTILINE)
@@ -69,3 +72,63 @@ def test_attach_names_every_round_trip_in_order(self, spawns, monkeypatch, capsy
             "devpod ssh",
             "total",
         ]
+
+
+@pytest.fixture
+def recording(monkeypatch):
+    """An active timing recorder, emitted into a buffer for inspection.
+
+    These tests exercise helpers below main(), so the per-command begin/emit
+    that main() does is driven here instead.
+    """
+    monkeypatch.setenv("DEVLAUNCH_TIMING", "1")
+    timing.begin()
+    buffer = io.StringIO()
+    yield buffer
+    timing.emit(buffer)
+
+
+class TestTransportAndGitGhCallsAreNamed:
+    """The other launch chokepoints show up in the summary by name."""
+
+    def test_openssh_transport_is_named(self, recording):
+        done = subprocess.CompletedProcess(["ssh", "myws.devpod"], 0)
+        with patch("devlaunch.dl.subprocess.run", return_value=done):
+            run_ssh(["ssh", "myws.devpod"])
+        timing.emit(recording)
+        assert timing_labels(recording.getvalue()) == ["ssh", "total"]
+
+    def test_gh_token_round_trip_is_named(self, recording, monkeypatch):
+        monkeypatch.setenv(gh_auth.DISABLE_VAR, "0")
+        for var in gh_auth.HOST_TOKEN_VARS:
+            monkeypatch.delenv(var, raising=False)
+        gh_auth.resolve_token.cache_clear()
+        answered = subprocess.CompletedProcess(
+            ["gh", "auth", "token"], 0, stdout="gho_" + "a" * 36 + "\n", stderr=""
+        )
+        with patch("devlaunch.gh_auth.shutil.which", return_value="/usr/bin/gh"):
+            with patch("devlaunch.gh_auth.subprocess.run", return_value=answered):
+                assert gh_auth.resolve_token() is not None
+        gh_auth.resolve_token.cache_clear()
+        timing.emit(recording)
+        assert timing_labels(recording.getvalue()) == ["gh auth token", "total"]
+
+    def test_clone_state_git_reads_are_named(self, recording, tmp_path):
+        # A directory that is not a repository still costs the rev-parse and
+        # status round trips, and those are what the summary must name.
+        workspace_state.read_clone(tmp_path)
+        timing.emit(recording)
+        assert timing_labels(recording.getvalue()) == [
+            "git rev-parse",
+            "git status",
+            "total",
+        ]
+
+    def test_remote_branch_probe_is_named(self, recording):
+        answered = subprocess.CompletedProcess(
+            ["git", "ls-remote"], 0, stdout="deadbeef\trefs/heads/main\n", stderr=""
+        )
+        with patch("devlaunch.dl.subprocess.run", return_value=answered):
+            assert remote_branch_exists("owner/repo", "main")
+        timing.emit(recording)
+        assert timing_labels(recording.getvalue()) == ["git ls-remote", "total"]

From 8917fdc59af85f25f6816315b51ba58993b00452 Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <blooop@gmail.com>
Date: Sun, 9 Aug 2026 08:00:08 +0100
Subject: [PATCH 04/13] Add a median wall-time bench harness
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

scripts/bench_launch.py runs a command N times and reports the median,
refusing to report one over a failing run — before/after perf numbers
are one command per side. Ticket #140 slice 4.
---
 scripts/bench_launch.py | 69 +++++++++++++++++++++++++++++++++++++++++
 test/test_timing.py     | 28 +++++++++++++++++
 2 files changed, 97 insertions(+)
 create mode 100644 scripts/bench_launch.py

diff --git a/scripts/bench_launch.py b/scripts/bench_launch.py
new file mode 100644
index 00000000..938d2087
--- /dev/null
+++ b/scripts/bench_launch.py
@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Run a command N times and report the median wall time.
+
+The repeatable half of the timing instrument (ticket #140): a before/after
+perf comparison is this script run once on each side of a change, e.g.
+
+    python scripts/bench_launch.py -n 5 -- dl-next owner/repo -- true
+
+Wall time per run and the median go to stdout; the command's own output is
+left on the terminal so a hung launch is visible. If any run exits non-zero
+the bench stops with that run's exit code and reports no median — a failing
+launch's time is not a number to compare against.
+
+Standard library only, on purpose: the instrument must not cost the project
+a dependency.
+"""
+
+import argparse
+import statistics
+import subprocess
+import sys
+import time
+from typing import List
+
+
+def bench(n: int, command: List[str]) -> int:
+    """Run *command* *n* times, print each wall time and the median.
+
+    Returns the exit code for the process: 0 after n clean runs, otherwise
+    the first failing run's exit code.
+    """
+    durations = []
+    for i in range(1, n + 1):
+        start = time.perf_counter()
+        # nosec B603 - list form, not shell=True; the command is the user's own argv
+        result = subprocess.run(command, check=False)
+        elapsed = time.perf_counter() - start
+        if result.returncode != 0:
+            print(
+                f"run {i}/{n} exited {result.returncode}; no median over a failing command",
+                file=sys.stderr,
+            )
+            return result.returncode
+        print(f"run {i}/{n}: {elapsed:.3f}s")
+        durations.append(elapsed)
+    print(f"median of {n}: {statistics.median(durations):.3f}s")
+    return 0
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Run a command N times and report the median wall time."
+    )
+    parser.add_argument("-n", type=int, default=5, help="number of runs (default: 5)")
+    parser.add_argument(
+        "command",
+        nargs=argparse.REMAINDER,
+        metavar="-- command...",
+        help="the command to time, after a `--`",
+    )
+    args = parser.parse_args(argv)
+    command = args.command[1:] if args.command[:1] == ["--"] else args.command
+    if not command:
+        parser.error("no command given; usage: bench_launch.py -n 5 -- dl <ws> -- true")
+    return bench(args.n, command)
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/test/test_timing.py b/test/test_timing.py
index 6e0dbad0..46bc2879 100644
--- a/test/test_timing.py
+++ b/test/test_timing.py
@@ -13,6 +13,8 @@
 import io
 import re
 import subprocess
+import sys
+from pathlib import Path
 from unittest.mock import patch
 
 import pytest
@@ -132,3 +134,29 @@ def test_remote_branch_probe_is_named(self, recording):
             assert remote_branch_exists("owner/repo", "main")
         timing.emit(recording)
         assert timing_labels(recording.getvalue()) == ["git ls-remote", "total"]
+
+
+BENCH = Path(__file__).parent.parent / "scripts" / "bench_launch.py"
+
+
+def run_bench(*argv: str) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        [sys.executable, str(BENCH), *argv], capture_output=True, text=True, check=False
+    )
+
+
+class TestBenchHarness:
+    """One command per side of a before/after: N runs, a median."""
+
+    def test_reports_each_run_and_the_median(self):
+        result = run_bench("-n", "3", "--", sys.executable, "-c", "pass")
+        assert result.returncode == 0
+        assert len(re.findall(r"^run \d+/3: \d+\.\d{3}s$", result.stdout, re.M)) == 3
+        assert re.search(r"^median of 3: \d+\.\d{3}s$", result.stdout, re.M)
+
+    def test_fails_loudly_when_the_command_fails(self):
+        """A failing launch's time is not a number to compare against, so the
+        bench must not report a median over it."""
+        result = run_bench("-n", "3", "--", sys.executable, "-c", "raise SystemExit(7)")
+        assert result.returncode != 0
+        assert "median" not in result.stdout

From f2593d68c07a65548079ef21fc2ebb0c285ff2d1 Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <blooop@gmail.com>
Date: Sun, 9 Aug 2026 08:02:26 +0100
Subject: [PATCH 05/13] Document the timing switch and bench command

README gains a 'Measuring launch time' section next to the perf notes,
and 'pixi run bench' wraps the harness for devcontainer use.
Ticket #140 slice 5.
---
 README.md           | 30 ++++++++++++++++++++++++++++++
 pyproject.toml      |  2 ++
 test/test_timing.py |  5 +++--
 3 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index e986228f..a2614f65 100644
--- a/README.md
+++ b/README.md
@@ -614,6 +614,36 @@ dl blooop/devlaunch stop         # Stop workspace
 - **Fast Autocomplete**: Completion cache for ~3ms response time (vs ~700ms without cache)
 - **One Round-Trip Per Question**: every `devpod` call costs ~0.45s, far more than `dl` itself, so a command reads the workspace list at most once — and `dl <ws> -- <cmd>` skips the extra round-trip that names an interactive prompt, since a one-shot command has none
 
+## Measuring launch time
+
+Every `dl` process can account for its own wall time. Set `DEVLAUNCH_TIMING=1`
+and the command ends with one summary on stderr, naming each subprocess round
+trip (`devpod status`, `devpod ssh`, `gh auth token`, `git ls-remote`, ...) and
+the total:
+
+```bash
+$ DEVLAUNCH_TIMING=1 dl myws -- true
+dl-timing: devpod status 0.412s
+dl-timing: devpod ssh 0.583s
+dl-timing: devpod ssh 1.102s
+dl-timing: total 2.201s
+```
+
+With the variable unset (or `0`) there is no output and nothing is recorded.
+The summary goes to stderr, after the command's own output, so it composes
+with one-shot commands.
+
+For before/after numbers, `scripts/bench_launch.py` runs a command N times and
+reports the median — one command per side of a change:
+
+```bash
+python scripts/bench_launch.py -n 5 -- dl-next owner/repo -- true   # warm launch
+```
+
+(`pixi run bench -n 5 -- ...` inside the devcontainer.) A cold launch is the
+same command after `dl-next owner/repo delete`. The bench refuses to report a
+median if any run fails, so a broken launch cannot pass as a fast one.
+
 ## Worktree Backend
 
 For git repositories, devlaunch uses an efficient worktree backend by default:
diff --git a/pyproject.toml b/pyproject.toml
index 476981b6..87587564 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -90,6 +90,8 @@ lint = { depends-on = ["ruff-lint", "ty", "pylint"] }
 style = { depends-on = ["format", "lint"] }
 commit-format = "git commit -a -m'autoformat code' || true"
 test = "pytest"
+# Median wall time of a command over N runs; see "Measuring launch time" in README.md.
+bench = "python scripts/bench_launch.py"
 # Needs a real Docker daemon and a real devpod. Inside this repo's devcontainer
 # that daemon is the container's own, via the docker-in-docker feature; on an
 # ephemeral CI runner or a machine you do not mind writing to, it is the host's.
diff --git a/test/test_timing.py b/test/test_timing.py
index 46bc2879..aeb92634 100644
--- a/test/test_timing.py
+++ b/test/test_timing.py
@@ -55,15 +55,16 @@ def spawns():
                 yield recorder
 
 
+@pytest.mark.usefixtures("spawns")
 class TestDevpodRoundTripsAreNamed:
     """The summary names each devpod round trip, in the order it happened."""
 
-    def test_ls_names_its_single_list_round_trip(self, spawns, monkeypatch, capsys):
+    def test_ls_names_its_single_list_round_trip(self, monkeypatch, capsys):
         monkeypatch.setenv("DEVLAUNCH_TIMING", "1")
         assert main(["--ls"]) == 0
         assert timing_labels(capsys.readouterr().err) == ["devpod list", "total"]
 
-    def test_attach_names_every_round_trip_in_order(self, spawns, monkeypatch, capsys):
+    def test_attach_names_every_round_trip_in_order(self, monkeypatch, capsys):
         """The attach chain from the spawn-count tests, seen as named timings:
         one status, the hostname ssh, then the session ssh."""
         monkeypatch.setenv("DEVLAUNCH_TIMING", "1")

From c5e1c854e34c40310528acd45d3acd76a5648dfa Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <blooop@gmail.com>
Date: Sun, 9 Aug 2026 08:04:06 +0100
Subject: [PATCH 06/13] Mark bench_launch.py executable to match its shebang

---
 scripts/bench_launch.py | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 mode change 100644 => 100755 scripts/bench_launch.py

diff --git a/scripts/bench_launch.py b/scripts/bench_launch.py
old mode 100644
new mode 100755

From f3b6ec94da2d1e8a114a4dafe0f872d2e751cdc1 Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <blooop@gmail.com>
Date: Sun, 9 Aug 2026 11:55:17 +0100
Subject: [PATCH 07/13] Scrub DEVLAUNCH_TIMING so the suite is hermetic against
 its own switch

The instrument this PR adds is one a perf developer leaves exported in their
shell, and the next thing they do is run the tests: with DEVLAUNCH_TIMING=1
set, dl appends a timing summary to stderr and four existing tests that assert
stderr is empty go red (4 failed, 1163 passed), including
test_version_never_touches_devpod.

An autouse fixture deletes the variable for every test, so the switch is off
unless a test turns it on itself. Pinned by running a slice of the suite in a
child process with the variable exported -- the same way a developer meets it,
rather than by asserting on the fixture.
---
 test/conftest.py    | 15 ++++++++++++++-
 test/test_timing.py | 28 ++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/test/conftest.py b/test/conftest.py
index 80832625..5494c435 100644
--- a/test/conftest.py
+++ b/test/conftest.py
@@ -20,7 +20,7 @@
 # Import fixtures from the fixtures package to make them available to all tests
 # Note: pytest automatically discovers fixtures in conftest.py
 # noqa: E402 - imports must come after sys.path modification
-from devlaunch import dl, gh_auth  # noqa: E402
+from devlaunch import dl, gh_auth, timing  # noqa: E402
 from fixtures.git_fixtures import (  # noqa: E402
     isolated_devlaunch_env,
     local_git_repo,
@@ -146,6 +146,19 @@ def fresh_clone_manager():
     dl.invalidate_clone_manager()
 
 
+@pytest.fixture(autouse=True)
+def timing_switch_off(monkeypatch):
+    """Start every test with the timing switch off, whatever the shell says.
+
+    DEVLAUNCH_TIMING makes dl append a timing summary to stderr, and a good few
+    tests assert stderr is empty. The developers this instrument exists for are
+    the ones who will have it exported when they run the suite, so the suite
+    scrubs it rather than going red in their shell. A test that wants the switch
+    on sets it itself.
+    """
+    monkeypatch.delenv(timing.ENV_VAR, raising=False)
+
+
 def pytest_configure():
     """Scope this run's devpod state.
 
diff --git a/test/test_timing.py b/test/test_timing.py
index aeb92634..60867c07 100644
--- a/test/test_timing.py
+++ b/test/test_timing.py
@@ -11,6 +11,7 @@
 """
 
 import io
+import os
 import re
 import subprocess
 import sys
@@ -31,6 +32,33 @@ def timing_labels(stderr: str):
     return TIMING_LINE.findall(stderr)
 
 
+REPO_ROOT = Path(__file__).parent.parent
+
+
+class TestSuiteIsHermeticAgainstTheSwitch:
+    """The suite must pass for a developer who has DEVLAUNCH_TIMING exported.
+
+    The people this instrument exists for are exactly the people who will leave
+    it on in their shell, and the next thing they do is run the tests. A switch
+    whose own suite goes red when the switch is on is a trap laid for the agent
+    debugging a launch a month from now, so the property is pinned by running a
+    slice of the suite in a child process with the variable exported -- the same
+    way a developer would meet it.
+    """
+
+    def test_suite_passes_with_the_switch_exported(self):
+        affected = "test/test_dl.py::TestMissingDevpodBinary"
+        result = subprocess.run(
+            [sys.executable, "-m", "pytest", affected, "-q", "-p", "no:randomly"],
+            cwd=REPO_ROOT,
+            env={**os.environ, "DEVLAUNCH_TIMING": "1"},
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        assert result.returncode == 0, result.stdout[-2000:]
+
+
 class TestSummaryGate:
     """Timing lines appear iff DEVLAUNCH_TIMING is set."""
 

From ea26a3a5445ba044e6824cdbcac83a05801289b6 Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <blooop@gmail.com>
Date: Sun, 9 Aug 2026 11:56:47 +0100
Subject: [PATCH 08/13] Reset per run, so a cold median is measured cold

#140's "Done when": "a contributor can produce a median warm-launch and
cold-launch wall time with one documented command."

The documented cold recipe was one `delete` followed by `-n 5`, and the harness
had no per-run setup: run 1 was cold and runs 2..5 were warm, so the printed
"median of 5" was a warm number under a cold label. That is worse than a
missing feature here -- this harness is what the rest of the perf map quotes,
and it biased in the direction that makes a change look better than it is.

`--before` runs a reset before every timed run and does not count its time, so
all N runs start from the same state. A reset that exits non-zero stops the
bench with no median: a run whose starting condition was never established is
not a measurement of that condition, and reporting it would be labelling a
number with a condition nobody checked.

Also rejects `-n 0` (and negatives) at the argument boundary instead of dying
inside statistics.median([]) -- there is no median of nothing to return.

README documents the cold recipe with the per-run reset, and scopes
XDG_CACHE_HOME so the reset deletes the bench's workspace, not yours.
---
 README.md               | 25 ++++++++++++++++---
 scripts/bench_launch.py | 54 +++++++++++++++++++++++++++++++++++------
 test/test_timing.py     | 46 +++++++++++++++++++++++++++++++++++
 3 files changed, 115 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index a2614f65..91207ae5 100644
--- a/README.md
+++ b/README.md
@@ -640,9 +640,28 @@ reports the median — one command per side of a change:
 python scripts/bench_launch.py -n 5 -- dl-next owner/repo -- true   # warm launch
 ```
 
-(`pixi run bench -n 5 -- ...` inside the devcontainer.) A cold launch is the
-same command after `dl-next owner/repo delete`. The bench refuses to report a
-median if any run fails, so a broken launch cannot pass as a fast one.
+(`pixi run bench -n 5 -- ...` inside the devcontainer.) The bench refuses to
+report a median if any run fails, so a broken launch cannot pass as a fast one.
+
+### A cold median needs a reset per run
+
+A cold launch measured once is one sample, and a cold launch deleted once and
+then benched five times is one cold run plus four warm ones — a warm median
+under a cold label. `--before` runs a reset command before every timed run and
+does not count its time, so all N runs start cold:
+
+```bash
+XDG_CACHE_HOME=/tmp/dl-bench/cache \
+python scripts/bench_launch.py -n 5 \
+  --before 'dl-next owner/repo delete' \
+  -- dl-next owner/repo -- true                                     # cold launch
+```
+
+Scope `XDG_CACHE_HOME` (that variable only — see `dev.sh`) so the reset deletes
+the bench's own workspace rather than one you are working in. If a reset exits
+non-zero the bench stops and prints no median: a run whose cold state was never
+established is not a cold measurement, and a number labelled cold has to have
+been taken cold.
 
 ## Worktree Backend
 
diff --git a/scripts/bench_launch.py b/scripts/bench_launch.py
index 938d2087..507485c9 100755
--- a/scripts/bench_launch.py
+++ b/scripts/bench_launch.py
@@ -11,26 +11,46 @@
 the bench stops with that run's exit code and reports no median — a failing
 launch's time is not a number to compare against.
 
+`--before` runs a reset command before each timed run, without counting its
+time. That is what makes a *cold* median possible: the state a cold launch
+starts from has to be re-established before every run, or runs 2..N are warm
+and the median is a warm number under a cold label. If a reset fails the bench
+stops with no median, for the same reason a failing run reports none — a run
+whose starting condition was never established is not a measurement of it.
+
 Standard library only, on purpose: the instrument must not cost the project
 a dependency.
 """
 
 import argparse
+import shlex
 import statistics
 import subprocess
 import sys
 import time
-from typing import List
+from typing import List, Optional
 
 
-def bench(n: int, command: List[str]) -> int:
+def bench(n: int, command: List[str], before: Optional[List[str]] = None) -> int:
     """Run *command* *n* times, print each wall time and the median.
 
-    Returns the exit code for the process: 0 after n clean runs, otherwise
-    the first failing run's exit code.
+    *before*, when given, runs before each timed run and is not timed.
+
+    Returns the exit code for the process: 0 after n clean runs, otherwise the
+    exit code of the first run — or reset — that failed.
     """
     durations = []
     for i in range(1, n + 1):
+        if before is not None:
+            # nosec B603 - list form, not shell=True; the reset is the user's own argv
+            reset = subprocess.run(before, check=False)
+            if reset.returncode != 0:
+                print(
+                    f"reset before run {i}/{n} exited {reset.returncode}; "
+                    "no median over runs whose starting state was not established",
+                    file=sys.stderr,
+                )
+                return reset.returncode
         start = time.perf_counter()
         # nosec B603 - list form, not shell=True; the command is the user's own argv
         result = subprocess.run(command, check=False)
@@ -43,15 +63,32 @@ def bench(n: int, command: List[str]) -> int:
             return result.returncode
         print(f"run {i}/{n}: {elapsed:.3f}s")
         durations.append(elapsed)
-    print(f"median of {n}: {statistics.median(durations):.3f}s")
+    median = statistics.median(durations)
+    print(f"median of {n}: {median:.3f}s")
     return 0
 
 
+def positive_int(text: str) -> int:
+    """A run count there is a median of: one or more."""
+    value = int(text)
+    if value < 1:
+        raise argparse.ArgumentTypeError(f"need at least one run, got {value}")
+    return value
+
+
 def main(argv=None) -> int:
     parser = argparse.ArgumentParser(
         description="Run a command N times and report the median wall time."
     )
-    parser.add_argument("-n", type=int, default=5, help="number of runs (default: 5)")
+    parser.add_argument("-n", type=positive_int, default=5, help="number of runs (default: 5)")
+    parser.add_argument(
+        "--before",
+        metavar="RESET",
+        help=(
+            "shell-quoted command to run before each timed run, untimed; "
+            "use it to re-establish a cold launch's starting state every run"
+        ),
+    )
     parser.add_argument(
         "command",
         nargs=argparse.REMAINDER,
@@ -62,7 +99,10 @@ def main(argv=None) -> int:
     command = args.command[1:] if args.command[:1] == ["--"] else args.command
     if not command:
         parser.error("no command given; usage: bench_launch.py -n 5 -- dl <ws> -- true")
-    return bench(args.n, command)
+    before = shlex.split(args.before) if args.before else None
+    if args.before and not before:
+        parser.error("--before given an empty command")
+    return bench(args.n, command, before)
 
 
 if __name__ == "__main__":
diff --git a/test/test_timing.py b/test/test_timing.py
index 60867c07..e0fecdd9 100644
--- a/test/test_timing.py
+++ b/test/test_timing.py
@@ -13,6 +13,7 @@
 import io
 import os
 import re
+import shlex
 import subprocess
 import sys
 from pathlib import Path
@@ -189,3 +190,48 @@ def test_fails_loudly_when_the_command_fails(self):
         result = run_bench("-n", "3", "--", sys.executable, "-c", "raise SystemExit(7)")
         assert result.returncode != 0
         assert "median" not in result.stdout
+
+    def test_rejects_a_run_count_below_one(self):
+        """There is no median of nothing, so the bench refuses to be asked for
+        one rather than dying inside statistics."""
+        result = run_bench("-n", "0", "--", sys.executable, "-c", "pass")
+        assert result.returncode == 2
+        assert "Traceback" not in result.stderr
+
+
+class TestColdBench:
+    """#140's "Done when": *a contributor can produce a median warm-launch and
+    cold-launch wall time with one documented command*.
+
+    A cold median needs the cold condition re-established before *every* timed
+    run: delete once and bench N times and runs 2..N are warm, so the printed
+    median is a warm number wearing a cold label. `--before` is that per-run
+    reset, and the bench refuses to report a median when the reset fails --
+    a run whose cold condition was never established is not a cold measurement.
+    """
+
+    def before_writing(self, marker: Path) -> str:
+        return shlex.join([sys.executable, "-c", f"open({str(marker)!r}, 'a').write('x')"])
+
+    def test_the_reset_runs_once_before_every_timed_run(self, tmp_path):
+        marker = tmp_path / "resets"
+        result = run_bench(
+            "-n", "3", "--before", self.before_writing(marker), "--", sys.executable, "-c", "pass"
+        )
+        assert result.returncode == 0, result.stderr
+        assert marker.read_text() == "xxx"
+
+    def test_the_reset_is_not_counted_as_launch_time(self):
+        """The number reported is the launch's, not the teardown's."""
+        slow_reset = shlex.join([sys.executable, "-c", "import time; time.sleep(0.5)"])
+        result = run_bench("-n", "1", "--before", slow_reset, "--", sys.executable, "-c", "pass")
+        assert result.returncode == 0, result.stderr
+        run = re.search(r"^run 1/1: (\d+\.\d{3})s", result.stdout, re.M)
+        assert run is not None, result.stdout
+        assert float(run.group(1)) < 0.4
+
+    def test_refuses_a_median_when_the_reset_fails(self):
+        failing_reset = shlex.join([sys.executable, "-c", "raise SystemExit(3)"])
+        result = run_bench("-n", "3", "--before", failing_reset, "--", sys.executable, "-c", "pass")
+        assert result.returncode != 0
+        assert "median" not in result.stdout

From 4f38b3c37ea4ae12a2a6435acc43961a2cdcffc7 Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <blooop@gmail.com>
Date: Sun, 9 Aug 2026 11:57:22 +0100
Subject: [PATCH 09/13] Say which clock each timing number is measured on

Two instruments now report the time of one launch and they do not measure the
same span: `dl-timing: total` starts at the top of main(), while the bench's
wall clock starts outside the process and so also contains interpreter startup
and this package's imports. Measured here on `dl --version`, total reported
0.001s against a bench median of 0.056s over 5 runs -- the ~55ms is startup,
not launch work.

#140 asks only for "total main() time" and that is what total is, so this is
not a change of measurement; it is a change of label. Every downstream perf
ticket on the map will quote both numbers, and side by side they invite the
assumption that they are the same quantity. Each line now names its own epoch
where it is printed, and the README says the difference out loud rather than
leaving a reader to discover it as a 50ms mystery.
---
 README.md               | 12 +++++++++++-
 devlaunch/timing.py     | 10 +++++++++-
 scripts/bench_launch.py |  8 +++++++-
 test/test_timing.py     | 31 +++++++++++++++++++++++++++++--
 4 files changed, 56 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 91207ae5..e72f1825 100644
--- a/README.md
+++ b/README.md
@@ -626,7 +626,7 @@ $ DEVLAUNCH_TIMING=1 dl myws -- true
 dl-timing: devpod status 0.412s
 dl-timing: devpod ssh 0.583s
 dl-timing: devpod ssh 1.102s
-dl-timing: total 2.201s
+dl-timing: total 2.201s (in-process, excluding interpreter startup)
 ```
 
 With the variable unset (or `0`) there is no output and nothing is recorded.
@@ -663,6 +663,16 @@ non-zero the bench stops and prints no median: a run whose cold state was never
 established is not a cold measurement, and a number labelled cold has to have
 been taken cold.
 
+### The two numbers are not the same quantity
+
+`dl-timing: total` starts at the top of `main()`; the bench's wall clock starts
+outside the process, so it also contains interpreter startup and this package's
+imports. Measured here on `dl --version`, `total` reported `0.001s` against a
+bench median of `0.056s` over 5 runs — the ~55 ms difference is startup, not
+launch work. Both lines say which clock they are. Quote one instrument on both
+sides of a change; don't compare a `total` on one side with a bench median on
+the other.
+
 ## Worktree Backend
 
 For git repositories, devlaunch uses an efficient worktree backend by default:
diff --git a/devlaunch/timing.py b/devlaunch/timing.py
index 7085d994..c66e52af 100644
--- a/devlaunch/timing.py
+++ b/devlaunch/timing.py
@@ -24,6 +24,14 @@
 
 ENV_VAR = "DEVLAUNCH_TIMING"
 
+# `total` runs from the top of main(), so it is a smaller quantity than the wall
+# time an outside stopwatch (`scripts/bench_launch.py`, `/usr/bin/time`) reports
+# for the same command: the interpreter's own startup and this package's imports
+# happen before main() is entered and are outside it. The two get quoted side by
+# side in perf write-ups, so each line carries its epoch rather than leaving the
+# reader to assume they are the same measurement.
+TOTAL_EPOCH = "in-process, excluding interpreter startup"
+
 
 @dataclass
 class _Recorder:
@@ -113,4 +121,4 @@ def emit(stream: Optional[TextIO] = None) -> None:
     total = time.perf_counter() - recorder.started
     for label, seconds in recorder.entries:
         print(f"dl-timing: {label} {seconds:.3f}s", file=out)
-    print(f"dl-timing: total {total:.3f}s", file=out)
+    print(f"dl-timing: total {total:.3f}s ({TOTAL_EPOCH})", file=out)
diff --git a/scripts/bench_launch.py b/scripts/bench_launch.py
index 507485c9..a76dd074 100755
--- a/scripts/bench_launch.py
+++ b/scripts/bench_launch.py
@@ -18,6 +18,12 @@
 stops with no median, for the same reason a failing run reports none — a run
 whose starting condition was never established is not a measurement of it.
 
+The wall time here is measured from outside the process, so it includes
+interpreter startup and imports. dl's own `dl-timing: total` line starts inside
+main() and excludes them, so the two numbers are close but not the same
+quantity; each line says which it is, and a before/after comparison should
+quote one instrument on both sides.
+
 Standard library only, on purpose: the instrument must not cost the project
 a dependency.
 """
@@ -64,7 +70,7 @@ def bench(n: int, command: List[str], before: Optional[List[str]] = None) -> int
         print(f"run {i}/{n}: {elapsed:.3f}s")
         durations.append(elapsed)
     median = statistics.median(durations)
-    print(f"median of {n}: {median:.3f}s")
+    print(f"median of {n}: {median:.3f}s (wall clock, including interpreter startup)")
     return 0
 
 
diff --git a/test/test_timing.py b/test/test_timing.py
index e0fecdd9..12cb5540 100644
--- a/test/test_timing.py
+++ b/test/test_timing.py
@@ -25,7 +25,9 @@
 from devlaunch.dl import main, remote_branch_exists, run_ssh
 from test_devpod_spawn_counts import DevpodSpawns
 
-TIMING_LINE = re.compile(r"^dl-timing: (.+) \d+\.\d{3}s$", re.MULTILINE)
+# The `total` line carries a trailing note naming which clock it is; the
+# per-round-trip lines do not, so the note is optional here.
+TIMING_LINE = re.compile(r"^dl-timing: (.+?) \d+\.\d{3}s(?: \(.*\))?$", re.MULTILINE)
 
 
 def timing_labels(stderr: str):
@@ -73,6 +75,18 @@ def test_summary_ends_with_total_when_env_set(self, monkeypatch, capsys):
         assert main(["--version"]) == 0
         assert timing_labels(capsys.readouterr().err) == ["total"]
 
+    def test_total_says_which_clock_it_is(self, monkeypatch, capsys):
+        """`total` is measured from inside main(), so it is smaller than the
+        wall time the bench harness reports for the same command. The line says
+        so, so a reader quoting both does not take them for one number."""
+        monkeypatch.setenv("DEVLAUNCH_TIMING", "1")
+        assert main(["--version"]) == 0
+        assert re.search(
+            r"^dl-timing: total \d+\.\d{3}s \(in-process, excluding interpreter startup\)$",
+            capsys.readouterr().err,
+            re.M,
+        )
+
 
 @pytest.fixture
 def spawns():
@@ -182,7 +196,20 @@ def test_reports_each_run_and_the_median(self):
         result = run_bench("-n", "3", "--", sys.executable, "-c", "pass")
         assert result.returncode == 0
         assert len(re.findall(r"^run \d+/3: \d+\.\d{3}s$", result.stdout, re.M)) == 3
-        assert re.search(r"^median of 3: \d+\.\d{3}s$", result.stdout, re.M)
+        assert re.search(r"^median of 3: \d+\.\d{3}s", result.stdout, re.M)
+
+    def test_the_median_says_which_clock_it_is(self):
+        """Two instruments time the same launch and do not measure the same
+        span: this one runs the clock from outside the process, so interpreter
+        startup and imports are in the number; dl's own `total` starts inside
+        main() and they are not. Downstream tickets will quote both side by
+        side, so each number names its own epoch where it is printed."""
+        result = run_bench("-n", "1", "--", sys.executable, "-c", "pass")
+        assert re.search(
+            r"^median of 1: \d+\.\d{3}s \(wall clock, including interpreter startup\)$",
+            result.stdout,
+            re.M,
+        )
 
     def test_fails_loudly_when_the_command_fails(self):
         """A failing launch's time is not a number to compare against, so the

From 5bfd2dedc5267d7fd9dff268280f565e2264a99a Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <austin.gregg-smith@bearrobotics.ai>
Date: Fri, 14 Aug 2026 07:41:02 +0100
Subject: [PATCH 10/13] Build the span out of contextlib instead of two
 hand-written classes

`_NoSpan`/`_NOOP_SPAN` is `contextlib.nullcontext()` under another name, and
`_Span` is a `@contextlib.contextmanager` with more ceremony: the `__slots__`
on it only buys anything when timing is ON, which is exactly when the caller
is already waiting ~450ms on devpod. Both go, and the module drops from 124
lines to 91 with the behaviour unchanged -- the PR's own test_timing.py from
before this commit still passes against it untouched.

Recording moves into a `finally`, which is what `__exit__` was doing: a spawn
that failed still took time, and dropping it would make the parts add up to
less than the total.
---
 devlaunch/timing.py | 103 +++++++++++++++-----------------------------
 1 file changed, 35 insertions(+), 68 deletions(-)

diff --git a/devlaunch/timing.py b/devlaunch/timing.py
index c66e52af..e40652e5 100644
--- a/devlaunch/timing.py
+++ b/devlaunch/timing.py
@@ -1,91 +1,49 @@
 """Env-gated wall-clock timing for dl's subprocess round trips.
 
 Set ``DEVLAUNCH_TIMING=1`` and every dl process ends with one summary on
-stderr: one ``dl-timing: <label> <seconds>s`` line per recorded subprocess
-call, then a ``total`` line for the whole command. With the variable unset
-(or ``0``) nothing is recorded and nothing is printed — the hot path must not
-pay for its own thermometer, so the off state is a single ``None`` check.
-
-stderr because stdout is parsed by the completion machinery, and one summary
-per process (rather than a line per event as it happens) so the output
-composes with one-shot commands: the numbers arrive after the command's own
-output, not interleaved with it.
-
-The on/off state is one optional recorder, not a flag plus fields that must
-agree with it: when timing is off there is nothing to hold, and every code
-path that records goes through the same ``span`` gate.
+stderr: a ``dl-timing: <label> <seconds>s`` line per recorded subprocess call,
+then a ``total`` for the whole command. Unset (or ``0``) records nothing and
+prints nothing — the hot path must not pay for its own thermometer, so the off
+state is a single ``None`` check. stderr because stdout is parsed by the
+completion machinery, and one summary at the end rather than a line per event,
+so the numbers land after the command's own output, not interleaved with it.
 """
 
+import contextlib
 import os
 import sys
 import time
 from dataclasses import dataclass, field
-from typing import List, Optional, TextIO, Tuple
+from typing import Iterator, List, Optional, TextIO, Tuple
 
 ENV_VAR = "DEVLAUNCH_TIMING"
 
 # `total` runs from the top of main(), so it is a smaller quantity than the wall
-# time an outside stopwatch (`scripts/bench_launch.py`, `/usr/bin/time`) reports
-# for the same command: the interpreter's own startup and this package's imports
-# happen before main() is entered and are outside it. The two get quoted side by
-# side in perf write-ups, so each line carries its epoch rather than leaving the
-# reader to assume they are the same measurement.
+# time an outside stopwatch (`scripts/bench_launch.py`) reports for the same
+# command: interpreter startup and this package's imports happen before main().
+# The two get quoted side by side, so each line carries its epoch.
 TOTAL_EPOCH = "in-process, excluding interpreter startup"
 
 
 @dataclass
 class _Recorder:
-    """Wall-clock records for one dl process: a start instant and spans."""
+    """One dl process's records: a start instant and the spans since."""
 
     started: float
     entries: List[Tuple[str, float]] = field(default_factory=list)
 
 
+# On/off is this one optional recorder, not a flag plus fields that would have
+# to agree with it: off, there is nothing to hold.
 _recorder: Optional[_Recorder] = None
 
 
-class _Span:
-    """Times one ``with`` block and records it, exceptions included.
-
-    A spawn that failed still took time, and a summary that silently dropped
-    it would make the remaining numbers add up to less than the total.
-    """
-
-    __slots__ = ("_recorder", "_label", "_start")
-
-    def __init__(self, recorder: _Recorder, label: str):
-        self._recorder = recorder
-        self._label = label
-        self._start = 0.0
-
-    def __enter__(self) -> "_Span":
-        self._start = time.perf_counter()
-        return self
-
-    def __exit__(self, *_exc) -> bool:
-        self._recorder.entries.append((self._label, time.perf_counter() - self._start))
-        return False
-
-
-class _NoSpan:
-    """The span handed out when timing is off: enter, exit, remember nothing."""
-
-    def __enter__(self) -> "_NoSpan":
-        return self
-
-    def __exit__(self, *_exc) -> bool:
-        return False
-
-
-_NOOP_SPAN = _NoSpan()
-
-
 def begin() -> None:
-    """Start recording for this process iff DEVLAUNCH_TIMING asks for it.
+    """Start recording iff DEVLAUNCH_TIMING asks for it.
 
-    Called once at the top of main(). Replaces any recorder left over from an
-    earlier main() call in the same process (a test, a shell wrapper), so one
-    command's spans never leak into the next command's summary.
+    Called once at the top of main(), replacing any recorder left from an
+    earlier main() in the same process, so one command's spans never leak into
+    the next command's summary.
     """
     global _recorder  # pylint: disable=global-statement
     if os.environ.get(ENV_VAR, "").strip() in ("", "0"):
@@ -94,20 +52,29 @@ def begin() -> None:
     _recorder = _Recorder(started=time.perf_counter())
 
 
-def span(label: str):
-    """A context manager timing one subprocess round trip as *label*.
+@contextlib.contextmanager
+def _record(recorder: _Recorder, label: str) -> Iterator[None]:
+    """Time the block, recording in ``finally`` and re-raising: a spawn that
+    failed still took time, and dropping it would make the parts add up to
+    less than the total."""
+    start = time.perf_counter()
+    try:
+        yield
+    finally:
+        recorder.entries.append((label, time.perf_counter() - start))
 
-    Free when timing is off: no allocation, no clock read, just the shared
-    no-op span.
-    """
+
+def span(label: str):
+    """Time one subprocess round trip as *label*; when timing is off, hand back
+    the stdlib no-op instead — no clock read, nothing recorded."""
     recorder = _recorder
     if recorder is None:
-        return _NOOP_SPAN
-    return _Span(recorder, label)
+        return contextlib.nullcontext()
+    return _record(recorder, label)
 
 
 def emit(stream: Optional[TextIO] = None) -> None:
-    """Write the summary and stop recording; silent when recording never began.
+    """Write the summary and stop recording; silent if recording never began.
 
     *stream* defaults to sys.stderr resolved now, not at import, so capture
     fixtures and redirections see the output.

From 3996c1ebbd090669eb304c7c4b2a77fdba9b8d84 Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <austin.gregg-smith@bearrobotics.ai>
Date: Fri, 14 Aug 2026 07:41:07 +0100
Subject: [PATCH 11/13] Drop the workspace_state span

It measures ~3ms of a ~2000ms launch, so it is below the noise the summary
exists to find. It was also the only span with a computed label expression,
and the only thing that pulled a package-internal import into a module that
is otherwise dependency-free -- both costs paid for a number nobody reads.

workspace_state.py is now byte-identical to main again, #174's
`--git-dir`/`--work-tree` argv included.
---
 devlaunch/workspace_state.py | 19 ++++++++-----------
 1 file changed, 8 insertions(+), 11 deletions(-)

diff --git a/devlaunch/workspace_state.py b/devlaunch/workspace_state.py
index 8f09f6f1..0e992dcd 100644
--- a/devlaunch/workspace_state.py
+++ b/devlaunch/workspace_state.py
@@ -59,8 +59,6 @@
 from pathlib import Path
 from typing import Any, Dict, List, NoReturn, Optional, Union
 
-from devlaunch import timing
-
 logger = logging.getLogger(__name__)
 
 
@@ -276,15 +274,14 @@ class reached by a second route, and it is the fail-*open* one.
     """
     root = repo.resolve()
     try:
-        with timing.span(f"git {args[0]}" if args else "git"):
-            result = subprocess.run(
-                ["git", f"--git-dir={root / '.git'}", f"--work-tree={root}", *args],
-                cwd=repo,
-                capture_output=True,
-                text=True,
-                check=False,
-                timeout=30,
-            )
+        result = subprocess.run(
+            ["git", f"--git-dir={root / '.git'}", f"--work-tree={root}", *args],
+            cwd=repo,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+        )
     except (OSError, subprocess.SubprocessError) as e:
         logger.debug(f"git {' '.join(args)} in {repo}: {e}")
         return GitRefused(str(e))

From 9dfb4cf70a1670a9150771f86dd6b99d1c564173 Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <austin.gregg-smith@bearrobotics.ai>
Date: Fri, 14 Aug 2026 07:41:17 +0100
Subject: [PATCH 12/13] Trim the timing tests to the behaviour they pin

264 lines to 194, mostly by deleting tests of the tests:

- `TestSuiteIsHermeticAgainstTheSwitch` spawned a nested pytest on every
  suite run to prove a two-line conftest fixture works. The fixture stays;
  the 22-line subprocess harness around it does not.
- Two tests pinned the exact wording of a parenthetical clock note. The note
  stays in the output; its phrasing is not an interface.
- `TestBenchHarness` and `TestColdBench` collapse into four tests, and the
  reset test's 0.5s sleep becomes 0.2s over two runs.
- The clone-state test went with the workspace_state span it existed to pin.

Two pins are added rather than removed, because they cover branches nothing
was holding: that `""` and `"0"` are both off (not just unset), and that a
span records a failed round trip without swallowing its exception -- the one
behaviour the contextlib rewrite could plausibly have changed.
---
 test/test_timing.py | 208 +++++++++++++++-----------------------------
 1 file changed, 69 insertions(+), 139 deletions(-)

diff --git a/test/test_timing.py b/test/test_timing.py
index 12cb5540..fb1e61d1 100644
--- a/test/test_timing.py
+++ b/test/test_timing.py
@@ -1,17 +1,13 @@
 # pylint: disable=redefined-outer-name
-"""Pin the env-gated wall-clock timing summary (ticket #140).
+"""Pin the env-gated wall-clock timing summary and its bench harness (#140).
 
 `DEVLAUNCH_TIMING=1` makes every dl process end with one stderr summary naming
-each subprocess round trip and the total wall time, so a perf change can land
-with before/after numbers. With the variable unset, dl must write no timing
-output at all: the hot path must not pay for its own thermometer.
-
-These tests pin behavior at the same boundaries as test_devpod_spawn_counts:
+each subprocess round trip and the total wall time; unset, dl must write no
+timing output at all. Pinned at the same boundaries as test_devpod_spawn_counts:
 the CLI entry point on one side, the subprocess module on the other.
 """
 
 import io
-import os
 import re
 import shlex
 import subprocess
@@ -21,7 +17,7 @@
 
 import pytest
 
-from devlaunch import gh_auth, timing, workspace_state
+from devlaunch import gh_auth, timing
 from devlaunch.dl import main, remote_branch_exists, run_ssh
 from test_devpod_spawn_counts import DevpodSpawns
 
@@ -35,58 +31,24 @@ def timing_labels(stderr: str):
     return TIMING_LINE.findall(stderr)
 
 
-REPO_ROOT = Path(__file__).parent.parent
-
-
-class TestSuiteIsHermeticAgainstTheSwitch:
-    """The suite must pass for a developer who has DEVLAUNCH_TIMING exported.
-
-    The people this instrument exists for are exactly the people who will leave
-    it on in their shell, and the next thing they do is run the tests. A switch
-    whose own suite goes red when the switch is on is a trap laid for the agent
-    debugging a launch a month from now, so the property is pinned by running a
-    slice of the suite in a child process with the variable exported -- the same
-    way a developer would meet it.
-    """
-
-    def test_suite_passes_with_the_switch_exported(self):
-        affected = "test/test_dl.py::TestMissingDevpodBinary"
-        result = subprocess.run(
-            [sys.executable, "-m", "pytest", affected, "-q", "-p", "no:randomly"],
-            cwd=REPO_ROOT,
-            env={**os.environ, "DEVLAUNCH_TIMING": "1"},
-            capture_output=True,
-            text=True,
-            check=False,
-        )
-        assert result.returncode == 0, result.stdout[-2000:]
-
-
 class TestSummaryGate:
-    """Timing lines appear iff DEVLAUNCH_TIMING is set."""
-
-    def test_no_timing_output_when_env_unset(self, monkeypatch, capsys):
-        monkeypatch.delenv("DEVLAUNCH_TIMING", raising=False)
+    """Timing lines appear iff DEVLAUNCH_TIMING asks for them."""
+
+    @pytest.mark.parametrize("value", [None, "", "0"])
+    def test_no_timing_output_when_the_switch_is_off(self, value, monkeypatch, capsys):
+        """Unset is the default, and the two ways of writing "off" are off too."""
+        if value is None:
+            monkeypatch.delenv("DEVLAUNCH_TIMING", raising=False)
+        else:
+            monkeypatch.setenv("DEVLAUNCH_TIMING", value)
         assert main(["--version"]) == 0
         assert "dl-timing:" not in capsys.readouterr().err
 
-    def test_summary_ends_with_total_when_env_set(self, monkeypatch, capsys):
+    def test_summary_ends_with_total_when_the_switch_is_on(self, monkeypatch, capsys):
         monkeypatch.setenv("DEVLAUNCH_TIMING", "1")
         assert main(["--version"]) == 0
         assert timing_labels(capsys.readouterr().err) == ["total"]
 
-    def test_total_says_which_clock_it_is(self, monkeypatch, capsys):
-        """`total` is measured from inside main(), so it is smaller than the
-        wall time the bench harness reports for the same command. The line says
-        so, so a reader quoting both does not take them for one number."""
-        monkeypatch.setenv("DEVLAUNCH_TIMING", "1")
-        assert main(["--version"]) == 0
-        assert re.search(
-            r"^dl-timing: total \d+\.\d{3}s \(in-process, excluding interpreter startup\)$",
-            capsys.readouterr().err,
-            re.M,
-        )
-
 
 @pytest.fixture
 def spawns():
@@ -100,33 +62,26 @@ def spawns():
 
 @pytest.mark.usefixtures("spawns")
 class TestDevpodRoundTripsAreNamed:
-    """The summary names each devpod round trip, in the order it happened."""
-
-    def test_ls_names_its_single_list_round_trip(self, monkeypatch, capsys):
-        monkeypatch.setenv("DEVLAUNCH_TIMING", "1")
-        assert main(["--ls"]) == 0
-        assert timing_labels(capsys.readouterr().err) == ["devpod list", "total"]
-
-    def test_attach_names_every_round_trip_in_order(self, monkeypatch, capsys):
-        """The attach chain from the spawn-count tests, seen as named timings:
-        one status, the hostname ssh, then the session ssh."""
+    """The summary names each devpod round trip, in the order it happened —
+    the chains from the spawn-count tests, seen as named timings."""
+
+    @pytest.mark.parametrize(
+        "argv, labels",
+        [
+            (["--ls"], ["devpod list"]),
+            (["myws"], ["devpod status", "devpod ssh", "devpod ssh"]),
+        ],
+    )
+    def test_the_chain_is_named_in_order(self, argv, labels, monkeypatch, capsys):
         monkeypatch.setenv("DEVLAUNCH_TIMING", "1")
-        assert main(["myws"]) == 0
-        assert timing_labels(capsys.readouterr().err) == [
-            "devpod status",
-            "devpod ssh",
-            "devpod ssh",
-            "total",
-        ]
+        assert main(argv) == 0
+        assert timing_labels(capsys.readouterr().err) == [*labels, "total"]
 
 
 @pytest.fixture
 def recording(monkeypatch):
-    """An active timing recorder, emitted into a buffer for inspection.
-
-    These tests exercise helpers below main(), so the per-command begin/emit
-    that main() does is driven here instead.
-    """
+    """An active recorder emitted into a buffer: these tests exercise helpers
+    below main(), so the begin/emit main() does is driven here instead."""
     monkeypatch.setenv("DEVLAUNCH_TIMING", "1")
     timing.begin()
     buffer = io.StringIO()
@@ -159,17 +114,6 @@ def test_gh_token_round_trip_is_named(self, recording, monkeypatch):
         timing.emit(recording)
         assert timing_labels(recording.getvalue()) == ["gh auth token", "total"]
 
-    def test_clone_state_git_reads_are_named(self, recording, tmp_path):
-        # A directory that is not a repository still costs the rev-parse and
-        # status round trips, and those are what the summary must name.
-        workspace_state.read_clone(tmp_path)
-        timing.emit(recording)
-        assert timing_labels(recording.getvalue()) == [
-            "git rev-parse",
-            "git status",
-            "total",
-        ]
-
     def test_remote_branch_probe_is_named(self, recording):
         answered = subprocess.CompletedProcess(
             ["git", "ls-remote"], 0, stdout="deadbeef\trefs/heads/main\n", stderr=""
@@ -179,8 +123,18 @@ def test_remote_branch_probe_is_named(self, recording):
         timing.emit(recording)
         assert timing_labels(recording.getvalue()) == ["git ls-remote", "total"]
 
+    def test_a_failed_round_trip_is_recorded_and_still_raises(self, recording):
+        """A spawn that raised still took time, and the span must not eat the
+        exception on its way out."""
+        with pytest.raises(RuntimeError):
+            with timing.span("devpod up"):
+                raise RuntimeError("spawn blew up")
+        timing.emit(recording)
+        assert timing_labels(recording.getvalue()) == ["devpod up", "total"]
+
 
 BENCH = Path(__file__).parent.parent / "scripts" / "bench_launch.py"
+FAILING = shlex.join([sys.executable, "-c", "raise SystemExit(3)"])
 
 
 def run_bench(*argv: str) -> subprocess.CompletedProcess:
@@ -190,7 +144,8 @@ def run_bench(*argv: str) -> subprocess.CompletedProcess:
 
 
 class TestBenchHarness:
-    """One command per side of a before/after: N runs, a median."""
+    """#140's "Done when": *a contributor can produce a median warm-launch and
+    cold-launch wall time with one documented command*."""
 
     def test_reports_each_run_and_the_median(self):
         result = run_bench("-n", "3", "--", sys.executable, "-c", "pass")
@@ -198,67 +153,42 @@ def test_reports_each_run_and_the_median(self):
         assert len(re.findall(r"^run \d+/3: \d+\.\d{3}s$", result.stdout, re.M)) == 3
         assert re.search(r"^median of 3: \d+\.\d{3}s", result.stdout, re.M)
 
-    def test_the_median_says_which_clock_it_is(self):
-        """Two instruments time the same launch and do not measure the same
-        span: this one runs the clock from outside the process, so interpreter
-        startup and imports are in the number; dl's own `total` starts inside
-        main() and they are not. Downstream tickets will quote both side by
-        side, so each number names its own epoch where it is printed."""
-        result = run_bench("-n", "1", "--", sys.executable, "-c", "pass")
-        assert re.search(
-            r"^median of 1: \d+\.\d{3}s \(wall clock, including interpreter startup\)$",
-            result.stdout,
-            re.M,
-        )
-
-    def test_fails_loudly_when_the_command_fails(self):
-        """A failing launch's time is not a number to compare against, so the
-        bench must not report a median over it."""
-        result = run_bench("-n", "3", "--", sys.executable, "-c", "raise SystemExit(7)")
+    @pytest.mark.parametrize(
+        "argv",
+        [
+            pytest.param(["-n", "3", "--", sys.executable, "-c", "raise SystemExit(7)"], id="run"),
+            pytest.param(
+                ["-n", "3", "--before", FAILING, "--", sys.executable, "-c", "pass"], id="reset"
+            ),
+        ],
+    )
+    def test_no_median_over_a_failed_run_or_a_failed_reset(self, argv):
+        """Neither a failing launch nor a run whose cold state was never
+        established is a number to compare against."""
+        result = run_bench(*argv)
         assert result.returncode != 0
         assert "median" not in result.stdout
 
     def test_rejects_a_run_count_below_one(self):
-        """There is no median of nothing, so the bench refuses to be asked for
-        one rather than dying inside statistics."""
+        """There is no median of nothing, so it refuses rather than dying
+        inside statistics."""
         result = run_bench("-n", "0", "--", sys.executable, "-c", "pass")
         assert result.returncode == 2
         assert "Traceback" not in result.stderr
 
-
-class TestColdBench:
-    """#140's "Done when": *a contributor can produce a median warm-launch and
-    cold-launch wall time with one documented command*.
-
-    A cold median needs the cold condition re-established before *every* timed
-    run: delete once and bench N times and runs 2..N are warm, so the printed
-    median is a warm number wearing a cold label. `--before` is that per-run
-    reset, and the bench refuses to report a median when the reset fails --
-    a run whose cold condition was never established is not a cold measurement.
-    """
-
-    def before_writing(self, marker: Path) -> str:
-        return shlex.join([sys.executable, "-c", f"open({str(marker)!r}, 'a').write('x')"])
-
-    def test_the_reset_runs_once_before_every_timed_run(self, tmp_path):
+    def test_the_reset_runs_before_every_timed_run_and_is_not_timed(self, tmp_path):
+        """Delete once and bench N times and runs 2..N are warm, so `--before`
+        resets per run — and the teardown's time is not the launch's."""
         marker = tmp_path / "resets"
-        result = run_bench(
-            "-n", "3", "--before", self.before_writing(marker), "--", sys.executable, "-c", "pass"
+        reset = shlex.join(
+            [
+                sys.executable,
+                "-c",
+                f"import time; time.sleep(0.2); open({str(marker)!r}, 'a').write('x')",
+            ]
         )
+        result = run_bench("-n", "2", "--before", reset, "--", sys.executable, "-c", "pass")
         assert result.returncode == 0, result.stderr
-        assert marker.read_text() == "xxx"
-
-    def test_the_reset_is_not_counted_as_launch_time(self):
-        """The number reported is the launch's, not the teardown's."""
-        slow_reset = shlex.join([sys.executable, "-c", "import time; time.sleep(0.5)"])
-        result = run_bench("-n", "1", "--before", slow_reset, "--", sys.executable, "-c", "pass")
-        assert result.returncode == 0, result.stderr
-        run = re.search(r"^run 1/1: (\d+\.\d{3})s", result.stdout, re.M)
-        assert run is not None, result.stdout
-        assert float(run.group(1)) < 0.4
-
-    def test_refuses_a_median_when_the_reset_fails(self):
-        failing_reset = shlex.join([sys.executable, "-c", "raise SystemExit(3)"])
-        result = run_bench("-n", "3", "--before", failing_reset, "--", sys.executable, "-c", "pass")
-        assert result.returncode != 0
-        assert "median" not in result.stdout
+        assert marker.read_text() == "xx"
+        runs = re.findall(r"^run \d+/2: (\d+\.\d{3})s$", result.stdout, re.M)
+        assert runs and all(float(seconds) < 0.15 for seconds in runs), result.stdout

From 496e19d82f7739c76d6569d45614831e5ec5f9ec Mon Sep 17 00:00:00 2001
From: Austin Gregg-Smith <austin.gregg-smith@bearrobotics.ai>
Date: Fri, 14 Aug 2026 07:41:17 +0100
Subject: [PATCH 13/13] Move the bench's contributor notes from the README into
 --help

The "cold median needs a reset per run" and "the two numbers are not the same
quantity" passages are notes for whoever runs the bench, not README material
for whoever runs dl. They move into `bench_launch.py`'s epilog, where they are
one `--help` away from the flag they explain, and the 28-line module docstring
that duplicated them shrinks to five. README's section goes 59 lines to 26,
keeping the DEVLAUNCH_TIMING block and one bench example.
---
 README.md               | 47 +++++---------------------------
 scripts/bench_launch.py | 59 +++++++++++++++++++----------------------
 2 files changed, 35 insertions(+), 71 deletions(-)

diff --git a/README.md b/README.md
index e72f1825..1fdcdd4f 100644
--- a/README.md
+++ b/README.md
@@ -616,10 +616,9 @@ dl blooop/devlaunch stop         # Stop workspace
 
 ## Measuring launch time
 
-Every `dl` process can account for its own wall time. Set `DEVLAUNCH_TIMING=1`
-and the command ends with one summary on stderr, naming each subprocess round
-trip (`devpod status`, `devpod ssh`, `gh auth token`, `git ls-remote`, ...) and
-the total:
+Set `DEVLAUNCH_TIMING=1` and a `dl` command ends with one summary on stderr,
+naming each subprocess round trip and the total. Unset (or `0`) records nothing
+and prints nothing.
 
 ```bash
 $ DEVLAUNCH_TIMING=1 dl myws -- true
@@ -629,10 +628,6 @@ dl-timing: devpod ssh 1.102s
 dl-timing: total 2.201s (in-process, excluding interpreter startup)
 ```
 
-With the variable unset (or `0`) there is no output and nothing is recorded.
-The summary goes to stderr, after the command's own output, so it composes
-with one-shot commands.
-
 For before/after numbers, `scripts/bench_launch.py` runs a command N times and
 reports the median — one command per side of a change:
 
@@ -640,38 +635,10 @@ reports the median — one command per side of a change:
 python scripts/bench_launch.py -n 5 -- dl-next owner/repo -- true   # warm launch
 ```
 
-(`pixi run bench -n 5 -- ...` inside the devcontainer.) The bench refuses to
-report a median if any run fails, so a broken launch cannot pass as a fast one.
-
-### A cold median needs a reset per run
-
-A cold launch measured once is one sample, and a cold launch deleted once and
-then benched five times is one cold run plus four warm ones — a warm median
-under a cold label. `--before` runs a reset command before every timed run and
-does not count its time, so all N runs start cold:
-
-```bash
-XDG_CACHE_HOME=/tmp/dl-bench/cache \
-python scripts/bench_launch.py -n 5 \
-  --before 'dl-next owner/repo delete' \
-  -- dl-next owner/repo -- true                                     # cold launch
-```
-
-Scope `XDG_CACHE_HOME` (that variable only — see `dev.sh`) so the reset deletes
-the bench's own workspace rather than one you are working in. If a reset exits
-non-zero the bench stops and prints no median: a run whose cold state was never
-established is not a cold measurement, and a number labelled cold has to have
-been taken cold.
-
-### The two numbers are not the same quantity
-
-`dl-timing: total` starts at the top of `main()`; the bench's wall clock starts
-outside the process, so it also contains interpreter startup and this package's
-imports. Measured here on `dl --version`, `total` reported `0.001s` against a
-bench median of `0.056s` over 5 runs — the ~55 ms difference is startup, not
-launch work. Both lines say which clock they are. Quote one instrument on both
-sides of a change; don't compare a `total` on one side with a bench median on
-the other.
+(`pixi run bench -n 5 -- ...` in the devcontainer.) It reports no median if any
+run fails, so a broken launch cannot pass as a fast one. See `bench_launch.py
+--help` for `--before` — the per-run reset that makes a *cold* median cold —
+and for why its wall clock and `dl-timing: total` are not the same quantity.
 
 ## Worktree Backend
 
diff --git a/scripts/bench_launch.py b/scripts/bench_launch.py
index a76dd074..664419fb 100755
--- a/scripts/bench_launch.py
+++ b/scripts/bench_launch.py
@@ -1,31 +1,10 @@
 #!/usr/bin/env python3
-"""Run a command N times and report the median wall time.
+"""Run a command N times and report the median wall time (ticket #140).
 
-The repeatable half of the timing instrument (ticket #140): a before/after
-perf comparison is this script run once on each side of a change, e.g.
-
-    python scripts/bench_launch.py -n 5 -- dl-next owner/repo -- true
-
-Wall time per run and the median go to stdout; the command's own output is
-left on the terminal so a hung launch is visible. If any run exits non-zero
-the bench stops with that run's exit code and reports no median — a failing
-launch's time is not a number to compare against.
-
-`--before` runs a reset command before each timed run, without counting its
-time. That is what makes a *cold* median possible: the state a cold launch
-starts from has to be re-established before every run, or runs 2..N are warm
-and the median is a warm number under a cold label. If a reset fails the bench
-stops with no median, for the same reason a failing run reports none — a run
-whose starting condition was never established is not a measurement of it.
-
-The wall time here is measured from outside the process, so it includes
-interpreter startup and imports. dl's own `dl-timing: total` line starts inside
-main() and excludes them, so the two numbers are close but not the same
-quantity; each line says which it is, and a before/after comparison should
-quote one instrument on both sides.
-
-Standard library only, on purpose: the instrument must not cost the project
-a dependency.
+The repeatable half of the timing instrument: a before/after perf comparison is
+this script run once on each side of a change. Stdlib only, on purpose — the
+instrument must not cost the project a dependency. See --help for the two
+traps: cold medians, and which clock each number is on.
 """
 
 import argparse
@@ -36,14 +15,30 @@
 import time
 from typing import List, Optional
 
+EPILOG = """\
+warm:  bench_launch.py -n 5 -- dl-next owner/repo -- true
+cold:  XDG_CACHE_HOME=/tmp/dl-bench/cache bench_launch.py -n 5 \\
+         --before 'dl-next owner/repo delete' -- dl-next owner/repo -- true
+
+A cold median needs the reset per *run*: delete once and bench five times and
+runs 2..5 are warm, so the median is a warm number under a cold label. Scope
+XDG_CACHE_HOME (that variable only, see dev.sh) so the reset deletes the
+bench's own workspace, not one you are using. A failed reset stops with no
+median, like a failed run: a run whose starting condition was never
+established is not a measurement of it.
+
+This clock starts outside the process, so it includes interpreter startup and
+imports; dl's own `dl-timing: total` starts inside main() and excludes them
+(on `dl --version`: 0.001s total against a 0.056s median here). Quote one
+instrument on both sides of a change.
+"""
+
 
 def bench(n: int, command: List[str], before: Optional[List[str]] = None) -> int:
     """Run *command* *n* times, print each wall time and the median.
 
-    *before*, when given, runs before each timed run and is not timed.
-
-    Returns the exit code for the process: 0 after n clean runs, otherwise the
-    exit code of the first run — or reset — that failed.
+    Returns 0 after n clean runs, otherwise the exit code of the first run --
+    or untimed *before* reset -- that failed.
     """
     durations = []
     for i in range(1, n + 1):
@@ -84,7 +79,9 @@ def positive_int(text: str) -> int:
 
 def main(argv=None) -> int:
     parser = argparse.ArgumentParser(
-        description="Run a command N times and report the median wall time."
+        description="Run a command N times and report the median wall time.",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     parser.add_argument("-n", type=positive_int, default=5, help="number of runs (default: 5)")
     parser.add_argument(