chore(deps): update github actions

irtt-client exposes a synchronous wait for managed target-set updates and keeps its packaged test dependency resolvable from crates.io. irtt-rs adds stdin-managed desired target sets and per-target HMAC configuration.

.gitea/workflows/ci.yml

@@ -7,7 +7,6 @@ on:
   pull_request:
     branches:
       - main
-  merge_group:
   workflow_dispatch:
 
 permissions:
@@ -24,7 +23,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           persist-credentials: false
 
@@ -32,7 +31,7 @@ jobs:
         uses: actions-rust-lang/setup-rust-toolchain@166cdcfd11aee3cb47222f9ddb555ce30ddb9659 # v1
         with:
           components: rustfmt
-          cache-key: fmt
+          cache: false
 
       - name: Check formatting
         uses: actions-rust-lang/rustfmt@4066006ec54a31931b9b1fddfd38f2fdf2d27143 # v1
@@ -44,7 +43,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           persist-credentials: false
 
@@ -52,7 +51,7 @@ jobs:
         uses: actions-rust-lang/setup-rust-toolchain@166cdcfd11aee3cb47222f9ddb555ce30ddb9659 # v1
         with:
           components: clippy
-          cache-key: clippy
+          cache: false
 
       - name: Run clippy
         run: |
@@ -72,58 +71,65 @@ jobs:
             --locked \
             -- -D warnings
 
-  check:
-    name: cargo check
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
+  verify:
+    name: cargo ${{ matrix.task }} (${{ matrix.target }})
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - task: check
+            target: x86_64-unknown-linux-gnu
+            musl: false
 
-    steps:
-      - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
-        with:
-          persist-credentials: false
+          - task: test
+            target: x86_64-unknown-linux-gnu
+            musl: false
 
-      - name: Install Rust toolchain
-        uses: actions-rust-lang/setup-rust-toolchain@166cdcfd11aee3cb47222f9ddb555ce30ddb9659 # v1
-        with:
-          cache-key: check
+          - task: check
+            target: x86_64-unknown-linux-musl
+            musl: true
 
-      - name: Run check without default features
-        run: |
-          cargo check \
-            --workspace \
-            --no-default-features \
-            --locked
+          - task: test
+            target: x86_64-unknown-linux-musl
+            musl: true
 
-  test:
-    name: cargo test
     runs-on: ubuntu-latest
     timeout-minutes: 25
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           persist-credentials: false
 
+      - name: Install musl toolchain
+        if: matrix.musl
+        run: |
+          sudo apt-get update
+          sudo apt-get install --no-install-recommends musl-tools
+
       - name: Install Rust toolchain
         uses: actions-rust-lang/setup-rust-toolchain@166cdcfd11aee3cb47222f9ddb555ce30ddb9659 # v1
         with:
-          cache-key: test
+          target: ${{ matrix.target }}
+          cache: false
 
-      - name: Run tests
+      - name: Run ${{ matrix.task }} with all features
         run: |
-          cargo test \
+          cargo ${{ matrix.task }} \
             --workspace \
             --all-targets \
             --all-features \
+            --target ${{ matrix.target }} \
             --locked
 
-      - name: Run tests without default features
+      - name: Run ${{ matrix.task }} without default features
         run: |
-          cargo test \
+          cargo ${{ matrix.task }} \
             --workspace \
+            --all-targets \
             --no-default-features \
+            --target ${{ matrix.target }} \
             --locked
 
   docs:
@@ -136,14 +142,14 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           persist-credentials: false
 
       - name: Install Rust toolchain
         uses: actions-rust-lang/setup-rust-toolchain@166cdcfd11aee3cb47222f9ddb555ce30ddb9659 # v1
         with:
-          cache-key: docs
+          cache: false
 
       - name: Check docs
         run: |
@@ -152,3 +158,6 @@ jobs:
             --all-features \
             --no-deps \
             --locked
+
+      - name: Run doctests
+        run: cargo test --workspace --doc --all-features --locked

.gitea/workflows/docker-publish.yml

@@ -0,0 +1,99 @@
+name: Publish irtt-server image
+
+on:
+  push:
+    tags:
+      # This repo tags each crate independently (irtt-proto/vX, irtt-client/vX,
+      # ...); only the app package's tag corresponds to this image.
+      - "irtt-rs/v*"
+  workflow_dispatch:
+
+env:
+  IMAGE_NAME: irtt-server
+  IMAGE_OWNER: lochnair
+  GITEA_REGISTRY: git.lochnair.net
+  GHCR_REGISTRY: ghcr.io
+  # Pinned so a floating "latest" release doesn't silently change the build.
+  CRANE_VERSION: v0.20.2
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Determine image tags
+        id: meta
+        run: |
+          if [ "${GITHUB_REF_TYPE}" = "tag" ]; then
+            version="${GITHUB_REF_NAME#irtt-rs/v}"
+            echo "version=${version}" >> "$GITHUB_OUTPUT"
+            echo "tags=${version},latest" >> "$GITHUB_OUTPUT"
+          else
+            # Manual dispatch off a branch: tag by commit only, never touch
+            # "latest", so an ad-hoc build can't clobber the last release.
+            version="sha-$(git rev-parse --short HEAD)"
+            echo "version=${version}" >> "$GITHUB_OUTPUT"
+            echo "tags=${version}" >> "$GITHUB_OUTPUT"
+          fi
+
+      # Cross-compilation is handled inside the Dockerfile via tonistiigi/xx
+      # (native builds, no emulation), but buildx still needs a driver that
+      # can assemble a multi-platform manifest list.
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4
+
+      - name: Log in to Gitea Container Registry
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
+        with:
+          registry: ${{ env.GITEA_REGISTRY }}
+          # The automatic per-job token comes back unauthorized for package
+          # writes on this instance, so use a PAT (scope: write:package) instead.
+          # (Secret names can't start with GITEA_/GITHUB_, hence REGISTRY_*.)
+          username: ${{ secrets.REGISTRY_USERNAME }}
+          password: ${{ secrets.REGISTRY_TOKEN }}
+
+      - name: Log in to GHCR
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
+        with:
+          registry: ${{ env.GHCR_REGISTRY }}
+          username: ${{ secrets.GHCR_USERNAME }}
+          password: ${{ secrets.GHCR_TOKEN }}
+
+      - name: Build tag list
+        id: tags
+        run: |
+          IFS=',' read -ra tag_list <<< "${{ steps.meta.outputs.tags }}"
+          gitea_tags=""
+          for t in "${tag_list[@]}"; do
+            gitea_tags="${gitea_tags}${GITEA_REGISTRY}/${IMAGE_OWNER}/${IMAGE_NAME}:${t},"
+          done
+          echo "gitea=${gitea_tags%,}" >> "$GITHUB_OUTPUT"
+
+      # Gitea is the primary publish target: this is the only build. Every
+      # other registry gets an exact digest copy of this same image (see
+      # below), never a separate build, so the hash matches everywhere.
+      - name: Build and push to Gitea
+        id: build
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.tags.outputs.gitea }}
+
+      - name: Install crane
+        run: |
+          mkdir -p "${HOME}/.local/bin"
+          curl -sL "https://github.com/google/go-containerregistry/releases/download/${CRANE_VERSION}/go-containerregistry_Linux_x86_64.tar.gz" \
+            | tar -xz -C "${HOME}/.local/bin" crane
+          echo "${HOME}/.local/bin" >> "$GITHUB_PATH"
+
+      - name: Duplicate image to GHCR (same digest, no rebuild)
+        run: |
+          source_ref="${GITEA_REGISTRY}/${IMAGE_OWNER}/${IMAGE_NAME}@${{ steps.build.outputs.digest }}"
+          IFS=',' read -ra tag_list <<< "${{ steps.meta.outputs.tags }}"
+          for t in "${tag_list[@]}"; do
+            crane copy "${source_ref}" "${GHCR_REGISTRY}/${IMAGE_OWNER}/${IMAGE_NAME}:${t}"
+          done

.gitea/workflows/fuzz.yml

@@ -0,0 +1,81 @@
+name: Proto Fuzz Smoke
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+  # Pinned for reproducibility; bump deliberately alongside `fuzz/Cargo.lock`.
+  CARGO_FUZZ_VERSION: 0.13.1
+  CARGO_FUZZ_SHA256: 86edc9b8f20c29ff07c3e5fcd67bc3f0784b3b960a5428635060f20d50555461
+  FUZZ_TOOLCHAIN: nightly-x86_64-unknown-linux-gnu
+  FUZZ_TARGET: x86_64-unknown-linux-gnu
+
+jobs:
+  fuzz-smoke:
+    name: cargo fuzz smoke
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install stable Rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@166cdcfd11aee3cb47222f9ddb555ce30ddb9659 # v1
+        with:
+          cache: false
+
+      - name: Install nightly Rust toolchain
+        # Installed alongside, but deliberately not made the directory
+        # default: cargo-fuzz itself is built with the default stable
+        # toolchain below, and only `fuzz build`/`fuzz run` are run with
+        # the GNU-host nightly below. Building cargo-fuzz's own dependency
+        # tree under a nightly override can trip build scripts (e.g. rustix) that gate
+        # unstable internal attributes on detecting a nightly compiler.
+        run: rustup toolchain install "${FUZZ_TOOLCHAIN}" --profile minimal --no-self-update
+
+      - name: Install cargo-fuzz
+        run: |
+          set -euo pipefail
+          archive="cargo-fuzz-${CARGO_FUZZ_VERSION}-x86_64-unknown-linux-musl.tar.gz"
+          curl --fail --show-error --location --retry 3 \
+            "https://github.com/rust-fuzz/cargo-fuzz/releases/download/${CARGO_FUZZ_VERSION}/${archive}" \
+            --output "$archive"
+          echo "${CARGO_FUZZ_SHA256}  ${archive}" | sha256sum --check --status -
+          tar -xzf "$archive" cargo-fuzz
+          install -Dm755 cargo-fuzz "${RUNNER_TEMP}/bin/cargo-fuzz"
+          echo "${RUNNER_TEMP}/bin" >> "$GITHUB_PATH"
+
+      - name: Build all fuzz targets
+        # libFuzzer sanitizers require dynamically linked GNU binaries; the
+        # runner's default Rust host can be static musl.
+        run: RUSTUP_TOOLCHAIN="${FUZZ_TOOLCHAIN}" cargo fuzz build --target "${FUZZ_TARGET}"
+        working-directory: fuzz
+
+      - name: Run bounded fuzz smoke for every target
+        # A single job building once and running each target sequentially
+        # avoids recompiling the fuzz workspace per target. Ten seconds per
+        # target is enough to catch a broken harness or an obvious
+        # regression; this is not meant to be exhaustive fuzzing.
+        run: |
+          set -euo pipefail
+          for target in decode_request decode_open_reply decode_echo_reply decode_params decode_varint; do
+            echo "::group::fuzz smoke: ${target}"
+            RUSTUP_TOOLCHAIN="${FUZZ_TOOLCHAIN}" cargo fuzz run --target "${FUZZ_TARGET}" "${target}" -- \
+              -max_total_time=10 \
+              -timeout=5
+            echo "::endgroup::"
+          done
+        working-directory: fuzz

.gitea/workflows/interop-netem.yml

@@ -25,20 +25,21 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           persist-credentials: false
 
       - name: Install Rust toolchain
         uses: actions-rust-lang/setup-rust-toolchain@166cdcfd11aee3cb47222f9ddb555ce30ddb9659 # v1
         with:
-          cache-key: interop-netem
+          cache: false
 
-      - name: Check host tools
+      - name: Check host tools and network administration access
         run: |
           ip -V
           tc -V
           go version
+          sudo -n true
 
       - name: Install upstream irtt
         run: |
@@ -46,8 +47,8 @@ jobs:
           go install "github.com/heistp/irtt/cmd/irtt@${IRTT_UPSTREAM_VERSION}"
           "$GOBIN/irtt" version
 
-      - name: Build irtt-rs CLI
-        run: cargo build -p irtt-cli --locked
+      - name: Build irtt-rs client
+        run: cargo build -p irtt-rs --bin irtt-client --locked
 
       - name: Run netem interop comparisons
         run: |
@@ -55,21 +56,21 @@ jobs:
             --all \
             --skip-build \
             --upstream-irtt "$GOBIN/irtt" \
-            --irtt-rs-command "$PWD/target/debug/irtt-cli"
+            --irtt-rs-command "$PWD/target/debug/irtt-client"
 
       - name: Append netem interop summary
         if: always()
         run: |
           latest_summary="$(find target/interop-netem -mindepth 2 -maxdepth 2 -name github-step-summary.md -type f -print 2>/dev/null | sort | tail -n 1)"
           if [ -n "$latest_summary" ]; then
-            cat "$latest_summary" >> "$GITHUB_STEP_SUMMARY"
+            cat "$latest_summary" >> "$GITEA_STEP_SUMMARY"
           else
-            echo "No netem interop github-step-summary.md found." >> "$GITHUB_STEP_SUMMARY"
+            echo "No netem interop github-step-summary.md found." >> "$GITEA_STEP_SUMMARY"
           fi
 
       - name: Upload netem interop artifacts
         if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        uses: https://gitea.com/actions/gitea-upload-artifact@v7
         with:
           name: interop-netem
           path: target/interop-netem

.gitea/workflows/semver.yml

@@ -0,0 +1,52 @@
+name: Semver
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "irtt-proto/v*.*.*"
+      - "irtt-client/v*.*.*"
+      - "irtt-server/v*.*.*"
+      - "irtt-stats/v*.*.*"
+      - "irtt-rs/v*.*.*"
+
+permissions:
+  contents: read
+
+env:
+  CARGO_SEMVER_CHECKS_VERSION: 0.50.0
+  CARGO_SEMVER_CHECKS_SHA256: 52a65dc88dc53fa8b57d6087954eb52cda149ca03bcfca78ce3fdecd23f893c4
+
+jobs:
+  semver:
+    name: cargo-semver-checks
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install Rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@166cdcfd11aee3cb47222f9ddb555ce30ddb9659 # v1
+        with:
+          cache: false
+
+      # The CLI preserves the previous wrapper's `feature-group: all-features`
+      # behavior without its GitHub API/cache dependency.
+      - name: Install cargo-semver-checks
+        run: |
+          set -euo pipefail
+          archive="cargo-semver-checks-x86_64-unknown-linux-gnu.tar.gz"
+          curl --fail --show-error --location --retry 3 \
+            "https://github.com/obi1kenobi/cargo-semver-checks/releases/download/v${CARGO_SEMVER_CHECKS_VERSION}/${archive}" \
+            --output "$archive"
+          echo "${CARGO_SEMVER_CHECKS_SHA256}  ${archive}" | sha256sum --check --status -
+          tar -xzf "$archive" cargo-semver-checks
+          install -Dm755 cargo-semver-checks "${RUNNER_TEMP}/bin/cargo-semver-checks"
+          echo "${RUNNER_TEMP}/bin" >> "$GITHUB_PATH"
+
+      - name: Check semver compatibility
+        run: cargo semver-checks check-release --all-features

.gitea/workflows/supply-chain.yml

@@ -0,0 +1,109 @@
+name: Supply chain
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  schedule:
+    - cron: "41 2 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  ACTIONLINT_VERSION: 1.7.7
+  CARGO_DENY_VERSION: 0.20.2
+  CARGO_DENY_SHA256: 9f12ed4c49936e09b48bf862b595cde2fe64fcbd9d74dfacac6131ca824c8d5f
+  ACTIONLINT_SHA256: 023070a287cd8cccd71515fedc843f1985bf96c436b7effaecce67290e7e0757
+
+jobs:
+  cargo-deny:
+    name: cargo-deny ${{ matrix.checks }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Advisories can appear after code was merged. Keep this visible,
+          # but don't let a surprise upstream advisory nuke every unrelated PR.
+          - checks: advisories
+            continue-on-error: true
+
+          # These are policy choices in this repo. They should block PRs.
+          - checks: bans licenses sources
+            continue-on-error: false
+
+    continue-on-error: ${{ matrix.continue-on-error }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install cargo-deny
+        run: |
+          set -euo pipefail
+          archive="cargo-deny-${CARGO_DENY_VERSION}-x86_64-unknown-linux-musl.tar.gz"
+          curl --fail --show-error --location --retry 3 \
+            "https://github.com/EmbarkStudios/cargo-deny/releases/download/${CARGO_DENY_VERSION}/${archive}" \
+            --output "$archive"
+          echo "${CARGO_DENY_SHA256}  ${archive}" | sha256sum --check --status -
+          tar -xzf "$archive" --strip-components=1 \
+            "cargo-deny-${CARGO_DENY_VERSION}-x86_64-unknown-linux-musl/cargo-deny"
+          install -Dm755 cargo-deny "${RUNNER_TEMP}/bin/cargo-deny"
+          echo "${RUNNER_TEMP}/bin" >> "$GITHUB_PATH"
+
+      - name: Run cargo-deny
+        run: >-
+          cargo deny --manifest-path Cargo.toml --all-features check
+          ${{ matrix.checks }}
+
+  actionlint:
+    name: actionlint
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install actionlint
+        run: |
+          set -euo pipefail
+          archive="actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz"
+          curl --fail --show-error --location --retry 3 \
+            "https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/${archive}" \
+            --output "$archive"
+          echo "${ACTIONLINT_SHA256}  ${archive}" | sha256sum --check --status -
+          tar -xzf "$archive" actionlint
+          install -Dm755 actionlint "${RUNNER_TEMP}/bin/actionlint"
+          echo "${RUNNER_TEMP}/bin" >> "$GITHUB_PATH"
+
+      - name: actionlint handwritten workflows
+        # actionlint validates GitHub Actions syntax. It cannot parse Gitea's
+        # required absolute action URL in interop-netem.yml, so that workflow
+        # is checked by the Gitea runner instead.
+        run: |
+          actionlint \
+            .gitea/workflows/ci.yml \
+            .gitea/workflows/docker-publish.yml \
+            .gitea/workflows/fuzz.yml \
+            .gitea/workflows/semver.yml \
+            .gitea/workflows/supply-chain.yml \
+            .github/workflows/actions-security.yml \
+            .github/workflows/ci-arm.yml \
+            .github/workflows/osv-scanner.yml \
+            .github/workflows/rust-clippy.yml
+
+      - name: actionlint generated release workflow
+        run: >-
+          actionlint -shellcheck= .github/workflows/irtt-rs-release.yml

.github/workflows/actions-security.yml

@@ -16,34 +16,6 @@ permissions:
   contents: read
 
 jobs:
-  actionlint:
-    name: actionlint
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
-        with:
-          persist-credentials: false
-
-      - name: actionlint handwritten workflows
-        uses: raven-actions/actionlint@205b530c5d9fa8f44ae9ed59f341a0db994aa6f8
-        with:
-          files: >-
-            .github/workflows/actions-security.yml,
-            .github/workflows/ci.yml,
-            .github/workflows/interop-netem.yml,
-            .github/workflows/osv-scanner.yml,
-            .github/workflows/rust-clippy.yml,
-            .github/workflows/semver.yml,
-            .github/workflows/supply-chain.yml
-
-      - name: actionlint generated release workflow
-        uses: raven-actions/actionlint@205b530c5d9fa8f44ae9ed59f341a0db994aa6f8
-        with:
-          files: .github/workflows/release.yml
-          shellcheck: false
   zizmor:
     name: zizmor
     runs-on: ubuntu-latest
@@ -56,11 +28,17 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           persist-credentials: false
 
+      # Zizmor's SARIF integration publishes GitHub Code Scanning results.
+      # It remains here while portable actionlint runs with Gitea CI, but scans
+      # both workflow directories through its GitHub Actions rule set.
       - name: Run zizmor
-        uses: zizmorcore/zizmor-action@192e21d79ab29983730a13d1382995c2307fbcaa # v0.5.7
+        uses: zizmorcore/zizmor-action@cc914d7f3750a2d13d75c7f184a1060aa0e9d482 # v0.6.4
         with:
           persona: regular
+          inputs: |
+            .github/workflows
+            .gitea/workflows

.github/workflows/ci-arm.yml

@@ -0,0 +1,80 @@
+name: Rust ARM CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  merge_group:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  verify:
+    name: cargo ${{ matrix.task }} (${{ matrix.target }})
+    # Gitea currently has only amd64 Linux runners; retain ARM coverage here.
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - task: check
+            target: aarch64-unknown-linux-gnu
+            musl: false
+
+          - task: test
+            target: aarch64-unknown-linux-gnu
+            musl: false
+
+          - task: check
+            target: aarch64-unknown-linux-musl
+            musl: true
+
+          - task: test
+            target: aarch64-unknown-linux-musl
+            musl: true
+
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 25
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Install musl toolchain
+        if: matrix.musl
+        run: |
+          sudo apt-get update
+          sudo apt-get install --no-install-recommends musl-tools
+
+      - name: Install Rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@166cdcfd11aee3cb47222f9ddb555ce30ddb9659 # v1
+        with:
+          target: ${{ matrix.target }}
+          cache-key: ${{ matrix.task }}-${{ matrix.target }}
+
+      - name: Run ${{ matrix.task }} with all features
+        run: |
+          cargo ${{ matrix.task }} \
+            --workspace \
+            --all-targets \
+            --all-features \
+            --target ${{ matrix.target }} \
+            --locked
+
+      - name: Run ${{ matrix.task }} without default features
+        run: |
+          cargo ${{ matrix.task }} \
+            --workspace \
+            --all-targets \
+            --no-default-features \
+            --target ${{ matrix.target }} \
+            --locked

.github/workflows/irtt-rs-release.yml

@@ -42,7 +42,7 @@ on:
   pull_request:
   push:
     tags:
-      - '**[0-9]+.[0-9]+.[0-9]+*'
+      - 'irtt-rs**[0-9]+.[0-9]+.[0-9]+*'
 
 jobs:
   # Run 'dist plan' (or host) to determine what tasks we need to do

.github/workflows/osv-scanner.yml

@@ -31,7 +31,7 @@ permissions:
 jobs:
   scan-scheduled:
     if: ${{ github.event_name == 'push' || github.event_name == 'schedule' }}
-    uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@9a498708959aeaef5ef730655706c5a1df1edbc2" # v2.3.8
+    uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@a345acffa64b0eaede81a3d9aae6141214d9c8fc" # v2.6.0
     with:
       # Example of specifying custom arguments
       scan-args: |-
@@ -40,7 +40,7 @@ jobs:
         ./
   scan-pr:
     if: ${{ github.event_name == 'pull_request' || github.event_name == 'merge_group' }}
-    uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable-pr.yml@9a498708959aeaef5ef730655706c5a1df1edbc2" # v2.3.8
+    uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable-pr.yml@a345acffa64b0eaede81a3d9aae6141214d9c8fc" # v2.6.0
     with:
       # Example of specifying custom arguments
       scan-args: |-

.github/workflows/rust-clippy.yml

@@ -24,7 +24,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           persist-credentials: false
 
@@ -60,7 +60,7 @@ jobs:
           exit 0
 
       - name: Upload Clippy SARIF
-        uses: github/codeql-action/upload-sarif@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4
+        uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4
         if: always()
         with:
           sarif_file: rust-clippy-results.sarif

.github/workflows/semver.yml

@@ -1,27 +0,0 @@
-name: Semver
-
-on:
-  workflow_dispatch:
-  push:
-    tags:
-      - "v*.*.*"
-
-permissions:
-  contents: read
-
-jobs:
-  semver:
-    name: cargo-semver-checks
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
-        with:
-          persist-credentials: false
-
-      - name: Check semver compatibility
-        uses: obi1kenobi/cargo-semver-checks-action@6b69fcf40e9b5fb17adeb57e4b6ecd020649a239 # v2
-        with:
-          feature-group: all-features

.github/workflows/supply-chain.yml

@@ -1,79 +0,0 @@
-name: Supply chain
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
-  merge_group:
-  schedule:
-    - cron: "41 2 * * 1"
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-jobs:
-  cargo-deny:
-    name: cargo-deny ${{ matrix.checks }}
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          # Advisories can appear after code was merged. Keep this visible,
-          # but don't let a surprise upstream advisory nuke every unrelated PR.
-          - checks: advisories
-            continue-on-error: true
-
-          # These are policy choices in this repo. They should block PRs.
-          - checks: bans licenses sources
-            continue-on-error: false
-
-    continue-on-error: ${{ matrix.continue-on-error }}
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
-        with:
-          persist-credentials: false
-
-      - name: Run cargo-deny
-        uses: EmbarkStudios/cargo-deny-action@bb137d7af7e4fb67e5f82a49c4fce4fad40782fe # v2
-        with:
-          command: check
-          arguments: --all-features
-          command-arguments: ${{ matrix.checks }}
-
-  actionlint:
-    name: actionlint
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
-        with:
-          persist-credentials: false
-
-      - name: actionlint handwritten workflows
-        uses: raven-actions/actionlint@205b530c5d9fa8f44ae9ed59f341a0db994aa6f8
-        with:
-          files: >-
-            .github/workflows/actions-security.yml,
-            .github/workflows/ci.yml,
-            .github/workflows/interop-netem.yml,
-            .github/workflows/osv-scanner.yml,
-            .github/workflows/rust-clippy.yml,
-            .github/workflows/semver.yml,
-            .github/workflows/supply-chain.yml
-
-      - name: actionlint generated release workflow
-        uses: raven-actions/actionlint@205b530c5d9fa8f44ae9ed59f341a0db994aa6f8
-        with:
-          files: .github/workflows/release.yml
-          shellcheck: false

AGENTS.md

@@ -0,0 +1,201 @@
+# Repository guidance
+
+Repository-wide guidance for contributors and coding agents working on `irtt-rs`.
+Before editing, also check for a more specific `AGENTS.md` in the target subtree.
+
+## Clean-room boundary
+
+`irtt-rs` is an independent Rust implementation of an IRTT-compatible protocol stack. It began as a clean-room client reimplementation and now contains project-specific architecture and behavior beyond that original compatibility baseline.
+
+- Do not inspect, quote, copy, translate, or derive implementation details from upstream `heistp/irtt` source code or upstream tests.
+- Do not use contaminated notes or source-derived pseudocode as implementation input.
+- Use the local clean-room specification, black-box verification artifacts, current `irtt-rs` code, and current tests.
+- Black-box interoperability testing against an installed upstream `irtt` binary is allowed when relevant. Treat it as an external implementation, not source material.
+- If behavior remains ambiguous, state the ambiguity instead of guessing or consulting upstream implementation code.
+
+Compatibility and interoperability references:
+
+- `docs/protocol/IRTT_CLIENT_PROTOCOL_SPEC.md` — verified client-side
+  compatibility baseline.
+- `docs/protocol/IRTT_SERVER_PROTOCOL_SPEC.md` — verified server-side
+  compatibility baseline.
+- `docs/protocol/BLACKBOX_VERIFICATION_REPORT.md` — black-box evidence and
+  corrections supporting both the client and server baselines.
+- `docs/protocol/test-vectors/README.md` — captured client-facing packet
+  vectors.
+- `docs/protocol/test-vectors/SERVER_BEHAVIORAL_VECTORS.md` — black-box
+  server behavioral vectors, edge cases, and session behavior.
+- `docs/protocol/captures/` — packet captures referenced by the verification
+  report and behavioral vectors. Behavioral vectors and captures are
+  evidence/artifacts, not architecture prescriptions.
+- `docs/INTEROP_COMPARISON.md` — procedures for black-box comparison against
+  the upstream `irtt` executable.
+- `docs/clean-room/CLEANROOM_NOTES.md` — provenance only; not a normative
+  protocol specification.
+
+The verified client spec predates later `irtt-rs` architecture and project-specific features. Its scope statements, including server implementation being out of scope, describe that document's scope and are not permanent repository restrictions.
+
+For compatibility questions, the verified spec and black-box observations define the baseline. For `irtt-rs`-specific APIs, runtime architecture, resource bounds, and later features, current code and current project documentation are authoritative.
+
+## Architecture
+
+Main boundary:
+
+> `irtt-proto` — wire semantics shared by client/server. `irtt-client` — client/session behavior. `irtt-server` — server/session behavior and Tokio runtime/orchestration. `irtt-stats` — statistics over client-facing events/results as currently designed. `irtt-rs` (application package, `crates/irtt-app`) — presentation/orchestration.
+
+- `irtt-proto`: pure protocol encoding/decoding, flags, layouts, params, varints/zigzag, HMAC-MD5, validation. No sockets, runtimes, lifecycle, stats, or presentation.
+- `irtt-client`: socket/session lifecycle, negotiation, probe send/receive, timing metadata, classification, bounded state, and events.
+  - `Client`: runtime-free blocking/manual adapter.
+  - `AsyncClient`: optional Tokio low-level adapter.
+  - `ManagedClientTask` / `ManagedClientHandle`: unified Tokio managed driver/control surface.
+  - `BlockingManagedClient`: synchronous owner using a dedicated current-thread Tokio runtime.
+- `irtt-server`: exists; see "Server architecture (`irtt-server`)" below.
+- `irtt-stats`: cumulative/rolling/finite statistics over client events. No wire/session state machine logic.
+- `irtt-rs` (application package, `crates/irtt-app`): argument parsing, managed orchestration, output, summaries, TUI, server applet orchestration, diagnostics, and exit behavior. Produces the `irtt-rs` multicall dispatcher plus the dedicated `irtt-client`, `irtt-tui`, and `irtt-server` binaries. Do not duplicate protocol/session state machines here.
+
+Tokio must remain optional for `irtt-client`; default builds must remain runtime-free and Tokio-free unless an explicit architectural change says otherwise. This rule is specific to `irtt-client` — do not generalize it to `irtt-server`, which has the opposite policy below.
+
+### Server architecture (`irtt-server`)
+
+`irtt-server` is a first-class reusable server crate. It contains the deterministic OPEN/ECHO/session core — packet admission, authentication policy, open negotiation, the bounded session table, open reply construction, echo processing with its per-session receive state and timestamps, per-session rate limiting, session lifetime with idle expiry, the maximum-duration server-initiated close, and client-initiated close — plus a reusable Tokio UDP `Server` that runs one sequential `ServerCore` per listener with caller-controlled shutdown and scheduled idle maintenance. Logical expiry remains exact on authenticated, structurally valid requests, while the runtime also reclaims expired sessions once per second when no traffic arrives. Each reply carries the raw traffic class it must be sent with, which the runtime applies to the listener before every send. A wildcard listener additionally recovers each request's local destination from packet metadata and sends that request's reply from it, on Linux, macOS and FreeBSD; a wildcard bind on a target without that path is refused at construction rather than served from a routing-table source address. Explicit-address listeners are unaffected everywhere. Echo replies fill their payload from the session's negotiated server fill; the policy and its deliberate divergences are in `crates/irtt-server/AGENTS.md`. Two optional negotiation policies restrict what a session may ask the server to provide — a timestamp allowance and DSCP permission — both off by default and both settled during open negotiation rather than in the runtime. Above that one-listener primitive sits `ServerSet`, the service-level owner of one or more independent `Server`s: it binds them all or none, runs each in its own Tokio task, fans one external shutdown out to them, joins them all, and fails the group if any listener fails or stops early. Ordinary process-level polish and observability decisions are what remains of the server architecture.
+
+- It shares wire semantics with the client through `irtt-proto` and follows the same clean-room boundary.
+- It must **not** depend on `irtt-client` merely to reuse protocol behavior.
+- Unlike `irtt-client`, the server has no product requirement to remain runtime-free: `irtt-server` is intentionally **Tokio-native**, and Tokio does not need to be optional for it.
+- There is currently no requirement for a blocking server API, alternate async runtimes, a runtime abstraction layer, or a runtime-free server feature. Do not build blocking/runtime variants merely for symmetry with the client, and do not invent a mirrored client-style API family (`BlockingServer`, `AsyncServer`, `ManagedServer`, `BlockingManagedServer`, or similar) ahead of agreement.
+- Protocol/session logic should be separated from socket/runtime orchestration where that materially improves deterministic testing, ownership clarity, state-machine reasoning, or maintainability. A `ServerCore`-like internal boundary is therefore desirable, but its exact name/API is not prescribed, it need not be public, it is not a promise of runtime independence, and simple code should not be tortured merely to make the core artificially pure.
+- Runtime/server orchestration belongs around that core and may freely use Tokio for UDP sockets, `recv_from`/`send_to`, IPv4/IPv6 listeners, timers, session expiry, max-duration deadlines, shutdown, bounded control/config channels where useful, and `select!`-style orchestration.
+- Ownership is layered and the layers do not blur: `Server` is the one-listener primitive (one socket, one `ServerCore`, one sequential loop), and `ServerSet` supervises one or more of them without owning protocol or session state itself. A common `ServerConfig` is cloned into each listener, so its bounds — `max_sessions` included — are per listener and not per process. Listeners share nothing else: no shared `ServerCore`, no global session table or token namespace, no shared clock, and one sequential sender per socket, which is what keeps the socket-wide reply traffic class race-free.
+- The server applet exists behind the `irtt-rs` application package's `server` feature, which is part of that crate's default build. It is thin orchestration/configuration over reusable `irtt-server` — one current-thread Tokio runtime, one repeatable `--bind`, one `ServerSet` — and must not grow a second server state machine. **It always uses `ServerSet`, including for a single bind**: there is no direct CLI-to-`Server` path and no bind-count branch, so startup, shutdown and listener-failure semantics are identical whatever was configured, and the singleton case exercises the same orchestration in normal use. Hostname resolution, interface expansion, daemonization, and configuration files are deliberately absent.
+- Resource policy: the server should use bounded session/resource policy. Upstream's observed lack of useful default session/per-peer bounds, and its never expiring a session that has not carried an echo request (see `IRTT_SERVER_PROTOCOL_SPEC.md`), are not interoperability requirements and must not be reproduced merely for compatibility.
+- Testing: prefer `irtt-server` for normal compliant fake-peer behavior where practical, as far as its implemented behavior reaches. Keep narrow adversarial/raw peers for intentionally malformed, ambiguous, or non-compliant wire behavior.
+
+## Engineering rules
+
+- Make the smallest coherent change that solves the requested problem.
+- Avoid unrelated cleanup and speculative abstractions.
+- Preserve public API and wire behavior unless the task explicitly changes them.
+- Treat resource bounds, wake behavior, blocking, cancellation, cleanup, and lifecycle termination as correctness concerns in long-running code.
+- Keep fallible preparation before irreversible side effects where transaction semantics require it.
+- Do not suppress compiler or Clippy warnings merely to make checks green.
+- If an apparent defect may encode an intentional design decision, inspect surrounding code/docs/history and ask rather than silently redesigning it.
+
+## Testing policy
+
+Tests protect durable behavior, compatibility, and important invariants. They do not exist to maximize test count or coverage percentage. Tests are maintained repository code: every persistent test adds review, CI, refactoring, and maintenance cost, so it must justify that cost.
+
+### Test at the owning layer
+
+Prefer production interfaces and component/integration tests at the lowest architectural layer that owns the complete behavior. Higher-level or process-level is not inherently better.
+
+- `irtt-proto`: wire formats, codecs, validation, malformed input, and protocol boundaries.
+- `irtt-client`: client/session behavior, multi-target orchestration, burst/staggered pacing, scheduling, lifecycle, managed events, and target updates.
+- `irtt-server`: server/session behavior and server runtime/orchestration.
+- `irtt-stats`: statistics, loss/IPDV accounting, rolling windows, and retention bounds.
+- `irtt-rs` / `irtt-app`: behavior introduced by the application layer itself, such as argument-to-config mapping, presentation/formatting, app-specific diagnostics/exit policy, and genuine process/signal behavior.
+
+Do not move library behavior into application-binary tests merely to make it more end-to-end. For example, pacing and multi-target scheduling belong in `irtt-client` even though the CLI exposes them.
+
+### Every persistent test must earn its place
+
+Before adding or retaining a test, be able to state the durable behavior, compatibility guarantee, regression, or invariant it protects. Other agents and humans will review tests on that basis. Do not add persistent tests merely because code changed, a branch exists, coverage would increase, or the test was useful during implementation.
+
+One strong behavioral test through a normal production interface is usually better than several tests of private helpers or reconstructed internals. Be especially skeptical of unit tests that depend on private functions, methods, structs, fields, or implementation sequence: harmless internal refactors should not require test rewrites.
+
+Avoid tests that primarily:
+
+- assert private representation or historical implementation details;
+- mirror implementation steps or exercise branches solely for coverage;
+- duplicate stronger coverage at another layer;
+- pin exact human-readable wording unless that wording is itself contractual;
+- test standard-library/dependency behavior;
+- use subprocess machinery or test-only observability when the owning crate exposes the behavior directly.
+
+If a component/integration test through the owning crate's normal API protects the same durable behavior, prefer it unless a focused unit test materially improves precision, diagnosis, or coverage of a hard-to-observe invariant.
+
+### Unit tests where they earn it
+
+Focused unit/table-driven tests are appropriate for stable pure or algorithmic behavior, especially protocol codecs/vectors, statistics formulas, hand-rolled data structures, and resource/liveness invariants that cannot be observed reliably from a higher-level production interface.
+
+### Temporary implementation tests
+
+Temporary narrow tests are welcome while implementing/debugging a change to prove a hypothesis, reproduce a bug, or exercise a difficult state transition. Remove or consolidate them before finalizing unless they independently protect a durable regression or invariant.
+
+### Resource/liveness tests and hooks
+
+Direct low-level tests and test-only counters are justified when the invariant is otherwise not observable, e.g. bounded work per poll, no starvation/eventual progress, avoiding an otherwise O(n) hot-path operation, or exact cancellation/stop/update linearization.
+
+Assert the invariant rather than the current mechanism used to achieve it. Prefer “bounded work and eventual progress” over a specific private cursor value when another fair implementation would also be valid.
+
+`#[cfg(test)]` fault injection is acceptable for conditions that cannot be produced reliably through normal interfaces, such as socket-option failures, short sends, false readiness, exact cancellation points, sequence wrap, or race linearization. Do not add test-only production hooks solely for convenient observability.
+
+### Fake peers and interoperability
+
+Use production protocol encoders/decoders for compliant fake peers. Do not maintain shadow packet encoders in tests unless intentionally constructing malformed wire data.
+
+Prefer a real `irtt-server` for normal compliant behavior once available; keep small adversarial peers for behavior a compliant server should not produce.
+
+Cross-implementation tests are especially valuable because two `irtt-rs` endpoints can otherwise agree on the same mistake.
+
+When compatibility is in question, prefer black-box interoperability testing
+against an upstream `irtt` executable where practical. Follow
+`docs/INTEROP_COMPARISON.md` and treat upstream only as an external executable;
+do not inspect its source or tests.
+
+### Synchronization and timing
+
+Prefer synchronization on actual events/state over sleeps or tiny wall-clock windows.
+
+- Use channels, condvars, packet gates, or equivalent deterministic signals with bounded failure timeouts.
+- Sleeps are fine when oversleeping cannot invalidate correctness; do not sleep merely hoping another thread/process finished work.
+- Avoid wall-clock assertions that include process spawn or unrelated setup time.
+- Condition-wait loops must be bounded and fail with a useful diagnostic rather than hang.
+
+When a test fails after a legitimate implementation change, determine whether production regressed or the harness encoded an invalid assumption. Do not change correct production behavior merely to satisfy a brittle test.
+
+## Workflow and verification
+
+For non-trivial work:
+
+1. Inspect relevant code, tests, and local protocol/design references.
+2. Identify the externally meaningful contract or internal invariant.
+3. Make a short plan for multi-file or subtle lifecycle/state changes.
+4. Implement the smallest coherent patch.
+5. Run focused verification while iterating.
+6. Review the final diff for accidental scope, brittle tests, and unnecessary test hooks.
+7. Run broader verification appropriate to the risk.
+
+Skip planning ceremony for tiny obvious edits. Do not add unrelated tests, abstractions, docs, or refactors merely because they are nearby.
+
+Use the narrowest useful checks first. For substantive workspace changes, final verification should normally include:
+
+```sh
+cargo fmt --all -- --check
+cargo check --workspace --all-targets --all-features --locked
+cargo test --workspace --all-targets --all-features --locked
+cargo test --workspace --doc --all-features --locked
+cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
+```
+
+Also verify `--no-default-features` when changing feature gates, optional dependencies, runtime boundaries, or code intended to build without Tokio.
+
+Interop tests require an external `irtt` binary and should only run when the task concerns interoperability or explicitly requests them. Do not run repetition loops, fuzzing, Miri, Loom, mutation testing, or similar expensive checks as routine ceremony.
+
+Never claim a command passed unless it actually ran successfully.
+
+## Repository hygiene
+
+- Do not use destructive Git operations unless explicitly requested.
+- Do not push, force-push, create/update a PR, or rewrite unrelated history unless explicitly requested.
+- Keep commits scoped to the requested work and preserve unrelated local changes.
+
+## Completion
+
+Report concisely:
+
+1. what changed;
+2. verification actually run and its result;
+3. meaningful tests added/updated/consolidated/removed, with justification for each persistent test added or materially expanded;
+4. remaining risks, ambiguities, or follow-ups.
+
+Do not produce a giant changelog of incidental edits.

CHANGELOG.md

@@ -0,0 +1,193 @@
+# Changelog
+
+This project's crates are versioned independently. Each release below is
+scoped to a single crate and tagged as `<crate>/vX.Y.Z` (see
+[Releasing](#releasing) below).
+
+All notable changes to each crate are documented in its own section per
+release. The format is loosely based on
+[Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## irtt-proto
+
+### 0.5.0
+
+#### Added
+
+- New server-direction wire codecs: `decode_open_request`, `encode_open_reply`, `decode_echo_request`, `encode_echo_reply`, and `decode_close_request`, so a server implementation (now `irtt-server`) can encode/decode the same wire format the client side already used, instead of duplicating protocol logic outside this crate.
+- New `ProtoError` variants `MissingField` and `UnexpectedField` for structural validation of optional fields that must be present/absent together.
+
+#### Changed
+
+- `encode_echo_request` (and the request-side echo codec generally) now takes the negotiated params as a separate argument rather than bundling them into `EchoRequest` — a breaking signature change for any direct caller of the proto-level echo encoder.
+- `ProtoError::NegativePacketLength` was renamed to `ProtoError::PacketLengthUnrepresentable { length: i64 }`, reflecting that the check now rejects any length that doesn't fit the wire representation, not only negative ones — a breaking rename for callers matching on this variant.
+
+#### Compatibility
+
+- The echo-reply length codec now accepts upstream `irtt`'s longer midpoint-echo compatibility length instead of rejecting it, fixing an interop gap against real upstream servers/clients that send that length.
+
+## irtt-client
+
+### 0.5.1
+
+#### Added
+
+- `ManagedCommandReceipt::blocking_wait()` lets synchronous callers wait for a managed target-set update to be applied or rejected without entering an async runtime.
+
+### 0.5.0
+
+#### Added
+
+- New optional `tokio` Cargo feature adding `AsyncClient`, a low-level non-blocking/poll-based Tokio adapter alongside the existing runtime-free blocking `Client`.
+- New managed driver stack built on top of `AsyncClient`: `ManagedClientTask` / `ManagedClientHandle` (a unified Tokio-based managed driver and control surface, supporting dynamic per-target updates to a running session group) and `BlockingManagedClient` (a synchronous owner that runs a dedicated current-thread Tokio runtime internally). This replaces the project's earlier managed-client design outright rather than extending it, including changes to the `ClientError` variants it can surface.
+- Linux kernel receive-timestamp capture (`SO_TIMESTAMPING`-family ancillary data) feeding one-way-delay (OWD) calculations, and equivalent kernel transmit-timestamp capture on the send side, materially improving OWD accuracy over the previous best-effort user-space send/receive timestamps on Linux. Both require the `ancillary` feature.
+
+#### Fixed
+
+- DSCP wire semantics: the negotiated DSCP value was being shifted twice on the wire path (double-application of the ECN/DSCP bit layout), which produced an incorrect traffic-class byte in some configurations; the client-side DSCP handling was reworked to apply the shift exactly once and is covered by expanded DSCP/negotiation tests.
+- Post-send timestamp capture correctness fix so the locally-recorded send timestamp used for OWD/RTT calculations reflects when the probe actually left the socket rather than a timestamp that could be skewed by scheduling between encode and send.
+- A batch of managed-session liveness and lifecycle fixes: dynamic target groups no longer spin instead of blocking while idle; empty dynamic groups stay idle correctly; peer-initiated closes are now recorded and surfaced (including counters/provenance) instead of being silently dropped or racing with correlation; authenticated close is honored ahead of reply correlation; terminal outcomes are now published for targets that fail rather than being dropped silently; completed event hubs are sealed and completed-target retention is bounded (preventing unbounded growth in long multi-target runs); missed probe slots are skipped rather than mis-scheduled; dropped-subscription events are now exposed to consumers instead of being swallowed; and a timeout-budget bug in the managed opening phase was corrected.
+- Linux receive paths (blocking `Client::open`/`recv_once`/`recv_available`, `AsyncClient`'s non-blocking recv/open polling, and the MSG_ERRQUEUE TX-timestamp drain) now retry transparently on `EINTR` instead of surfacing it as a fatal socket error, while preserving each path's existing timeout/deadline contract (no retransmit, no timeout extension under repeated interruption).
+- `ClientError` failure classification was made exhaustive/more precise, giving callers a fuller and more accurate error taxonomy to match on instead of a catch-all in some paths.
+
+#### Compatibility
+
+- The `ancillary` (Linux socket ancillary-data) feature was hardened to only perform safe operations, closing a soundness gap in how ancillary control-message buffers were handled.
+
+## irtt-server
+
+### 0.5.2
+
+#### Changed
+
+- `parse_hex_pattern`'s chunking now uses the stable `slice::as_chunks` API instead of `chunks_exact`; no behavior change.
+
+### 0.5.1
+
+#### Added
+
+- New public `address_family_available()` helper (re-exported from `set`), for probing whether an address family can actually bind locally rather than merely constructing a socket for it. Used by the `irtt-rs` server applet to distinguish a genuinely unsupported address family from an ordinary bind failure when falling back from its default dual-family bind.
+
+### 0.5.0
+
+#### Added
+
+- `irtt-server` is a new first-class, reusable crate this release, built from scratch: a deterministic `ServerCore` handling OPEN/ECHO/CLOSE packet admission, authentication policy, open negotiation, a bounded session table, echo processing with per-session receive state and timestamps, per-session rate limiting, session lifetime with idle expiry, server-initiated close on maximum duration, and client-initiated close.
+- A reusable Tokio UDP `Server` runs one sequential `ServerCore` per listener with caller-controlled shutdown and once-per-second scheduled idle-session maintenance (in addition to exact logical expiry on authenticated, structurally valid requests). `ServerSet` sits above it as the service-level owner of one or more independent `Server`s: it binds them all-or-none, runs each in its own Tokio task, fans one external shutdown signal out to all of them, joins them, and fails the group if any listener fails or stops early — enabling multi-listener deployments from a single `ServerConfig`.
+- Each reply now carries the raw traffic class it must be sent with, applied to the listener socket immediately before every send.
+- Wildcard listeners recover each request's local destination from packet ancillary metadata and send that request's reply from the same address, on Linux, macOS, and FreeBSD. `Server::from_socket`/`Server::bind` are now fallible specifically because of this: a wildcard bind on a platform without that path is refused at construction (`ServerRuntimeError::WildcardSourceSelectionUnsupported`) rather than silently served from a routing-table-chosen source address. Explicit-address listeners are unaffected on all platforms.
+- Configurable echo-reply payload fill policy (`ServerFill`), controlling what bytes a session's echo replies are padded with.
+- Two optional negotiation policies, both off by default and settled during open negotiation: a timestamp allowance and a DSCP permission, restricting what a session may ask the server to provide.
+- Linux kernel receive-timestamp capture for inbound packets, feeding more accurate server-side timing metadata, mirroring the equivalent client-side capability added in `irtt-client`.
+
+#### Fixed
+
+- The DSCP/traffic-class byte applied to replies was corrected to match the client-side wire-semantics fix (see `irtt-client`), so server-echoed DSCP marking is now consistent with what clients expect.
+- Executable-params validation on OPEN requests was tightened so malformed/contradictory negotiated parameters are rejected during open negotiation rather than accepted and mishandled later.
+- Packet-length policy corrected so oversized/invalid negotiated lengths are rejected consistently with the updated `irtt-proto` length validation.
+- A receive-drop/backpressure policy fix for malformed or unauthenticated inbound packets, preventing them from disrupting the session table or other in-flight sessions.
+- A receive-timestamp "wall clock" fix on the kernel RX-capture path, and a 32-bit (i686) `timespec` conversion correctness fix covered by a dedicated regression test.
+- The server's ancillary receive loop now retries transparently on `EINTR` instead of terminating the listener, matching the equivalent `irtt-client` fix.
+
+#### Compatibility
+
+- Resource bounds are enforced by design (bounded session table, per-listener `max_sessions`, rate limiting, idle/max-duration expiry) rather than mirroring upstream `irtt`'s effectively unbounded session/per-peer behavior; this is a deliberate divergence, not an oversight, and is documented in `crates/irtt-server/AGENTS.md`.
+
+## irtt-stats
+
+### 0.5.0
+
+#### Fixed
+
+- Exact median calculation for `send_call`, `timer_error`, and `server_processing` event-duration statistics, which previously always reported `None` for these medians instead of a computed value.
+
+#### Added
+
+- `LateReplyMode` (`Measure` / `CountOnly`) lets a consumer choose whether replies that arrive after their probe is considered late are still fully measured into the running statistics or only counted, without affecting the other samples.
+- `StatsConfig::estimated_retained_bytes(probe_count)` gives callers an API to estimate the memory a stats configuration will retain for a given probe count, ahead of actually running a session (used by `irtt-cli`'s multi-target memory-usage warning, see below).
+
+## irtt-rs
+
+### 0.7.0
+
+#### Added
+
+- Client target arguments now support per-target HMAC configuration: append `@hmac=KEY` to override the global `--hmac` value for that target, or use `@hmac=` to explicitly disable HMAC for it. The target syntax supports context-aware escaping for literal delimiters.
+- Continuous client runs can now take complete desired target sets from standard input with `--targets-stdin`. Each non-empty record atomically replaces the current set, `[]` selects an empty set, and EOF requests a graceful stop. The controller retains only the newest unapplied record under transient replacement backpressure, with explicit bounds on record size, desired targets, and live target generations.
+
+#### Changed
+
+- A peer-initiated close is now target-local in stdin-controlled continuous runs: the controller and other desired targets keep running, and a later desired set can start that target again.
+
+### 0.6.2
+
+#### Added
+
+- Every `irtt-server` applet flag can now also be set via an `IRTT_SERVER_*` environment variable (`IRTT_SERVER_BIND`, `IRTT_SERVER_HMAC`, `IRTT_SERVER_MAX_SESSIONS`, `IRTT_SERVER_MAX_PACKET_LENGTH`, `IRTT_SERVER_MIN_INTERVAL`, `IRTT_SERVER_BURST`, `IRTT_SERVER_IDLE_TIMEOUT`, `IRTT_SERVER_MAX_DURATION`, `IRTT_SERVER_TIMESTAMP_ALLOWANCE`, `IRTT_SERVER_NO_DSCP`), for deployments that configure by environment (containers, orchestrators) instead of command-line flags. An explicit flag on the command line still overrides the corresponding variable.
+- A `Dockerfile` and Gitea Actions workflow publishing a minimal, statically linked `irtt-server` container image (cross-compiled for `amd64`/`arm64` via `tonistiigi/xx`, no QEMU) to this project's Gitea and GHCR container registries.
+
+#### Changed
+
+- The bundled `ctrlc` dependency now enables its `termination` feature, so the applet also handles `SIGTERM` (not just `SIGINT`) for graceful shutdown.
+
+### 0.6.1
+
+#### Added
+
+- The `irtt-server` applet now has sensible zero-argument defaults: with no `--bind`, it binds the wildcard IRTT port on both address families (`[::]:2112` then `0.0.0.0:2112`) instead of requiring an explicit address, on platforms where wildcard reply-source selection is supported. Any explicit `--bind` fully replaces the default pair rather than adding to it.
+
+#### Changed
+
+- If one of the two default listeners fails because its address family has no local support on the host (e.g. IPv6 administratively disabled on an otherwise IPv4-capable host), the server now falls back to serving just the surviving family instead of failing outright. Any other failure reason (port in use, permission denied, no safe wildcard reply-source path) still fails startup as it would for an explicit `--bind`.
+
+### 0.6.0
+
+#### Changed
+
+- The application Cargo package was renamed from `irtt-cli` to `irtt-rs`, moving to `crates/irtt-app`. This is the application distribution package that produces the `irtt-rs`, `irtt-client`, `irtt-tui`, and `irtt-server` binaries; it is unrelated to the reusable `irtt-client` library crate, which keeps its existing name and version.
+- The `irtt-cli` executable was hard-renamed to `irtt-client` to avoid reading as an umbrella CLI now that the application also ships a first-class server. There is no `irtt-cli` compatibility binary or alias.
+- Dedicated binaries now have role-specific entry points (`irtt-client`, `irtt-tui`, `irtt-server`) instead of all funneling through the multicall dispatcher's argv0/subcommand logic. Each dedicated binary always runs its own role regardless of the name it is invoked or copied under, and no longer links code for the other applet roles it doesn't implement. The `irtt-rs` binary remains the feature-selectable multicall dispatcher and is the only binary that inspects argv0 or subcommands.
+- Future application releases move to the `irtt-rs/vX.Y.Z` tag namespace (previously `irtt-cli/vX.Y.Z`); see [Releasing](#releasing).
+
+## irtt-cli
+
+### 0.5.0
+
+#### Added
+
+- A new `server` applet (the `irtt-server` binary and `irtt-rs server` subcommand), gated behind the `server` Cargo feature which is now part of `irtt-cli`'s default feature set. It is thin orchestration over the new `irtt-server` crate: one current-thread Tokio runtime, one repeatable `--bind`, and `ServerSet` for startup/shutdown/listener-failure handling — including for a single bind.
+- Positional `[LABEL=]TARGET` argument syntax for specifying client targets.
+
+#### Changed
+
+- Target specification moved from a `--target LABEL=TARGET` flag to plain positional `[LABEL=]TARGET` arguments — a breaking CLI syntax change for any script invoking targets via the old flag.
+- The `Target` column is now always present in default, CSV, TSV, and JSONL output, rather than only appearing once more than one target was specified. This is a breaking output-format change for scripts that parsed single-target output and assumed no `Target` column.
+- Cargo feature flags were simplified: the separate `stats`, `full`, and `client-runtime` features were removed, and statistics support is now mandatory whenever the `client` (or `tui`) feature is enabled, rather than optional. Consumers building with `--no-default-features` and selectively re-enabling a `stats` or `client-runtime` feature will need to update their feature selection.
+- The stats-related memory-usage warning now scales with the number of configured targets (using `irtt-stats`'s new `estimated_retained_bytes`), instead of assuming a single target's worth of retained memory.
+
+#### Fixed
+
+- Single-target runs are now driven through the same `ManagedClient` path as multi-target runs, instead of a separate single-target code path, fixing behavioral drift between the two (e.g. continuous single-target runs now stop correctly on peer-initiated close and multi-target failures are now reported with a nonzero exit status).
+- Continuous (unbounded-duration) runs, both single- and multi-target, now stop and report correctly when the peer closes the session, instead of hanging or exiting silently.
+- The TUI's input-event draining is now bounded per tick, fixing a starvation/liveness issue where a burst of input could stall rendering or probe scheduling.
+- The TUI's live graph history buffer is now allocated lazily instead of eagerly, avoiding unnecessary upfront allocation for graphs that are never shown.
+- A managed-session terminal-state reconciliation fix in the CLI's use of the managed client, correcting a case where a target's final/terminal outcome could be reconciled incorrectly.
+
+#### Compatibility
+
+- MSRV raised to Rust 1.88 (from 1.85), to track `ratatui`'s minimum supported Rust version; this applies to the whole workspace, including `irtt-cli`.
+- CI test coverage was expanded to include `musl` and `aarch64` targets, increasing confidence in `irtt-cli` binaries built for those platforms (no code-level behavior change).
+
+## Releasing
+
+Starting with this release, crates are versioned and tagged independently
+rather than in lockstep. Each crate's release is tagged as `<crate>/vX.Y.Z`
+(e.g. `irtt-proto/v0.5.0`), pointing at the commit its version was released
+from. `irtt-proto`, `irtt-client`, `irtt-server`, and `irtt-stats` are
+libraries published to [crates.io](https://crates.io); their tags exist to
+identify the exact source for a given crates.io release and do not produce a
+GitHub Release. The application package (`irtt-cli` through 0.5.0, `irtt-rs`
+from 0.6.0 onward) is the only package with prebuilt binary artifacts: pushing
+an `irtt-rs/vX.Y.Z` tag triggers [cargo-dist](https://opensource.axo.dev/cargo-dist/)
+to build and publish a GitHub Release with platform binaries. The historical
+`irtt-cli/v0.5.0` tag remains as released; it is not rewritten or replaced.

CLAUDE.md

@@ -0,0 +1,4 @@
+# Claude Code
+
+Read and follow `AGENTS.md` before making changes. When working below a subtree
+that contains a more specific `AGENTS.md`, read and follow that file as well.

Cargo.toml

@@ -2,32 +2,32 @@
 members = [
     "crates/irtt-proto",
     "crates/irtt-client",
+    "crates/irtt-server",
     "crates/irtt-stats",
-    "crates/irtt-cli",
+    "crates/irtt-app",
+    "crates/irtt-integration-tests",
 ]
 resolver = "2"
 
 [workspace.package]
 edition = "2021"
 license = "Apache-2.0"
-rust-version = "1.85"
+rust-version = "1.88"
 repository = "https://github.com/Lochnair/irtt-rs"
 homepage = "https://github.com/Lochnair/irtt-rs"
-readme = "README.md"
 
 [workspace.dependencies]
-irtt-proto = { version = "0.4.0", path = "crates/irtt-proto" }
-irtt-client = { version = "0.4.0", path = "crates/irtt-client" }
-irtt-stats = { version = "0.4.0", path = "crates/irtt-stats" }
+irtt-proto = { version = "0.5.0", path = "crates/irtt-proto" }
+irtt-client = { version = "0.5.1", path = "crates/irtt-client" }
+irtt-server = { version = "0.5.2", path = "crates/irtt-server" }
+irtt-stats = { version = "0.5.0", path = "crates/irtt-stats" }
 
 [profile.release]
 opt-level = "z"
 lto = true
 codegen-units = 1
-panic = "abort"
 strip = "symbols"
 
 # The profile that 'dist' will build with
 [profile.dist]
 inherits = "release"
-lto = "thin"

Dockerfile

@@ -0,0 +1,42 @@
+# syntax=docker/dockerfile:1
+
+# Builds the irtt-server applet only, statically linked against musl, and
+# ships it in a scratch image with no shell or libc.
+#
+# Cross-compiles for TARGETPLATFORM using tonistiigi/xx: the builder stage
+# always runs natively on BUILDPLATFORM (no QEMU emulation) and xx-cargo
+# picks the right musl target triple, sysroot, and linker for whatever
+# platform buildx asked for.
+
+FROM --platform=$BUILDPLATFORM tonistiigi/xx AS xx
+
+FROM --platform=$BUILDPLATFORM rust:1.98-alpine AS builder
+
+COPY --from=xx / /
+
+RUN apk add --no-cache clang lld file
+
+ARG TARGETPLATFORM
+RUN xx-apk add --no-cache musl-dev
+
+WORKDIR /build
+
+COPY Cargo.toml Cargo.lock ./
+COPY crates ./crates
+
+RUN xx-cargo build \
+    --release \
+    --locked \
+    -p irtt-rs \
+    --bin irtt-server \
+    --no-default-features \
+    --features server \
+    --target-dir /build/target \
+    && xx-verify /build/target/$(xx-cargo --print-target-triple)/release/irtt-server \
+    && cp /build/target/$(xx-cargo --print-target-triple)/release/irtt-server /irtt-server
+
+FROM scratch
+
+COPY --from=builder /irtt-server /irtt-server
+
+ENTRYPOINT ["/irtt-server"]

README.md

@@ -1,264 +1,180 @@
 # irtt-rs
 
-`irtt-rs` is a Rust implementation of an IRTT-compatible client.
+`irtt-rs` is a Rust implementation of an IRTT-compatible client and server:
+finite or continuous UDP latency probing, plus the server side those probes
+run against.
 
-It is not the upstream IRTT project. For the original implementation, protocol background, and broader project documentation, see:
+This is not the upstream IRTT project. For the original implementation,
+protocol background, and broader documentation, see
+[heistp/irtt](https://github.com/heistp/irtt). The installed dispatcher is
+named `irtt-rs` rather than `irtt` to avoid conflicting with or being
+mistaken for it.
 
-<https://github.com/heistp/irtt>
+## Features
 
-## Status
+* Finite and continuous probe sessions
+* Concurrent probing of multiple targets, with staggered or burst pacing
+* Reusable client library with a structured event stream (blocking, Tokio,
+  or managed)
+* Human-readable table output, plus CSV, TSV, and JSON Lines for scripts and
+  monitoring systems, with selectable output columns
+* Optional terminal UI
+* Reusable Tokio-native server library
+* UDP server applet with sensible zero-argument defaults and explicit bind
+  and session-policy options
+* Router-friendly multi-applet binary layout
 
-This repository currently provides:
+## Comparison with upstream IRTT
 
-- `irtt-rs`, the canonical multi-applet binary
-- `irtt-cli`, a stream/text IRTT-compatible client applet
-- `irtt-tui`, an optional terminal UI applet when built with the `tui` feature
-- `irtt-client`, a Rust library for running client sessions and consuming events
-- finite and continuous probe runs
-- table, CSV, TSV, and JSON Lines event-row output formats with selectable columns
-- optional local summary statistics
+`irtt-rs` is an independent, compatible reimplementation, not a successor or
+replacement for upstream IRTT — [heistp/irtt](https://github.com/heistp/irtt)
+remains the original implementation. Interoperability is a project goal; see
+[`docs/INTEROP_COMPARISON.md`](docs/INTEROP_COMPARISON.md) and
+[`docs/protocol/`](docs/protocol/) for the black-box interoperability
+methodology and protocol baseline this project verifies against. Choose
+between them based on the capabilities and deployment model you need.
 
-Server support is not implemented.
-The installed binary is intentionally not named `irtt` to avoid conflicting or
-confusing overlap with upstream IRTT.
+The table below was checked against upstream release
+[v0.9.2](https://github.com/heistp/irtt/releases/tag/v0.9.2) (2026-07-17).
+This project's own interop testing and protocol baseline are currently
+pinned to the prior release, v0.9.1; the wire protocol version number is
+unchanged between the two, but v0.9.2 has not itself been exercised against
+this project's interop harness.
 
-## Install
+| Capability | irtt-rs | upstream IRTT (v0.9.2) |
+| --- | --- | --- |
+| Wire protocol | Protocol version 1, verified against upstream v0.9.1 | Protocol version 1 (unchanged in v0.9.2) |
+| Finite probing | Supported, default 10s | Supported, default 1m |
+| Continuous/indefinite operation | Supported (`--duration 0`); still computes running statistics (see below) | Supported via streaming mode (`-s`, added in v0.9.2); computes no statistics at all in that mode |
+| Statistics in continuous mode | Running count/min/max/mean/variance per target; exact medians unavailable; bounded IPDV tracking | None in streaming mode — raw/event output only, by design, to avoid unbounded memory |
+| Multi-target probing (one invocation) | Supported, with labels and staggered/burst pacing | Not supported — one remote address per invocation |
+| Terminal UI | `irtt-tui`, a live graph/dashboard applet | Not present |
+| Output formats | table, csv, tsv, jsonl, with selectable columns | Text summary, JSON (optionally gzip to file), and a fixed-field raw mode; no CSV/TSV and no column selection |
+| Client/server library API | Separate, independently versioned Rust crates (`irtt-client`, `irtt-server`) | One combined Go package exposing both roles |
+| Server: multiple listeners | `ServerSet` supervises several listeners in one process | `ListenAndServe` also serves multiple requested addresses |
+| Server: wildcard reply-source | Default behavior on Linux/macOS/FreeBSD; refused elsewhere rather than served incorrectly | Opt-in via `--set-src-ip`, with a documented per-packet allocation cost |
+| Server: zero-argument bind | Binds the wildcard address on both families by default, gated by the platform check above | Binds the wildcard address on both families by default; no documented platform gate |
+| Prebuilt release binaries | Published for six target triples | None published; install via `go install` or manual build |
 
-Requires Rust 1.85 or newer.
+Upstream has capabilities this project does not implement: a `report`
+subcommand for replaying saved JSON results, benchmarking and
+timer/clock-diagnostic subcommands, client-side payload fill and
+don't-fragment/wait-strategy/timer-algorithm controls, an operator-configurable
+server-side fill policy (this project's server always honors a session's
+negotiated fill request, with a fixed fallback pattern, but has no equivalent
+to upstream's flags for restricting or overriding it), syslog logging, and
+bundled systemd/OpenRC service files.
 
-From a local checkout:
+This project has capabilities upstream does not implement: multi-target
+probing with labels, the terminal UI, CSV/TSV output with selectable
+columns, a quantified and actively-warned memory-retention model for
+long-running client sessions, and best-effort Linux kernel-timestamp
+preference for its own send/receive endpoint.
+
+## Installation
+
+The build requires Rust 1.88 or newer.
+
+Install the latest release from crates.io:
+
+```sh
+cargo install irtt-rs --locked
+```
+
+This installs the `irtt-rs` dispatcher plus dedicated `irtt-client`,
+`irtt-tui`, and `irtt-server` binaries. Each applet can also be built in
+isolation with `--no-default-features` plus the applet's own feature, for
+example a lightweight client-only install:
+
+```sh
+cargo install irtt-rs --locked --no-default-features --features client
+```
+
+For development, or to install directly from a checkout:
 
 ```sh
 git clone https://github.com/Lochnair/irtt-rs.git
 cd irtt-rs
-cargo install --path crates/irtt-cli
+cargo install --path crates/irtt-app --locked
 ```
 
-The default install provides the normal client-oriented binaries, including
-`irtt-rs` and `irtt-cli`. To install the TUI applet as a separate binary target:
+## Quick start
+
+Probe a server:
 
 ```sh
-cargo install --path crates/irtt-cli --features tui
+irtt-client netperf-eu.bufferbloat.net:2112 --duration 30s --interval 100ms
 ```
 
-Or run it directly without installing:
+Probe continuously until interrupted (`Ctrl-C`):
 
 ```sh
-cargo run -p irtt-cli --bin irtt-cli -- <server>
+irtt-client netperf-eu.bufferbloat.net:2112 --duration 0
 ```
 
-For space-sensitive packaging, such as OpenWrt packages, distributors can ship
-only `irtt-rs` and symlink or hardlink enabled applet names such as `irtt-cli`
-and, when built with the `tui` feature, `irtt-tui` to it. Applet dispatch is
-based on the invoked binary name. Server support is not implemented.
-
-cargo-dist release archives are currently configured with the `full` feature
-set, so target archives bundle the enabled applet binaries: `irtt-rs`,
-`irtt-cli`, and `irtt-tui`. That is separate from space-sensitive package
-layouts, which may still ship one dispatcher binary plus applet-name symlinks
-or hardlinks. cargo-dist is not currently configured to create those links.
-
-## Build verification
-
-Useful local release/package sanity checks:
+Watch the same session live in the terminal UI:
 
 ```sh
-cargo fmt --check
-cargo test -p irtt-cli
-cargo clippy --workspace --all-targets -- -D warnings
-cargo build -p irtt-cli --release
-cargo build -p irtt-cli --no-default-features --release
-cargo build -p irtt-cli --features tui --release
-cargo build -p irtt-cli --all-features --release
+irtt-tui netperf-eu.bufferbloat.net:2112
 ```
 
-The no-default-features build only provides the `irtt-rs` dispatcher binary;
-the default build provides `irtt-rs` and `irtt-cli`; `tui`, `full`, and
-all-features builds also provide `irtt-tui`.
-
-## CLI usage
-
-Basic test:
+Run a server with sensible defaults — no `--bind` needed:
 
 ```sh
-irtt-cli <server>
+irtt-server
 ```
 
-Set duration and interval:
+## Documentation
+
+* [`docs/irtt-client.md`](docs/irtt-client.md) — target syntax, output
+  formats and columns, measurement field definitions, finite/continuous
+  memory behavior, kernel timestamps.
+* [`docs/irtt-tui.md`](docs/irtt-tui.md) — controls, continuous default,
+  retained history.
+* [`docs/irtt-server.md`](docs/irtt-server.md) — bind defaults and
+  overrides, wildcard listener behavior, session policy, HMAC.
+* [`docs/irtt-rs.md`](docs/irtt-rs.md) — the multicall dispatcher, applet
+  binary names, feature-gated builds.
+* [docs.rs](https://docs.rs) for the library crates below.
+* [`docs/protocol/`](docs/protocol/) and
+  [`docs/INTEROP_COMPARISON.md`](docs/INTEROP_COMPARISON.md) for the wire
+  protocol specification and interoperability validation against upstream
+  `irtt`.
+
+Every applet also documents its full option list with `--help`.
+
+## Crates
+
+| Crate | crates.io | What it is |
+| --- | --- | --- |
+| [`irtt-rs`](crates/irtt-app) | [crates.io](https://crates.io/crates/irtt-rs) | Application package: the `irtt-rs`, `irtt-client`, `irtt-tui`, and `irtt-server` binaries |
+| [`irtt-client`](crates/irtt-client) | [crates.io](https://crates.io/crates/irtt-client) | Reusable client/session library ([docs.rs](https://docs.rs/irtt-client)) |
+| [`irtt-server`](crates/irtt-server) | [crates.io](https://crates.io/crates/irtt-server) | Reusable Tokio-native server library ([docs.rs](https://docs.rs/irtt-server)) |
+| [`irtt-stats`](crates/irtt-stats) | [crates.io](https://crates.io/crates/irtt-stats) | Statistics aggregation over `irtt-client` events ([docs.rs](https://docs.rs/irtt-stats)) |
+| [`irtt-proto`](crates/irtt-proto) | [crates.io](https://crates.io/crates/irtt-proto) | Low-level wire protocol encode/decode ([docs.rs](https://docs.rs/irtt-proto)) |
+
+Each library crate has its own crates.io README describing what it's for and
+when to use it instead of `irtt-client`/`irtt-server` directly.
+
+## Binaries and features
+
+| Build | Binaries |
+| --- | --- |
+| `--no-default-features` | `irtt-rs` |
+| `--no-default-features --features client` | `irtt-rs`, `irtt-client` |
+| `--no-default-features --features server` | `irtt-rs`, `irtt-server` |
+| `--no-default-features --features tui` | `irtt-rs`, `irtt-tui` |
+| Default features (or `--all-features`) | `irtt-rs`, `irtt-client`, `irtt-tui`, `irtt-server` |
+
+## Development
 
 ```sh
-irtt-cli <server> --duration 30s --interval 100ms
+cargo fmt --all -- --check
+cargo test --workspace --locked
+cargo test --workspace --doc --all-features --locked
+cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
 ```
 
-Run continuously:
-
-```sh
-irtt-cli <server> --duration 0
-```
-
-Probe multiple targets concurrently:
-
-```sh
-irtt-cli host-a:2112 host-b:2112
-irtt-cli --target ams=ams.example.com:2112 --target sg=sg.example.com:2112
-irtt-cli host-a:2112 host-b:2112 --pacing burst
-```
-
-For positional multi-target runs, the original target string is used as the
-logical target label. Repeated positional strings get a stable numeric suffix.
-For `--target label=host:port`, `label` is used in the `target` output column.
-Labels must be unique. `--pacing staggered|burst` selects managed group pacing
-for multi-target runs; the default is `staggered`.
-
-Use a specific output format or column selection:
-
-```sh
-irtt-cli <server> --format table
-irtt-cli <server> --format jsonl
-irtt-cli <server> --format csv --columns event,seq,remote,effective_rtt_us
-irtt-cli host-a:2112 host-b:2112 --format csv --columns target,seq,effective_rtt_us
-irtt-cli <server> --format tsv --columns effective_rtt_us --header never
-irtt-cli --list-columns
-```
-
-With the optional TUI feature, `irtt-tui` opens a live cumulative dashboard for
-interactive probing. It defaults to continuous probing, equivalent to
-`--duration 0`. Quit with `q` or `Ctrl-C`; the client will drain and close the
-session gracefully.
-
-```sh
-irtt-tui <server>
-irtt-tui <server> --duration 30s
-irtt-tui host-a:2112 host-b:2112 --pacing burst
-irtt-tui --target ams=ams.example.com:2112 --target sg=sg.example.com:2112
-cargo run -p irtt-cli --features tui --bin irtt-tui -- <server>
-```
-
-For available options:
-
-```sh
-irtt-cli --help
-irtt-tui --help   # when built or installed with the tui feature
-```
-
-## Event row output
-
-The stream client separates event row rendering from final summaries. Event rows
-are controlled by `--format`, `--columns`, and `--header`; final summaries remain
-separate table-style text and are printed for table output when the run policy
-allows a summary.
-
-Formats:
-
-- `table`: default, terminal-readable columns with a header
-- `csv`: comma-separated rows, intended for scripts
-- `tsv`: tab-separated rows, useful for one-value streams and shell pipelines
-- `jsonl`: one JSON object per event row, suitable for streaming consumers
-
-Headers are controlled with `--header auto|always|never`. In `auto`, table, CSV,
-and TSV print one header row; JSON Lines never prints a header.
-
-Columns are selected with `-c, --columns <COLUMNS>`, where `COLUMNS` is a
-comma-separated list. Use `--list-columns` to print the available names. Useful
-columns include:
-
-```text
-target, event, seq, remote, token, rtt, rtt_us, raw_rtt_us, effective_rtt_us,
-adjusted_rtt_us, rd, rd_us, sd, sd_us, ipdv, ipdv_us, proc,
-server_processing_us, bytes, send_call_us, timer_error_us, highest_seen,
-server_received, server_window, dscp, ecn, traffic_class, kernel_rx_ns,
-warning_kind, message, event_wall_ns, client_send_wall_ns,
-client_receive_wall_ns
-```
-
-Aliases are accepted for readability: `receive_delay` and `receive_delay_us`
-for `rd` and `rd_us`, `send_delay` and `send_delay_us` for `sd` and `sd_us`,
-`server_processing` for `proc`, `server_received_count` for
-`server_received`, and `server_received_window` for `server_window`.
-
-The default single-target table output favors readability with compact columns:
-`event,seq,rtt,rd,sd,ipdv,proc,message`. It omits `echo_sent` rows. Passing
-`--columns default` is the same as omitting `--columns`, including the default
-table row filtering. Multi-target defaults add `target` as the first column so
-rows can be attributed to a logical target label. Custom table column selections
-include all event rows. CSV, TSV, and JSONL default to all non-target columns
-for single-target export and include `target` by default for multi-target
-export; use `--columns all` explicitly to request every column in any format.
-Missing table values render as `-`; missing CSV and TSV values render as empty
-fields; missing JSONL values render as `null`.
-
-Use JSON Lines for structured event streaming:
-
-Example:
-
-```sh
-irtt-cli <server> --duration 0 --interval 250ms --format jsonl
-```
-
-Each line is one client event object, for example:
-
-```json
-{"event":"echo_reply","seq":4,"remote":"203.0.113.10:2112","token":null,"rtt":"12.1ms","rtt_us":12100,"raw_rtt_us":12400,"effective_rtt_us":12100,"adjusted_rtt_us":12100,"rd":"6.0ms","rd_us":6000,"sd":"6.1ms","sd_us":6100,"ipdv":"300.0µs","ipdv_us":300,"proc":"300.0µs","server_processing_us":300,"bytes":64,"send_call_us":null,"timer_error_us":null,"highest_seen":null,"server_received":5,"server_window":"0x1f","dscp":0,"ecn":0,"traffic_class":0,"kernel_rx_ns":null,"warning_kind":null,"message":null,"event_wall_ns":1760000000012400000,"client_send_wall_ns":1760000000000000000,"client_receive_wall_ns":1760000000012400000}
-```
-
-Consumers should match on the `event` property and read the columns they need.
-RTT, send-call, and timer-error `*_us` fields are reported in microseconds.
-`raw_rtt_us` is the measured client send-to-receive RTT. `effective_rtt_us` and
-`adjusted_rtt_us` are signed and may be negative when server processing exceeds
-the raw RTT or timing correction produces a negative adjusted value. When
-one-way delay fields are present, `sd_us` and `rd_us` are also signed
-microseconds and may be negative due to wall-clock skew.
-
-For consumers that only need effective RTT values in microseconds, use:
-
-```sh
-irtt-cli <server> --format tsv --columns effective_rtt_us --header never
-```
-
-## Library usage
-
-`irtt-client` can be used directly from Rust code.
-
-Example `Cargo.toml` dependency from a local checkout:
-
-```toml
-[dependencies]
-irtt-client = { path = "crates/irtt-client" }
-```
-
-Minimal managed-client example:
-
-```rust
-use std::time::Duration;
-
-use irtt_client::{
-    ClientConfig, ClientEvent, ManagedClient, SubscriberConfig,
-};
-
-fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let config = ClientConfig {
-        server_addr: "netperf-eu.bufferbloat.net:2112".to_owned(),
-        duration: Some(Duration::from_secs(10)),
-        interval: Duration::from_secs(1),
-        ..ClientConfig::default()
-    };
-
-    let (session, events) =
-        ManagedClient::start_with_subscription(config, SubscriberConfig::default())?;
-
-    while let Ok(event) = events.recv() {
-        match event {
-            ClientEvent::EchoReply { seq, rtt, .. } => {
-                println!("seq={seq} rtt_us={}", rtt.effective.as_micros());
-            }
-            ClientEvent::SessionClosed { .. } => break,
-            _ => {}
-        }
-    }
-
-    let outcome = session.join()?;
-    println!("session ended: {:?}", outcome.end_reason);
-
-    Ok(())
-}
-```
+See [`AGENTS.md`](AGENTS.md) for architecture, testing policy, and the
+clean-room provenance boundary this project maintains against upstream
+`irtt`.

crates/irtt-app/Cargo.toml

@@ -0,0 +1,68 @@
+[package]
+name = "irtt-rs"
+version = "0.7.0"
+description = "IRTT-compatible client, TUI, and server applications"
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+repository.workspace = true
+homepage.workspace = true
+readme = "README.md"
+keywords = ["irtt", "networking", "latency", "rtt"]
+categories = ["command-line-utilities", "network-programming"]
+
+[lib]
+name = "irtt_app"
+doc = false
+
+[[bin]]
+name = "irtt-rs"
+path = "src/bin/irtt-rs.rs"
+
+[[bin]]
+name = "irtt-client"
+path = "src/bin/irtt-client.rs"
+required-features = ["client"]
+# This applet shares its name with the irtt-client library crate, whose rustdoc
+# output it would otherwise collide with.
+doc = false
+
+[[bin]]
+name = "irtt-tui"
+path = "src/bin/irtt-tui.rs"
+required-features = ["tui"]
+
+[[bin]]
+name = "irtt-server"
+path = "src/bin/irtt-server.rs"
+required-features = ["server"]
+# This applet shares its name with the irtt-server library crate, whose rustdoc
+# output it would otherwise collide with.
+doc = false
+
+[features]
+default = ["client", "server", "tui"]
+client = ["dep:irtt-client", "irtt-client/ancillary", "irtt-client/tokio", "dep:irtt-proto", "dep:irtt-stats"]
+server = ["dep:irtt-server", "dep:tokio"]
+tui =["dep:irtt-client", "irtt-client/ancillary", "irtt-client/tokio", "dep:irtt-proto", "dep:irtt-stats", "dep:ratatui", "dep:crossterm"]
+
+[dependencies]
+clap = { version = "4.6.6", features = ["derive", "env"] }
+crossterm = { version = "0.29.0", optional = true }
+ctrlc = { version = "3.5.2", features = ["termination"] }
+irtt-client = { workspace = true, optional = true }
+irtt-proto = { workspace = true, optional = true }
+irtt-server = { workspace = true, optional = true }
+irtt-stats = { workspace = true, optional = true }
+ratatui = { version = "0.30.2", optional = true }
+tokio = { version = "1.53.1", default-features = false, features = ["rt", "time"], optional = true }
+
+[dev-dependencies]
+irtt-server.workspace = true
+tokio = { version = "1.53.1", default-features = false, features = ["rt", "sync"] }
+
+[profile.release]
+opt-level = "z"
+lto = true
+codegen-units = 1
+strip = "symbols"

crates/irtt-app/README.md

@@ -0,0 +1,33 @@
+# irtt-rs
+
+The IRTT-compatible client, TUI, and server applications, packaged as Cargo
+package `irtt-rs`.
+
+Installing this crate builds:
+
+- `irtt-rs` — a multicall dispatcher binary that runs the client, TUI, or
+  server applet by subcommand.
+- `irtt-client` — the dedicated client binary (feature `client`).
+- `irtt-tui` — the interactive terminal UI (feature `tui`).
+- `irtt-server` — the dedicated server binary (feature `server`).
+
+All three features are enabled by default, so a plain `cargo install irtt-rs`
+installs everything.
+
+## This is an application, not a library
+
+This package's library target is undocumented (`doc = false`) and exists only
+to share code between its binaries. If you're looking for the client/session
+or server API to embed in your own Rust program, use
+[`irtt-client`](https://crates.io/crates/irtt-client) or
+[`irtt-server`](https://crates.io/crates/irtt-server) instead.
+
+## Usage
+
+See the [project repository](https://github.com/Lochnair/irtt-rs) for
+installation instructions, command-line usage, and configuration.
+
+## Project
+
+Part of [irtt-rs](https://github.com/Lochnair/irtt-rs), an independent Rust
+implementation of an IRTT-compatible protocol stack.

crates/irtt-app/src/applet.rs

@@ -20,9 +20,9 @@ pub enum AppletDispatch {
 
 pub fn detect_applet_from_argv0(argv0: &str) -> Option<RequestedApplet> {
     match applet_basename(argv0) {
-        "irtt-cli" => Some(RequestedApplet::Client),
+        "irtt-client" => Some(RequestedApplet::Client),
         "irtt-tui" => Some(RequestedApplet::Tui),
-        "irttd" | "irtt-server" => Some(RequestedApplet::Server),
+        "irtt-server" => Some(RequestedApplet::Server),
         "irtt-rs" => None,
         _ => None,
     }
@@ -58,7 +58,7 @@ pub fn dispatch_from_argv(argv: Vec<OsString>) -> Result<AppletDispatch, String>
         "-h" | "--help" => Ok(AppletDispatch::Help(dispatcher_help())),
         "client" => Ok(AppletDispatch::Run {
             applet: RequestedApplet::Client,
-            argv: applet_argv("irtt-cli", &argv[2..]),
+            argv: applet_argv("irtt-client", &argv[2..]),
         }),
         "tui" => Ok(AppletDispatch::Run {
             applet: RequestedApplet::Tui,
@@ -81,7 +81,7 @@ pub fn dispatcher_help() -> String {
         .about("IRTT-compatible multi-applet dispatcher")
         .subcommand(Command::new("client").about(client_applet_about()))
         .subcommand(Command::new("tui").about(tui_applet_about()))
-        .subcommand(Command::new("server").about("Server applet is not available in this build"))
+        .subcommand(Command::new("server").about(server_applet_about()))
         .after_help(dispatcher_after_help());
     command.render_help().to_string()
 }
@@ -102,29 +102,76 @@ fn tui_applet_about() -> &'static str {
     }
 }
 
+fn server_applet_about() -> &'static str {
+    if cfg!(feature = "server") {
+        "Run the UDP server applet"
+    } else {
+        "UDP server applet is not available in this build"
+    }
+}
+
 fn known_applet_binary_names() -> &'static str {
-    "irtt-rs, irtt-cli, irtt-tui, irtt-server"
+    "irtt-rs, irtt-client, irtt-tui, irtt-server"
 }
 
 fn applet_command_names() -> &'static str {
     "client, tui, or server"
 }
 
-fn dispatcher_after_help() -> &'static str {
-    if cfg!(feature = "tui") {
-        "Recognized applet binary names: irtt-cli, irtt-tui, irtt-server"
-    } else if cfg!(feature = "client") {
-        "Recognized applet binary names: irtt-cli, irtt-tui, irtt-server\nOptional applet: irtt-tui requires the tui feature"
-    } else {
-        "Recognized applet binary names: irtt-cli, irtt-tui, irtt-server\nOptional applets: irtt-cli requires the client feature; irtt-tui requires the tui feature"
+fn dispatcher_after_help() -> String {
+    let mut help = "Recognized applet binary names: irtt-client, irtt-tui, irtt-server".to_owned();
+
+    let mut missing = Vec::new();
+    if !cfg!(feature = "client") {
+        missing.push("irtt-client requires the client feature");
     }
+    if !cfg!(feature = "server") {
+        missing.push("irtt-server requires the server feature");
+    }
+    if !cfg!(feature = "tui") {
+        missing.push("irtt-tui requires the tui feature");
+    }
+
+    match missing.len() {
+        0 => {}
+        1 => help.push_str(&format!("\nOptional applet: {}", missing[0])),
+        _ => help.push_str(&format!("\nOptional applets: {}", missing.join("; "))),
+    }
+    help
 }
 
 fn applet_basename(argv0: &str) -> &str {
-    Path::new(argv0)
+    let name = Path::new(argv0)
         .file_name()
         .and_then(|name| name.to_str())
-        .unwrap_or(argv0)
+        .unwrap_or(argv0);
+    strip_suffix_ignoring_case(name, std::env::consts::EXE_SUFFIX)
+}
+
+/// Removes the platform executable suffix from a file name.
+///
+/// The suffix is part of the file name on Windows and empty everywhere else, so
+/// this is a no-op on Unix. Without it, every applet name — including the
+/// `irtt-rs` dispatcher itself — reaches argv0 detection as `<name>.exe` and is
+/// rejected as an unknown applet. The applet names themselves are still matched
+/// exactly; only this platform artifact is case-insensitive, because it is not
+/// a name the user chose.
+///
+/// The suffix is a parameter so that Windows behavior is assertable from any
+/// host, not only where `EXE_SUFFIX` happens to be non-empty.
+fn strip_suffix_ignoring_case<'a>(name: &'a str, suffix: &str) -> &'a str {
+    if suffix.is_empty() || name.len() <= suffix.len() {
+        return name;
+    }
+    let split = name.len() - suffix.len();
+    let (Some(stem), Some(tail)) = (name.get(..split), name.get(split..)) else {
+        return name;
+    };
+    if tail.eq_ignore_ascii_case(suffix) {
+        stem
+    } else {
+        name
+    }
 }
 
 fn applet_argv(applet_name: &str, args: &[OsString]) -> Vec<OsString> {
@@ -141,7 +188,7 @@ mod tests {
     #[test]
     fn applet_detection_maps_binary_names() {
         assert_eq!(
-            detect_applet_from_argv0("/usr/bin/irtt-cli"),
+            detect_applet_from_argv0("/usr/bin/irtt-client"),
             Some(RequestedApplet::Client)
         );
         assert_eq!(
@@ -152,10 +199,63 @@ mod tests {
             detect_applet_from_argv0("irtt-server"),
             Some(RequestedApplet::Server)
         );
+        assert_eq!(detect_applet_from_argv0("irttd"), None);
         assert_eq!(detect_applet_from_argv0("irtt-rs"), None);
         assert_eq!(detect_applet_from_argv0("custom-name"), None);
     }
 
+    #[test]
+    fn old_irtt_cli_binary_name_is_no_longer_a_recognized_applet() {
+        assert_eq!(detect_applet_from_argv0("irtt-cli"), None);
+        assert_eq!(detect_applet_from_argv0("/usr/bin/irtt-cli"), None);
+    }
+
+    #[test]
+    fn applet_detection_ignores_the_platform_executable_suffix() {
+        let exe = std::env::consts::EXE_SUFFIX;
+
+        assert_eq!(
+            detect_applet_from_argv0(&format!("/opt/irtt/irtt-server{exe}")),
+            Some(RequestedApplet::Server)
+        );
+        assert_eq!(
+            detect_applet_from_argv0(&format!("irtt-client{exe}")),
+            Some(RequestedApplet::Client)
+        );
+
+        // The dispatcher's own name must not be taken for an unknown applet.
+        let dispatcher = format!("irtt-rs{exe}");
+        assert_eq!(detect_applet_from_argv0(&dispatcher), None);
+        assert!(dispatch_from_argv(vec![dispatcher.into(), "--help".into()]).is_ok());
+
+        // A name that merely ends in the suffix letters keeps them.
+        assert!(detect_applet_from_argv0("irtt-serverexe").is_none());
+    }
+
+    #[test]
+    fn windows_executable_suffix_handling_is_assertable_from_any_host() {
+        assert_eq!(
+            strip_suffix_ignoring_case("irtt-server.exe", ".exe"),
+            "irtt-server"
+        );
+        assert_eq!(strip_suffix_ignoring_case("IRTT-RS.EXE", ".exe"), "IRTT-RS");
+        assert_eq!(
+            strip_suffix_ignoring_case("irtt-server", ".exe"),
+            "irtt-server"
+        );
+        assert_eq!(
+            strip_suffix_ignoring_case("irtt-serverexe", ".exe"),
+            "irtt-serverexe"
+        );
+        assert_eq!(strip_suffix_ignoring_case(".exe", ".exe"), ".exe");
+        assert_eq!(
+            strip_suffix_ignoring_case("irtt-server.exe", ""),
+            "irtt-server.exe"
+        );
+        // A multi-byte tail must not split mid-character.
+        assert_eq!(strip_suffix_ignoring_case("irtt-så", ".exe"), "irtt-så");
+    }
+
     #[test]
     fn canonical_help_renders_dispatcher_help() {
         let dispatch = dispatch_from_argv(vec!["irtt-rs".into(), "--help".into()]).unwrap();
@@ -170,6 +270,11 @@ mod tests {
             assert!(help.contains("Terminal UI applet is not available in this build"));
         }
         assert!(help.contains("server"));
+        if cfg!(feature = "server") {
+            assert!(help.contains("Run the UDP server applet"));
+        } else {
+            assert!(help.contains("UDP server applet is not available in this build"));
+        }
     }
 
     #[test]
@@ -190,7 +295,7 @@ mod tests {
                 .unwrap(),
             AppletDispatch::Run {
                 applet: RequestedApplet::Client,
-                argv: vec!["irtt-cli".into(), "host:2112".into()],
+                argv: vec!["irtt-client".into(), "host:2112".into()],
             }
         );
         assert_eq!(
@@ -213,7 +318,7 @@ mod tests {
     fn unknown_irtt_binary_name_is_an_error() {
         let err = dispatch_from_argv(vec!["/usr/bin/irtt-typo".into()]).unwrap_err();
         assert!(err.contains("unknown applet name 'irtt-typo'"));
-        assert!(err.contains("irtt-cli"));
+        assert!(err.contains("irtt-client"));
         if cfg!(feature = "tui") {
             assert!(err.contains("irtt-tui"));
         }

crates/irtt-app/src/bin/irtt-client.rs

@@ -1,5 +1,5 @@
 use std::process::ExitCode;
 
 fn main() -> ExitCode {
-    irtt_cli::entry::main()
+    irtt_app::entry::client_main()
 }

crates/irtt-app/src/bin/irtt-rs.rs

@@ -0,0 +1,5 @@
+use std::process::ExitCode;
+
+fn main() -> ExitCode {
+    irtt_app::entry::dispatcher_main()
+}

crates/irtt-app/src/bin/irtt-server.rs

@@ -1,5 +1,5 @@
 use std::process::ExitCode;
 
 fn main() -> ExitCode {
-    irtt_cli::entry::main()
+    irtt_app::entry::server_main()
 }

crates/irtt-app/src/bin/irtt-tui.rs

@@ -1,5 +1,5 @@
 use std::process::ExitCode;
 
 fn main() -> ExitCode {
-    irtt_cli::entry::main()
+    irtt_app::entry::tui_main()
 }

crates/irtt-app/src/cmd/client/args.rs

@@ -1,34 +1,31 @@
 use std::time::Duration;
 
-use clap::{Parser, ValueEnum};
-use irtt_client::ClientConfig;
-
 use crate::shared::client::{
-    parse_labelled_target, parse_test_duration, resolved_managed_targets, target_specs,
-    CommonClientArgs, GroupPacingArg, LabelledTargetArg, ResolvedTarget, TargetSpec, TimestampArg,
+    parse_target, parse_test_duration, prepare_managed_run, CommonClientArgs, GroupPacingArg,
+    ManagedRunSetup, TargetArg, TargetSelection, TimestampArg,
 };
+use clap::{Parser, ValueEnum};
 
 pub const DEFAULT_CLIENT_DURATION: Duration = Duration::from_secs(10);
 
 #[derive(Debug, Clone, Parser)]
-#[command(name = "irtt-cli", about = "Minimal IRTT-compatible stream client")]
+#[command(name = "irtt-client", about = "Minimal IRTT-compatible stream client")]
 pub struct ClientArgs {
-    /// Server address or host, with optional port. Repeat for multi-target mode.
+    /// Server address/host, optionally prefixed with LABEL= and suffixed with @hmac=KEY. Repeat for multi-target mode.
     #[arg(
         value_name = "TARGET",
         num_args = 0..,
-        long_help = "Server address or host, with optional port. Repeat the positional target for multi-target mode, for example: irtt-cli host-a:2112 host-b:2112."
+        value_parser = parse_target,
+        long_help = "Server address/host, optionally prefixed with LABEL= and suffixed with @hmac=KEY. Repeat for multi-target mode.\n\nExamples:\n  irtt-client host-a:2112 host-b:2112\n  irtt-client eu=host-a:2112 us=host-b:2112\n  irtt-client ams=host-a:2112@hmac=secret public=host-b:2112@hmac=\n\nA target without @hmac= inherits --hmac. @hmac= explicitly disables it for that target."
     )]
-    pub targets: Vec<String>,
+    pub targets: Vec<TargetArg>,
 
-    /// Explicit labelled target, as label=host:port. Repeat for multi-target mode.
+    /// Read complete desired target sets from standard input in continuous mode.
     #[arg(
-        long = "target",
-        value_name = "LABEL=TARGET",
-        value_parser = parse_labelled_target,
-        long_help = "Explicit labelled target, as label=host:port. Repeat for multi-target mode. The label is used as the target column and must be unique."
+        long,
+        long_help = "Read one complete desired target set per stdin line in continuous mode. Commas separate targets and backslash escapes commas within a target. [] selects an empty desired set. Records are limited to 64 KiB. EOF stops the client gracefully and may discard a revision that has not yet been acknowledged as applied."
     )]
-    pub labelled_targets: Vec<LabelledTargetArg>,
+    pub targets_stdin: bool,
 
     /// Managed group pacing for multi-target mode.
     #[arg(
@@ -44,7 +41,7 @@ pub struct ClientArgs {
         default_value = "10s",
         value_parser = parse_test_duration,
         help = "Test duration; use 0 for continuous mode",
-        long_help = "Test duration; use 0 for continuous mode.\n\nFinite runs retain exact statistics for final summaries. Continuous mode uses bounded-memory running statistics and prints a final summary only when interrupted."
+        long_help = "Test duration; use 0 for continuous mode.\n\nFinite runs retain exact statistics for final summaries. Continuous mode uses bounded-memory running statistics and prints a final summary when interrupted; --targets-stdin also prints the final retained summary on EOF."
     )]
     pub duration: Duration,
 
@@ -91,11 +88,22 @@ pub struct ClientArgs {
 }
 
 impl ClientArgs {
-    pub fn to_client_config(&self) -> ClientConfig {
-        self.common.to_client_config(
-            self.primary_target_addr()
-                .expect("target is required unless --list-columns is set"),
+    /// Validate the selected targets and prepare the managed run.
+    ///
+    /// Targets are only required here. `--list-columns` returns before this is
+    /// called, so listing columns still needs no target.
+    pub fn prepare(&self) -> Result<ManagedRunSetup, String> {
+        if self.targets_stdin && !self.is_continuous() {
+            return Err("--targets-stdin requires --duration 0".to_owned());
+        }
+        prepare_managed_run(
+            &self.common,
             self.duration,
+            TargetSelection {
+                targets: &self.targets,
+                pacing: self.pacing,
+                stdin_controlled: self.targets_stdin,
+            },
         )
     }
 
@@ -106,24 +114,6 @@ impl ClientArgs {
     pub fn timestamp_mode(&self) -> TimestampArg {
         self.common.tstamp
     }
-
-    pub fn target_specs(&self) -> Result<Vec<CliTargetSpec>, String> {
-        target_specs(&self.targets, &self.labelled_targets)
-    }
-
-    pub fn resolved_managed_targets(&self) -> Result<Vec<ResolvedCliTarget>, String> {
-        let specs = self.target_specs()?;
-        let config = self.to_client_config();
-        resolved_managed_targets(specs, &config)
-    }
-
-    fn primary_target_addr(&self) -> Option<&str> {
-        self.targets.first().map(String::as_str).or_else(|| {
-            self.labelled_targets
-                .first()
-                .map(|target| target.addr.as_str())
-        })
-    }
 }
 
 impl std::ops::Deref for ClientArgs {
@@ -146,9 +136,6 @@ pub enum OutputFormat {
     Jsonl,
 }
 
-pub type CliTargetSpec = TargetSpec;
-pub type ResolvedCliTarget = ResolvedTarget;
-
 impl OutputFormat {
     pub fn prints_summary(self) -> bool {
         matches!(self, Self::Table)
@@ -173,7 +160,7 @@ mod tests {
     use irtt_proto::{Clock, ReceivedStats, StampAt};
 
     fn parse(args: &[&str]) -> Result<ClientArgs, clap::Error> {
-        let mut argv = vec!["irtt-cli"];
+        let mut argv = vec!["irtt-client"];
         argv.extend_from_slice(args);
         ClientArgs::try_parse_from(argv)
     }
@@ -182,18 +169,19 @@ mod tests {
     fn client_parser_keeps_finite_default_duration() {
         let args = parse(&["127.0.0.1:2112"]).unwrap();
 
-        assert_eq!(args.targets, ["127.0.0.1:2112"]);
-        assert!(args.labelled_targets.is_empty());
+        assert_eq!(args.targets.len(), 1);
+        assert_eq!(args.prepare().unwrap().targets[0].label, "127.0.0.1:2112");
         assert_eq!(args.pacing, GroupPacingArg::Staggered);
         assert_eq!(args.duration, DEFAULT_CLIENT_DURATION);
         assert_eq!(args.interval, Duration::from_secs(1));
         assert_eq!(args.format, OutputFormat::Table);
         assert_eq!(args.columns, None);
         assert_eq!(args.header, HeaderMode::Auto);
+        assert!(!args.targets_stdin);
         assert!(!args.is_continuous());
         assert_eq!(args.timestamp_mode(), TimestampArg::Both);
 
-        let config = args.to_client_config();
+        let config = args.prepare().unwrap().client;
         assert_eq!(config.duration, Some(DEFAULT_CLIENT_DURATION));
         assert_eq!(config.received_stats, ReceivedStats::Both);
         assert_eq!(config.stamp_at, StampAt::Both);
@@ -214,40 +202,48 @@ mod tests {
         let args = parse(&["--list-columns"]).unwrap();
         assert!(args.targets.is_empty());
         assert!(args.list_columns);
+        // The parser accepts no target; preparation is where a target becomes
+        // mandatory, and the stream command returns before preparing when
+        // listing columns.
+        let err = args.prepare().unwrap_err();
+        assert!(err.contains("--list-columns"));
     }
 
     #[test]
     fn multiple_positional_targets_parse_as_targets() {
         let args = parse(&["host-a:2112", "host-b:2112"]).unwrap();
-        let specs = args.target_specs().unwrap();
+        let specs = args.prepare().unwrap().targets;
 
         assert_eq!(specs[0].label, "host-a:2112");
-        assert_eq!(specs[0].addr, "host-a:2112");
+        assert_eq!(specs[0].managed.server_addr, "host-a:2112");
         assert_eq!(specs[1].label, "host-b:2112");
-        assert_eq!(specs[1].addr, "host-b:2112");
+        assert_eq!(specs[1].managed.server_addr, "host-b:2112");
     }
 
     #[test]
-    fn repeated_labelled_targets_parse() {
-        let args = parse(&[
-            "--target",
-            "ams=ams.example.com:2112",
-            "--target",
-            "sg=sg.example.com:2112",
-        ])
-        .unwrap();
-        let specs = args.target_specs().unwrap();
+    fn repeated_labeled_targets_parse() {
+        let args = parse(&["ams=ams.example.com:2112", "sg=sg.example.com:2112"]).unwrap();
+        let specs = args.prepare().unwrap().targets;
 
         assert_eq!(specs[0].label, "ams");
-        assert_eq!(specs[0].addr, "ams.example.com:2112");
+        assert_eq!(specs[0].managed.server_addr, "ams.example.com:2112");
         assert_eq!(specs[1].label, "sg");
-        assert_eq!(specs[1].addr, "sg.example.com:2112");
+        assert_eq!(specs[1].managed.server_addr, "sg.example.com:2112");
+    }
+
+    #[test]
+    fn mixed_labeled_and_unlabeled_targets_preserve_argument_order() {
+        let args = parse(&["local.example", "eu=a.example", "backup.example"]).unwrap();
+        let specs = args.prepare().unwrap().targets;
+
+        let labels: Vec<_> = specs.iter().map(|target| target.label.as_str()).collect();
+        assert_eq!(labels, ["local.example", "eu", "backup.example"]);
     }
 
     #[test]
     fn duplicate_labels_are_rejected() {
-        let args = parse(&["host-a:2112", "--target", "host-a:2112=host-b:2112"]).unwrap();
-        let err = args.target_specs().unwrap_err();
+        let args = parse(&["host-a:2112", "host-a:2112=host-b:2112"]).unwrap();
+        let err = args.prepare().unwrap_err();
 
         assert!(err.contains("duplicate target label"));
     }
@@ -255,25 +251,27 @@ mod tests {
     #[test]
     fn duplicate_positional_target_strings_get_stable_suffixes() {
         let args = parse(&["host-a:2112", "host-a:2112"]).unwrap();
-        let specs = args.target_specs().unwrap();
+        let specs = args.prepare().unwrap().targets;
 
         assert_eq!(specs[0].label, "host-a:2112");
         assert_eq!(specs[1].label, "host-a:2112#2");
     }
 
     #[test]
-    fn duplicate_resolved_target_addresses_are_rejected() {
+    fn duplicate_target_endpoints_are_allowed() {
         let args = parse(&["127.0.0.1:2112", "127.0.0.1"]).unwrap();
-        let err = args.resolved_managed_targets().unwrap_err();
-
-        assert!(err.contains("duplicate resolved target address 127.0.0.1:2112"));
+        assert_eq!(args.prepare().unwrap().target_count(), 2);
     }
 
     #[test]
     fn invalid_labelled_target_syntax_is_rejected() {
-        assert!(parse(&["--target", "missing-equals"]).is_err());
-        assert!(parse(&["--target", "=127.0.0.1:2112"]).is_err());
-        assert!(parse(&["--target", "label="]).is_err());
+        assert!(parse(&["=127.0.0.1:2112"]).unwrap().prepare().is_err());
+        assert!(parse(&["label="]).unwrap().prepare().is_err());
+    }
+
+    #[test]
+    fn old_target_option_is_rejected() {
+        assert!(parse(&["--target", "eu=host.example"]).is_err());
     }
 
     #[test]
@@ -296,7 +294,7 @@ mod tests {
     fn client_help_lists_shared_protocol_options() {
         let help = ClientArgs::command().render_help().to_string();
         assert!(help.contains("--format <FORMAT>"));
-        assert!(help.contains("--target <LABEL=TARGET>"));
+        assert!(!help.contains("--target "));
         assert!(help.contains("--pacing <PACING>"));
         assert!(help.contains("--columns <COLUMNS>"));
         assert!(help.contains("--list-columns"));
@@ -309,6 +307,34 @@ mod tests {
         assert!(help.contains("--loose"));
     }
 
+    #[test]
+    fn an_empty_hmac_key_is_rejected() {
+        let err = parse(&["--hmac", "", "127.0.0.1:2112"]).unwrap_err();
+        assert!(err.to_string().contains("HMAC key must not be empty"));
+    }
+
+    #[test]
+    fn a_non_empty_hmac_key_is_accepted() {
+        let args = parse(&["--hmac", "secret", "127.0.0.1:2112"]).unwrap();
+        let config = args.prepare().unwrap().client;
+        assert_eq!(config.hmac_key, Some(b"secret".to_vec()));
+    }
+
+    #[test]
+    fn targets_stdin_requires_continuous_mode_and_allows_empty_initial_set() {
+        assert!(parse(&["--targets-stdin"]).unwrap().prepare().is_err());
+        let args = parse(&["--duration", "0", "--targets-stdin"]).unwrap();
+        let setup = args.prepare().unwrap();
+        assert!(setup.targets.is_empty());
+        assert!(setup.stdin_controlled);
+        let config = setup.managed_config();
+        assert_eq!(
+            config.completion,
+            irtt_client::managed::ManagedCompletionPolicy::ExplicitStop
+        );
+        assert_eq!(config.max_live_target_generations, 256);
+    }
+
     #[test]
     fn output_format_summary_policy_is_table_only() {
         assert!(OutputFormat::Table.prints_summary());

crates/irtt-app/src/cmd/client/mod.rs

@@ -1,7 +1,6 @@
 pub mod args;
 pub mod output;
 pub mod run;
-#[cfg(feature = "stats")]
 pub mod summary;
 
 pub use args::{ClientArgs, HeaderMode, OutputFormat};

crates/irtt-app/src/cmd/client/output.rs

@@ -10,6 +10,7 @@ use irtt_client::{
 };
 
 use super::args::{HeaderMode, OutputFormat};
+use crate::cmd::format::{format_duration, format_signed_duration, ABSENT};
 
 #[derive(Debug, Clone)]
 pub(super) struct OutputConfig {
@@ -26,15 +27,14 @@ impl OutputConfig {
         columns: Option<&str>,
         header: HeaderMode,
         verbose: bool,
-        multi_target: bool,
     ) -> Result<Self, String> {
         let uses_default_columns = columns
             .map(|columns| columns.trim() == "default")
             .unwrap_or(true);
         let default_table_rows = format == OutputFormat::Table && uses_default_columns;
         let columns = match columns {
-            Some(columns) => parse_columns(columns, format, verbose, multi_target)?,
-            None => default_columns(format, verbose, multi_target),
+            Some(columns) => parse_columns(columns, format, verbose)?,
+            None => default_columns(format, verbose),
         };
 
         Ok(Self {
@@ -164,7 +164,6 @@ pub struct IpdvPair {
     pub receive_ipdv: Option<Duration>,
 }
 
-#[cfg(feature = "stats")]
 impl From<irtt_stats::EventStatsUpdate> for EventRenderStats {
     fn from(value: irtt_stats::EventStatsUpdate) -> Self {
         Self {
@@ -174,7 +173,6 @@ impl From<irtt_stats::EventStatsUpdate> for EventRenderStats {
     }
 }
 
-#[cfg(feature = "stats")]
 impl From<irtt_stats::IpdvPairUpdate> for IpdvPair {
     fn from(value: irtt_stats::IpdvPairUpdate) -> Self {
         Self {
@@ -724,12 +722,7 @@ impl CellValue {
     }
 }
 
-fn parse_columns(
-    input: &str,
-    format: OutputFormat,
-    verbose: bool,
-    multi_target: bool,
-) -> Result<Vec<Column>, String> {
+fn parse_columns(input: &str, format: OutputFormat, verbose: bool) -> Result<Vec<Column>, String> {
     let trimmed = input.trim();
     if trimmed.is_empty() {
         return Err("--columns requires at least one column".to_owned());
@@ -738,7 +731,7 @@ fn parse_columns(
         return Ok(ALL_COLUMNS.to_vec());
     }
     if trimmed == "default" {
-        return Ok(default_columns(format, verbose, multi_target));
+        return Ok(default_columns(format, verbose));
     }
 
     let mut columns = Vec::new();
@@ -755,10 +748,11 @@ fn parse_columns(
     Ok(columns)
 }
 
-fn default_columns(format: OutputFormat, verbose: bool, multi_target: bool) -> Vec<Column> {
+fn default_columns(format: OutputFormat, verbose: bool) -> Vec<Column> {
     match format {
         OutputFormat::Table => {
             let mut columns = vec![
+                Column::Target,
                 Column::Event,
                 Column::Seq,
                 Column::Rtt,
@@ -768,9 +762,6 @@ fn default_columns(format: OutputFormat, verbose: bool, multi_target: bool) -> V
                 Column::ServerProcessing,
                 Column::Message,
             ];
-            if multi_target {
-                columns.insert(0, Column::Target);
-            }
             if verbose {
                 columns.extend([
                     Column::Remote,
@@ -785,17 +776,7 @@ fn default_columns(format: OutputFormat, verbose: bool, multi_target: bool) -> V
             }
             columns
         }
-        OutputFormat::Csv | OutputFormat::Tsv | OutputFormat::Jsonl => {
-            if multi_target {
-                ALL_COLUMNS.to_vec()
-            } else {
-                ALL_COLUMNS
-                    .iter()
-                    .copied()
-                    .filter(|column| *column != Column::Target)
-                    .collect()
-            }
-        }
+        OutputFormat::Csv | OutputFormat::Tsv | OutputFormat::Jsonl => ALL_COLUMNS.to_vec(),
     }
 }
 
@@ -819,8 +800,13 @@ fn render_table_row(row: &OutputRow, columns: &[Column], context: RenderContext<
 }
 
 fn format_table_cell(column: &Column, value: Option<String>) -> String {
-    let value = value.unwrap_or_else(|| "-".to_owned());
+    let value = value.unwrap_or_else(|| ABSENT.to_owned());
     let width = column.table_width();
+    let value = if matches!(column, Column::Target) {
+        truncate_for_table(&value, width)
+    } else {
+        value
+    };
     if column.align_right() {
         format!("{value:>width$}")
     } else {
@@ -828,6 +814,25 @@ fn format_table_cell(column: &Column, value: Option<String>) -> String {
     }
 }
 
+/// Shortens `value` to fit within `max_width` display characters for TABLE
+/// presentation only. Values within the limit are returned unchanged. Longer
+/// values keep a prefix and end with `"..."` so the result is exactly
+/// `max_width` characters. Operates on `char`s (never raw byte indices) so a
+/// multibyte UTF-8 value cannot be split mid-code-point.
+///
+/// This is a presentation-only concern: callers must keep the untruncated
+/// value for CSV/TSV/JSONL and any non-display use.
+fn truncate_for_table(value: &str, max_width: usize) -> String {
+    if value.chars().count() <= max_width {
+        return value.to_owned();
+    }
+    let suffix = "...";
+    let prefix_len = max_width.saturating_sub(suffix.len());
+    let mut truncated: String = value.chars().take(prefix_len).collect();
+    truncated.push_str(suffix);
+    truncated
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 enum DelimitedFormat {
     Csv,
@@ -1163,34 +1168,6 @@ fn wall_time_ns(wall: SystemTime) -> Option<u128> {
         .map(|duration| duration.as_nanos())
 }
 
-fn format_duration(duration: Duration) -> String {
-    format_ns(duration.as_nanos() as f64)
-}
-
-fn format_signed_duration(duration: SignedDuration) -> String {
-    format_signed_ns(duration.as_nanos() as f64)
-}
-
-fn format_signed_ns(ns: f64) -> String {
-    if ns < 0.0 {
-        format!("-{}", format_ns(-ns))
-    } else {
-        format_ns(ns)
-    }
-}
-
-fn format_ns(ns: f64) -> String {
-    if ns < 1_000.0 {
-        format!("{ns:.0}ns")
-    } else if ns < 1_000_000.0 {
-        format!("{:.1}µs", ns / 1_000.0)
-    } else if ns < 1_000_000_000.0 {
-        format!("{:.1}ms", ns / 1_000_000.0)
-    } else {
-        format!("{:.3}s", ns / 1_000_000_000.0)
-    }
-}
-
 fn warning_kind(kind: WarningKind) -> &'static str {
     match kind {
         WarningKind::MalformedOrUnrelatedPacket => "malformed_or_unrelated_packet",
@@ -1238,12 +1215,8 @@ mod tests {
         time::Instant,
     };
 
-    fn output_config(
-        format: OutputFormat,
-        columns: Option<&str>,
-        multi_target: bool,
-    ) -> OutputConfig {
-        OutputConfig::new(format, columns, HeaderMode::Auto, false, multi_target).unwrap()
+    fn output_config(format: OutputFormat, columns: Option<&str>) -> OutputConfig {
+        OutputConfig::new(format, columns, HeaderMode::Auto, false).unwrap()
     }
 
     fn remote() -> SocketAddr {
@@ -1283,38 +1256,48 @@ mod tests {
     }
 
     #[test]
-    fn default_table_columns_include_target_only_for_multi_target() {
-        let single = output_config(OutputFormat::Table, None, false)
-            .render_header()
-            .unwrap();
-        let multi = output_config(OutputFormat::Table, None, true)
+    fn default_table_columns_always_include_target_first() {
+        let header = output_config(OutputFormat::Table, None)
             .render_header()
             .unwrap();
 
-        assert!(!single.split_whitespace().any(|column| column == "target"));
-        assert_eq!(multi.split_whitespace().next(), Some("target"));
+        assert_eq!(header.split_whitespace().next(), Some("target"));
     }
 
     #[test]
-    fn default_structured_columns_include_target_for_multi_target() {
-        let single = output_config(OutputFormat::Csv, None, false)
-            .render_header()
-            .unwrap();
-        let multi = output_config(OutputFormat::Csv, None, true)
-            .render_header()
-            .unwrap();
+    fn default_structured_columns_always_include_target_first() {
+        for format in [OutputFormat::Csv, OutputFormat::Tsv, OutputFormat::Jsonl] {
+            let columns = default_columns(format, false);
+            assert_eq!(columns.first(), Some(&Column::Target));
+            assert_eq!(columns, ALL_COLUMNS);
+        }
+    }
 
-        assert!(!single.split(',').any(|column| column == "target"));
-        assert_eq!(multi.split(',').next(), Some("target"));
+    #[test]
+    fn columns_default_keyword_matches_omitted_columns() {
+        for format in [
+            OutputFormat::Table,
+            OutputFormat::Csv,
+            OutputFormat::Tsv,
+            OutputFormat::Jsonl,
+        ] {
+            let omitted = output_config(format, None).render_header();
+            let explicit = output_config(format, Some("default")).render_header();
+            assert_eq!(omitted, explicit);
+        }
+    }
+
+    #[test]
+    fn custom_columns_do_not_insert_target() {
+        let config = output_config(OutputFormat::Csv, Some("seq,effective_rtt_us"));
+        let header = config.render_header().unwrap();
+
+        assert!(!header.split(',').any(|column| column == "target"));
     }
 
     #[test]
     fn custom_target_column_renders_label() {
-        let config = output_config(
-            OutputFormat::Csv,
-            Some("target,seq,effective_rtt_us"),
-            false,
-        );
+        let config = output_config(OutputFormat::Csv, Some("target,seq,effective_rtt_us"));
         let line = config
             .render_event(&reply(), Some("ams"), Some(&EventRenderStats::default()))
             .unwrap();
@@ -1325,4 +1308,170 @@ mod tests {
         );
         assert_eq!(line, "ams,7,1200");
     }
+
+    #[test]
+    fn default_csv_renders_target_label_in_row() {
+        let config = output_config(OutputFormat::Csv, None);
+        let line = config
+            .render_event(&reply(), Some("ams"), Some(&EventRenderStats::default()))
+            .unwrap();
+
+        assert_eq!(line.split(',').next(), Some("ams"));
+    }
+
+    #[test]
+    fn default_jsonl_renders_target_key_first() {
+        let config = output_config(OutputFormat::Jsonl, None);
+        let line = config
+            .render_event(&reply(), Some("ams"), Some(&EventRenderStats::default()))
+            .unwrap();
+
+        assert!(line.starts_with("{\"target\":\"ams\""));
+    }
+
+    #[test]
+    fn truncate_for_table_leaves_short_value_unchanged() {
+        assert_eq!(truncate_for_table("ams", 18), "ams");
+    }
+
+    #[test]
+    fn truncate_for_table_leaves_exact_width_value_unchanged() {
+        let value = "a".repeat(18);
+        assert_eq!(truncate_for_table(&value, 18), value);
+    }
+
+    #[test]
+    fn truncate_for_table_shortens_long_value_to_width() {
+        let value = "a".repeat(40);
+        let truncated = truncate_for_table(&value, 18);
+
+        assert_eq!(truncated.chars().count(), 18);
+        assert!(truncated.len() <= 18); // ASCII: byte len matches char len
+    }
+
+    #[test]
+    fn truncate_for_table_keeps_prefix_and_appends_ellipsis_deterministically() {
+        let value = "abcdefghijklmnopqrstuvwxyz";
+        let truncated = truncate_for_table(value, 18);
+
+        assert_eq!(truncated, "abcdefghijklmno...");
+        assert_eq!(truncated.chars().count(), 18);
+    }
+
+    #[test]
+    fn truncate_for_table_does_not_split_multibyte_code_points() {
+        // Each character below is multibyte in UTF-8; a byte-index slice
+        // would panic or corrupt the string on a non-boundary cut.
+        let value = "\u{1F600}".repeat(40); // 😀 repeated, well past width 18
+        let truncated = truncate_for_table(&value, 18);
+
+        // Must not panic (validated by test completing) and must remain
+        // valid UTF-8 with exactly 18 chars (15 prefix chars + "...").
+        assert_eq!(truncated.chars().count(), 18);
+        assert!(truncated.ends_with("..."));
+        assert_eq!(truncated.chars().filter(|c| *c == '\u{1F600}').count(), 15);
+    }
+
+    #[test]
+    fn table_row_with_long_target_keeps_next_column_aligned() {
+        let config = output_config(OutputFormat::Table, None);
+        let long_target = "a".repeat(40);
+        let header = config.render_header().unwrap();
+        let line = config
+            .render_event(
+                &reply(),
+                Some(&long_target),
+                Some(&EventRenderStats::default()),
+            )
+            .unwrap();
+
+        // Target column is truncated to its table width (18), so the
+        // "event" column starts at the same offset for both a normal and an
+        // overlong target label.
+        let short_config = output_config(OutputFormat::Table, None);
+        let short_line = short_config
+            .render_event(&reply(), Some("ams"), Some(&EventRenderStats::default()))
+            .unwrap();
+
+        let target_width = Column::Target.table_width();
+        let expected_event_offset = target_width + "  ".len();
+        assert_eq!(&header[expected_event_offset..][..5], "event");
+        // The event column ("echo_reply") starts at the same offset
+        // regardless of whether the target label was short or overlong.
+        assert_eq!(
+            &line[expected_event_offset..][.."echo_reply".len()],
+            "echo_reply"
+        );
+        assert_eq!(
+            &short_line[expected_event_offset..][.."echo_reply".len()],
+            "echo_reply"
+        );
+    }
+
+    #[test]
+    fn csv_preserves_full_long_target_label() {
+        let config = output_config(OutputFormat::Csv, Some("target,seq"));
+        let long_target = "a".repeat(40);
+        let line = config
+            .render_event(
+                &reply(),
+                Some(&long_target),
+                Some(&EventRenderStats::default()),
+            )
+            .unwrap();
+
+        assert_eq!(line, format!("{long_target},7"));
+    }
+
+    #[test]
+    fn tsv_preserves_full_long_target_label() {
+        let config = output_config(OutputFormat::Tsv, Some("target,seq"));
+        let long_target = "b".repeat(40);
+        let line = config
+            .render_event(
+                &reply(),
+                Some(&long_target),
+                Some(&EventRenderStats::default()),
+            )
+            .unwrap();
+
+        assert_eq!(line, format!("{long_target}\t7"));
+    }
+
+    #[test]
+    fn jsonl_preserves_full_long_target_label() {
+        let config = output_config(OutputFormat::Jsonl, Some("target,seq"));
+        let long_target = "c".repeat(40);
+        let line = config
+            .render_event(
+                &reply(),
+                Some(&long_target),
+                Some(&EventRenderStats::default()),
+            )
+            .unwrap();
+
+        assert_eq!(line, format!("{{\"target\":\"{long_target}\",\"seq\":7}}"));
+    }
+
+    #[test]
+    fn explicit_table_columns_with_target_truncate_same_as_default() {
+        let config = output_config(OutputFormat::Table, Some("target,seq"));
+        let long_target = "d".repeat(40);
+        let line = config
+            .render_event(
+                &reply(),
+                Some(&long_target),
+                Some(&EventRenderStats::default()),
+            )
+            .unwrap();
+
+        let target_width = Column::Target.table_width();
+        let expected_prefix: String = long_target
+            .chars()
+            .take(target_width - 3)
+            .chain("...".chars())
+            .collect();
+        assert!(line.starts_with(&expected_prefix));
+        assert_eq!(&line[..target_width], expected_prefix.as_str());
+    }
 }

crates/irtt-app/src/cmd/client/summary.rs

@@ -2,6 +2,11 @@ use std::fmt::Write as _;
 
 use irtt_stats::{Snapshot, TimeStats};
 
+use crate::cmd::format::{
+    format_ns_f64, format_optional_ns_f64 as format_ns_f64_opt,
+    format_optional_ns_i128 as format_ns_i128, format_percent,
+};
+
 pub fn format_summary(summary: &Snapshot) -> String {
     format_summary_with_options(summary, SummaryFormatOptions::default())
 }
@@ -117,34 +122,6 @@ fn write_time_row(out: &mut String, label: &str, value: &TimeStats) {
     .unwrap();
 }
 
-fn format_percent(value: f64) -> String {
-    format!("{value:.2}%")
-}
-
-fn format_ns_i128(value: Option<i128>) -> String {
-    value
-        .map(|value| format_ns_f64(value as f64))
-        .unwrap_or_else(|| "-".to_owned())
-}
-
-fn format_ns_f64_opt(value: Option<f64>) -> String {
-    value.map(format_ns_f64).unwrap_or_else(|| "-".to_owned())
-}
-
-fn format_ns_f64(value: f64) -> String {
-    let sign = if value.is_sign_negative() { "-" } else { "" };
-    let value = value.abs();
-    if value < 1_000.0 {
-        format!("{sign}{value:.0}ns")
-    } else if value < 1_000_000.0 {
-        format!("{sign}{:.1}µs", value / 1_000.0)
-    } else if value < 1_000_000_000.0 {
-        format!("{sign}{:.1}ms", value / 1_000_000.0)
-    } else {
-        format!("{sign}{:.3}s", value / 1_000_000_000.0)
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -241,6 +218,97 @@ mod tests {
         assert!(!output.contains("medians unavailable"));
     }
 
+    /// Returns the Median cell of the row with this label.
+    fn median_cell(output: &str, label: &str) -> String {
+        let row = output
+            .lines()
+            .find(|line| line.trim_start().starts_with(label))
+            .unwrap_or_else(|| panic!("summary should contain a {label:?} row:\n{output}"));
+        // Metric, Count, Min, Mean, Median, ...
+        // Counting from the right keeps multi-word labels out of the way.
+        row.split_whitespace()
+            .rev()
+            .nth(2)
+            .unwrap_or_else(|| panic!("row {row:?} should have a Median cell"))
+            .to_owned()
+    }
+
+    /// Collects probes whose send-call, timer-error, and server-processing
+    /// values each have a median distinct from their min, mean, and max, so
+    /// the rendered cell can only come from a real median calculation.
+    fn spread_finite_summary(config: StatsConfig) -> Snapshot {
+        let mut collector = StatsCollector::new(config);
+        for (seq, (send_call_us, timer_error_us, processing_us)) in
+            [(10_u64, 2_u64, 100_u64), (40, 12, 700), (20, 4, 300)]
+                .into_iter()
+                .enumerate()
+        {
+            let seq = seq as u32;
+            let offset = Duration::from_secs(1) + Duration::from_millis(u64::from(seq));
+            let sent_at = test_timestamp(offset);
+            let received_at = test_timestamp(offset + Duration::from_micros(1500));
+
+            collector.process(&ClientEvent::EchoSent {
+                seq,
+                remote: test_remote(),
+                scheduled_at: sent_at.mono,
+                sent_at,
+                bytes: 64,
+                send_call: Duration::from_micros(send_call_us),
+                timer_error: Duration::from_micros(timer_error_us),
+            });
+            collector.process(&ClientEvent::EchoReply {
+                seq,
+                remote: test_remote(),
+                sent_at,
+                received_at,
+                rtt: RttSample {
+                    raw: Duration::from_micros(1500),
+                    adjusted: None,
+                    effective: SignedDuration::from_nanos(1_500_000),
+                },
+                server_timing: Some(ServerTiming {
+                    receive_wall_ns: None,
+                    receive_mono_ns: None,
+                    send_wall_ns: None,
+                    send_mono_ns: None,
+                    midpoint_wall_ns: None,
+                    midpoint_mono_ns: None,
+                    processing: Some(Duration::from_micros(processing_us)),
+                }),
+                one_way: None,
+                received_stats: None,
+                bytes: 64,
+                packet_meta: PacketMeta::default(),
+            });
+        }
+        collector.snapshot()
+    }
+
+    #[test]
+    fn finite_summary_shows_medians_for_send_call_timer_error_and_processing() {
+        let output = format_summary(&spread_finite_summary(StatsConfig::finite()));
+
+        // Medians of 10/20/40, 2/4/12, and 100/300/700 µs. None of these
+        // equals the row's min, mean, or max.
+        assert_eq!(median_cell(&output, "send call"), "20.0µs");
+        assert_eq!(median_cell(&output, "timer error"), "4.0µs");
+        assert_eq!(median_cell(&output, "server processing"), "300.0µs");
+    }
+
+    #[test]
+    fn continuous_summary_still_shows_no_medians_for_those_rows() {
+        let output = format_summary(&spread_finite_summary(StatsConfig::continuous()));
+
+        for label in ["send call", "timer error", "server processing"] {
+            assert_eq!(
+                median_cell(&output, label),
+                "-",
+                "continuous mode retains no exact samples for {label}"
+            );
+        }
+    }
+
     #[test]
     fn verbose_summary_includes_raw_and_adjusted_rtt_rows() {
         let mut collector = StatsCollector::new(StatsConfig::finite());

crates/irtt-app/src/cmd/format.rs

@@ -0,0 +1,207 @@
+//! Scalar presentation vocabulary shared by the CLI frontends.
+//!
+//! Stream output, the run summary, and the TUI display different metrics in
+//! different layouts, but they render the same *scalars*: nanosecond-scale
+//! durations, percentages, and counts. This module owns those spellings so the
+//! frontends cannot drift apart on units, rounding, or how an absent value is
+//! rendered.
+//!
+//! It is presentation only. Nothing here belongs in `irtt-stats`, and it is
+//! deliberately not a general formatting framework: it holds exactly the
+//! vocabulary more than one frontend needs.
+
+use std::time::Duration;
+
+#[cfg(feature = "client")]
+use irtt_client::SignedDuration;
+
+/// Rendering used wherever a scalar is unavailable.
+pub(crate) const ABSENT: &str = "-";
+
+/// Format a nanosecond scalar.
+///
+/// Unit selection and rounding are one policy for every frontend:
+///
+/// | magnitude | unit | precision |
+/// |-----------|------|-----------|
+/// | `< 1µs`   | `ns` | whole     |
+/// | `< 1ms`   | `µs` | 1 decimal |
+/// | `< 1s`    | `ms` | 1 decimal |
+/// | `>= 1s`   | `s`  | 3 decimals |
+///
+/// Negative values are meaningful (clock offsets, one-way deltas, IPDV), so
+/// the unit is selected from the magnitude and the sign is preserved. Values
+/// that are not finite render as [`ABSENT`].
+pub(crate) fn format_ns_f64(value: f64) -> String {
+    if !value.is_finite() {
+        return ABSENT.to_owned();
+    }
+    let sign = if value.is_sign_negative() { "-" } else { "" };
+    let magnitude = value.abs();
+    if magnitude < 1_000.0 {
+        format!("{sign}{magnitude:.0}ns")
+    } else if magnitude < 1_000_000.0 {
+        format!("{sign}{:.1}µs", magnitude / 1_000.0)
+    } else if magnitude < 1_000_000_000.0 {
+        format!("{sign}{:.1}ms", magnitude / 1_000_000.0)
+    } else {
+        format!("{sign}{:.3}s", magnitude / 1_000_000_000.0)
+    }
+}
+
+/// Format an exact nanosecond scalar with [`format_ns_f64`]'s policy.
+pub(crate) fn format_ns_i128(value: i128) -> String {
+    let sign = if value < 0 { "-" } else { "" };
+    let magnitude = value.saturating_abs() as f64;
+    format!("{sign}{}", format_ns_f64(magnitude))
+}
+
+/// Format an optional nanosecond scalar, rendering `None` as [`ABSENT`].
+pub(crate) fn format_optional_ns_i128(value: Option<i128>) -> String {
+    value.map(format_ns_i128).unwrap_or_else(absent)
+}
+
+/// Format an optional nanosecond scalar, rendering `None` as [`ABSENT`].
+#[cfg(feature = "client")]
+pub(crate) fn format_optional_ns_f64(value: Option<f64>) -> String {
+    value.map(format_ns_f64).unwrap_or_else(absent)
+}
+
+/// Format a duration as a nanosecond scalar.
+pub(crate) fn format_duration(value: Duration) -> String {
+    format_ns_i128(i128::try_from(value.as_nanos()).unwrap_or(i128::MAX))
+}
+
+/// Format a signed duration as a nanosecond scalar, preserving its sign.
+#[cfg(feature = "client")]
+pub(crate) fn format_signed_duration(value: SignedDuration) -> String {
+    format_ns_i128(value.as_nanos())
+}
+
+/// Format a percentage with two decimals; non-finite values render as
+/// [`ABSENT`].
+pub(crate) fn format_percent(value: f64) -> String {
+    if value.is_finite() {
+        format!("{value:.2}%")
+    } else {
+        ABSENT.to_owned()
+    }
+}
+
+/// Format `value` as a percentage of `total`, capped at 100%.
+///
+/// A zero total has no percentage to report and renders as [`ABSENT`].
+#[cfg(feature = "tui")]
+pub(crate) fn format_percent_ratio(value: u64, total: u64) -> String {
+    if total == 0 {
+        ABSENT.to_owned()
+    } else {
+        format_percent((value as f64 / total as f64 * 100.0).min(100.0))
+    }
+}
+
+/// Format a scalar count.
+#[cfg(feature = "tui")]
+pub(crate) fn format_count(value: u64) -> String {
+    value.to_string()
+}
+
+/// Format an optional scalar count, rendering `None` as [`ABSENT`].
+#[cfg(feature = "tui")]
+pub(crate) fn format_optional_count(value: Option<u64>) -> String {
+    value.map(format_count).unwrap_or_else(absent)
+}
+
+fn absent() -> String {
+    ABSENT.to_owned()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn nanosecond_scalars_select_units_at_the_defined_boundaries() {
+        assert_eq!(format_ns_f64(0.0), "0ns");
+        assert_eq!(format_ns_f64(999.0), "999ns");
+        assert_eq!(format_ns_f64(1_000.0), "1.0µs");
+        assert_eq!(format_ns_f64(999_999.0), "1000.0µs");
+        assert_eq!(format_ns_f64(1_000_000.0), "1.0ms");
+        assert_eq!(format_ns_f64(999_999_999.0), "1000.0ms");
+        assert_eq!(format_ns_f64(1_000_000_000.0), "1.000s");
+        assert_eq!(format_ns_f64(1_500_000_000.0), "1.500s");
+    }
+
+    #[test]
+    fn negative_nanosecond_scalars_keep_their_sign() {
+        assert_eq!(format_ns_f64(-500.0), "-500ns");
+        assert_eq!(format_ns_f64(-1_500.0), "-1.5µs");
+        assert_eq!(format_ns_f64(-2_500_000.0), "-2.5ms");
+        assert_eq!(format_ns_f64(-1_000_000_000.0), "-1.000s");
+        assert_eq!(format_ns_i128(-1_500), "-1.5µs");
+    }
+
+    #[test]
+    fn exact_and_floating_nanosecond_scalars_agree() {
+        for value in [0_i128, 1, 999, 1_000, 1_234_567, -1_234_567, 5_000_000_000] {
+            assert_eq!(format_ns_i128(value), format_ns_f64(value as f64));
+        }
+    }
+
+    #[test]
+    fn microseconds_use_the_micro_sign() {
+        assert!(format_ns_f64(1_500.0).ends_with("µs"));
+        assert!(!format_ns_f64(1_500.0).contains("us"));
+    }
+
+    #[test]
+    fn durations_render_as_nanosecond_scalars() {
+        assert_eq!(format_duration(Duration::from_millis(25)), "25.0ms");
+        assert_eq!(format_duration(Duration::from_secs(1)), "1.000s");
+    }
+
+    #[test]
+    #[cfg(feature = "client")]
+    fn signed_durations_render_as_nanosecond_scalars() {
+        assert_eq!(
+            format_signed_duration(SignedDuration::from_nanos(-1_500)),
+            "-1.5µs"
+        );
+    }
+
+    #[test]
+    fn absent_and_non_finite_scalars_render_as_a_placeholder() {
+        assert_eq!(format_optional_ns_i128(None), ABSENT);
+        assert_eq!(format_ns_f64(f64::NAN), ABSENT);
+        assert_eq!(format_ns_f64(f64::INFINITY), ABSENT);
+        assert_eq!(format_percent(f64::NAN), ABSENT);
+    }
+
+    #[test]
+    #[cfg(feature = "client")]
+    fn absent_optional_ns_f64_renders_as_a_placeholder() {
+        assert_eq!(format_optional_ns_f64(None), ABSENT);
+    }
+
+    #[test]
+    #[cfg(feature = "tui")]
+    fn absent_counts_and_ratios_render_as_a_placeholder() {
+        assert_eq!(format_optional_count(None), ABSENT);
+        assert_eq!(format_percent_ratio(1, 0), ABSENT);
+    }
+
+    #[test]
+    fn percentages_have_one_spelling() {
+        assert_eq!(format_percent(0.0), "0.00%");
+        assert_eq!(format_percent(12.345), "12.35%");
+    }
+
+    #[test]
+    #[cfg(feature = "tui")]
+    fn percent_ratios_and_counts_have_one_spelling() {
+        assert_eq!(format_percent_ratio(1, 4), "25.00%");
+        assert_eq!(format_percent_ratio(5, 4), "100.00%");
+        assert_eq!(format_count(42), "42");
+        assert_eq!(format_optional_count(Some(0)), "0");
+    }
+}

crates/irtt-app/src/cmd/mod.rs

@@ -1,5 +1,9 @@
 #[cfg(feature = "client")]
 pub mod client;
+#[cfg(any(feature = "client", feature = "tui"))]
+mod format;
+#[cfg(feature = "server")]
+pub mod server;
 #[cfg(feature = "tui")]
 pub mod tui;
 

crates/irtt-app/src/cmd/server/args.rs

@@ -0,0 +1,650 @@
+use std::{
+    net::{Ipv4Addr, Ipv6Addr, SocketAddr},
+    time::Duration,
+};
+
+use clap::{Parser, ValueEnum};
+use irtt_server::{ServerConfig, TimestampAllowance};
+
+/// The ordinary IRTT port, used to build the zero-argument default binds.
+const DEFAULT_PORT: u16 = 2112;
+
+// Every policy option is optional. An omitted option leaves the corresponding
+// `ServerConfig` default in place rather than restating it here, so library and
+// CLI defaults cannot drift apart.
+#[derive(Debug, Clone, Parser)]
+#[command(
+    name = "irtt-server",
+    about = "Minimal IRTT-compatible UDP server",
+    after_help = "With no --bind, the server listens on the wildcard IRTT port for both address families ([::]:2112 and 0.0.0.0:2112) where the platform supports wildcard reply-source selection.\nRepeat --bind to serve multiple addresses in one process; any explicit --bind replaces the default pair entirely. All listeners use the same policy but keep independent session namespaces."
+)]
+pub struct ServerArgs {
+    /// Local UDP address to bind, as ADDR:PORT. Repeatable.
+    #[arg(
+        long,
+        value_name = "ADDR",
+        env = "IRTT_SERVER_BIND",
+        long_help = "Local UDP address to bind, as ADDR:PORT, for example 127.0.0.1:2112 or [::1]:2112. Host names are not resolved.\n\nRepeat the option to serve several addresses from one process, in the order given. Every listener applies the same policy options, but each keeps its own sessions and tokens, so a session belongs to the address it was opened on. Binding is all or nothing: if any address cannot be bound, none are served.\n\nWith no --bind at all, the server binds the wildcard IRTT port on both address families, [::]:2112 then 0.0.0.0:2112, on platforms with wildcard reply-source support; elsewhere it fails and asks for an explicit address instead of guessing one. Any explicit --bind replaces that default pair rather than adding to it.\n\nA wildcard bind such as 0.0.0.0:2112 answers each request from the address it was sent to, using per-packet destination metadata. That is supported on Linux, macOS and FreeBSD; on other systems a wildcard bind is refused and an explicit interface address is required.\n\nA port of 0 selects an unused port per listener, so two such binds get two different ports.\n\nIRTT_SERVER_BIND sets the same thing for deployments that configure by environment (systemd, Docker, ...), and takes exactly one address, the same as one --bind. Leave it unset on ordinary hosts: the wildcard default above is already what you want there. A --bind on the command line overrides it entirely."
+    )]
+    pub bind: Vec<SocketAddr>,
+
+    /// HMAC key; every request must then carry a valid MAC.
+    #[arg(
+        long,
+        value_name = "KEY",
+        value_parser = parse_hmac_key,
+        env = "IRTT_SERVER_HMAC",
+        long_help = "HMAC key, taken as the UTF-8 bytes of this argument.\n\nAuthentication is global: with a key configured, every request must carry a valid MAC and every reply is authenticated. Without one, authenticated requests are dropped. The key is visible in the process arguments, or in the environment as IRTT_SERVER_HMAC."
+    )]
+    pub hmac: Option<String>,
+
+    /// Maximum simultaneously live sessions per listener.
+    #[arg(
+        long,
+        value_name = "COUNT",
+        env = "IRTT_SERVER_MAX_SESSIONS",
+        long_help = "Maximum number of simultaneously live sessions per listener. Once a listener's table is full, a session-creating open to it is dropped silently; nothing is evicted. Zero refuses every session-creating open.\n\nThis is a per-listener bound, not a process-wide one: with two --bind options, each listener admits up to this many sessions."
+    )]
+    pub max_sessions: Option<usize>,
+
+    /// Maximum echo datagram size a session may negotiate, in bytes.
+    #[arg(
+        long,
+        value_name = "BYTES",
+        env = "IRTT_SERVER_MAX_PACKET_LENGTH",
+        long_help = "Maximum echo datagram size a session may negotiate, in bytes. A longer requested length is reduced during negotiation, an open whose mandatory field block would not fit is refused, and inbound echo requests are admitted against the same limit. This is a resource bound, not an MTU."
+    )]
+    pub max_packet_length: Option<usize>,
+
+    /// Floor on the negotiated send interval.
+    #[arg(
+        long,
+        value_name = "DURATION",
+        value_parser = parse_duration_allow_zero,
+        env = "IRTT_SERVER_MIN_INTERVAL",
+        long_help = "Floor on the send interval a session may negotiate. The negotiated interval is still capped at a quarter of the idle timeout afterwards, so a value above that cap is not what actually gets negotiated.\n\nA session's reply allowance refills at the shorter of this floor and the interval it actually negotiated. Ordinarily that is this floor itself; it is the shorter, negotiated value only where the idle-timeout cap above pulled the negotiated interval below it. Use 0 for no time-based throttling."
+    )]
+    pub min_interval: Option<Duration>,
+
+    /// Echo replies a session may burst before its allowance refills.
+    #[arg(
+        long,
+        value_name = "COUNT",
+        env = "IRTT_SERVER_BURST",
+        long_help = "Echo replies one session may have answered before its allowance has to refill. Use 0 for no allowance at all, which rate-limits every echo request whatever the interval is."
+    )]
+    pub burst: Option<u32>,
+
+    /// Release a session after this long without an echo request.
+    #[arg(
+        long,
+        value_name = "DURATION",
+        value_parser = parse_duration_allow_zero,
+        env = "IRTT_SERVER_IDLE_TIMEOUT",
+        long_help = "Release a session after this long without a served or rate-limited echo request. The deadline runs from the open, and release is silent. Use 0 to expire a session at the next evaluation; it is not a way to disable expiry."
+    )]
+    pub idle_timeout: Option<Duration>,
+
+    /// Maximum test duration a session may negotiate.
+    #[arg(
+        long,
+        value_name = "DURATION",
+        value_parser = parse_positive_duration,
+        env = "IRTT_SERVER_MAX_DURATION",
+        long_help = "Maximum test duration a session may negotiate. A longer request is reduced to it, and a continuous request is answered with it. Omit this flag for no maximum; a maximum of zero cannot be expressed, because a negotiated duration of zero means continuous."
+    )]
+    pub max_duration: Option<Duration>,
+
+    /// How many timestamps this server will provide.
+    #[arg(
+        long,
+        value_name = "MODE",
+        value_enum,
+        env = "IRTT_SERVER_TIMESTAMP_ALLOWANCE",
+        long_help = "How many timestamps this server will provide.\n\ndual: honor a request for send, receive, both or midpoint timestamps.\nsingle: provide at most one timestamp instant; a request for both is negotiated to midpoint.\nnone: provide no timestamps at all.\n\nThe requested clock source is never changed, only which instants are reported, so a single instant is still reported once per requested clock. Omit this flag to honor every requested placement."
+    )]
+    pub timestamp_allowance: Option<TimestampAllowanceArg>,
+
+    /// Refuse to provide requested DSCP marking.
+    //
+    // `FalseyValueParser` rather than clap's default `bool` parser for a flag,
+    // which is what makes IRTT_SERVER_NO_DSCP usable from the environment at
+    // all. A flag's default parser accepts only the literals `true` and
+    // `false`, so the ordinary container/orchestrator spelling
+    // `IRTT_SERVER_NO_DSCP=1` did not enable the flag — it failed argument
+    // parsing and the server refused to start. Falsey semantics are clap's own
+    // documented recipe for a boolean environment flag: `0`, `false`, `no`,
+    // `n`, `off` and empty are off, anything else is on, and an absent
+    // variable is off as before. The command-line flag is unaffected: it still
+    // takes no value and still means "on".
+    #[arg(
+        long,
+        env = "IRTT_SERVER_NO_DSCP",
+        value_parser = clap::builder::FalseyValueParser::new(),
+        long_help = "Refuse to provide requested traffic-class marking. Any requested DSCP is negotiated to zero, so the client is told its echo replies will be unmarked, and they are sent unmarked. The session is not refused.\n\nIRTT_SERVER_NO_DSCP sets the same thing from the environment: 0, false, no, n, off and an empty value leave marking enabled, and any other value disables it."
+    )]
+    pub no_dscp: bool,
+}
+
+/// The command-line spelling of [`TimestampAllowance`].
+///
+/// A CLI-local enum rather than a `clap` derive on the library type: `irtt-server`
+/// is a reusable crate and has no business depending on an argument parser.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub enum TimestampAllowanceArg {
+    /// Honor every requested timestamp placement.
+    Dual,
+    /// Provide at most one timestamp instant; both becomes midpoint.
+    Single,
+    /// Provide no timestamps.
+    None,
+}
+
+impl From<TimestampAllowanceArg> for TimestampAllowance {
+    fn from(value: TimestampAllowanceArg) -> Self {
+        match value {
+            TimestampAllowanceArg::Dual => Self::Dual,
+            TimestampAllowanceArg::Single => Self::Single,
+            TimestampAllowanceArg::None => Self::None,
+        }
+    }
+}
+
+impl ServerArgs {
+    /// The addresses this invocation binds: the requested `--bind` list, or
+    /// the wildcard IRTT port on both address families if none was given.
+    #[must_use]
+    pub fn resolve_binds(&self) -> Vec<SocketAddr> {
+        if self.bind.is_empty() {
+            vec![
+                SocketAddr::from((Ipv6Addr::UNSPECIFIED, DEFAULT_PORT)),
+                SocketAddr::from((Ipv4Addr::UNSPECIFIED, DEFAULT_PORT)),
+            ]
+        } else {
+            self.bind.clone()
+        }
+    }
+
+    /// Builds the server configuration this invocation asks for.
+    #[must_use]
+    pub fn server_config(&self) -> ServerConfig {
+        let mut config = ServerConfig::default();
+        if let Some(key) = self.hmac.as_ref() {
+            config = config.with_hmac_key(key.as_bytes());
+        }
+        if let Some(value) = self.max_sessions {
+            config = config.with_max_sessions(value);
+        }
+        if let Some(value) = self.max_packet_length {
+            config = config.with_max_packet_length(value);
+        }
+        if let Some(value) = self.min_interval {
+            config = config.with_min_send_interval(value);
+        }
+        if let Some(value) = self.burst {
+            config = config.with_burst_allowance(value);
+        }
+        if let Some(value) = self.idle_timeout {
+            config = config.with_idle_timeout(value);
+        }
+        if let Some(value) = self.max_duration {
+            config = config.with_max_test_duration(value);
+        }
+        if let Some(value) = self.timestamp_allowance {
+            config = config.with_timestamp_allowance(value.into());
+        }
+        // A negative capability flag, so absence is the ordinary enabled state
+        // and the library default is what an unset flag leaves in place.
+        if self.no_dscp {
+            config = config.with_dscp_allowed(false);
+        }
+        config
+    }
+}
+
+/// Rejects an empty HMAC key so a blank shell expansion cannot silently
+/// enable authentication with predictable, empty key material.
+fn parse_hmac_key(input: &str) -> Result<String, String> {
+    if input.is_empty() {
+        return Err("HMAC key must not be empty".to_owned());
+    }
+    Ok(input.to_owned())
+}
+
+/// Parses a duration whose zero is meaningful server policy.
+fn parse_duration_allow_zero(input: &str) -> Result<Duration, String> {
+    if input == "0" {
+        return Ok(Duration::ZERO);
+    }
+    parse_duration_units(input)
+}
+
+/// Parses a duration that must be positive, where absence means "no limit".
+fn parse_positive_duration(input: &str) -> Result<Duration, String> {
+    let value = if input == "0" {
+        Duration::ZERO
+    } else {
+        parse_duration_units(input)?
+    };
+    if value.is_zero() {
+        return Err(
+            "duration must be greater than zero; omit the option for no maximum".to_owned(),
+        );
+    }
+    Ok(value)
+}
+
+fn parse_duration_units(input: &str) -> Result<Duration, String> {
+    let split = input
+        .find(|ch: char| !ch.is_ascii_digit())
+        .ok_or_else(|| "duration must include a unit: ms, s, or m".to_owned())?;
+    let (number, unit) = input.split_at(split);
+    if number.is_empty() {
+        return Err("duration must include a value and a unit: ms, s, or m".to_owned());
+    }
+    let value: u64 = number
+        .parse()
+        .map_err(|_| format!("invalid duration value {input:?}"))?;
+    match unit {
+        "ms" => Ok(Duration::from_millis(value)),
+        "s" => Ok(Duration::from_secs(value)),
+        "m" => value
+            .checked_mul(60)
+            .map(Duration::from_secs)
+            .ok_or_else(|| "duration is too large".to_owned()),
+        _ => Err(format!(
+            "unsupported duration unit {unit:?}; use ms, s, or m"
+        )),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::net::{Ipv4Addr, Ipv6Addr};
+
+    use super::*;
+    use crate::cmd::server::env_lock::with_env_lock;
+
+    fn parse(args: &[&str]) -> Result<ServerArgs, clap::Error> {
+        with_env_lock(|| {
+            let mut argv = vec!["irtt-server"];
+            argv.extend_from_slice(args);
+            ServerArgs::try_parse_from(argv)
+        })
+    }
+
+    fn bound(args: &[&str]) -> ServerArgs {
+        let mut argv = vec!["--bind", "127.0.0.1:2112"];
+        argv.extend_from_slice(args);
+        parse(&argv).unwrap()
+    }
+
+    #[test]
+    fn bind_is_optional_and_parses_both_families() {
+        let ipv4 = parse(&["--bind", "127.0.0.1:2112"]).unwrap();
+        assert_eq!(ipv4.bind, [SocketAddr::from((Ipv4Addr::LOCALHOST, 2112))]);
+
+        let ipv6 = parse(&["--bind", "[::1]:2112"]).unwrap();
+        assert_eq!(ipv6.bind, [SocketAddr::from((Ipv6Addr::LOCALHOST, 2112))]);
+
+        assert!(parse(&["--bind", "127.0.0.1"]).is_err());
+        assert!(parse(&["--bind", "localhost:2112"]).is_err());
+        // Still one address per option: comma-separated syntax is not a thing
+        // here, and accepting it silently would be worse than rejecting it.
+        assert!(parse(&["--bind", "127.0.0.1:2112,[::1]:2112"]).is_err());
+    }
+
+    #[test]
+    fn no_explicit_bind_resolves_to_the_wildcard_default_pair() {
+        let args = parse(&[]).unwrap();
+        assert!(
+            args.bind.is_empty(),
+            "the empty list is the parsed representation of \"no explicit bind\""
+        );
+        assert_eq!(
+            args.resolve_binds(),
+            [
+                SocketAddr::from((Ipv6Addr::UNSPECIFIED, 2112)),
+                SocketAddr::from((Ipv4Addr::UNSPECIFIED, 2112)),
+            ],
+            "zero explicit binds means the ordinary port on both wildcard families, IPv6 first"
+        );
+    }
+
+    #[test]
+    fn an_explicit_bind_replaces_the_defaults_rather_than_augmenting_them() {
+        let args = parse(&["--bind", "127.0.0.1:2112"]).unwrap();
+        assert_eq!(
+            args.resolve_binds(),
+            [SocketAddr::from((Ipv4Addr::LOCALHOST, 2112))],
+            "one explicit bind means exactly that one listener, not that listener plus defaults"
+        );
+    }
+
+    #[test]
+    fn repeated_explicit_binds_are_unaffected_by_the_default_resolution() {
+        let args = parse(&["--bind", "127.0.0.1:2112", "--bind", "[::1]:2112"]).unwrap();
+        assert_eq!(args.resolve_binds(), args.bind);
+    }
+
+    #[test]
+    fn bind_is_repeatable_and_keeps_the_requested_order() {
+        let args = parse(&[
+            "--bind",
+            "[::1]:2112",
+            "--bind",
+            "127.0.0.1:2112",
+            "--bind",
+            "127.0.0.1:2113",
+        ])
+        .unwrap();
+
+        assert_eq!(
+            args.bind,
+            [
+                SocketAddr::from((Ipv6Addr::LOCALHOST, 2112)),
+                SocketAddr::from((Ipv4Addr::LOCALHOST, 2112)),
+                SocketAddr::from((Ipv4Addr::LOCALHOST, 2113)),
+            ],
+            "listeners are served in the order they were requested"
+        );
+    }
+
+    #[test]
+    fn the_configuration_is_one_policy_however_many_listeners_there_are() {
+        // Addresses never enter the server configuration: every listener is
+        // built from a clone of this one value.
+        let one = parse(&["--bind", "127.0.0.1:2112", "--max-sessions", "4"])
+            .unwrap()
+            .server_config();
+        let several = parse(&[
+            "--bind",
+            "127.0.0.1:2112",
+            "--bind",
+            "[::1]:2112",
+            "--max-sessions",
+            "4",
+        ])
+        .unwrap()
+        .server_config();
+
+        assert_eq!(one, several);
+        assert_eq!(several.max_sessions(), 4, "and it is a per-listener bound");
+    }
+
+    #[test]
+    fn omitted_policy_options_keep_the_library_defaults() {
+        assert_eq!(bound(&[]).server_config(), ServerConfig::default());
+    }
+
+    #[test]
+    fn policy_options_map_onto_the_server_config() {
+        let config = bound(&[
+            "--hmac",
+            "secret",
+            "--max-sessions",
+            "512",
+            "--max-packet-length",
+            "1472",
+            "--min-interval",
+            "20ms",
+            "--burst",
+            "3",
+            "--idle-timeout",
+            "30s",
+            "--max-duration",
+            "2m",
+        ])
+        .server_config();
+
+        assert_eq!(config.hmac_key(), Some(b"secret".as_slice()));
+        assert_eq!(config.max_sessions(), 512);
+        assert_eq!(config.max_packet_length(), 1472);
+        assert_eq!(config.min_send_interval(), Duration::from_millis(20));
+        assert_eq!(config.burst_allowance(), 3);
+        assert_eq!(config.idle_timeout(), Duration::from_secs(30));
+        assert_eq!(config.max_test_duration(), Some(Duration::from_secs(120)));
+    }
+
+    #[test]
+    fn the_capability_restrictions_map_onto_the_server_config() {
+        let config = bound(&["--timestamp-allowance", "single", "--no-dscp"]).server_config();
+
+        assert_eq!(
+            config.timestamp_allowance(),
+            TimestampAllowance::Single,
+            "a request for both timestamps is negotiated to midpoint"
+        );
+        assert!(!config.dscp_allowed());
+    }
+
+    #[test]
+    fn every_timestamp_allowance_mode_parses() {
+        for (argument, expected) in [
+            ("dual", TimestampAllowance::Dual),
+            ("single", TimestampAllowance::Single),
+            ("none", TimestampAllowance::None),
+        ] {
+            assert_eq!(
+                bound(&["--timestamp-allowance", argument])
+                    .server_config()
+                    .timestamp_allowance(),
+                expected,
+                "--timestamp-allowance {argument}"
+            );
+        }
+
+        assert!(parse(&[
+            "--bind",
+            "127.0.0.1:2112",
+            "--timestamp-allowance",
+            "midpoint"
+        ])
+        .is_err());
+        assert!(parse(&["--bind", "127.0.0.1:2112", "--timestamp-allowance", "both"]).is_err());
+    }
+
+    #[test]
+    fn the_capability_restrictions_are_off_when_their_flags_are_absent() {
+        // Explicitly, and not only through the whole-config comparison above:
+        // these are the two values that would silently change every existing
+        // deployment's negotiation if the CLI restated them.
+        let config = bound(&["--idle-timeout", "30s"]).server_config();
+
+        assert_eq!(config.timestamp_allowance(), TimestampAllowance::Dual);
+        assert!(config.dscp_allowed());
+    }
+
+    #[test]
+    fn explicit_zero_policy_values_are_preserved() {
+        let config = bound(&[
+            "--min-interval",
+            "0",
+            "--idle-timeout",
+            "0ms",
+            "--burst",
+            "0",
+            "--max-sessions",
+            "0",
+            "--max-packet-length",
+            "0",
+        ])
+        .server_config();
+
+        assert_eq!(config.min_send_interval(), Duration::ZERO);
+        assert_eq!(config.idle_timeout(), Duration::ZERO);
+        assert_eq!(config.burst_allowance(), 0);
+        assert_eq!(config.max_sessions(), 0);
+        assert_eq!(config.max_packet_length(), 0);
+    }
+
+    #[test]
+    fn durations_require_a_supported_unit() {
+        assert!(parse(&["--bind", "127.0.0.1:2112", "--idle-timeout", "30"]).is_err());
+        assert!(parse(&["--bind", "127.0.0.1:2112", "--min-interval", "20us"]).is_err());
+        assert!(parse(&["--bind", "127.0.0.1:2112", "--max-duration", "2h"]).is_err());
+        assert!(parse(&["--bind", "127.0.0.1:2112", "--idle-timeout", "ms"]).is_err());
+    }
+
+    #[test]
+    fn an_empty_hmac_key_is_rejected() {
+        let err = parse(&["--bind", "127.0.0.1:2112", "--hmac", ""]).unwrap_err();
+        assert!(err.to_string().contains("HMAC key must not be empty"));
+    }
+
+    #[test]
+    fn a_whitespace_only_hmac_key_is_accepted_literally() {
+        let config = bound(&["--hmac", " "]).server_config();
+        assert_eq!(config.hmac_key(), Some(b" ".as_slice()));
+    }
+
+    #[test]
+    fn a_zero_maximum_duration_is_not_a_spelling_of_no_maximum() {
+        assert!(parse(&["--bind", "127.0.0.1:2112", "--max-duration", "0"]).is_err());
+        assert!(parse(&["--bind", "127.0.0.1:2112", "--max-duration", "0s"]).is_err());
+        assert_eq!(bound(&[]).server_config().max_test_duration(), None);
+    }
+
+    /// Runs `body` with the given environment variables set, restoring
+    /// whatever was there before (present or absent) once `body` returns.
+    /// Held under `with_env_lock` for the whole span, including `body`, so a
+    /// `parse` call elsewhere never observes a partially-applied environment.
+    fn with_env<T>(vars: &[(&str, &str)], body: impl FnOnce() -> T) -> T {
+        with_env_lock(|| {
+            let previous: Vec<(&str, Option<String>)> = vars
+                .iter()
+                .map(|(k, _)| (*k, std::env::var(k).ok()))
+                .collect();
+            for (k, v) in vars {
+                std::env::set_var(k, v);
+            }
+            let result = body();
+            for (k, v) in previous {
+                match v {
+                    Some(v) => std::env::set_var(k, v),
+                    None => std::env::remove_var(k),
+                }
+            }
+            result
+        })
+    }
+
+    #[test]
+    fn environment_variables_supply_policy_when_no_flag_is_given() {
+        with_env(
+            &[
+                ("IRTT_SERVER_MAX_SESSIONS", "512"),
+                ("IRTT_SERVER_MAX_PACKET_LENGTH", "1472"),
+                ("IRTT_SERVER_MIN_INTERVAL", "20ms"),
+                ("IRTT_SERVER_BURST", "3"),
+                ("IRTT_SERVER_IDLE_TIMEOUT", "30s"),
+                ("IRTT_SERVER_MAX_DURATION", "2m"),
+                ("IRTT_SERVER_TIMESTAMP_ALLOWANCE", "single"),
+                ("IRTT_SERVER_HMAC", "secret"),
+                ("IRTT_SERVER_NO_DSCP", "true"),
+            ],
+            || {
+                let config = parse(&["--bind", "127.0.0.1:2112"])
+                    .unwrap()
+                    .server_config();
+                assert_eq!(config.max_sessions(), 512);
+                assert_eq!(config.max_packet_length(), 1472);
+                assert_eq!(config.min_send_interval(), Duration::from_millis(20));
+                assert_eq!(config.burst_allowance(), 3);
+                assert_eq!(config.idle_timeout(), Duration::from_secs(30));
+                assert_eq!(config.max_test_duration(), Some(Duration::from_secs(120)));
+                assert_eq!(config.timestamp_allowance(), TimestampAllowance::Single);
+                assert_eq!(config.hmac_key(), Some(b"secret".as_slice()));
+                assert!(!config.dscp_allowed());
+            },
+        );
+    }
+
+    /// `IRTT_SERVER_NO_DSCP` is the one policy variable whose value is a
+    /// boolean rather than a number, a duration or a string, and the
+    /// container/orchestrator deployments this whole environment surface
+    /// exists for spell booleans `1`/`0`. clap's default parser for a flag
+    /// accepts only the literals `true`/`false` and turns everything else
+    /// into a *parse failure*, so `IRTT_SERVER_NO_DSCP=1` used to stop the
+    /// server from starting at all rather than enabling the flag. Falsey
+    /// semantics are what keeps that from being a startup failure.
+    #[test]
+    fn the_no_dscp_environment_variable_accepts_ordinary_boolean_spellings() {
+        for value in ["1", "true", "TRUE", "yes", "on", "enabled"] {
+            with_env(&[("IRTT_SERVER_NO_DSCP", value)], || {
+                let config = parse(&["--bind", "127.0.0.1:2112"])
+                    .expect("a truthy value must not fail argument parsing")
+                    .server_config();
+                assert!(!config.dscp_allowed(), "IRTT_SERVER_NO_DSCP={value}");
+            });
+        }
+
+        for value in ["0", "false", "no", "off", ""] {
+            with_env(&[("IRTT_SERVER_NO_DSCP", value)], || {
+                let config = parse(&["--bind", "127.0.0.1:2112"])
+                    .expect("a falsey value must not fail argument parsing")
+                    .server_config();
+                assert!(config.dscp_allowed(), "IRTT_SERVER_NO_DSCP={value}");
+            });
+        }
+    }
+
+    /// The command-line flag stays a flag: it takes no value, whatever the
+    /// environment parser accepts.
+    #[test]
+    fn the_no_dscp_flag_still_takes_no_command_line_value() {
+        assert!(parse(&["--bind", "127.0.0.1:2112", "--no-dscp=false"]).is_err());
+        assert!(!bound(&["--no-dscp"]).server_config().dscp_allowed());
+    }
+
+    #[test]
+    fn an_explicit_flag_overrides_the_environment() {
+        with_env(&[("IRTT_SERVER_MAX_SESSIONS", "512")], || {
+            let config = parse(&["--bind", "127.0.0.1:2112", "--max-sessions", "4"])
+                .unwrap()
+                .server_config();
+            assert_eq!(
+                config.max_sessions(),
+                4,
+                "the command-line value wins over the environment"
+            );
+        });
+    }
+
+    #[test]
+    fn the_environment_wins_over_the_built_in_default() {
+        with_env(&[("IRTT_SERVER_BURST", "9")], || {
+            let config = bound(&[]).server_config();
+            assert_eq!(
+                config.burst_allowance(),
+                9,
+                "an unset flag still falls back to the environment before the library default"
+            );
+        });
+    }
+
+    #[test]
+    fn irtt_server_bind_supplies_a_single_address_from_the_environment() {
+        with_env(&[("IRTT_SERVER_BIND", "127.0.0.1:2113")], || {
+            let args = parse(&[]).unwrap();
+            assert_eq!(args.bind, [SocketAddr::from((Ipv4Addr::LOCALHOST, 2113))]);
+        });
+    }
+
+    #[test]
+    fn an_explicit_bind_flag_overrides_irtt_server_bind() {
+        with_env(&[("IRTT_SERVER_BIND", "127.0.0.1:2113")], || {
+            let args = parse(&["--bind", "[::1]:2112"]).unwrap();
+            assert_eq!(args.bind, [SocketAddr::from((Ipv6Addr::LOCALHOST, 2112))]);
+        });
+    }
+
+    #[test]
+    fn leaving_irtt_server_bind_unset_keeps_the_wildcard_default() {
+        let args = parse(&[]).unwrap();
+        assert!(
+            args.bind.is_empty(),
+            "with no --bind and no IRTT_SERVER_BIND, resolve_binds still falls back to the wildcard pair"
+        );
+    }
+}

crates/irtt-app/src/cmd/server/env_lock.rs

@@ -0,0 +1,30 @@
+//! Serializes every test in this module tree that touches process
+//! environment variables.
+//!
+//! `ServerArgs` parsing reads `IRTT_SERVER_*` via `clap`'s `env` support, and
+//! `std::env::set_var`/`remove_var` mutate genuinely process-wide state.
+//! Every test that parses `ServerArgs` — whether or not it sets an env var
+//! itself — must go through [`with_env_lock`], or a parse in one test thread
+//! can observe a value another thread's test set only for the duration of
+//! its own assertions. Reentrant per-thread, since a test that sets env vars
+//! typically calls `parse` again from inside its own locked section.
+
+use std::{cell::Cell, sync::Mutex};
+
+static ENV_LOCK: Mutex<()> = Mutex::new(());
+thread_local! {
+    static ENV_LOCK_HELD: Cell<bool> = const { Cell::new(false) };
+}
+
+pub(crate) fn with_env_lock<T>(f: impl FnOnce() -> T) -> T {
+    if ENV_LOCK_HELD.with(Cell::get) {
+        return f();
+    }
+    let _guard = ENV_LOCK
+        .lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner);
+    ENV_LOCK_HELD.with(|held| held.set(true));
+    let result = f();
+    ENV_LOCK_HELD.with(|held| held.set(false));
+    result
+}

crates/irtt-app/src/cmd/server/mod.rs

@@ -0,0 +1,7 @@
+pub mod args;
+#[cfg(test)]
+pub(crate) mod env_lock;
+pub mod run;
+
+pub use args::ServerArgs;
+pub use run::run_server;

crates/irtt-app/src/cmd/server/run.rs

@@ -0,0 +1,209 @@
+use std::{
+    net::SocketAddr,
+    sync::atomic::{AtomicBool, Ordering},
+    time::Duration,
+};
+
+use irtt_server::{address_family_available, ServerSet, ServerSetError};
+
+use super::args::ServerArgs;
+
+/// How often the shutdown future samples the process-wide signal flag.
+///
+/// The flag a signal handler sets has no async wake mechanism, so the future
+/// polls it on a timer rather than spinning. `ServerSet::run` owns everything
+/// after that future becomes ready, including fanning it out to the listeners.
+const SHUTDOWN_POLL_INTERVAL: Duration = Duration::from_millis(50);
+
+/// Runs the configured listeners until the process is asked to shut down.
+///
+/// The applet owns exactly one current-thread Tokio runtime and one
+/// [`ServerSet`], whatever number of addresses was requested. A single `--bind`
+/// is an ordinary set of one and takes the same path as a set of several: one
+/// construction, one shutdown future, one supervision rule. Listener
+/// concurrency is async I/O concurrency and needs no worker threads.
+pub fn run_server(
+    args: ServerArgs,
+    shutdown_requested: &AtomicBool,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let runtime = tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()?;
+    runtime.block_on(serve(args, shutdown_requested))
+}
+
+async fn serve(
+    args: ServerArgs,
+    shutdown_requested: &AtomicBool,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let config = args.server_config();
+    let binds = args.resolve_binds();
+    let is_implicit_default = args.bind.is_empty();
+    let set = match ServerSet::bind(binds.clone(), config.clone()).await {
+        Ok(set) => set,
+        Err(ServerSetError::ListenerSetup { addr, source }) => {
+            let family_available = address_family_available(addr);
+            match implicit_default_fallback(is_implicit_default, family_available, &binds, addr) {
+                Some(remaining) => {
+                    eprintln!(
+                        "irtt-server: default listener {addr} unavailable ({source}); \
+                         continuing with the remaining default listener"
+                    );
+                    // `remaining`'s lone survivor is bound exactly as it
+                    // would be alone: the address family that just failed
+                    // has no local support at all, so nothing on that family
+                    // could be competing for the surviving listener's port.
+                    ServerSet::bind(remaining, config).await?
+                }
+                None => return Err(ServerSetError::ListenerSetup { addr, source }.into()),
+            }
+        }
+        Err(err) => return Err(err.into()),
+    };
+    // Only once every listener is up. Announcing one address and then failing
+    // to bind the next would report a service that never started.
+    for addr in set.local_addrs() {
+        eprintln!("irtt-server: listening on {addr}");
+    }
+    set.run(shutdown_signal(shutdown_requested)).await?;
+    Ok(())
+}
+
+/// Whether a listener-setup failure for `failed_addr` should be retried with
+/// a reduced bind set instead of failing the whole invocation, and if so,
+/// what to retry with.
+///
+/// Only the implicit zero-argument default gets this treatment, and only
+/// when `failed_addr`'s own address family has no local support on this host
+/// at all (`family_available` is `false`) — not merely because its specific
+/// port was unavailable for some other reason: already in use, permission
+/// denied, no safe wildcard reply-source path, or anything else
+/// `ServerSet::bind` can fail with. Those are real configuration or
+/// environment problems this invocation should fail on, not silently work
+/// around by dropping a listener the operator asked for. An explicit
+/// `--bind` list keeps the library's ordinary all-or-nothing behavior
+/// regardless.
+fn implicit_default_fallback(
+    is_implicit_default: bool,
+    family_available: bool,
+    original_binds: &[SocketAddr],
+    failed_addr: SocketAddr,
+) -> Option<Vec<SocketAddr>> {
+    if !is_implicit_default || family_available || !original_binds.contains(&failed_addr) {
+        return None;
+    }
+    let remaining: Vec<SocketAddr> = original_binds
+        .iter()
+        .copied()
+        .filter(|&addr| addr != failed_addr)
+        .collect();
+    (!remaining.is_empty()).then_some(remaining)
+}
+
+async fn shutdown_signal(shutdown_requested: &AtomicBool) {
+    while !shutdown_requested.load(Ordering::Relaxed) {
+        tokio::time::sleep(SHUTDOWN_POLL_INTERVAL).await;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use clap::Parser;
+
+    use super::*;
+    use crate::cmd::server::env_lock::with_env_lock;
+
+    /// The ordinary invocation, and the one that keeps the single-listener case
+    /// on the same orchestration path as every other.
+    #[test]
+    fn an_already_requested_shutdown_binds_one_listener_and_returns() {
+        let args = with_env_lock(|| {
+            ServerArgs::try_parse_from(["irtt-server", "--bind", "127.0.0.1:0"]).unwrap()
+        });
+        let shutdown_requested = AtomicBool::new(true);
+
+        run_server(args, &shutdown_requested).unwrap();
+    }
+
+    #[test]
+    fn an_already_requested_shutdown_binds_every_listener_and_returns() {
+        let args = with_env_lock(|| {
+            ServerArgs::try_parse_from([
+                "irtt-server",
+                "--bind",
+                "127.0.0.1:0",
+                "--bind",
+                "127.0.0.1:0",
+            ])
+            .unwrap()
+        });
+        let shutdown_requested = AtomicBool::new(true);
+
+        run_server(args, &shutdown_requested).unwrap();
+    }
+
+    fn default_binds() -> Vec<SocketAddr> {
+        with_env_lock(|| {
+            ServerArgs::try_parse_from(["irtt-server"])
+                .unwrap()
+                .resolve_binds()
+        })
+    }
+
+    #[test]
+    fn implicit_default_losing_an_unsupported_family_falls_back_to_the_other() {
+        let binds = default_binds();
+        let failed = binds[0];
+
+        let remaining = implicit_default_fallback(true, false, &binds, failed).unwrap();
+
+        assert_eq!(remaining, [binds[1]]);
+    }
+
+    #[test]
+    fn a_supported_familys_failure_never_falls_back() {
+        // The family itself works fine here; whatever made this specific
+        // bind fail (port in use, permission, ...) is a real problem this
+        // invocation should surface, not paper over.
+        let binds = default_binds();
+
+        assert_eq!(
+            implicit_default_fallback(true, true, &binds, binds[0]),
+            None,
+            "family_available: true means this is not a family-support problem"
+        );
+    }
+
+    #[test]
+    fn explicit_binds_never_fall_back() {
+        let binds = default_binds();
+
+        assert_eq!(
+            implicit_default_fallback(false, false, &binds, binds[0]),
+            None
+        );
+    }
+
+    #[test]
+    fn a_failure_outside_the_requested_set_does_not_fall_back() {
+        let binds = default_binds();
+        let unrelated = SocketAddr::from(([127, 0, 0, 1], 2113));
+
+        assert_eq!(
+            implicit_default_fallback(true, false, &binds, unrelated),
+            None,
+            "the failing address must actually be one this invocation asked for"
+        );
+    }
+
+    #[test]
+    fn losing_the_only_remaining_default_address_does_not_fall_back() {
+        let single = [SocketAddr::from(([0, 0, 0, 0], 2112))];
+
+        assert_eq!(
+            implicit_default_fallback(true, false, &single, single[0]),
+            None,
+            "no address would be left to retry with"
+        );
+    }
+}

crates/irtt-app/src/cmd/tui/args.rs

@@ -1,13 +1,12 @@
 use std::time::Duration;
 
 use clap::Parser;
-use irtt_client::ClientConfig;
 
 #[cfg(test)]
 use crate::shared::client::TimestampArg;
 use crate::shared::client::{
-    parse_labelled_target, parse_test_duration, resolved_managed_targets, target_specs,
-    CommonClientArgs, GroupPacingArg, LabelledTargetArg, ResolvedTarget, TargetSpec,
+    parse_target, parse_test_duration, prepare_managed_run, CommonClientArgs, GroupPacingArg,
+    ManagedRunSetup, TargetArg, TargetSelection,
 };
 
 pub const DEFAULT_TUI_DURATION: Duration = Duration::ZERO;
@@ -15,23 +14,15 @@ pub const DEFAULT_TUI_DURATION: Duration = Duration::ZERO;
 #[derive(Debug, Clone, Parser)]
 #[command(name = "irtt-tui", about = "Minimal IRTT-compatible TUI client")]
 pub struct TuiArgs {
-    /// Server address or host, with optional port. Repeat for multi-target mode.
+    /// Server address/host, optionally prefixed with LABEL= and suffixed with @hmac=KEY. Repeat for multi-target mode.
     #[arg(
         value_name = "TARGET",
-        num_args = 0..,
-        required_unless_present = "labelled_targets",
-        long_help = "Server address or host, with optional port. Repeat the positional target for multi-target mode, for example: irtt-tui host-a:2112 host-b:2112."
+        num_args = 1..,
+        required = true,
+        value_parser = parse_target,
+        long_help = "Server address/host, optionally prefixed with LABEL= and suffixed with @hmac=KEY. Repeat for multi-target mode.\n\nExplicit labels are used in the legend and status table. A target without @hmac= inherits --hmac; @hmac= disables it for that target.\n\nExamples:\n  irtt-tui host.example\n  irtt-tui eu=host.example\n  irtt-tui eu=host-a.example@hmac=secret us=host-b.example"
     )]
-    pub targets: Vec<String>,
-
-    /// Explicit labelled target, as label=host:port. Repeat for multi-target mode.
-    #[arg(
-        long = "target",
-        value_name = "LABEL=TARGET",
-        value_parser = parse_labelled_target,
-        long_help = "Explicit labelled target, as label=host:port. Repeat for multi-target mode. The label is used in the legend and status table and must be unique."
-    )]
-    pub labelled_targets: Vec<LabelledTargetArg>,
+    pub targets: Vec<TargetArg>,
 
     /// Managed group pacing for multi-target mode.
     #[arg(
@@ -56,11 +47,19 @@ pub struct TuiArgs {
 }
 
 impl TuiArgs {
-    pub fn to_client_config(&self) -> ClientConfig {
-        self.common.to_client_config(
-            self.primary_target_addr()
-                .expect("at least one target is required"),
+    /// Validate the selected targets and prepare the managed run.
+    ///
+    /// The TUI always requires a target: the parser rejects an empty target
+    /// list, and this rejects a target set that cannot be labelled uniquely.
+    pub fn prepare(&self) -> Result<ManagedRunSetup, String> {
+        prepare_managed_run(
+            &self.common,
             self.duration,
+            TargetSelection {
+                targets: &self.targets,
+                pacing: self.pacing,
+                stdin_controlled: false,
+            },
         )
     }
 
@@ -68,33 +67,12 @@ impl TuiArgs {
         self.duration == Duration::ZERO
     }
 
-    pub fn target_specs(&self) -> Result<Vec<TuiTargetSpec>, String> {
-        target_specs(&self.targets, &self.labelled_targets)
-    }
-
-    pub fn resolved_managed_targets(&self) -> Result<Vec<ResolvedTuiTarget>, String> {
-        let specs = self.target_specs()?;
-        let config = self.to_client_config();
-        resolved_managed_targets(specs, &config)
-    }
-
     #[cfg(test)]
     pub fn timestamp_mode(&self) -> TimestampArg {
         self.common.tstamp
     }
-
-    fn primary_target_addr(&self) -> Option<&str> {
-        self.targets.first().map(String::as_str).or_else(|| {
-            self.labelled_targets
-                .first()
-                .map(|target| target.addr.as_str())
-        })
-    }
 }
 
-pub type TuiTargetSpec = TargetSpec;
-pub type ResolvedTuiTarget = ResolvedTarget;
-
 impl std::ops::Deref for TuiArgs {
     type Target = CommonClientArgs;
 
@@ -129,17 +107,17 @@ mod tests {
     #[test]
     fn tui_parser_defaults_to_continuous_and_has_no_output_option() {
         let args = parse(&["127.0.0.1:2112"]).unwrap();
-        assert_eq!(args.targets, ["127.0.0.1:2112"]);
-        assert!(args.labelled_targets.is_empty());
+        assert_eq!(args.targets.len(), 1);
+        assert_eq!(args.prepare().unwrap().targets[0].label, "127.0.0.1:2112");
         assert_eq!(args.pacing, GroupPacingArg::Staggered);
         assert_eq!(args.duration, DEFAULT_TUI_DURATION);
         assert!(args.is_continuous());
-        assert_eq!(args.to_client_config().duration, None);
+        assert_eq!(args.prepare().unwrap().client.duration, None);
 
         let finite = parse(&["--duration", "30s", "127.0.0.1:2112"]).unwrap();
         assert_eq!(finite.duration, Duration::from_secs(30));
         assert_eq!(
-            finite.to_client_config().duration,
+            finite.prepare().unwrap().client.duration,
             Some(Duration::from_secs(30))
         );
 
@@ -151,40 +129,37 @@ mod tests {
     #[test]
     fn multiple_positional_targets_parse() {
         let args = parse(&["host-a:2112", "host-b:2112"]).unwrap();
-        let specs = args.target_specs().unwrap();
+        let specs = args.prepare().unwrap().targets;
 
         assert_eq!(specs[0].label, "host-a:2112");
-        assert_eq!(specs[0].addr, "host-a:2112");
+        assert_eq!(specs[0].managed.server_addr, "host-a:2112");
         assert_eq!(specs[1].label, "host-b:2112");
-        assert_eq!(specs[1].addr, "host-b:2112");
+        assert_eq!(specs[1].managed.server_addr, "host-b:2112");
     }
 
     #[test]
-    fn repeated_labelled_targets_parse() {
-        let args = parse(&[
-            "--target",
-            "ams=ams.example.com:2112",
-            "--target",
-            "sg=sg.example.com:2112",
-        ])
-        .unwrap();
-        let specs = args.target_specs().unwrap();
+    fn repeated_labeled_targets_parse() {
+        let args = parse(&["ams=ams.example.com:2112", "sg=sg.example.com:2112"]).unwrap();
+        let specs = args.prepare().unwrap().targets;
 
         assert_eq!(specs[0].label, "ams");
-        assert_eq!(specs[0].addr, "ams.example.com:2112");
+        assert_eq!(specs[0].managed.server_addr, "ams.example.com:2112");
         assert_eq!(specs[1].label, "sg");
-        assert_eq!(specs[1].addr, "sg.example.com:2112");
+        assert_eq!(specs[1].managed.server_addr, "sg.example.com:2112");
     }
 
     #[test]
     fn at_least_one_target_is_required() {
+        // The TUI has no target-free mode, so this is rejected at parse time
+        // rather than during preparation.
         assert!(parse(&[]).is_err());
+        assert!(parse(&["ams=ams.example.com:2112"]).is_ok());
     }
 
     #[test]
     fn duplicate_labels_are_rejected() {
-        let args = parse(&["host-a:2112", "--target", "host-a:2112=host-b:2112"]).unwrap();
-        let err = args.target_specs().unwrap_err();
+        let args = parse(&["host-a:2112", "host-a:2112=host-b:2112"]).unwrap();
+        let err = args.prepare().unwrap_err();
 
         assert!(err.contains("duplicate target label"));
     }
@@ -192,25 +167,27 @@ mod tests {
     #[test]
     fn duplicate_positional_target_strings_get_stable_suffixes() {
         let args = parse(&["host-a:2112", "host-a:2112"]).unwrap();
-        let specs = args.target_specs().unwrap();
+        let specs = args.prepare().unwrap().targets;
 
         assert_eq!(specs[0].label, "host-a:2112");
         assert_eq!(specs[1].label, "host-a:2112#2");
     }
 
     #[test]
-    fn duplicate_resolved_target_addresses_are_rejected() {
+    fn duplicate_target_endpoints_are_allowed() {
         let args = parse(&["127.0.0.1:2112", "127.0.0.1"]).unwrap();
-        let err = args.resolved_managed_targets().unwrap_err();
-
-        assert!(err.contains("duplicate resolved target address 127.0.0.1:2112"));
+        assert_eq!(args.prepare().unwrap().target_count(), 2);
     }
 
     #[test]
     fn invalid_labelled_target_syntax_is_rejected() {
-        assert!(parse(&["--target", "missing-equals"]).is_err());
-        assert!(parse(&["--target", "=127.0.0.1:2112"]).is_err());
-        assert!(parse(&["--target", "label="]).is_err());
+        assert!(parse(&["=127.0.0.1:2112"]).unwrap().prepare().is_err());
+        assert!(parse(&["label="]).unwrap().prepare().is_err());
+    }
+
+    #[test]
+    fn old_target_option_is_rejected() {
+        assert!(parse(&["--target", "eu=host.example"]).is_err());
     }
 
     #[test]
@@ -276,11 +253,10 @@ mod tests {
             "--loose",
             "127.0.0.1:2112",
         ];
-        let tui = parse(&tui_args).unwrap().to_client_config();
+        let tui = parse(&tui_args).unwrap().prepare().unwrap().client;
         let common = parse_shared(&shared).unwrap().common;
-        let shared = common.to_client_config("127.0.0.1:2112", Duration::from_secs(30));
+        let shared = common.to_client_config(Duration::from_secs(30));
 
-        assert_eq!(shared.server_addr, tui.server_addr);
         assert_eq!(shared.duration, tui.duration);
         assert_eq!(shared.interval, tui.interval);
         assert_eq!(shared.length, tui.length);
@@ -294,10 +270,18 @@ mod tests {
         assert_eq!(shared.socket_config.ttl, tui.socket_config.ttl);
     }
 
+    #[test]
+    fn an_empty_hmac_key_is_rejected_via_the_shared_args() {
+        // CommonClientArgs is flattened into both the client and TUI parsers,
+        // so proving rejection once here covers both without duplicating it.
+        let err = parse(&["--hmac", "", "127.0.0.1:2112"]).unwrap_err();
+        assert!(err.to_string().contains("HMAC key must not be empty"));
+    }
+
     #[test]
     fn tui_help_lists_multi_target_options() {
         let help = TuiArgs::command().render_help().to_string();
-        assert!(help.contains("--target <LABEL=TARGET>"));
+        assert!(!help.contains("--target "));
         assert!(help.contains("--pacing <PACING>"));
     }
 }

crates/irtt-app/src/cmd/tui/run.rs

@@ -0,0 +1,303 @@
+use std::{
+    collections::HashSet,
+    io,
+    sync::atomic::{AtomicBool, Ordering},
+    thread,
+    time::{Duration, Instant},
+};
+
+use super::ui::{should_render, TuiConfig, TuiState, TuiStatus, TuiTerminal};
+use crate::{
+    cmd::tui::args::TuiArgs,
+    shared::client::{
+        is_shutdown_requested,
+        session::{
+            drain_managed_events, peer_close_run_error, request_managed_stop_for_peer_close,
+            request_managed_stop_once, ManagedDrainState,
+        },
+    },
+};
+use crossterm::event::{self, Event, KeyCode, KeyEventKind, KeyModifiers};
+use irtt_client::managed::{
+    BlockingManagedClient, ManagedEndReason, ManagedEvent, ManagedEventSubscription,
+    ManagedEventTryRecvError, TargetInstance,
+};
+
+const RENDER_INTERVAL: Duration = Duration::from_millis(250);
+const TUI_WAIT_SLICE: Duration = Duration::from_millis(20);
+const INPUT_EVENT_WORK_BUDGET: usize = 128;
+
+pub fn run_tui(
+    args: TuiArgs,
+    shutdown_requested: &AtomicBool,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let setup = args
+        .prepare()
+        .map_err(|err| io::Error::new(io::ErrorKind::InvalidInput, err))?;
+    let continuous = args.is_continuous();
+    let mut terminal = TuiTerminal::enter()?;
+    let mut state = TuiState::with_target_labels(
+        TuiConfig::from_args(&args, &setup),
+        setup.targets.iter().map(|target| target.label.clone()),
+    );
+    let mut next_render = Instant::now();
+    if is_shutdown_requested(shutdown_requested) {
+        return Ok(());
+    }
+    state.set_status(TuiStatus::Opening);
+    render_if_due(&mut terminal, &state, &mut next_render, true)?;
+    let (owner, mut events) = match BlockingManagedClient::start_with_subscription(
+        setup.managed_config(),
+        setup.managed_targets(),
+    ) {
+        Ok(value) => value,
+        Err(error) => {
+            state.set_error(error.to_string());
+            render_if_due(&mut terminal, &state, &mut next_render, true)?;
+            return Err(Box::new(error));
+        }
+    };
+    let handle = owner.handle();
+    let mut interrupted = false;
+    let mut stop_requested = false;
+    let mut terminal_targets = HashSet::new();
+    let mut dropped_events = 0;
+    let mut subscription_closed = false;
+    loop {
+        if is_shutdown_requested(shutdown_requested) {
+            interrupted = true;
+            if request_managed_stop_once(&mut stop_requested) {
+                drop(handle.stop());
+            }
+        }
+        if handle_input(&mut state, shutdown_requested)? {
+            render_if_due(&mut terminal, &state, &mut next_render, true)?;
+        }
+        if state.quit_requested {
+            interrupted = true;
+            if request_managed_stop_once(&mut stop_requested) {
+                drop(handle.stop());
+            }
+        }
+        if request_managed_stop_for_peer_close(
+            continuous,
+            interrupted,
+            handle.status().peer_closed_target_outcomes,
+            &mut stop_requested,
+        ) {
+            drop(handle.stop());
+        }
+        let drain_state = drain_tui_events(
+            &mut events,
+            &mut state,
+            &mut terminal_targets,
+            &mut dropped_events,
+        );
+        match drain_state {
+            ManagedDrainState::Empty => {
+                thread::sleep(managed_tui_wait_duration(&next_render, state.paused));
+            }
+            ManagedDrainState::Closed => subscription_closed = true,
+            ManagedDrainState::BudgetExhausted => {}
+        }
+        if handle.status().final_outcome.is_some() || subscription_closed {
+            break;
+        }
+        render_if_due(&mut terminal, &state, &mut next_render, false)?;
+    }
+    if interrupted {
+        state.set_status(TuiStatus::Interrupted);
+        render_if_due(&mut terminal, &state, &mut next_render, true)?;
+    }
+    state.set_status(TuiStatus::Closing);
+    render_if_due(&mut terminal, &state, &mut next_render, true)?;
+    let outcome = owner.join()?;
+    drain_final_tui_events(
+        &mut events,
+        &mut state,
+        &mut terminal_targets,
+        &mut dropped_events,
+    );
+    state.mark_dropped_managed_events(dropped_events);
+    if outcome.discarded_target_outcomes != 0 {
+        state.set_run_error(format!(
+            "{} final target outcomes were discarded",
+            outcome.discarded_target_outcomes
+        ));
+    }
+    for target in outcome.recent_target_outcomes.iter() {
+        if terminal_targets.insert(target.target.clone()) {
+            state.process_target_outcome(target);
+        }
+    }
+    interrupted |= is_shutdown_requested(shutdown_requested);
+    let error = match &outcome.end_reason {
+        ManagedEndReason::DriverFailed(failure) => {
+            Some(format!("managed driver failed: {failure}"))
+        }
+        _ => peer_close_run_error(continuous, interrupted, outcome.peer_closed_target_outcomes)
+            .or_else(|| {
+                (!interrupted
+                    && outcome.successful_target_outcomes == 0
+                    && outcome.failed_target_outcomes > 0)
+                    .then(|| {
+                        format!(
+                            "no managed target completed successfully ({} failed)",
+                            outcome.failed_target_outcomes
+                        )
+                    })
+            }),
+    };
+    if let Some(error) = error {
+        state.set_run_error(error.clone());
+        render_if_due(&mut terminal, &state, &mut next_render, true)?;
+        return Err(error.into());
+    }
+    state.set_status(TuiStatus::Complete);
+    render_if_due(&mut terminal, &state, &mut next_render, true)?;
+    Ok(())
+}
+
+fn process_tui_event(
+    event: ManagedEvent,
+    state: &mut TuiState,
+    terminal_targets: &mut HashSet<TargetInstance>,
+) {
+    match event {
+        ManagedEvent::Client { target, event } => state.process_target_event(&target, &event),
+        ManagedEvent::TargetFinished { outcome } => {
+            terminal_targets.insert(outcome.target.clone());
+            state.process_target_outcome(&outcome);
+        }
+        _ => {}
+    }
+}
+fn drain_tui_events(
+    events: &mut ManagedEventSubscription,
+    state: &mut TuiState,
+    terminal_targets: &mut HashSet<TargetInstance>,
+    dropped_events: &mut u64,
+) -> ManagedDrainState {
+    drain_managed_events(events, dropped_events, |event| {
+        process_tui_event(event, state, terminal_targets);
+        Ok::<(), std::convert::Infallible>(())
+    })
+    .expect("processing TUI managed events is infallible")
+}
+
+fn drain_final_tui_events(
+    events: &mut ManagedEventSubscription,
+    state: &mut TuiState,
+    terminal_targets: &mut HashSet<TargetInstance>,
+    dropped_events: &mut u64,
+) {
+    loop {
+        match events.try_recv() {
+            Ok(event) => process_tui_event(event, state, terminal_targets),
+            Err(ManagedEventTryRecvError::Empty | ManagedEventTryRecvError::Closed) => break,
+            Err(ManagedEventTryRecvError::Lagged(count)) => {
+                *dropped_events = dropped_events.saturating_add(count);
+            }
+        }
+    }
+}
+fn handle_input(state: &mut TuiState, shutdown_requested: &AtomicBool) -> io::Result<bool> {
+    let mut force_render = false;
+    for _ in 0..INPUT_EVENT_WORK_BUDGET {
+        if !event::poll(Duration::ZERO)? {
+            break;
+        }
+        let Event::Key(key) = event::read()? else {
+            continue;
+        };
+        if key.kind == KeyEventKind::Release {
+            continue;
+        }
+        match key.code {
+            KeyCode::Char('q') | KeyCode::Char('c')
+                if key.code == KeyCode::Char('q')
+                    || key.modifiers.contains(KeyModifiers::CONTROL) =>
+            {
+                state.quit_requested = true;
+                shutdown_requested.store(true, Ordering::Relaxed);
+                force_render = true;
+                break;
+            }
+            KeyCode::Char('r') => {
+                state.clear_visible_history();
+                force_render = true;
+            }
+            KeyCode::Char('p') => {
+                state.toggle_pause();
+                force_render = true;
+            }
+            KeyCode::Char('g') => {
+                state.toggle_view();
+                force_render = true;
+            }
+            KeyCode::Char('m') => {
+                state.cycle_graph_metric();
+                force_render = true;
+            }
+            KeyCode::Left => {
+                state.pan_graph_left();
+                force_render = true;
+            }
+            KeyCode::Right => {
+                state.pan_graph_right();
+                force_render = true;
+            }
+            KeyCode::PageUp => {
+                state.pan_graph_page_left();
+                force_render = true;
+            }
+            KeyCode::PageDown => {
+                state.pan_graph_page_right();
+                force_render = true;
+            }
+            KeyCode::Home => {
+                state.jump_graph_oldest();
+                force_render = true;
+            }
+            KeyCode::End => {
+                state.jump_graph_live();
+                force_render = true;
+            }
+            KeyCode::Char('+') | KeyCode::Char('=') => {
+                state.zoom_graph_in();
+                force_render = true;
+            }
+            KeyCode::Char('-') => {
+                state.zoom_graph_out();
+                force_render = true;
+            }
+            KeyCode::Char('0') => {
+                state.reset_graph_window();
+                force_render = true;
+            }
+            _ => {}
+        }
+    }
+    Ok(force_render)
+}
+fn render_if_due(
+    terminal: &mut TuiTerminal,
+    state: &TuiState,
+    next_render: &mut Instant,
+    force: bool,
+) -> io::Result<()> {
+    let now = Instant::now();
+    if should_render(now, *next_render, state.paused, force) {
+        terminal.draw(state)?;
+        *next_render = now + RENDER_INTERVAL;
+    }
+    Ok(())
+}
+fn managed_tui_wait_duration(next_render: &Instant, paused: bool) -> Duration {
+    let render_wait = if paused {
+        TUI_WAIT_SLICE
+    } else {
+        next_render.saturating_duration_since(Instant::now())
+    };
+    render_wait.min(TUI_WAIT_SLICE)
+}

crates/irtt-app/src/entry.rs

@@ -0,0 +1,133 @@
+#[cfg(any(feature = "client", feature = "server", feature = "tui"))]
+use std::sync::{atomic::AtomicBool, Arc};
+use std::{env, ffi::OsString, process::ExitCode};
+
+use crate::applet::{dispatch_from_argv, AppletDispatch, RequestedApplet};
+#[cfg(any(feature = "client", feature = "server", feature = "tui"))]
+use crate::signal::install_signal_handler;
+
+/// Entry point for the `irtt-rs` multicall dispatcher binary.
+///
+/// Chooses an applet by subcommand or by recognized argv0 and may reference
+/// every applet enabled by the active feature set.
+pub fn dispatcher_main() -> ExitCode {
+    run_with_exit_code("irtt-rs", run_dispatcher_from_env)
+}
+
+/// Entry point for the dedicated `irtt-client` binary.
+///
+/// Runs the stream client directly; it never consults argv0 or the applet
+/// dispatcher, so a renamed or copied executable still runs the client.
+#[cfg(feature = "client")]
+pub fn client_main() -> ExitCode {
+    run_with_exit_code("irtt-client", || {
+        run_client_applet(env::args_os().collect())
+    })
+}
+
+/// Entry point for the dedicated `irtt-tui` binary.
+///
+/// Runs the terminal UI directly; it never consults argv0 or the applet
+/// dispatcher, so a renamed or copied executable still runs the TUI.
+#[cfg(feature = "tui")]
+pub fn tui_main() -> ExitCode {
+    run_with_exit_code("irtt-tui", || run_tui_applet(env::args_os().collect()))
+}
+
+/// Entry point for the dedicated `irtt-server` binary.
+///
+/// Runs the server directly; it never consults argv0 or the applet
+/// dispatcher, so a renamed or copied executable still runs the server.
+#[cfg(feature = "server")]
+pub fn server_main() -> ExitCode {
+    run_with_exit_code("irtt-server", || {
+        run_server_applet(env::args_os().collect())
+    })
+}
+
+fn run_with_exit_code(
+    program: &str,
+    f: impl FnOnce() -> Result<(), Box<dyn std::error::Error>>,
+) -> ExitCode {
+    match f() {
+        Ok(()) => ExitCode::SUCCESS,
+        Err(err) => {
+            eprintln!("{program}: {err}");
+            ExitCode::FAILURE
+        }
+    }
+}
+
+fn run_dispatcher_from_env() -> Result<(), Box<dyn std::error::Error>> {
+    let argv: Vec<OsString> = env::args_os().collect();
+    let (requested, argv) = match dispatch_from_argv(argv)? {
+        AppletDispatch::Run { applet, argv } => (applet, argv),
+        AppletDispatch::Help(help) => {
+            print!("{help}");
+            return Ok(());
+        }
+    };
+
+    match requested {
+        RequestedApplet::Client => run_client_applet(argv),
+        RequestedApplet::Tui => run_tui_applet(argv),
+        RequestedApplet::Server => run_server_applet(argv),
+    }
+}
+
+/// Installs the shutdown signal handler shared by every applet and hands the
+/// resulting flag to `f`.
+#[cfg(any(feature = "client", feature = "server", feature = "tui"))]
+fn with_shutdown_flag(
+    f: impl FnOnce(&AtomicBool) -> Result<(), Box<dyn std::error::Error>>,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let shutdown_requested = Arc::new(AtomicBool::new(false));
+    install_signal_handler(Arc::clone(&shutdown_requested))
+        .map_err(|err| format!("failed to install signal handler: {err}"))?;
+    f(shutdown_requested.as_ref())
+}
+
+#[cfg(feature = "client")]
+fn run_client_applet(argv: Vec<OsString>) -> Result<(), Box<dyn std::error::Error>> {
+    use clap::Parser;
+
+    with_shutdown_flag(|shutdown_requested| {
+        let args = crate::cmd::client::ClientArgs::parse_from(argv);
+        crate::cmd::client::run_stream(args, shutdown_requested)
+    })
+}
+
+#[cfg(not(feature = "client"))]
+fn run_client_applet(_argv: Vec<OsString>) -> Result<(), Box<dyn std::error::Error>> {
+    Err("client applet is not available; rebuild with the client feature".into())
+}
+
+#[cfg(feature = "server")]
+fn run_server_applet(argv: Vec<OsString>) -> Result<(), Box<dyn std::error::Error>> {
+    use clap::Parser;
+
+    with_shutdown_flag(|shutdown_requested| {
+        let args = crate::cmd::server::ServerArgs::parse_from(argv);
+        crate::cmd::server::run_server(args, shutdown_requested)
+    })
+}
+
+#[cfg(not(feature = "server"))]
+fn run_server_applet(_argv: Vec<OsString>) -> Result<(), Box<dyn std::error::Error>> {
+    Err("server applet is not available; rebuild with the server feature".into())
+}
+
+#[cfg(feature = "tui")]
+fn run_tui_applet(argv: Vec<OsString>) -> Result<(), Box<dyn std::error::Error>> {
+    use clap::Parser;
+
+    with_shutdown_flag(|shutdown_requested| {
+        let args = crate::cmd::tui::TuiArgs::parse_from(argv);
+        crate::cmd::tui::run_tui(args, shutdown_requested)
+    })
+}
+
+#[cfg(not(feature = "tui"))]
+fn run_tui_applet(_argv: Vec<OsString>) -> Result<(), Box<dyn std::error::Error>> {
+    Err("TUI applet is not available; rebuild with the tui feature".into())
+}

crates/irtt-app/src/shared/client/args.rs

@@ -15,7 +15,7 @@ pub struct CommonClientArgs {
     pub length: u32,
 
     /// HMAC key.
-    #[arg(long)]
+    #[arg(long, value_parser = parse_hmac_key)]
     pub hmac: Option<String>,
 
     /// Clock mode to request.
@@ -189,6 +189,13 @@ pub fn parse_length(input: &str) -> Result<u32, String> {
     Ok(length)
 }
 
+pub fn parse_hmac_key(input: &str) -> Result<String, String> {
+    if input.is_empty() {
+        return Err("HMAC key must not be empty".to_owned());
+    }
+    Ok(input.to_owned())
+}
+
 pub fn parse_server_fill(input: &str) -> Result<String, String> {
     if input.is_empty() {
         return Err("server fill must not be empty".to_owned());

crates/irtt-app/src/shared/client/config.rs

@@ -7,9 +7,13 @@ use super::args::CommonClientArgs;
 pub const DEFAULT_RECV_TIMEOUT: Duration = Duration::from_millis(20);
 
 impl CommonClientArgs {
-    pub fn to_client_config(&self, server: &str, duration: Duration) -> ClientConfig {
+    /// Build the shared client configuration template for a managed run.
+    ///
+    /// The template carries no server address: the managed driver replaces it
+    /// per target from that target's configuration, so deriving one here from
+    /// an arbitrary target would be dead data.
+    pub fn to_client_config(&self, duration: Duration) -> ClientConfig {
         ClientConfig {
-            server_addr: server.to_owned(),
             duration: (!duration.is_zero()).then_some(duration),
             interval: self.interval,
             length: self.length,

crates/irtt-app/src/shared/client/mod.rs

@@ -0,0 +1,20 @@
+pub mod args;
+pub mod config;
+pub mod prepare;
+pub mod session;
+pub mod targets;
+
+pub use args::{
+    parse_dscp, parse_duration, parse_length, parse_server_fill, parse_test_duration, parse_ttl,
+    ClockArg, CommonClientArgs, ReceivedStatsArg, TimestampArg,
+};
+pub use config::{expected_probe_count, DEFAULT_RECV_TIMEOUT};
+pub use prepare::{
+    prepare_managed_run, ManagedRunSetup, TargetSelection, MANAGED_EVENT_CAPACITY,
+    STDIN_MAX_DESIRED_TARGETS, STDIN_MAX_LIVE_TARGET_GENERATIONS, STDIN_OUTCOME_HISTORY_LIMIT,
+};
+pub use session::is_shutdown_requested;
+pub use targets::{
+    parse_stdin_target_set, parse_target, prepare_managed_targets, target_specs, GroupPacingArg,
+    PreparedTarget, TargetArg, TargetSpec,
+};

crates/irtt-app/src/shared/client/prepare.rs

@@ -0,0 +1,276 @@
+//! One preparation step from parsed arguments to a runnable managed setup.
+//!
+//! Both client applets accept the same target and pacing arguments and then
+//! have to turn them into the same three things: a validated target set, one
+//! shared [`ClientConfig`] template, and a [`ManagedPacing`]. Doing that
+//! separately in each applet is how the CLI ended up deriving its client
+//! configuration from an arbitrary "primary" target whose address the managed
+//! driver immediately replaced per target.
+
+use std::time::Duration;
+
+use irtt_client::{
+    managed::{ManagedClientConfig, ManagedCompletionPolicy, ManagedPacing},
+    ClientConfig,
+};
+
+use super::{
+    args::CommonClientArgs,
+    targets::{prepare_managed_targets, target_specs, GroupPacingArg, TargetArg},
+    PreparedTarget,
+};
+
+/// Capacity of the lossy managed presentation event channel.
+pub const MANAGED_EVENT_CAPACITY: usize = 16_384;
+pub const STDIN_MAX_DESIRED_TARGETS: usize = 128;
+pub const STDIN_MAX_LIVE_TARGET_GENERATIONS: usize = 256;
+pub const STDIN_OUTCOME_HISTORY_LIMIT: usize = 256;
+
+/// Target and pacing arguments common to the client applets.
+///
+/// Duration is deliberately absent: the applets disagree about what a duration
+/// means and what its default is, so each keeps its own.
+#[derive(Debug, Clone, Copy)]
+pub struct TargetSelection<'a> {
+    pub targets: &'a [TargetArg],
+    pub pacing: GroupPacingArg,
+    pub stdin_controlled: bool,
+}
+
+/// Everything a managed run needs, prepared and validated together.
+#[derive(Debug, Clone)]
+pub struct ManagedRunSetup {
+    /// Validated targets, in the order the user gave them.
+    pub targets: Vec<PreparedTarget>,
+    /// Shared client configuration template.
+    ///
+    /// The managed driver supplies each target's address and authentication
+    /// from its [`ManagedTargetConfig`](irtt_client::managed::ManagedTargetConfig),
+    /// so this template carries no target of its own.
+    pub client: ClientConfig,
+    /// Send coordination across active targets.
+    pub pacing: ManagedPacing,
+    /// Whether this stream may replace its desired set from stdin.
+    pub stdin_controlled: bool,
+}
+
+impl ManagedRunSetup {
+    /// Number of validated targets.
+    pub fn target_count(&self) -> usize {
+        self.targets.len()
+    }
+
+    /// Whether this run drives more than one target.
+    pub fn is_multi_target(&self) -> bool {
+        self.targets.len() > 1
+    }
+
+    /// Managed target configurations, in argument order.
+    pub fn managed_targets(&self) -> Vec<irtt_client::managed::ManagedTargetConfig> {
+        self.targets
+            .iter()
+            .map(|target| target.managed.clone())
+            .collect()
+    }
+
+    /// Managed driver configuration for this run.
+    pub fn managed_config(&self) -> ManagedClientConfig {
+        let target_count = self.target_count();
+        let mut config = ManagedClientConfig {
+            client: self.client.clone(),
+            pacing: self.pacing,
+            completion: ManagedCompletionPolicy::FinishWhenQuiescent,
+            event_capacity: MANAGED_EVENT_CAPACITY,
+            outcome_history_limit: target_count,
+            max_live_target_generations: target_count,
+            ..ManagedClientConfig::default()
+        };
+        if self.stdin_controlled {
+            config.completion = ManagedCompletionPolicy::ExplicitStop;
+            config.outcome_history_limit = STDIN_OUTCOME_HISTORY_LIMIT;
+            config.max_live_target_generations = STDIN_MAX_LIVE_TARGET_GENERATIONS;
+        }
+        config
+    }
+}
+
+/// Validate the selected targets and build the shared run setup.
+///
+/// Targets are validated before any configuration is built, so a bad target set
+/// fails before the caller can act on a half-prepared run.
+pub fn prepare_managed_run(
+    common: &CommonClientArgs,
+    duration: Duration,
+    selection: TargetSelection<'_>,
+) -> Result<ManagedRunSetup, String> {
+    let specs = if selection.stdin_controlled {
+        if selection.targets.len() > STDIN_MAX_DESIRED_TARGETS {
+            return Err(format!(
+                "initial target set exceeds the {STDIN_MAX_DESIRED_TARGETS}-target limit"
+            ));
+        }
+        super::targets::target_specs_with_empty(selection.targets, true)?
+    } else {
+        target_specs(selection.targets)?
+    };
+    let targets = prepare_managed_targets(specs)?;
+    Ok(ManagedRunSetup {
+        targets,
+        client: common.to_client_config(duration),
+        pacing: selection.pacing.into(),
+        stdin_controlled: selection.stdin_controlled,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use clap::Parser;
+
+    use super::*;
+
+    #[derive(Parser)]
+    struct CommonOnlyArgs {
+        #[command(flatten)]
+        common: CommonClientArgs,
+    }
+
+    fn common(args: &[&str]) -> CommonClientArgs {
+        let mut argv = vec!["common-only"];
+        argv.extend_from_slice(args);
+        CommonOnlyArgs::try_parse_from(argv).unwrap().common
+    }
+
+    fn unlabeled(addr: &str) -> TargetArg {
+        TargetArg::new(addr)
+    }
+
+    fn labeled(label: &str, addr: &str) -> TargetArg {
+        TargetArg::new(format!("{label}={addr}"))
+    }
+
+    fn prepare(
+        targets: &[TargetArg],
+        pacing: GroupPacingArg,
+        duration: Duration,
+    ) -> Result<ManagedRunSetup, String> {
+        prepare_managed_run(
+            &common(&[]),
+            duration,
+            TargetSelection {
+                targets,
+                pacing,
+                stdin_controlled: false,
+            },
+        )
+    }
+
+    #[test]
+    fn a_single_target_prepares_one_managed_target_and_a_finite_duration() {
+        let setup = prepare(
+            &[unlabeled("127.0.0.1:2112")],
+            GroupPacingArg::Staggered,
+            Duration::from_secs(30),
+        )
+        .unwrap();
+
+        assert_eq!(setup.target_count(), 1);
+        assert!(!setup.is_multi_target());
+        assert_eq!(setup.targets[0].label, "127.0.0.1:2112");
+        assert_eq!(setup.targets[0].managed.server_addr, "127.0.0.1:2112");
+        assert_eq!(setup.client.duration, Some(Duration::from_secs(30)));
+        assert_eq!(setup.pacing, ManagedPacing::Staggered);
+    }
+
+    #[test]
+    fn a_zero_duration_prepares_a_continuous_client_config() {
+        let setup = prepare(
+            &[unlabeled("127.0.0.1:2112")],
+            GroupPacingArg::Staggered,
+            Duration::ZERO,
+        )
+        .unwrap();
+
+        assert_eq!(setup.client.duration, None);
+    }
+
+    #[test]
+    fn multiple_targets_keep_argument_order_and_share_one_client_config() {
+        let setup = prepare(
+            &[
+                unlabeled("host-a:2112"),
+                unlabeled("host-b:2112"),
+                labeled("sg", "sg.example.test:2112"),
+            ],
+            GroupPacingArg::Burst,
+            Duration::from_secs(10),
+        )
+        .unwrap();
+
+        assert!(setup.is_multi_target());
+        let labels: Vec<_> = setup
+            .targets
+            .iter()
+            .map(|target| target.label.as_str())
+            .collect();
+        assert_eq!(labels, ["host-a:2112", "host-b:2112", "sg"]);
+        assert_eq!(setup.targets[2].managed.server_addr, "sg.example.test:2112");
+        assert_eq!(setup.pacing, ManagedPacing::Burst);
+
+        let config = setup.managed_config();
+        assert_eq!(config.outcome_history_limit, 3);
+        assert_eq!(config.max_live_target_generations, 3);
+        assert_eq!(config.event_capacity, MANAGED_EVENT_CAPACITY);
+        assert_eq!(config.pacing, ManagedPacing::Burst);
+        assert_eq!(config.client, setup.client);
+        assert_eq!(setup.managed_targets().len(), 3);
+    }
+
+    #[test]
+    fn the_shared_client_config_carries_no_target_of_its_own() {
+        // The managed driver replaces the address, and the CLI's key, per
+        // target, so the template must not pin either to one target.
+        let targets = vec![unlabeled("host-a:2112"), unlabeled("host-b:2112")];
+        let setup = prepare_managed_run(
+            &common(&["--hmac", "secret"]),
+            Duration::from_secs(10),
+            TargetSelection {
+                targets: &targets,
+                pacing: GroupPacingArg::Staggered,
+                stdin_controlled: false,
+            },
+        )
+        .unwrap();
+
+        assert_eq!(
+            setup.client.server_addr,
+            ClientConfig::default().server_addr
+        );
+        assert_eq!(setup.client.hmac_key, Some(b"secret".to_vec()));
+        // Per-target authentication is not exposed on the command line, so no
+        // target carries an override of the shared key.
+        assert!(setup
+            .targets
+            .iter()
+            .all(|target| target.managed.auth.is_none()));
+    }
+
+    #[test]
+    fn an_empty_target_set_is_rejected_with_the_list_columns_hint() {
+        let err = prepare(&[], GroupPacingArg::Staggered, Duration::from_secs(10)).unwrap_err();
+
+        assert!(err.contains("at least one target is required"));
+        assert!(err.contains("--list-columns"));
+    }
+
+    #[test]
+    fn a_duplicate_label_is_rejected_before_any_configuration_is_built() {
+        let targets = vec![
+            unlabeled("host-a:2112"),
+            labeled("host-a:2112", "host-b:2112"),
+        ];
+        let err =
+            prepare(&targets, GroupPacingArg::Staggered, Duration::from_secs(10)).unwrap_err();
+
+        assert!(err.contains("duplicate target label"));
+    }
+}

crates/irtt-app/src/shared/client/session.rs

@@ -0,0 +1,141 @@
+use std::sync::atomic::{AtomicBool, Ordering};
+
+#[cfg(any(feature = "client", feature = "tui"))]
+use irtt_client::managed::{ManagedEvent, ManagedEventSubscription, ManagedEventTryRecvError};
+
+#[cfg(any(feature = "client", feature = "tui"))]
+pub(crate) const MANAGED_EVENT_WORK_BUDGET: usize = 128;
+
+#[cfg(any(feature = "client", feature = "tui"))]
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(crate) enum ManagedDrainState {
+    Empty,
+    Closed,
+    BudgetExhausted,
+}
+
+/// Drain a bounded amount of lossy presentation work before returning to the
+/// frontend control loop.
+#[cfg(any(feature = "client", feature = "tui"))]
+pub(crate) fn drain_managed_events<E>(
+    events: &mut ManagedEventSubscription,
+    dropped_events: &mut u64,
+    mut process: impl FnMut(ManagedEvent) -> Result<(), E>,
+) -> Result<ManagedDrainState, E> {
+    for _ in 0..MANAGED_EVENT_WORK_BUDGET {
+        match events.try_recv() {
+            Ok(event) => process(event)?,
+            Err(ManagedEventTryRecvError::Lagged(count)) => {
+                *dropped_events = dropped_events.saturating_add(count);
+            }
+            Err(ManagedEventTryRecvError::Empty) => return Ok(ManagedDrainState::Empty),
+            Err(ManagedEventTryRecvError::Closed) => return Ok(ManagedDrainState::Closed),
+        }
+    }
+    Ok(ManagedDrainState::BudgetExhausted)
+}
+
+pub fn is_shutdown_requested(shutdown_requested: &AtomicBool) -> bool {
+    shutdown_requested.load(Ordering::Relaxed)
+}
+
+pub fn should_print_final_summary(continuous: bool, interrupted: bool) -> bool {
+    !continuous || interrupted
+}
+
+pub fn peer_close_run_error(
+    continuous: bool,
+    interrupted: bool,
+    peer_closed_target_outcomes: u64,
+) -> Option<String> {
+    if !continuous || interrupted || peer_closed_target_outcomes == 0 {
+        return None;
+    }
+
+    let sessions = if peer_closed_target_outcomes == 1 {
+        "target session"
+    } else {
+        "target sessions"
+    };
+    Some(format!(
+        "continuous run ended because of peer closure ({peer_closed_target_outcomes} {sessions})"
+    ))
+}
+
+pub fn request_managed_stop_for_peer_close(
+    continuous: bool,
+    interrupted: bool,
+    peer_closed_target_outcomes: u64,
+    stop_requested: &mut bool,
+) -> bool {
+    if !continuous || interrupted || peer_closed_target_outcomes == 0 {
+        return false;
+    }
+    request_managed_stop_once(stop_requested)
+}
+
+pub fn request_managed_stop_once(stop_requested: &mut bool) -> bool {
+    if *stop_requested {
+        return false;
+    }
+    *stop_requested = true;
+    true
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn peer_close_run_error_is_run_mode_and_interruption_aware() {
+        assert_eq!(peer_close_run_error(false, false, 1), None);
+        assert_eq!(peer_close_run_error(true, false, 0), None);
+        assert_eq!(peer_close_run_error(true, true, 1), None);
+        assert_eq!(
+            peer_close_run_error(true, false, 1).as_deref(),
+            Some("continuous run ended because of peer closure (1 target session)")
+        );
+        assert_eq!(
+            peer_close_run_error(true, false, 3).as_deref(),
+            Some("continuous run ended because of peer closure (3 target sessions)")
+        );
+    }
+
+    #[test]
+    fn grouped_peer_close_stop_policy_is_run_mode_and_one_shot() {
+        let mut stop_requested = false;
+        assert!(!request_managed_stop_for_peer_close(
+            false,
+            false,
+            1,
+            &mut stop_requested,
+        ));
+        assert!(!request_managed_stop_for_peer_close(
+            true,
+            true,
+            1,
+            &mut stop_requested,
+        ));
+        assert!(!request_managed_stop_for_peer_close(
+            true,
+            false,
+            0,
+            &mut stop_requested,
+        ));
+        assert!(!stop_requested);
+
+        assert!(request_managed_stop_for_peer_close(
+            true,
+            false,
+            1,
+            &mut stop_requested,
+        ));
+        assert!(stop_requested);
+        assert!(!request_managed_stop_for_peer_close(
+            true,
+            false,
+            1,
+            &mut stop_requested,
+        ));
+    }
+}

crates/irtt-app/src/shared/client/targets.rs

@@ -0,0 +1,491 @@
+use std::{collections::HashSet, fmt};
+
+use clap::ValueEnum;
+use irtt_client::{
+    managed::{ManagedPacing, ManagedTargetConfig, TargetId},
+    ClientAuthConfig,
+};
+
+/// One raw positional target captured by Clap.
+///
+/// Parsing happens during run preparation so invalid target syntax never makes
+/// Clap include the original argument (which may carry an HMAC key) in an
+/// error diagnostic.
+#[derive(Clone, PartialEq, Eq)]
+pub struct TargetArg {
+    input: String,
+}
+
+impl TargetArg {
+    pub fn new(input: impl Into<String>) -> Self {
+        Self {
+            input: input.into(),
+        }
+    }
+}
+
+impl fmt::Debug for TargetArg {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str("TargetArg(<redacted>)")
+    }
+}
+
+/// Capture one positional target without exposing it through Clap diagnostics.
+pub fn parse_target(input: &str) -> Result<TargetArg, String> {
+    Ok(TargetArg::new(input))
+}
+
+#[derive(Clone, PartialEq, Eq)]
+pub enum TargetAuth {
+    Inherit,
+    Override(Vec<u8>),
+    Disable,
+}
+
+impl fmt::Debug for TargetAuth {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Inherit => f.write_str("Inherit"),
+            Self::Override(_) => f.write_str("Override(<redacted>)"),
+            Self::Disable => f.write_str("Disable"),
+        }
+    }
+}
+
+#[derive(Clone, PartialEq, Eq)]
+pub struct TargetSpec {
+    pub label: String,
+    pub addr: String,
+    pub auth: TargetAuth,
+}
+
+impl fmt::Debug for TargetSpec {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("TargetSpec")
+            .field("label", &self.label)
+            .field("addr", &self.addr)
+            .field("auth", &self.auth)
+            .finish()
+    }
+}
+
+#[derive(Clone)]
+pub struct PreparedTarget {
+    pub label: String,
+    pub managed: ManagedTargetConfig,
+}
+
+impl fmt::Debug for PreparedTarget {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("PreparedTarget")
+            .field("label", &self.label)
+            .field("server_addr", &self.managed.server_addr)
+            .field(
+                "auth",
+                &match &self.managed.auth {
+                    None => TargetAuth::Inherit,
+                    Some(ClientAuthConfig { hmac_key: Some(_) }) => {
+                        TargetAuth::Override(Vec::new())
+                    }
+                    Some(ClientAuthConfig { hmac_key: None }) => TargetAuth::Disable,
+                },
+            )
+            .finish()
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub enum GroupPacingArg {
+    Staggered,
+    Burst,
+}
+
+impl From<GroupPacingArg> for ManagedPacing {
+    fn from(value: GroupPacingArg) -> Self {
+        match value {
+            GroupPacingArg::Staggered => Self::Staggered,
+            GroupPacingArg::Burst => Self::Burst,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum TargetParseError {
+    EmptyLabel,
+    EmptyAddress,
+    InvalidEscape,
+    EmptyTarget,
+}
+
+impl fmt::Display for TargetParseError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let message = match self {
+            Self::EmptyLabel => "target label must not be empty",
+            Self::EmptyAddress => "target address must not be empty",
+            Self::InvalidEscape => "invalid target escape sequence",
+            Self::EmptyTarget => "target must not be empty",
+        };
+        f.write_str(message)
+    }
+}
+
+fn split_unescaped(input: &str, delimiter: char) -> Result<Vec<&str>, TargetParseError> {
+    let mut parts = Vec::new();
+    let mut start = 0;
+    let mut escaped = false;
+    for (index, ch) in input.char_indices() {
+        if escaped {
+            escaped = false;
+        } else if ch == '\\' {
+            escaped = true;
+        } else if ch == delimiter {
+            parts.push(&input[start..index]);
+            start = index + ch.len_utf8();
+        }
+    }
+    if escaped {
+        return Err(TargetParseError::InvalidEscape);
+    }
+    parts.push(&input[start..]);
+    Ok(parts)
+}
+
+fn first_unescaped(input: &str, delimiter: char) -> Result<Option<usize>, TargetParseError> {
+    let mut escaped = false;
+    for (index, ch) in input.char_indices() {
+        if escaped {
+            escaped = false;
+        } else if ch == '\\' {
+            escaped = true;
+        } else if ch == delimiter {
+            return Ok(Some(index));
+        }
+    }
+    if escaped {
+        return Err(TargetParseError::InvalidEscape);
+    }
+    Ok(None)
+}
+
+fn unescape(input: &str) -> Result<String, TargetParseError> {
+    let mut output = String::with_capacity(input.len());
+    let mut escaped = false;
+    for ch in input.chars() {
+        if escaped {
+            if !matches!(ch, '\\' | '=' | ';' | ',' | '@') {
+                return Err(TargetParseError::InvalidEscape);
+            }
+            output.push(ch);
+            escaped = false;
+        } else if ch == '\\' {
+            escaped = true;
+        } else {
+            output.push(ch);
+        }
+    }
+    if escaped {
+        return Err(TargetParseError::InvalidEscape);
+    }
+    Ok(output)
+}
+
+fn hmac_modifier(input: &str) -> Result<Option<usize>, TargetParseError> {
+    let mut escaped = false;
+    for (index, ch) in input.char_indices() {
+        if escaped {
+            escaped = false;
+        } else if ch == '\\' {
+            escaped = true;
+        } else if input[index..].starts_with("@hmac=") {
+            return Ok(Some(index));
+        }
+    }
+    if escaped {
+        return Err(TargetParseError::InvalidEscape);
+    }
+    Ok(None)
+}
+
+fn parse_target_syntax(
+    input: &str,
+) -> Result<(Option<String>, String, TargetAuth), TargetParseError> {
+    if input.is_empty() {
+        return Err(TargetParseError::EmptyTarget);
+    }
+    let (main, auth) = match hmac_modifier(input)? {
+        Some(index) => {
+            let value = unescape(&input[index + "@hmac=".len()..])?;
+            let auth = if value.is_empty() {
+                TargetAuth::Disable
+            } else {
+                TargetAuth::Override(value.into_bytes())
+            };
+            (&input[..index], auth)
+        }
+        None => (input, TargetAuth::Inherit),
+    };
+    let (label, address) = match first_unescaped(main, '=')? {
+        None => (None, unescape(main)?),
+        Some(index) => {
+            let label = unescape(&main[..index])?;
+            let address = unescape(&main[index + '='.len_utf8()..])?;
+            (Some(label), address)
+        }
+    };
+    if label.as_deref().is_some_and(str::is_empty) {
+        return Err(TargetParseError::EmptyLabel);
+    }
+    if address.is_empty() {
+        return Err(TargetParseError::EmptyAddress);
+    }
+    Ok((label, address, auth))
+}
+
+pub(crate) fn target_specs_with_empty(
+    targets: &[TargetArg],
+    allow_empty: bool,
+) -> Result<Vec<TargetSpec>, String> {
+    let mut specs = Vec::with_capacity(targets.len());
+    let mut unlabeled_counts = std::collections::HashMap::<String, usize>::new();
+    for (index, target) in targets.iter().enumerate() {
+        let (explicit_label, addr, auth) = parse_target_syntax(&target.input)
+            .map_err(|error| format!("invalid target {}: {error}", index + 1))?;
+        let label = match explicit_label {
+            Some(label) => label,
+            None => {
+                let count = unlabeled_counts.entry(addr.clone()).or_default();
+                *count += 1;
+                if *count == 1 {
+                    addr.clone()
+                } else {
+                    format!("{}#{}", addr, *count)
+                }
+            }
+        };
+        specs.push(TargetSpec { label, addr, auth });
+    }
+
+    if specs.is_empty() && !allow_empty {
+        return Err("at least one target is required unless --list-columns is set".to_owned());
+    }
+
+    let mut labels = HashSet::new();
+    for spec in &specs {
+        if !labels.insert(spec.label.clone()) {
+            return Err("duplicate target label".to_owned());
+        }
+    }
+
+    Ok(specs)
+}
+
+pub fn target_specs(targets: &[TargetArg]) -> Result<Vec<TargetSpec>, String> {
+    target_specs_with_empty(targets, false)
+}
+
+pub fn prepare_managed_targets(specs: Vec<TargetSpec>) -> Result<Vec<PreparedTarget>, String> {
+    let mut targets = Vec::with_capacity(specs.len());
+    for spec in specs {
+        let mut managed = ManagedTargetConfig::new(TargetId::from(spec.label.clone()), spec.addr);
+        managed.auth = match spec.auth {
+            TargetAuth::Inherit => None,
+            TargetAuth::Override(hmac_key) => Some(ClientAuthConfig {
+                hmac_key: Some(hmac_key),
+            }),
+            TargetAuth::Disable => Some(ClientAuthConfig { hmac_key: None }),
+        };
+        targets.push(PreparedTarget {
+            label: spec.label,
+            managed,
+        });
+    }
+    Ok(targets)
+}
+
+/// Parse one complete stdin target set after its line terminator was removed.
+///
+/// Commas frame stdin elements only; positional target arguments do not use
+/// this framing and may therefore contain raw commas.
+pub fn parse_stdin_target_set(
+    record: &str,
+    maximum_targets: usize,
+) -> Result<Vec<PreparedTarget>, String> {
+    if record == "[]" {
+        return Ok(Vec::new());
+    }
+    let elements = split_unescaped(record, ',').map_err(|error| error.to_string())?;
+    if elements.len() > maximum_targets {
+        return Err(format!(
+            "target set exceeds the {maximum_targets}-target limit"
+        ));
+    }
+    let args = elements.into_iter().map(TargetArg::new).collect::<Vec<_>>();
+    prepare_managed_targets(target_specs_with_empty(&args, true)?)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn target(input: &str) -> TargetArg {
+        TargetArg::new(input)
+    }
+
+    fn specs(inputs: &[&str]) -> Result<Vec<TargetSpec>, String> {
+        target_specs(&inputs.iter().map(|input| target(input)).collect::<Vec<_>>())
+    }
+
+    #[test]
+    fn legacy_target_syntax_and_ipv6_remain_supported() {
+        let parsed = specs(&[
+            "host.example",
+            "host.example:2112",
+            "[::1]:2112",
+            "eu=host.example",
+        ])
+        .unwrap();
+        assert_eq!(parsed[0].label, "host.example");
+        assert_eq!(parsed[1].label, "host.example:2112");
+        assert_eq!(parsed[2].label, "[::1]:2112");
+        assert_eq!(parsed[3].label, "eu");
+        assert!(parsed
+            .iter()
+            .all(|target| matches!(target.auth, TargetAuth::Inherit)));
+    }
+
+    #[test]
+    fn target_hmac_supports_inherit_override_disable_and_base64_padding() {
+        let parsed = specs(&[
+            "default=default.example",
+            "private=private.example@hmac=YWJjZA==",
+            "public=public.example@hmac=",
+        ])
+        .unwrap();
+        assert!(matches!(parsed[0].auth, TargetAuth::Inherit));
+        assert_eq!(parsed[1].auth, TargetAuth::Override(b"YWJjZA==".to_vec()));
+        assert!(matches!(parsed[2].auth, TargetAuth::Disable));
+    }
+
+    #[test]
+    fn target_delimiters_are_escaped_contextually() {
+        let parsed = specs(&["eu\\=west=host\\@hmac=literal@hmac=a\\@b\\,c\\=d\\\\e"]).unwrap();
+        assert_eq!(parsed[0].label, "eu=west");
+        assert_eq!(parsed[0].addr, "host@hmac=literal");
+        assert_eq!(parsed[0].auth, TargetAuth::Override(b"a@b,c=d\\e".to_vec()));
+    }
+
+    #[test]
+    fn positional_commas_are_not_reserved() {
+        let parsed = specs(&["edge=host,region@hmac=key,part"]).unwrap();
+        assert_eq!(parsed[0].addr, "host,region");
+        assert_eq!(parsed[0].auth, TargetAuth::Override(b"key,part".to_vec()));
+    }
+
+    #[test]
+    fn parser_diagnostics_and_debug_do_not_reveal_hmac_values() {
+        let secret = "very-secret-value";
+        let error = specs(&[&format!("target=host@hmac={secret}\\q")]).unwrap_err();
+        assert!(!error.contains(secret));
+        assert!(!format!("{:?}", target(&format!("target=host@hmac={secret}"))).contains(secret));
+        assert!(
+            !format!("{:?}", TargetAuth::Override(secret.as_bytes().to_vec())).contains(secret)
+        );
+    }
+
+    #[test]
+    fn target_specs_suffix_repeated_unlabeled_and_reject_duplicate_labels() {
+        let parsed = specs(&["host-a:2112", "host-a:2112"]).unwrap();
+        assert_eq!(parsed[0].label, "host-a:2112");
+        assert_eq!(parsed[1].label, "host-a:2112#2");
+        assert_eq!(
+            specs(&["host-a:2112", "host-a:2112=host-b:2112"]).unwrap_err(),
+            "duplicate target label"
+        );
+    }
+
+    #[test]
+    fn target_specs_preserve_argument_order_and_unlabeled_counts() {
+        let parsed = specs(&["local", "eu=eu.example", "foo", "us=us.example", "foo"]).unwrap();
+        let labels: Vec<_> = parsed.iter().map(|target| target.label.as_str()).collect();
+        assert_eq!(labels, ["local", "eu", "foo", "us", "foo#2"]);
+        let addresses: Vec<_> = parsed.iter().map(|target| target.addr.as_str()).collect();
+        assert_eq!(
+            addresses,
+            ["local", "eu.example", "foo", "us.example", "foo"]
+        );
+    }
+
+    #[test]
+    fn target_specs_reject_generated_suffix_collisions() {
+        assert_eq!(
+            specs(&[
+                "host.example",
+                "host.example",
+                "host.example#2=other.example"
+            ])
+            .unwrap_err(),
+            "duplicate target label"
+        );
+    }
+
+    #[test]
+    fn malformed_target_syntax_is_rejected_without_echoing_input() {
+        for input in ["=host", "label=", "host@hmac=value\\q", "host\\x"] {
+            assert!(specs(&[input]).is_err(), "{input}");
+        }
+    }
+
+    #[test]
+    fn target_preparation_maps_auth_to_managed_config() {
+        let prepared =
+            prepare_managed_targets(specs(&["a=one@hmac=key", "b=two@hmac="]).unwrap()).unwrap();
+        assert_eq!(
+            prepared[0]
+                .managed
+                .auth
+                .as_ref()
+                .unwrap()
+                .hmac_key
+                .as_deref(),
+            Some(b"key".as_slice())
+        );
+        assert_eq!(prepared[1].managed.auth.as_ref().unwrap().hmac_key, None);
+    }
+
+    #[test]
+    fn target_preparation_preserves_duplicate_endpoints() {
+        let prepared =
+            prepare_managed_targets(specs(&["a=example.test", "b=example.test"]).unwrap()).unwrap();
+        assert_eq!(prepared[0].managed.server_addr, "example.test");
+        assert_eq!(prepared[1].managed.server_addr, "example.test");
+    }
+
+    #[test]
+    fn stdin_target_sets_frame_commas_without_trimming_payload() {
+        let parsed = parse_stdin_target_set("a=one@hmac=x\\,y,b=two", 128).unwrap();
+        assert_eq!(
+            parsed[0].managed.auth.as_ref().unwrap().hmac_key.as_deref(),
+            Some(b"x,y".as_slice())
+        );
+        assert_eq!(parsed[1].label, "b");
+        assert_eq!(
+            parse_stdin_target_set(" []", 128).unwrap()[0]
+                .managed
+                .server_addr,
+            " []"
+        );
+        assert_eq!(
+            parse_stdin_target_set("[] ", 128).unwrap()[0]
+                .managed
+                .server_addr,
+            "[] "
+        );
+        assert!(parse_stdin_target_set("", 128).is_err());
+        assert!(parse_stdin_target_set("a=one,b=two", 1).is_err());
+    }
+
+    #[test]
+    fn stdin_empty_set_is_exactly_bracket_pair() {
+        assert!(parse_stdin_target_set("[]", 128).unwrap().is_empty());
+    }
+}

crates/irtt-app/src/shared/mod.rs

@@ -0,0 +1,2 @@
+#[cfg(any(feature = "client", feature = "tui"))]
+pub mod client;

crates/irtt-cli/Cargo.toml

@@ -1,46 +0,0 @@
-[package]
-name = "irtt-cli"
-version = "0.4.0"
-description = "Command-line IRTT-compatible client"
-edition.workspace = true
-license.workspace = true
-rust-version.workspace = true
-repository.workspace = true
-homepage.workspace = true
-readme.workspace = true
-keywords = ["irtt", "networking", "latency", "rtt"]
-categories = ["command-line-utilities", "network-programming"]
-
-[lib]
-doc = false
-
-[[bin]]
-name = "irtt-rs"
-path = "src/bin/irtt-rs.rs"
-
-[[bin]]
-name = "irtt-cli"
-path = "src/bin/irtt-cli.rs"
-required-features = ["client"]
-
-[[bin]]
-name = "irtt-tui"
-path = "src/bin/irtt-tui.rs"
-required-features = ["tui"]
-
-[features]
-default = ["client", "stats"]
-client-runtime = ["dep:irtt-client", "dep:irtt-proto"]
-client = ["client-runtime"]
-stats = ["client-runtime", "dep:irtt-stats"]
-tui = ["client-runtime", "stats", "dep:ratatui", "dep:crossterm"]
-full = ["client", "stats", "tui"]
-
-[dependencies]
-clap = { version = "4.6.1", features = ["derive"] }
-crossterm = { version = "0.29.0", optional = true }
-ctrlc = "3.5.2"
-irtt-client = { workspace = true, optional = true }
-irtt-proto = { workspace = true, optional = true }
-irtt-stats = { workspace = true, optional = true }
-ratatui = { version = "0.30.2", optional = true }

crates/irtt-cli/src/cmd/client/run.rs

@@ -1,766 +0,0 @@
-#[cfg(feature = "stats")]
-use std::collections::BTreeMap;
-use std::{
-    collections::HashSet,
-    io::{self, Write},
-    sync::atomic::AtomicBool,
-    thread,
-    time::{Duration, Instant},
-};
-
-use irtt_client::{
-    ClientEvent, EventSubscriptionError, ManagedClientGroup, ManagedClientGroupConfig,
-    ManagedGroupEndReason, SubscriberConfig, SubscriberOverflow, TargetEvent,
-};
-#[cfg(all(test, feature = "stats"))]
-use irtt_client::{ClientTimestamp, PacketMeta, RttSample, SignedDuration};
-
-use super::{
-    args::{ClientArgs, ResolvedCliTarget},
-    output::{EventRenderStats, OutputConfig},
-};
-#[cfg(feature = "stats")]
-use crate::shared::client::expected_probe_count;
-use crate::shared::client::{
-    is_shutdown_requested, session::should_print_final_summary, ClientSession,
-};
-
-#[cfg(feature = "stats")]
-use irtt_stats::{StatsCollector, StatsConfig};
-
-#[cfg(feature = "stats")]
-const FINITE_STATS_BYTES_PER_PROBE: u64 = 500;
-#[cfg(feature = "stats")]
-const MIB: u64 = 1024 * 1024;
-#[cfg(feature = "stats")]
-const GIB: u64 = 1024 * MIB;
-#[cfg(feature = "stats")]
-const FINITE_STATS_MEMORY_WARNING_BYTES: u64 = 128 * MIB;
-#[cfg(feature = "stats")]
-const FINITE_STATS_MEMORY_STRONG_WARNING_BYTES: u64 = 512 * MIB;
-#[cfg(feature = "stats")]
-const FINITE_STATS_MEMORY_VERY_STRONG_WARNING_BYTES: u64 = GIB;
-
-const GROUP_IDLE_SLEEP: Duration = Duration::from_millis(5);
-const GROUP_COMPLETION_GRACE: Duration = Duration::from_secs(1);
-
-pub fn run_stream(
-    args: ClientArgs,
-    shutdown_requested: &AtomicBool,
-) -> Result<(), Box<dyn std::error::Error>> {
-    if args.list_columns {
-        print!("{}", OutputConfig::list_columns());
-        return Ok(());
-    }
-    let output_config = OutputConfig::new(
-        args.format,
-        args.columns.as_deref(),
-        args.header,
-        args.verbose,
-        args.target_specs()
-            .map(|targets| targets.len() > 1)
-            .unwrap_or(false),
-    )
-    .map_err(|err| io::Error::new(io::ErrorKind::InvalidInput, err))?;
-
-    let targets = args
-        .resolved_managed_targets()
-        .map_err(|err| io::Error::new(io::ErrorKind::InvalidInput, err))?;
-    let multi_target = targets.len() > 1;
-
-    let continuous = args.is_continuous();
-    #[cfg(feature = "stats")]
-    if let Some(warning) = finite_stats_memory_warning(&args) {
-        eprintln!("{warning}");
-    }
-
-    if multi_target {
-        return run_group_stream(args, targets, output_config, continuous, shutdown_requested);
-    }
-
-    let target_label = targets
-        .first()
-        .map(|target| target.label.as_str())
-        .expect("at least one target was validated");
-    let mut stdout = io::LineWriter::new(io::stdout().lock());
-    #[cfg(feature = "stats")]
-    let mut stats = StatsCollector::new(stats_config(continuous));
-    let mut stream_output = StreamOutput {
-        config: output_config,
-        header_printed: false,
-        print_final_summary: false,
-        show_running_only_summary_note: false,
-        out: &mut stdout,
-    };
-
-    if is_shutdown_requested(shutdown_requested) {
-        return Ok(());
-    }
-
-    let mut session = ClientSession::connect(args.to_client_config(), continuous)?;
-
-    if is_shutdown_requested(shutdown_requested) {
-        return Ok(());
-    }
-
-    let events = session.open()?;
-    #[cfg(feature = "stats")]
-    print_events_with_stats(&mut stream_output, &events, Some(target_label), &mut stats)?;
-    #[cfg(not(feature = "stats"))]
-    print_events_with_stats(&mut stream_output, &events, Some(target_label))?;
-
-    let mut interrupted = false;
-    while session.should_continue(shutdown_requested) {
-        let events = session.step(shutdown_requested)?;
-        #[cfg(feature = "stats")]
-        print_events_with_stats(&mut stream_output, &events, Some(target_label), &mut stats)?;
-        #[cfg(not(feature = "stats"))]
-        print_events_with_stats(&mut stream_output, &events, Some(target_label))?;
-
-        if is_shutdown_requested(shutdown_requested) {
-            interrupted = true;
-            break;
-        }
-
-        session.sleep_until_next_send();
-    }
-    interrupted |= is_shutdown_requested(shutdown_requested);
-
-    if interrupted {
-        eprintln!("interrupted, closing session...");
-    }
-
-    if session.should_drain_final(interrupted) {
-        session.drain_final(|events| {
-            #[cfg(feature = "stats")]
-            let _ =
-                print_events_with_stats(&mut stream_output, events, Some(target_label), &mut stats);
-            #[cfg(not(feature = "stats"))]
-            let _ = print_events_with_stats(&mut stream_output, events, Some(target_label));
-        })?;
-    }
-
-    let events = session.poll_timeouts()?;
-    #[cfg(feature = "stats")]
-    print_events_with_stats(&mut stream_output, &events, Some(target_label), &mut stats)?;
-    #[cfg(not(feature = "stats"))]
-    print_events_with_stats(&mut stream_output, &events, Some(target_label))?;
-
-    let events = session.close()?;
-    #[cfg(feature = "stats")]
-    print_events_with_stats(&mut stream_output, &events, Some(target_label), &mut stats)?;
-    #[cfg(not(feature = "stats"))]
-    print_events_with_stats(&mut stream_output, &events, Some(target_label))?;
-    let print_final_summary = should_print_final_summary(continuous, interrupted);
-    stream_output.print_final_summary = print_final_summary;
-    stream_output.show_running_only_summary_note = continuous && interrupted && print_final_summary;
-    #[cfg(feature = "stats")]
-    stream_output.print_summary(&stats)?;
-    #[cfg(not(feature = "stats"))]
-    stream_output.print_summary()?;
-    stream_output.out.flush()?;
-    Ok(())
-}
-
-struct StreamOutput<'a, W: Write> {
-    config: OutputConfig,
-    header_printed: bool,
-    print_final_summary: bool,
-    show_running_only_summary_note: bool,
-    out: &'a mut W,
-}
-
-impl<W: Write> StreamOutput<'_, W> {
-    fn print_events(
-        &mut self,
-        events: &[ClientEvent],
-        target: Option<&str>,
-        stats_updates: &[EventRenderStats],
-    ) -> io::Result<()> {
-        self.print_header()?;
-        for (event, stats_update) in events.iter().zip(stats_updates) {
-            self.print_event(event, target, stats_update)?;
-        }
-        Ok(())
-    }
-
-    fn print_event(
-        &mut self,
-        event: &ClientEvent,
-        target: Option<&str>,
-        stats_update: &EventRenderStats,
-    ) -> io::Result<()> {
-        if let Some(line) = self.config.render_event(event, target, Some(stats_update)) {
-            writeln!(self.out, "{line}")?;
-        }
-        Ok(())
-    }
-
-    fn print_header(&mut self) -> io::Result<()> {
-        if self.header_printed {
-            return Ok(());
-        }
-        self.header_printed = true;
-        if let Some(header) = self.config.render_header() {
-            writeln!(self.out, "{header}")?;
-        }
-        Ok(())
-    }
-
-    #[cfg(feature = "stats")]
-    fn print_summary(&mut self, stats: &StatsCollector) -> io::Result<()> {
-        if !self.print_final_summary || !self.config.prints_summary() {
-            return Ok(());
-        }
-
-        write!(
-            self.out,
-            "{}",
-            crate::cmd::client::summary::format_summary_with_options(
-                &stats.snapshot(),
-                crate::cmd::client::summary::SummaryFormatOptions {
-                    verbose: self.config.summary_verbose(),
-                    show_running_only_note: self.show_running_only_summary_note,
-                },
-            )
-        )?;
-
-        Ok(())
-    }
-
-    #[cfg(not(feature = "stats"))]
-    fn print_summary(&mut self) -> io::Result<()> {
-        Ok(())
-    }
-}
-
-#[cfg(feature = "stats")]
-fn print_events_with_stats<W: Write>(
-    stream_output: &mut StreamOutput<'_, W>,
-    events: &[ClientEvent],
-    target: Option<&str>,
-    stats: &mut StatsCollector,
-) -> io::Result<()> {
-    let stats_updates = events
-        .iter()
-        .map(|event| EventRenderStats::from(stats.process(event)))
-        .collect::<Vec<_>>();
-    stream_output.print_events(events, target, &stats_updates)
-}
-
-#[cfg(not(feature = "stats"))]
-fn print_events_with_stats<W: Write>(
-    stream_output: &mut StreamOutput<'_, W>,
-    events: &[ClientEvent],
-    target: Option<&str>,
-) -> io::Result<()> {
-    let stats_updates = vec![EventRenderStats::default(); events.len()];
-    stream_output.print_events(events, target, &stats_updates)
-}
-
-fn run_group_stream(
-    args: ClientArgs,
-    targets: Vec<ResolvedCliTarget>,
-    output_config: OutputConfig,
-    continuous: bool,
-    shutdown_requested: &AtomicBool,
-) -> Result<(), Box<dyn std::error::Error>> {
-    let mut config = args.to_client_config();
-    let managed_targets = targets
-        .iter()
-        .map(|target| target.managed.clone())
-        .collect::<Vec<_>>();
-    let expected_target_count = managed_targets.len();
-    if let Some(first) = managed_targets.first() {
-        config.server_addr = first.remote.to_string();
-    }
-
-    let group_config = ManagedClientGroupConfig {
-        client: config,
-        pacing: args.pacing.into(),
-    };
-
-    let (session, events) = ManagedClientGroup::start_with_subscription(
-        group_config,
-        managed_targets,
-        SubscriberConfig {
-            capacity: 16_384,
-            // CLI output is best-effort under sustained backpressure. Dropping
-            // stale rows keeps continuous runs attached to the running group
-            // instead of turning a full output queue into a disconnected
-            // subscriber and a potentially blocking join.
-            overflow: SubscriberOverflow::DropOldest,
-        },
-    )?;
-
-    let mut stdout = io::LineWriter::new(io::stdout().lock());
-    #[cfg(feature = "stats")]
-    let mut stats = targets
-        .iter()
-        .map(|target| {
-            (
-                target.label.clone(),
-                StatsCollector::new(stats_config(continuous)),
-            )
-        })
-        .collect::<BTreeMap<_, _>>();
-    let mut stream_output = StreamOutput {
-        config: output_config,
-        header_printed: false,
-        print_final_summary: false,
-        show_running_only_summary_note: false,
-        out: &mut stdout,
-    };
-
-    let mut interrupted = false;
-    let mut terminal_targets = HashSet::new();
-    let mut last_event_at = Instant::now();
-    let mut saw_target_event = false;
-
-    loop {
-        if is_shutdown_requested(shutdown_requested) {
-            interrupted = true;
-            session.stop();
-        }
-
-        match events.try_recv() {
-            Ok(Some(target_event)) => {
-                last_event_at = Instant::now();
-                saw_target_event = true;
-                let label = target_event.target.as_str();
-                if is_terminal_target_event(&target_event.event) {
-                    terminal_targets.insert(label.to_owned());
-                }
-                #[cfg(feature = "stats")]
-                {
-                    let stats = stats
-                        .entry(label.to_owned())
-                        .or_insert_with(|| StatsCollector::new(stats_config(continuous)));
-                    print_target_event_with_stats(&mut stream_output, &target_event, stats)?;
-                }
-                #[cfg(not(feature = "stats"))]
-                {
-                    print_target_event_with_stats(&mut stream_output, &target_event)?;
-                }
-            }
-            Ok(None) => {
-                if interrupted {
-                    break;
-                }
-                if terminal_targets.len() >= expected_target_count {
-                    break;
-                }
-                if should_join_group_after_idle(&args, continuous, saw_target_event, last_event_at)
-                {
-                    break;
-                }
-                thread::sleep(GROUP_IDLE_SLEEP);
-            }
-            Err(EventSubscriptionError::Disconnected) => break,
-        }
-    }
-
-    if interrupted {
-        eprintln!("interrupted, closing group...");
-    }
-
-    let outcome = session.join()?;
-    while let Ok(Some(target_event)) = events.try_recv() {
-        let label = target_event.target.as_str();
-        #[cfg(feature = "stats")]
-        {
-            let stats = stats
-                .entry(label.to_owned())
-                .or_insert_with(|| StatsCollector::new(stats_config(continuous)));
-            print_target_event_with_stats(&mut stream_output, &target_event, stats)?;
-        }
-        #[cfg(not(feature = "stats"))]
-        {
-            print_target_event_with_stats(&mut stream_output, &target_event)?;
-        }
-    }
-
-    if outcome.end_reason == ManagedGroupEndReason::Cancelled && !interrupted {
-        return Err("managed client group was cancelled".into());
-    }
-
-    let print_final_summary = should_print_final_summary(continuous, interrupted);
-    stream_output.print_final_summary = print_final_summary;
-    stream_output.show_running_only_summary_note = continuous && interrupted && print_final_summary;
-    #[cfg(feature = "stats")]
-    {
-        for (label, stats) in &stats {
-            if stream_output.print_final_summary && stream_output.config.prints_summary() {
-                writeln!(stream_output.out)?;
-                writeln!(stream_output.out, "target: {label}")?;
-            }
-            stream_output.print_summary(stats)?;
-        }
-    }
-    #[cfg(not(feature = "stats"))]
-    {
-        stream_output.print_summary()?;
-    }
-    stream_output.out.flush()?;
-    Ok(())
-}
-
-fn is_terminal_target_event(event: &ClientEvent) -> bool {
-    matches!(
-        event,
-        ClientEvent::SessionClosed { .. } | ClientEvent::NoTestCompleted { .. }
-    )
-}
-
-fn estimated_group_completion_grace(args: &ClientArgs) -> Duration {
-    let open_timeout: Duration = args.to_client_config().open_timeouts.iter().sum();
-    open_timeout
-        .saturating_add(args.duration)
-        .saturating_add(GROUP_COMPLETION_GRACE)
-}
-
-fn should_join_group_after_idle(
-    args: &ClientArgs,
-    continuous: bool,
-    saw_target_event: bool,
-    last_event_at: Instant,
-) -> bool {
-    if continuous && saw_target_event {
-        return false;
-    }
-    last_event_at.elapsed() > estimated_group_completion_grace(args)
-}
-
-#[cfg(feature = "stats")]
-fn print_target_event_with_stats<W: Write>(
-    stream_output: &mut StreamOutput<'_, W>,
-    target_event: &TargetEvent,
-    stats: &mut StatsCollector,
-) -> io::Result<()> {
-    print_events_with_stats(
-        stream_output,
-        std::slice::from_ref(&target_event.event),
-        Some(target_event.target.as_str()),
-        stats,
-    )
-}
-
-#[cfg(not(feature = "stats"))]
-fn print_target_event_with_stats<W: Write>(
-    stream_output: &mut StreamOutput<'_, W>,
-    target_event: &TargetEvent,
-) -> io::Result<()> {
-    print_events_with_stats(
-        stream_output,
-        std::slice::from_ref(&target_event.event),
-        Some(target_event.target.as_str()),
-    )
-}
-
-#[cfg(feature = "stats")]
-fn stats_config(continuous: bool) -> StatsConfig {
-    if continuous {
-        StatsConfig::continuous()
-    } else {
-        StatsConfig::finite()
-    }
-}
-
-#[cfg(feature = "stats")]
-fn estimate_finite_stats_memory_bytes(expected_probes: u64) -> u64 {
-    expected_probes.saturating_mul(FINITE_STATS_BYTES_PER_PROBE)
-}
-
-#[cfg(feature = "stats")]
-fn finite_stats_memory_warning(args: &ClientArgs) -> Option<String> {
-    if args.is_continuous() || args.duration.is_zero() {
-        return None;
-    }
-
-    let expected_probes = expected_probe_count(args.duration, args.interval);
-    let estimated_bytes = estimate_finite_stats_memory_bytes(expected_probes);
-    if estimated_bytes < FINITE_STATS_MEMORY_WARNING_BYTES {
-        return None;
-    }
-
-    let formatted = format_bytes_for_warning(estimated_bytes);
-    let guidance = if estimated_bytes >= FINITE_STATS_MEMORY_VERY_STRONG_WARNING_BYTES {
-        "this may be unsuitable on memory-constrained systems"
-    } else if estimated_bytes >= FINITE_STATS_MEMORY_STRONG_WARNING_BYTES {
-        "consider shortening the run, increasing the interval, or using continuous mode"
-    } else {
-        "use continuous mode for bounded-memory long-running tests"
-    };
-
-    Some(format!(
-        "irtt-rs: warning: finite exact statistics may retain about {formatted} for this run; {guidance}"
-    ))
-}
-
-#[cfg(feature = "stats")]
-fn format_bytes_for_warning(bytes: u64) -> String {
-    if bytes >= GIB {
-        format!("{} GiB", bytes.saturating_add(GIB / 2) / GIB)
-    } else {
-        format!("{} MiB", bytes.saturating_add(MIB / 2) / MIB)
-    }
-}
-
-#[cfg(all(test, feature = "stats"))]
-mod tests {
-    use super::*;
-    use std::{
-        net::{IpAddr, Ipv4Addr, SocketAddr},
-        time::{Duration, Instant, UNIX_EPOCH},
-    };
-
-    fn test_timestamp(offset: Duration) -> ClientTimestamp {
-        ClientTimestamp {
-            wall: UNIX_EPOCH + offset,
-            mono: Instant::now() + offset,
-        }
-    }
-
-    fn test_remote() -> SocketAddr {
-        SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 2112)
-    }
-
-    fn reply_event(seq: u32, rtt_us: u64) -> ClientEvent {
-        let sent_at = test_timestamp(Duration::from_millis(seq as u64));
-        let received_at = ClientTimestamp {
-            wall: sent_at.wall + Duration::from_micros(rtt_us),
-            mono: sent_at.mono + Duration::from_micros(rtt_us),
-        };
-        ClientEvent::EchoReply {
-            seq,
-            remote: test_remote(),
-            sent_at,
-            received_at,
-            rtt: RttSample {
-                raw: Duration::from_micros(rtt_us),
-                adjusted: None,
-                effective: SignedDuration::from_nanos(i128::from(rtt_us) * 1_000),
-            },
-            server_timing: None,
-            one_way: None,
-            received_stats: None,
-            bytes: 64,
-            packet_meta: PacketMeta::default(),
-        }
-    }
-
-    fn cli_args(args: &[&str]) -> ClientArgs {
-        let mut argv = vec!["irtt-rs"];
-        argv.extend_from_slice(args);
-        <ClientArgs as clap::Parser>::try_parse_from(argv).unwrap()
-    }
-
-    fn output_config(
-        format: crate::cmd::client::OutputFormat,
-        columns: Option<&str>,
-        header: crate::cmd::client::HeaderMode,
-        verbose: bool,
-    ) -> OutputConfig {
-        OutputConfig::new(format, columns, header, verbose, false).unwrap()
-    }
-
-    #[test]
-    fn output_helper_streams_and_collects_events() {
-        let sent_at = test_timestamp(Duration::from_secs(1));
-        let received_at = test_timestamp(Duration::from_secs(1) + Duration::from_micros(1200));
-        let events = [
-            ClientEvent::EchoSent {
-                seq: 1,
-                remote: test_remote(),
-                scheduled_at: sent_at.mono,
-                sent_at,
-                bytes: 64,
-                send_call: Duration::from_micros(10),
-                timer_error: Duration::ZERO,
-            },
-            ClientEvent::EchoReply {
-                seq: 1,
-                remote: test_remote(),
-                sent_at,
-                received_at,
-                rtt: RttSample {
-                    raw: Duration::from_micros(1200),
-                    adjusted: None,
-                    effective: SignedDuration::from_nanos(1_200_000),
-                },
-                server_timing: None,
-                one_way: None,
-                received_stats: None,
-                bytes: 64,
-                packet_meta: PacketMeta::default(),
-            },
-        ];
-
-        let mut stats = StatsCollector::new(StatsConfig::finite());
-        let mut out = Vec::new();
-        {
-            let mut stream_output = StreamOutput {
-                config: output_config(
-                    crate::cmd::client::OutputFormat::Tsv,
-                    Some("effective_rtt_us"),
-                    crate::cmd::client::HeaderMode::Never,
-                    false,
-                ),
-                header_printed: false,
-                print_final_summary: true,
-                show_running_only_summary_note: false,
-                out: &mut out,
-            };
-            print_events_with_stats(&mut stream_output, &events, None, &mut stats).unwrap();
-            stream_output.print_summary(&stats).unwrap();
-        }
-
-        let rendered = String::from_utf8(out).unwrap();
-        let summary = stats.snapshot();
-        assert!(!rendered.is_empty());
-        assert_eq!(summary.packets.packets_sent, 1);
-        assert_eq!(summary.packets.unique_replies, 1);
-    }
-
-    #[test]
-    fn continuous_summary_prints_when_enabled_and_suppresses_when_disabled() {
-        let mut stats = StatsCollector::new(StatsConfig::continuous());
-        let mut out = Vec::new();
-        {
-            let mut stream_output = StreamOutput {
-                config: output_config(
-                    crate::cmd::client::OutputFormat::Table,
-                    None,
-                    crate::cmd::client::HeaderMode::Auto,
-                    false,
-                ),
-                header_printed: false,
-                print_final_summary: true,
-                show_running_only_summary_note: true,
-                out: &mut out,
-            };
-            print_events_with_stats(
-                &mut stream_output,
-                &[reply_event(1, 1200)],
-                None,
-                &mut stats,
-            )
-            .unwrap();
-            stream_output.print_summary(&stats).unwrap();
-        }
-
-        let rendered = String::from_utf8(out).unwrap();
-        assert!(rendered.contains("irtt-rs summary"));
-        assert!(rendered.contains("medians unavailable"));
-        assert!(rendered.contains("continuous mode"));
-        assert!(rendered.contains("packets:"));
-        assert!(rendered.contains("received=1"));
-
-        let stats = StatsCollector::new(StatsConfig::continuous());
-        let mut out = Vec::new();
-        {
-            let mut stream_output = StreamOutput {
-                config: output_config(
-                    crate::cmd::client::OutputFormat::Table,
-                    None,
-                    crate::cmd::client::HeaderMode::Auto,
-                    false,
-                ),
-                header_printed: false,
-                print_final_summary: false,
-                show_running_only_summary_note: true,
-                out: &mut out,
-            };
-            stream_output.print_summary(&stats).unwrap();
-        }
-
-        assert!(out.is_empty());
-    }
-
-    #[test]
-    fn continuous_mode_uses_continuous_stats_config() {
-        let mut collector = StatsCollector::new(stats_config(true));
-        for seq in 0..5000_u32 {
-            let sent_at = test_timestamp(Duration::from_micros(seq as u64));
-            let received_at = test_timestamp(Duration::from_micros(seq as u64 + 1));
-            collector.process(&ClientEvent::EchoReply {
-                seq,
-                remote: test_remote(),
-                sent_at,
-                received_at,
-                rtt: RttSample {
-                    raw: Duration::from_micros(1),
-                    adjusted: None,
-                    effective: SignedDuration::from_nanos(1_000),
-                },
-                server_timing: None,
-                one_way: None,
-                received_stats: None,
-                bytes: 64,
-                packet_meta: PacketMeta::default(),
-            });
-        }
-
-        assert_eq!(collector.snapshot().rtt.primary.median_ns, None);
-    }
-
-    #[test]
-    fn finite_stats_memory_warning_reports_only_large_finite_runs() {
-        for args in [
-            cli_args(&["--duration", "0", "--interval", "1ms", "127.0.0.1:2112"]),
-            cli_args(&[
-                "--duration",
-                "1000ms",
-                "--interval",
-                "1ms",
-                "127.0.0.1:2112",
-            ]),
-        ] {
-            assert_eq!(finite_stats_memory_warning(&args), None);
-        }
-
-        for (threshold, size, guidance) in [
-            (
-                FINITE_STATS_MEMORY_WARNING_BYTES,
-                "about 128 MiB",
-                "bounded-memory long-running tests",
-            ),
-            (
-                FINITE_STATS_MEMORY_STRONG_WARNING_BYTES,
-                "about 512 MiB",
-                "shortening the run",
-            ),
-            (
-                FINITE_STATS_MEMORY_VERY_STRONG_WARNING_BYTES,
-                "about 1 GiB",
-                "memory-constrained systems",
-            ),
-        ] {
-            let expected_probes = threshold.div_ceil(FINITE_STATS_BYTES_PER_PROBE);
-            let args = cli_args(&[
-                "--duration",
-                &format!("{expected_probes}ms"),
-                "--interval",
-                "1ms",
-                "127.0.0.1:2112",
-            ]);
-
-            let warning = finite_stats_memory_warning(&args).unwrap();
-            assert!(warning.contains(size));
-            assert!(warning.contains(guidance));
-        }
-    }
-
-    #[test]
-    fn expected_probe_count_rounds_up() {
-        assert_eq!(
-            expected_probe_count(Duration::from_millis(1001), Duration::from_secs(1)),
-            2
-        );
-    }
-
-    #[test]
-    fn estimate_finite_stats_memory_bytes_saturates() {
-        assert_eq!(estimate_finite_stats_memory_bytes(u64::MAX), u64::MAX);
-    }
-}

crates/irtt-cli/src/cmd/tui/run.rs

@@ -1,468 +0,0 @@
-use std::{
-    io,
-    sync::atomic::{AtomicBool, Ordering},
-    thread,
-    time::{Duration, Instant},
-};
-
-use crossterm::event::{self, Event, KeyCode, KeyEventKind, KeyModifiers};
-use irtt_client::{
-    ClientEvent, EventSubscriptionError, ManagedClientGroup, ManagedClientGroupConfig,
-    ManagedGroupEndReason, SubscriberConfig, SubscriberOverflow,
-};
-
-use crate::{
-    cmd::tui::args::{ResolvedTuiTarget, TuiArgs},
-    shared::client::{is_shutdown_requested, ClientSession},
-};
-
-use super::ui::{should_render, TuiConfig, TuiState, TuiStatus, TuiTerminal};
-
-const RENDER_INTERVAL: Duration = Duration::from_millis(250);
-const TUI_WAIT_SLICE: Duration = Duration::from_millis(20);
-const IDLE_SLEEP: Duration = Duration::from_millis(5);
-const GROUP_COMPLETION_GRACE: Duration = Duration::from_secs(1);
-
-pub fn run_tui(
-    args: TuiArgs,
-    shutdown_requested: &AtomicBool,
-) -> Result<(), Box<dyn std::error::Error>> {
-    let targets = args
-        .resolved_managed_targets()
-        .map_err(|err| io::Error::new(io::ErrorKind::InvalidInput, err))?;
-    let continuous = args.is_continuous();
-    let mut terminal = TuiTerminal::enter()?;
-    let mut state = TuiState::with_target_labels(
-        TuiConfig::from_args(&args),
-        targets.iter().map(|target| target.label.clone()),
-    );
-    let mut next_render = Instant::now();
-
-    if is_shutdown_requested(shutdown_requested) {
-        return Ok(());
-    }
-
-    state.set_status(TuiStatus::Opening);
-    render_if_due(&mut terminal, &state, &mut next_render, true)?;
-
-    if targets.len() > 1 {
-        return run_group_tui(
-            args,
-            targets,
-            &mut terminal,
-            &mut state,
-            &mut next_render,
-            shutdown_requested,
-        );
-    }
-
-    let mut session = match ClientSession::connect(args.to_client_config(), continuous) {
-        Ok(session) => session,
-        Err(err) => {
-            state.set_error(err.to_string());
-            render_if_due(&mut terminal, &state, &mut next_render, true)?;
-            return Err(Box::new(err));
-        }
-    };
-
-    if is_shutdown_requested(shutdown_requested) {
-        return Ok(());
-    }
-
-    let events = session.open()?;
-    state.process_events(&events);
-    render_if_due(&mut terminal, &state, &mut next_render, true)?;
-
-    let mut interrupted = false;
-    // Keep this in lockstep with run_stream: send due probes, drain available
-    // replies, poll timeouts, sleep toward the next absolute send deadline,
-    // then perform the same final drain, timeout poll, and close sequence.
-    while session.should_continue(shutdown_requested) {
-        if handle_input(&mut state, shutdown_requested)? {
-            render_if_due(&mut terminal, &state, &mut next_render, true)?;
-        }
-        if state.quit_requested {
-            interrupted = true;
-            break;
-        }
-
-        let events = session.step(shutdown_requested)?;
-        state.process_events(&events);
-
-        if is_shutdown_requested(shutdown_requested) {
-            interrupted = true;
-            break;
-        }
-
-        render_if_due(&mut terminal, &state, &mut next_render, false)?;
-        wait_for_tui_activity(
-            session.next_send_deadline(),
-            &mut next_render,
-            &mut state,
-            &mut terminal,
-            shutdown_requested,
-        )?;
-    }
-    interrupted |= is_shutdown_requested(shutdown_requested);
-
-    if interrupted {
-        state.set_status(TuiStatus::Interrupted);
-        render_if_due(&mut terminal, &state, &mut next_render, true)?;
-    }
-
-    if session.should_drain_final(interrupted) {
-        state.set_status(TuiStatus::Draining);
-        let mut drain_render = Instant::now();
-        session.drain_final(|events| {
-            state.process_events(events);
-            let _ = render_if_due(&mut terminal, &state, &mut drain_render, false);
-        })?;
-        render_if_due(&mut terminal, &state, &mut next_render, true)?;
-    }
-
-    let events = session.poll_timeouts()?;
-    state.process_events(&events);
-
-    state.set_status(TuiStatus::Closing);
-    render_if_due(&mut terminal, &state, &mut next_render, true)?;
-
-    let events = session.close()?;
-    state.process_events(&events);
-    state.set_status(TuiStatus::Complete);
-    render_if_due(&mut terminal, &state, &mut next_render, true)?;
-    Ok(())
-}
-
-fn run_group_tui(
-    args: TuiArgs,
-    targets: Vec<ResolvedTuiTarget>,
-    terminal: &mut TuiTerminal,
-    state: &mut TuiState,
-    next_render: &mut Instant,
-    shutdown_requested: &AtomicBool,
-) -> Result<(), Box<dyn std::error::Error>> {
-    let mut config = args.to_client_config();
-    let managed_targets = targets
-        .iter()
-        .map(|target| target.managed.clone())
-        .collect::<Vec<_>>();
-    let expected_target_count = managed_targets.len();
-    if let Some(first) = managed_targets.first() {
-        config.server_addr = first.remote.to_string();
-    }
-
-    let group_config = ManagedClientGroupConfig {
-        client: config,
-        pacing: args.pacing.into(),
-    };
-    let (session, events) = ManagedClientGroup::start_with_subscription(
-        group_config,
-        managed_targets,
-        SubscriberConfig {
-            capacity: 16_384,
-            overflow: SubscriberOverflow::DropOldest,
-        },
-    )?;
-
-    let mut interrupted = false;
-    let mut terminal_targets = std::collections::HashSet::new();
-    let mut saw_target_event = false;
-    let mut last_event_at = Instant::now();
-
-    let exit = loop {
-        if is_shutdown_requested(shutdown_requested) {
-            interrupted = true;
-            session.stop();
-        }
-
-        if handle_input(state, shutdown_requested)? {
-            render_if_due(terminal, state, next_render, true)?;
-        }
-        if state.quit_requested {
-            interrupted = true;
-            session.stop();
-        }
-
-        match events.try_recv() {
-            Ok(Some(target_event)) => {
-                saw_target_event = true;
-                last_event_at = Instant::now();
-                if is_terminal_target_event(&target_event.event) {
-                    terminal_targets.insert(target_event.target.as_str().to_owned());
-                }
-                state.process_target_event(&target_event);
-                render_if_due(terminal, state, next_render, false)?;
-            }
-            Ok(None) => {
-                if interrupted {
-                    break GroupLoopExit::Interrupted;
-                }
-                if terminal_targets.len() >= expected_target_count {
-                    break GroupLoopExit::AllTargetsTerminal;
-                }
-                if should_join_group_after_idle(&args, saw_target_event, last_event_at) {
-                    break GroupLoopExit::IdleGraceElapsed;
-                }
-                wait_for_tui_activity(None, next_render, state, terminal, shutdown_requested)?;
-                thread::sleep(IDLE_SLEEP);
-            }
-            Err(EventSubscriptionError::Disconnected) => {
-                break GroupLoopExit::SubscriptionDisconnected
-            }
-        }
-    };
-
-    if exit.should_stop_before_join() {
-        session.stop();
-    }
-
-    if interrupted {
-        state.set_status(TuiStatus::Interrupted);
-        render_if_due(terminal, state, next_render, true)?;
-    }
-
-    state.set_status(TuiStatus::Closing);
-    render_if_due(terminal, state, next_render, true)?;
-
-    let outcome = session.join()?;
-    while let Ok(Some(target_event)) = events.try_recv() {
-        state.process_target_event(&target_event);
-    }
-
-    if outcome.end_reason == ManagedGroupEndReason::Cancelled && !interrupted {
-        return match exit {
-            GroupLoopExit::IdleGraceElapsed => {
-                Err("managed client group stayed idle before all targets completed".into())
-            }
-            GroupLoopExit::SubscriptionDisconnected => {
-                Err("managed client group event subscription disconnected before completion".into())
-            }
-            GroupLoopExit::Interrupted | GroupLoopExit::AllTargetsTerminal => {
-                Err("managed client group was cancelled".into())
-            }
-        };
-    }
-
-    state.set_status(TuiStatus::Complete);
-    render_if_due(terminal, state, next_render, true)?;
-    Ok(())
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-enum GroupLoopExit {
-    Interrupted,
-    AllTargetsTerminal,
-    IdleGraceElapsed,
-    SubscriptionDisconnected,
-}
-
-impl GroupLoopExit {
-    fn should_stop_before_join(self) -> bool {
-        matches!(
-            self,
-            Self::Interrupted | Self::IdleGraceElapsed | Self::SubscriptionDisconnected
-        )
-    }
-}
-
-fn is_terminal_target_event(event: &ClientEvent) -> bool {
-    matches!(
-        event,
-        ClientEvent::SessionClosed { .. } | ClientEvent::NoTestCompleted { .. }
-    )
-}
-
-fn estimated_group_completion_grace(args: &TuiArgs) -> Duration {
-    let open_timeout: Duration = args.to_client_config().open_timeouts.iter().sum();
-    open_timeout
-        .saturating_add(args.duration)
-        .saturating_add(GROUP_COMPLETION_GRACE)
-}
-
-fn should_join_group_after_idle(
-    args: &TuiArgs,
-    saw_target_event: bool,
-    last_event_at: Instant,
-) -> bool {
-    if args.is_continuous() && saw_target_event {
-        return false;
-    }
-    last_event_at.elapsed() > estimated_group_completion_grace(args)
-}
-
-fn handle_input(state: &mut TuiState, shutdown_requested: &AtomicBool) -> io::Result<bool> {
-    let mut force_render = false;
-    while event::poll(Duration::ZERO)? {
-        let Event::Key(key) = event::read()? else {
-            continue;
-        };
-        if key.kind == KeyEventKind::Release {
-            continue;
-        }
-        match key.code {
-            KeyCode::Char('q') => {
-                state.quit_requested = true;
-                shutdown_requested.store(true, Ordering::Relaxed);
-                force_render = true;
-            }
-            KeyCode::Char('c') if key.modifiers.contains(KeyModifiers::CONTROL) => {
-                state.quit_requested = true;
-                shutdown_requested.store(true, Ordering::Relaxed);
-                force_render = true;
-            }
-            KeyCode::Char('r') => {
-                state.clear_visible_history();
-                force_render = true;
-            }
-            KeyCode::Char('p') => {
-                state.toggle_pause();
-                force_render = true;
-            }
-            KeyCode::Char('g') => {
-                state.toggle_view();
-                force_render = true;
-            }
-            KeyCode::Char('m') => {
-                state.cycle_graph_metric();
-                force_render = true;
-            }
-            KeyCode::Left => {
-                state.pan_graph_left();
-                force_render = true;
-            }
-            KeyCode::Right => {
-                state.pan_graph_right();
-                force_render = true;
-            }
-            KeyCode::PageUp => {
-                state.pan_graph_page_left();
-                force_render = true;
-            }
-            KeyCode::PageDown => {
-                state.pan_graph_page_right();
-                force_render = true;
-            }
-            KeyCode::Home => {
-                state.jump_graph_oldest();
-                force_render = true;
-            }
-            KeyCode::End => {
-                state.jump_graph_live();
-                force_render = true;
-            }
-            KeyCode::Char('+') | KeyCode::Char('=') => {
-                state.zoom_graph_in();
-                force_render = true;
-            }
-            KeyCode::Char('-') => {
-                state.zoom_graph_out();
-                force_render = true;
-            }
-            KeyCode::Char('0') => {
-                state.reset_graph_window();
-                force_render = true;
-            }
-            _ => {}
-        }
-    }
-    Ok(force_render)
-}
-
-fn render_if_due(
-    terminal: &mut TuiTerminal,
-    state: &TuiState,
-    next_render: &mut Instant,
-    force: bool,
-) -> io::Result<()> {
-    let now = Instant::now();
-    if !should_render(now, *next_render, state.paused, force) {
-        return Ok(());
-    }
-    terminal.draw(state)?;
-    *next_render = now + RENDER_INTERVAL;
-    Ok(())
-}
-
-fn wait_for_tui_activity(
-    next_send_deadline: Option<Instant>,
-    next_render: &mut Instant,
-    state: &mut TuiState,
-    terminal: &mut TuiTerminal,
-    shutdown_requested: &AtomicBool,
-) -> io::Result<()> {
-    let wait_for = tui_wait_duration(next_send_deadline, *next_render, state.paused);
-    if wait_for.is_zero() || !event::poll(wait_for)? {
-        return Ok(());
-    }
-
-    if handle_input(state, shutdown_requested)? {
-        render_if_due(terminal, state, next_render, true)?;
-    }
-    Ok(())
-}
-
-fn tui_wait_duration(
-    next_send_deadline: Option<Instant>,
-    next_render: Instant,
-    paused: bool,
-) -> Duration {
-    let now = Instant::now();
-    let send_wait = next_send_deadline
-        .map(|deadline| deadline.saturating_duration_since(now))
-        .unwrap_or(IDLE_SLEEP);
-    let render_wait = if paused {
-        send_wait
-    } else {
-        next_render.saturating_duration_since(now)
-    };
-    send_wait.min(render_wait).min(TUI_WAIT_SLICE)
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use clap::Parser;
-
-    fn parse(args: &[&str]) -> TuiArgs {
-        let mut argv = vec!["irtt-tui"];
-        argv.extend_from_slice(args);
-        TuiArgs::try_parse_from(argv).unwrap()
-    }
-
-    #[test]
-    fn continuous_multi_target_idle_does_not_stop_after_events() {
-        let args = parse(&["127.0.0.1:2112", "127.0.0.2:2112"]);
-        let old_event_at = Instant::now() - estimated_group_completion_grace(&args) - IDLE_SLEEP;
-
-        assert!(!should_join_group_after_idle(&args, true, old_event_at));
-    }
-
-    #[test]
-    fn finite_or_unopened_group_can_leave_after_idle_grace() {
-        let finite = parse(&["--duration", "1s", "127.0.0.1:2112", "127.0.0.2:2112"]);
-        let finite_old_event_at =
-            Instant::now() - estimated_group_completion_grace(&finite) - IDLE_SLEEP;
-        assert!(should_join_group_after_idle(
-            &finite,
-            true,
-            finite_old_event_at
-        ));
-
-        let continuous = parse(&["127.0.0.1:2112", "127.0.0.2:2112"]);
-        let unopened_old_event_at =
-            Instant::now() - estimated_group_completion_grace(&continuous) - IDLE_SLEEP;
-        assert!(should_join_group_after_idle(
-            &continuous,
-            false,
-            unopened_old_event_at
-        ));
-    }
-
-    #[test]
-    fn protective_group_exits_stop_before_joining() {
-        assert!(GroupLoopExit::Interrupted.should_stop_before_join());
-        assert!(GroupLoopExit::IdleGraceElapsed.should_stop_before_join());
-        assert!(GroupLoopExit::SubscriptionDisconnected.should_stop_before_join());
-        assert!(!GroupLoopExit::AllTargetsTerminal.should_stop_before_join());
-    }
-}

crates/irtt-cli/src/entry.rs

@@ -1,80 +0,0 @@
-use std::{
-    env,
-    ffi::OsString,
-    process::ExitCode,
-    sync::{atomic::AtomicBool, Arc},
-};
-
-use crate::{
-    applet::{dispatch_from_argv, AppletDispatch, RequestedApplet},
-    signal::install_signal_handler,
-};
-
-pub fn main() -> ExitCode {
-    match run_from_env() {
-        Ok(()) => ExitCode::SUCCESS,
-        Err(err) => {
-            eprintln!("irtt-rs: {err}");
-            ExitCode::FAILURE
-        }
-    }
-}
-
-fn run_from_env() -> Result<(), Box<dyn std::error::Error>> {
-    let argv: Vec<OsString> = env::args_os().collect();
-    let (requested, argv) = match dispatch_from_argv(argv)? {
-        AppletDispatch::Run { applet, argv } => (applet, argv),
-        AppletDispatch::Help(help) => {
-            print!("{help}");
-            return Ok(());
-        }
-    };
-
-    let shutdown_requested = Arc::new(AtomicBool::new(false));
-    install_signal_handler(Arc::clone(&shutdown_requested))
-        .map_err(|err| format!("failed to install signal handler: {err}"))?;
-
-    match requested {
-        RequestedApplet::Client => run_client_applet(argv, shutdown_requested.as_ref()),
-        RequestedApplet::Tui => run_tui_applet(argv, shutdown_requested.as_ref()),
-        RequestedApplet::Server => Err("server applet is not available in this build".into()),
-    }
-}
-
-#[cfg(feature = "client")]
-fn run_client_applet(
-    argv: Vec<OsString>,
-    shutdown_requested: &AtomicBool,
-) -> Result<(), Box<dyn std::error::Error>> {
-    use clap::Parser;
-
-    let args = crate::cmd::client::ClientArgs::parse_from(argv);
-    crate::cmd::client::run_stream(args, shutdown_requested)
-}
-
-#[cfg(not(feature = "client"))]
-fn run_client_applet(
-    _argv: Vec<OsString>,
-    _shutdown_requested: &AtomicBool,
-) -> Result<(), Box<dyn std::error::Error>> {
-    Err("client applet is not available; rebuild with the client feature".into())
-}
-
-#[cfg(feature = "tui")]
-fn run_tui_applet(
-    argv: Vec<OsString>,
-    shutdown_requested: &AtomicBool,
-) -> Result<(), Box<dyn std::error::Error>> {
-    use clap::Parser;
-
-    let args = crate::cmd::tui::TuiArgs::parse_from(argv);
-    crate::cmd::tui::run_tui(args, shutdown_requested)
-}
-
-#[cfg(not(feature = "tui"))]
-fn run_tui_applet(
-    _argv: Vec<OsString>,
-    _shutdown_requested: &AtomicBool,
-) -> Result<(), Box<dyn std::error::Error>> {
-    Err("TUI applet is not available; rebuild with the tui feature".into())
-}

crates/irtt-cli/src/shared/client/mod.rs

@@ -1,15 +0,0 @@
-pub mod args;
-pub mod config;
-pub mod session;
-pub mod targets;
-
-pub use args::{
-    parse_dscp, parse_duration, parse_length, parse_server_fill, parse_test_duration, parse_ttl,
-    ClockArg, CommonClientArgs, ReceivedStatsArg, TimestampArg,
-};
-pub use config::{expected_probe_count, DEFAULT_RECV_TIMEOUT};
-pub use session::{final_drain_duration, is_shutdown_requested, ClientSession, RECV_BUDGET};
-pub use targets::{
-    parse_labelled_target, resolved_managed_targets, target_specs, GroupPacingArg,
-    LabelledTargetArg, ResolvedTarget, TargetSpec,
-};

crates/irtt-cli/src/shared/client/session.rs

@@ -1,370 +0,0 @@
-use std::{
-    sync::atomic::{AtomicBool, Ordering},
-    thread,
-    time::{Duration, Instant},
-};
-
-use irtt_client::{Client, ClientConfig, ClientEvent, OpenOutcome, RecvBudget};
-
-pub const RECV_BUDGET: RecvBudget = RecvBudget { max_packets: 16 };
-const MAX_FINAL_DRAIN: Duration = Duration::from_secs(30);
-const IDLE_SLEEP: Duration = Duration::from_millis(5);
-const MAX_SLEEP: Duration = Duration::from_millis(20);
-
-pub struct ClientSession {
-    client: Client,
-    continuous: bool,
-}
-
-impl ClientSession {
-    pub fn connect(
-        config: ClientConfig,
-        continuous: bool,
-    ) -> Result<Self, irtt_client::ClientError> {
-        Ok(Self {
-            client: Client::connect(config)?,
-            continuous,
-        })
-    }
-
-    pub fn open(&mut self) -> Result<Vec<ClientEvent>, irtt_client::ClientError> {
-        Ok(vec![open_event(&self.client.open()?).clone()])
-    }
-
-    pub fn step(
-        &mut self,
-        shutdown_requested: &AtomicBool,
-    ) -> Result<Vec<ClientEvent>, irtt_client::ClientError> {
-        let mut events = Vec::new();
-        if should_send_probe(self.client.next_send_deadline(), shutdown_requested) {
-            events.extend(self.client.send_probe()?);
-        }
-        events.extend(self.client.recv_available(RECV_BUDGET)?);
-        if self.client.is_peer_closed() {
-            return Ok(events);
-        }
-        events.extend(self.client.poll_timeouts()?);
-        Ok(events)
-    }
-
-    pub fn should_continue(&self, shutdown_requested: &AtomicBool) -> bool {
-        !is_shutdown_requested(shutdown_requested)
-            && !self.client.is_peer_closed()
-            && (self.continuous || self.client.next_send_deadline().is_some())
-    }
-
-    pub fn should_drain_final(&self, interrupted: bool) -> bool {
-        should_drain_final(self.continuous, interrupted)
-    }
-
-    pub fn drain_final<F>(&mut self, mut on_events: F) -> Result<(), irtt_client::ClientError>
-    where
-        F: FnMut(&[ClientEvent]),
-    {
-        let deadline = Instant::now() + final_drain_duration(self.client.probe_timeout());
-        loop {
-            if self.client.is_peer_closed() {
-                break;
-            }
-
-            let mut received = false;
-
-            let events = self.client.recv_available(RECV_BUDGET)?;
-            received |= !events.is_empty();
-            on_events(&events);
-
-            if self.client.is_peer_closed() {
-                break;
-            }
-
-            let events = self.client.poll_timeouts()?;
-            received |= !events.is_empty();
-            on_events(&events);
-
-            if self.client.is_run_complete() || Instant::now() >= deadline {
-                break;
-            }
-
-            if !received {
-                thread::sleep(IDLE_SLEEP);
-            }
-        }
-        Ok(())
-    }
-
-    pub fn poll_timeouts(&mut self) -> Result<Vec<ClientEvent>, irtt_client::ClientError> {
-        if self.client.is_peer_closed() {
-            return Ok(vec![]);
-        }
-        self.client.poll_timeouts()
-    }
-
-    pub fn close(&mut self) -> Result<Vec<ClientEvent>, irtt_client::ClientError> {
-        if self.client.is_peer_closed() {
-            return Ok(vec![]);
-        }
-        self.client.close()
-    }
-
-    pub fn next_send_deadline(&self) -> Option<Instant> {
-        self.client.next_send_deadline()
-    }
-
-    pub fn probe_timeout(&self) -> Duration {
-        self.client.probe_timeout()
-    }
-
-    pub fn sleep_until_next_send(&self) {
-        let sleep_for = match self.next_send_deadline() {
-            Some(deadline) => deadline
-                .saturating_duration_since(Instant::now())
-                .min(MAX_SLEEP),
-            None => Duration::from_millis(1),
-        };
-        if !sleep_for.is_zero() {
-            thread::sleep(sleep_for);
-        }
-    }
-}
-
-pub fn is_shutdown_requested(shutdown_requested: &AtomicBool) -> bool {
-    shutdown_requested.load(Ordering::Relaxed)
-}
-
-pub fn should_drain_final(continuous: bool, interrupted: bool) -> bool {
-    !continuous || interrupted
-}
-
-pub fn should_print_final_summary(continuous: bool, interrupted: bool) -> bool {
-    !continuous || interrupted
-}
-
-pub fn final_drain_duration(probe_timeout: Duration) -> Duration {
-    probe_timeout.min(MAX_FINAL_DRAIN)
-}
-
-fn should_send_probe(next_send_deadline: Option<Instant>, shutdown_requested: &AtomicBool) -> bool {
-    !is_shutdown_requested(shutdown_requested)
-        && next_send_deadline.is_some_and(|deadline| deadline <= Instant::now())
-}
-
-fn open_event(outcome: &OpenOutcome) -> &ClientEvent {
-    match outcome {
-        OpenOutcome::Started { event, .. } | OpenOutcome::NoTestCompleted { event, .. } => event,
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use irtt_proto::{
-        echo_packet_len,
-        flags::{self, FLAG_OPEN, FLAG_REPLY},
-        layout::PacketLayout,
-        Clock, Params, ReceivedStats, StampAt, TimestampFields, MAGIC, PROTOCOL_VERSION,
-    };
-    use std::{
-        net::{SocketAddr, UdpSocket},
-        thread::JoinHandle,
-    };
-
-    const TOKEN: u64 = 0x1234_5678_90ab_cdef;
-
-    struct FakeServer {
-        addr: SocketAddr,
-        done: JoinHandle<()>,
-    }
-
-    impl FakeServer {
-        fn join(self) {
-            self.done.join().unwrap();
-        }
-    }
-
-    #[test]
-    fn final_drain_uses_capped_probe_timeout() {
-        assert_eq!(
-            final_drain_duration(Duration::from_secs(4)),
-            Duration::from_secs(4)
-        );
-        assert_eq!(
-            final_drain_duration(Duration::from_secs(60)),
-            Duration::from_secs(30)
-        );
-    }
-
-    #[test]
-    fn should_drain_final_for_finite_or_interrupted_runs() {
-        assert!(should_drain_final(false, false));
-        assert!(should_drain_final(false, true));
-        assert!(should_drain_final(true, true));
-        assert!(!should_drain_final(true, false));
-    }
-
-    #[test]
-    fn peer_close_followed_by_session_cleanup_is_successful() {
-        let params = test_params(None, Duration::from_millis(10));
-        let server = start_peer_close_server(params);
-        let mut session = ClientSession::connect(config(server.addr, None), true).unwrap();
-        let shutdown_requested = AtomicBool::new(false);
-
-        assert!(matches!(
-            session.open().unwrap().as_slice(),
-            [ClientEvent::SessionStarted { .. }]
-        ));
-
-        let events = session.step(&shutdown_requested).unwrap();
-        assert!(events
-            .iter()
-            .any(|event| matches!(event, ClientEvent::EchoReply { .. })));
-        assert!(events
-            .iter()
-            .any(|event| matches!(event, ClientEvent::SessionClosed { .. })));
-        assert!(!session.should_continue(&shutdown_requested));
-
-        session.drain_final(|_| {}).unwrap();
-        assert!(session.poll_timeouts().unwrap().is_empty());
-        assert!(session.close().unwrap().is_empty());
-        server.join();
-    }
-
-    fn config(addr: SocketAddr, duration: Option<Duration>) -> ClientConfig {
-        ClientConfig {
-            server_addr: addr.to_string(),
-            duration,
-            interval: Duration::from_millis(10),
-            open_timeouts: vec![Duration::from_millis(200)],
-            probe_timeout: Duration::from_millis(20),
-            socket_config: irtt_client::SocketConfig {
-                recv_timeout: Some(Duration::from_millis(200)),
-                ..Default::default()
-            },
-            ..ClientConfig::default()
-        }
-    }
-
-    fn test_params(duration: Option<Duration>, interval: Duration) -> Params {
-        Params {
-            protocol_version: PROTOCOL_VERSION,
-            duration_ns: duration.map_or(0, test_duration_ns_i64),
-            interval_ns: test_duration_ns_i64(interval),
-            length: 0,
-            received_stats: ReceivedStats::Both,
-            stamp_at: StampAt::Both,
-            clock: Clock::Both,
-            dscp: 0,
-            server_fill: None,
-        }
-    }
-
-    fn test_duration_ns_i64(duration: Duration) -> i64 {
-        i64::try_from(duration.as_nanos()).expect("test duration fits i64 nanoseconds")
-    }
-
-    fn start_peer_close_server(params: Params) -> FakeServer {
-        let socket = UdpSocket::bind("127.0.0.1:0").unwrap();
-        let addr = socket.local_addr().unwrap();
-        let done = thread::spawn(move || {
-            let (_, peer) = recv_request(&socket);
-            socket
-                .send_to(&open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params), peer)
-                .unwrap();
-
-            let (packet, peer) = recv_request(&socket);
-            let seq = u32::from_le_bytes(packet[12..16].try_into().unwrap());
-            socket
-                .send_to(
-                    &echo_reply_packet(
-                        TOKEN,
-                        seq,
-                        &params,
-                        &TimestampFields::default(),
-                        FLAG_REPLY | flags::FLAG_CLOSE,
-                    ),
-                    peer,
-                )
-                .unwrap();
-
-            socket
-                .set_read_timeout(Some(Duration::from_millis(250)))
-                .unwrap();
-            if let Some((packet, _)) = recv_request_timeout(&socket) {
-                panic!(
-                    "session cleanup must not send any packet after peer close; flags={:?} len={}",
-                    packet.get(3).copied(),
-                    packet.len()
-                );
-            }
-        });
-        FakeServer { addr, done }
-    }
-
-    fn recv_request(socket: &UdpSocket) -> (Vec<u8>, SocketAddr) {
-        let mut buf = [0_u8; 2048];
-        let (size, peer) = socket.recv_from(&mut buf).unwrap();
-        (buf[..size].to_vec(), peer)
-    }
-
-    fn recv_request_timeout(socket: &UdpSocket) -> Option<(Vec<u8>, SocketAddr)> {
-        let mut buf = [0_u8; 2048];
-        socket
-            .recv_from(&mut buf)
-            .ok()
-            .map(|(size, peer)| (buf[..size].to_vec(), peer))
-    }
-
-    fn open_reply(flags: u8, token: u64, params: &Params) -> Vec<u8> {
-        let mut packet = Vec::new();
-        packet.extend_from_slice(&MAGIC);
-        packet.push(flags);
-        packet.extend_from_slice(&token.to_le_bytes());
-        packet.extend_from_slice(&params.encode());
-        packet
-    }
-
-    fn echo_reply_packet(
-        token: u64,
-        seq: u32,
-        params: &Params,
-        timestamps: &TimestampFields,
-        flags: u8,
-    ) -> Vec<u8> {
-        let layout = PacketLayout::echo(false, params);
-        let packet_len = echo_packet_len(false, params)
-            .expect("session test params must have a non-negative packet length");
-        let mut packet = Vec::with_capacity(packet_len);
-
-        packet.extend_from_slice(&MAGIC);
-        packet.push(flags);
-        packet.extend_from_slice(&token.to_le_bytes());
-        packet.extend_from_slice(&seq.to_le_bytes());
-
-        if layout.recv_count {
-            packet.extend_from_slice(&42_u32.to_le_bytes());
-        }
-        if layout.recv_window {
-            packet.extend_from_slice(&0_u64.to_le_bytes());
-        }
-        if layout.recv_wall {
-            packet.extend_from_slice(&timestamps.recv_wall.unwrap_or(0).to_le_bytes());
-        }
-        if layout.recv_mono {
-            packet.extend_from_slice(&timestamps.recv_mono.unwrap_or(0).to_le_bytes());
-        }
-        if layout.midpoint_wall {
-            packet.extend_from_slice(&timestamps.midpoint_wall.unwrap_or(0).to_le_bytes());
-        }
-        if layout.midpoint_mono {
-            packet.extend_from_slice(&timestamps.midpoint_mono.unwrap_or(0).to_le_bytes());
-        }
-        if layout.send_wall {
-            packet.extend_from_slice(&timestamps.send_wall.unwrap_or(0).to_le_bytes());
-        }
-        if layout.send_mono {
-            packet.extend_from_slice(&timestamps.send_mono.unwrap_or(0).to_le_bytes());
-        }
-
-        packet.resize(packet_len, 0);
-        packet
-    }
-}

crates/irtt-cli/src/shared/client/targets.rs

@@ -1,240 +0,0 @@
-use std::{collections::HashSet, net::ToSocketAddrs};
-
-use clap::ValueEnum;
-use irtt_client::{ClientConfig, ManagedGroupPacing, ManagedTargetConfig, TargetId};
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct LabelledTargetArg {
-    pub label: String,
-    pub addr: String,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct TargetSpec {
-    pub label: String,
-    pub addr: String,
-}
-
-#[derive(Debug, Clone)]
-pub struct ResolvedTarget {
-    pub label: String,
-    pub managed: ManagedTargetConfig,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
-pub enum GroupPacingArg {
-    Staggered,
-    Burst,
-}
-
-impl From<GroupPacingArg> for ManagedGroupPacing {
-    fn from(value: GroupPacingArg) -> Self {
-        match value {
-            GroupPacingArg::Staggered => Self::Staggered,
-            GroupPacingArg::Burst => Self::Burst,
-        }
-    }
-}
-
-pub fn parse_labelled_target(input: &str) -> Result<LabelledTargetArg, String> {
-    let (label, addr) = input
-        .split_once('=')
-        .ok_or_else(|| "target must use LABEL=TARGET syntax".to_owned())?;
-    if label.is_empty() {
-        return Err("target label must not be empty".to_owned());
-    }
-    if addr.is_empty() {
-        return Err("target address must not be empty".to_owned());
-    }
-    Ok(LabelledTargetArg {
-        label: label.to_owned(),
-        addr: addr.to_owned(),
-    })
-}
-
-pub fn target_specs(
-    positional_targets: &[String],
-    labelled_targets: &[LabelledTargetArg],
-) -> Result<Vec<TargetSpec>, String> {
-    let mut specs = Vec::new();
-    let mut positional_counts = std::collections::HashMap::<&str, usize>::new();
-    for target in positional_targets {
-        let count = positional_counts.entry(target.as_str()).or_default();
-        *count += 1;
-        let label = if *count == 1 {
-            target.clone()
-        } else {
-            format!("{target}#{}", *count)
-        };
-        specs.push(TargetSpec {
-            label,
-            addr: target.clone(),
-        });
-    }
-
-    for target in labelled_targets {
-        specs.push(TargetSpec {
-            label: target.label.clone(),
-            addr: target.addr.clone(),
-        });
-    }
-
-    if specs.is_empty() {
-        return Err("at least one target is required unless --list-columns is set".to_owned());
-    }
-
-    let mut labels = HashSet::new();
-    for spec in &specs {
-        if !labels.insert(spec.label.clone()) {
-            return Err(format!("duplicate target label {:?}", spec.label));
-        }
-    }
-
-    Ok(specs)
-}
-
-pub fn resolved_managed_targets(
-    specs: Vec<TargetSpec>,
-    config: &ClientConfig,
-) -> Result<Vec<ResolvedTarget>, String> {
-    let mut remotes = HashSet::new();
-    let mut targets = Vec::with_capacity(specs.len());
-    for spec in specs {
-        let remote = resolve_target(&spec.addr, config).map_err(|err| {
-            format!(
-                "failed to resolve target {} ({:?}): {err}",
-                spec.label, spec.addr
-            )
-        })?;
-        if !remotes.insert(remote) {
-            return Err(format!(
-                "duplicate resolved target address {remote} for label {}",
-                spec.label
-            ));
-        }
-        targets.push(ResolvedTarget {
-            label: spec.label.clone(),
-            managed: ManagedTargetConfig {
-                id: TargetId::from(spec.label),
-                remote,
-                auth: None,
-            },
-        });
-    }
-    Ok(targets)
-}
-
-pub fn resolve_target(addr: &str, config: &ClientConfig) -> Result<std::net::SocketAddr, String> {
-    let normalized = normalize_target_addr(addr);
-    let mut addrs = normalized
-        .to_socket_addrs()
-        .map_err(|_| format!("failed to resolve address {normalized:?}"))?;
-    addrs
-        .find(|addr| {
-            (!config.socket_config.ipv4_only || addr.is_ipv4())
-                && (!config.socket_config.ipv6_only || addr.is_ipv6())
-        })
-        .ok_or_else(|| format!("failed to resolve address {normalized:?}"))
-}
-
-pub fn normalize_target_addr(addr: &str) -> String {
-    const DEFAULT_PORT: u16 = 2112;
-    if addr.parse::<std::net::SocketAddr>().is_ok() {
-        return addr.to_owned();
-    }
-    if addr.starts_with('[') && addr.ends_with(']') {
-        return format!("{addr}:{DEFAULT_PORT}");
-    }
-    if addr.starts_with('[') {
-        return addr.to_owned();
-    }
-    if addr.parse::<std::net::Ipv6Addr>().is_ok() {
-        return format!("[{addr}]:{DEFAULT_PORT}");
-    }
-    if addr
-        .rsplit_once(':')
-        .is_some_and(|(_, port)| port.parse::<u16>().is_ok())
-    {
-        return addr.to_owned();
-    }
-    format!("{addr}:{DEFAULT_PORT}")
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn target_normalization_matches_single_target_forms() {
-        assert_eq!(normalize_target_addr("127.0.0.1"), "127.0.0.1:2112");
-        assert_eq!(normalize_target_addr("127.0.0.1:1234"), "127.0.0.1:1234");
-        assert_eq!(normalize_target_addr("example.com"), "example.com:2112");
-        assert_eq!(
-            normalize_target_addr("example.com:1234"),
-            "example.com:1234"
-        );
-        assert_eq!(normalize_target_addr("[::1]"), "[::1]:2112");
-        assert_eq!(normalize_target_addr("[::1]:1234"), "[::1]:1234");
-        assert_eq!(normalize_target_addr("::1"), "[::1]:2112");
-    }
-
-    #[test]
-    fn target_resolution_respects_family_filters() {
-        let config = ClientConfig::default();
-        assert_eq!(
-            resolve_target("127.0.0.1", &config).unwrap(),
-            "127.0.0.1:2112".parse().unwrap()
-        );
-        assert_eq!(
-            resolve_target("[::1]", &config).unwrap(),
-            "[::1]:2112".parse().unwrap()
-        );
-        assert_eq!(
-            resolve_target("::1", &config).unwrap(),
-            "[::1]:2112".parse().unwrap()
-        );
-
-        let mut ipv4_only = ClientConfig::default();
-        ipv4_only.socket_config.ipv4_only = true;
-        assert!(resolve_target("127.0.0.1", &ipv4_only).unwrap().is_ipv4());
-        assert!(resolve_target("::1", &ipv4_only).is_err());
-
-        let mut ipv6_only = ClientConfig::default();
-        ipv6_only.socket_config.ipv6_only = true;
-        assert!(resolve_target("::1", &ipv6_only).unwrap().is_ipv6());
-        assert!(resolve_target("127.0.0.1", &ipv6_only).is_err());
-    }
-
-    #[test]
-    fn target_specs_suffix_repeated_positionals_and_reject_duplicate_labels() {
-        let positionals = vec!["host-a:2112".to_owned(), "host-a:2112".to_owned()];
-        let specs = target_specs(&positionals, &[]).unwrap();
-
-        assert_eq!(specs[0].label, "host-a:2112");
-        assert_eq!(specs[1].label, "host-a:2112#2");
-
-        let labels = vec![LabelledTargetArg {
-            label: "host-a:2112".to_owned(),
-            addr: "host-b:2112".to_owned(),
-        }];
-        let err = target_specs(&positionals[..1], &labels).unwrap_err();
-        assert!(err.contains("duplicate target label"));
-    }
-
-    #[test]
-    fn duplicate_resolved_target_addresses_are_rejected() {
-        let specs = vec![
-            TargetSpec {
-                label: "a".to_owned(),
-                addr: "127.0.0.1:2112".to_owned(),
-            },
-            TargetSpec {
-                label: "b".to_owned(),
-                addr: "127.0.0.1".to_owned(),
-            },
-        ];
-        let err = resolved_managed_targets(specs, &ClientConfig::default()).unwrap_err();
-
-        assert!(err.contains("duplicate resolved target address 127.0.0.1:2112"));
-    }
-}

crates/irtt-cli/src/shared/mod.rs

@@ -1,2 +0,0 @@
-#[cfg(feature = "client-runtime")]
-pub mod client;

crates/irtt-cli/tests/applet_dispatch.rs

@@ -1,155 +0,0 @@
-use std::process::{Command, Output};
-
-fn irtt_rs() -> Command {
-    Command::new(env!("CARGO_BIN_EXE_irtt-rs"))
-}
-
-#[cfg(unix)]
-fn irtt_rs_with_arg0(arg0: &str) -> Command {
-    use std::os::unix::process::CommandExt;
-
-    let mut command = irtt_rs();
-    command.arg0(arg0);
-    command
-}
-
-fn output_text(output: &Output) -> String {
-    let mut text = String::new();
-    text.push_str(&String::from_utf8_lossy(&output.stdout));
-    text.push_str(&String::from_utf8_lossy(&output.stderr));
-    text
-}
-
-#[test]
-fn canonical_help_shows_dispatcher_help() {
-    let output = irtt_rs().arg("--help").output().unwrap();
-    let text = output_text(&output);
-
-    assert!(output.status.success(), "{text}");
-    assert!(text.contains("IRTT-compatible multi-applet dispatcher"));
-    assert!(text.contains("client"));
-    assert!(text.contains("tui"));
-    assert!(text.contains("server"));
-}
-
-#[test]
-fn canonical_without_applet_errors() {
-    let output = irtt_rs().output().unwrap();
-    let text = output_text(&output);
-
-    assert!(!output.status.success());
-    assert!(text.contains("choose an applet"), "{text}");
-    assert!(text.contains("client"));
-    assert!(text.contains("tui"));
-    assert!(text.contains("server"));
-}
-
-#[cfg(feature = "client")]
-#[test]
-fn canonical_client_subcommand_dispatches_to_client() {
-    let output = irtt_rs().args(["client", "--help"]).output().unwrap();
-    let text = output_text(&output);
-
-    assert!(output.status.success(), "{text}");
-    assert!(text.contains("Minimal IRTT-compatible stream client"));
-    assert!(text.contains("--format <FORMAT>"));
-    assert!(text.contains("--columns <COLUMNS>"));
-}
-
-#[cfg(not(feature = "client"))]
-#[test]
-fn canonical_client_subcommand_reports_unavailable_when_disabled() {
-    let output = irtt_rs().args(["client", "--help"]).output().unwrap();
-    let text = output_text(&output);
-
-    assert!(!output.status.success());
-    assert!(
-        text.contains("client applet is not available; rebuild with the client feature"),
-        "{text}"
-    );
-}
-
-#[cfg(unix)]
-#[cfg(feature = "client")]
-#[test]
-fn client_applet_name_dispatches_to_client() {
-    let output = irtt_rs_with_arg0("irtt-cli")
-        .arg("--help")
-        .output()
-        .unwrap();
-    let text = output_text(&output);
-
-    assert!(output.status.success(), "{text}");
-    assert!(text.contains("Minimal IRTT-compatible stream client"));
-    assert!(text.contains("--format <FORMAT>"));
-    assert!(text.contains("--columns <COLUMNS>"));
-}
-
-#[cfg(all(unix, not(feature = "client")))]
-#[test]
-fn client_applet_name_reports_unavailable_when_disabled() {
-    let output = irtt_rs_with_arg0("irtt-cli")
-        .arg("--help")
-        .output()
-        .unwrap();
-    let text = output_text(&output);
-
-    assert!(!output.status.success());
-    assert!(
-        text.contains("client applet is not available; rebuild with the client feature"),
-        "{text}"
-    );
-}
-
-#[cfg(all(unix, feature = "tui"))]
-#[test]
-fn tui_applet_name_dispatches_to_tui_when_enabled() {
-    let output = irtt_rs_with_arg0("irtt-tui")
-        .arg("--help")
-        .output()
-        .unwrap();
-    let text = output_text(&output);
-
-    assert!(output.status.success(), "{text}");
-    assert!(text.contains("Minimal IRTT-compatible TUI client"));
-    assert!(text.contains("--duration <DURATION>"));
-}
-
-#[cfg(all(unix, not(feature = "tui")))]
-#[test]
-fn tui_applet_name_reports_unavailable_when_disabled() {
-    let output = irtt_rs_with_arg0("irtt-tui")
-        .arg("--help")
-        .output()
-        .unwrap();
-    let text = output_text(&output);
-
-    assert!(!output.status.success());
-    assert!(text.contains("TUI applet is not available"), "{text}");
-}
-
-#[cfg(unix)]
-#[test]
-fn server_applet_name_reports_unavailable() {
-    let output = irtt_rs_with_arg0("irtt-server")
-        .arg("--help")
-        .output()
-        .unwrap();
-    let text = output_text(&output);
-
-    assert!(!output.status.success());
-    assert!(text.contains("server applet is not available"), "{text}");
-}
-
-#[cfg(unix)]
-#[test]
-fn unknown_irtt_applet_name_errors() {
-    let output = irtt_rs_with_arg0("irtt-typo").output().unwrap();
-    let text = output_text(&output);
-
-    assert!(!output.status.success());
-    assert!(text.contains("unknown applet name 'irtt-typo'"), "{text}");
-    assert!(text.contains("irtt-cli"));
-    assert!(text.contains("irtt-tui"));
-    assert!(text.contains("irtt-server"));
-}

crates/irtt-cli/tests/client_multi_target.rs

@@ -1,284 +0,0 @@
-#![cfg(feature = "client")]
-
-use std::{
-    net::{SocketAddr, UdpSocket},
-    process::Command,
-    thread,
-    thread::JoinHandle,
-    time::Duration,
-};
-
-use irtt_proto::{
-    echo_packet_len,
-    flags::{FLAG_CLOSE, FLAG_OPEN, FLAG_REPLY},
-    layout::PacketLayout,
-    Clock, Params, ReceivedStats, StampAt, TimestampFields, MAGIC, PROTOCOL_VERSION,
-};
-
-const TOKEN: u64 = 0x1234_5678_90ab_cdef;
-
-struct FakeServer {
-    addr: SocketAddr,
-    done: JoinHandle<()>,
-}
-
-impl FakeServer {
-    fn join(self) {
-        self.done.join().unwrap();
-    }
-}
-
-#[test]
-fn list_columns_succeeds_without_target() {
-    let output = Command::new(env!("CARGO_BIN_EXE_irtt-cli"))
-        .arg("--list-columns")
-        .output()
-        .unwrap();
-
-    assert!(
-        output.status.success(),
-        "status={:?}\nstderr={}",
-        output.status.code(),
-        String::from_utf8_lossy(&output.stderr)
-    );
-    let stdout = String::from_utf8(output.stdout).unwrap();
-    assert!(stdout.contains("Available event columns:"), "{stdout}");
-    assert!(stdout.contains("target"), "{stdout}");
-}
-
-#[test]
-fn single_target_default_table_omits_target_and_accepts_pacing() {
-    let server = start_echo_server(test_params(
-        Some(Duration::from_millis(30)),
-        Duration::from_millis(10),
-    ));
-
-    let output = Command::new(env!("CARGO_BIN_EXE_irtt-cli"))
-        .args([
-            "--duration",
-            "30ms",
-            "--interval",
-            "10ms",
-            "--pacing",
-            "burst",
-            "--header",
-            "always",
-            &server.addr.to_string(),
-        ])
-        .output()
-        .unwrap();
-
-    server.join();
-
-    assert!(
-        output.status.success(),
-        "status={:?}\nstderr={}",
-        output.status.code(),
-        String::from_utf8_lossy(&output.stderr)
-    );
-    let stdout = String::from_utf8(output.stdout).unwrap();
-    let header = stdout.lines().next().unwrap_or_default();
-    assert!(!header.split_whitespace().any(|column| column == "target"));
-}
-
-#[test]
-fn single_target_custom_target_column_renders_positional_label() {
-    let server = start_echo_server(test_params(
-        Some(Duration::from_millis(30)),
-        Duration::from_millis(10),
-    ));
-    let target = server.addr.to_string();
-
-    let output = Command::new(env!("CARGO_BIN_EXE_irtt-cli"))
-        .args([
-            "--duration",
-            "30ms",
-            "--interval",
-            "10ms",
-            "--format",
-            "csv",
-            "--columns",
-            "target,seq",
-            "--header",
-            "never",
-            &target,
-        ])
-        .output()
-        .unwrap();
-
-    server.join();
-
-    assert!(
-        output.status.success(),
-        "status={:?}\nstderr={}",
-        output.status.code(),
-        String::from_utf8_lossy(&output.stderr)
-    );
-    let stdout = String::from_utf8(output.stdout).unwrap();
-    assert!(
-        stdout
-            .lines()
-            .any(|line| line.starts_with(&format!("{target},"))),
-        "{stdout}"
-    );
-}
-
-#[test]
-fn multi_target_csv_emits_rows_for_both_labels() {
-    let params = test_params(Some(Duration::from_millis(40)), Duration::from_millis(10));
-    let a = start_echo_server(params.clone());
-    let b = start_echo_server(params);
-
-    let output = Command::new(env!("CARGO_BIN_EXE_irtt-cli"))
-        .args([
-            "--duration",
-            "40ms",
-            "--interval",
-            "10ms",
-            "--format",
-            "csv",
-            "--columns",
-            "target,seq,effective_rtt_us",
-            "--header",
-            "never",
-            "--target",
-            &format!("a={}", a.addr),
-            "--target",
-            &format!("b={}", b.addr),
-        ])
-        .output()
-        .unwrap();
-
-    a.join();
-    b.join();
-
-    assert!(
-        output.status.success(),
-        "status={:?}\nstderr={}",
-        output.status.code(),
-        String::from_utf8_lossy(&output.stderr)
-    );
-    let stdout = String::from_utf8(output.stdout).unwrap();
-    assert!(
-        stdout.lines().any(|line| line.starts_with("a,")),
-        "{stdout}"
-    );
-    assert!(
-        stdout.lines().any(|line| line.starts_with("b,")),
-        "{stdout}"
-    );
-}
-
-fn start_echo_server(params: Params) -> FakeServer {
-    let socket = UdpSocket::bind("127.0.0.1:0").unwrap();
-    socket
-        .set_read_timeout(Some(Duration::from_secs(2)))
-        .unwrap();
-    let addr = socket.local_addr().unwrap();
-    let done = thread::spawn(move || {
-        let (_, peer) = recv_request(&socket);
-        socket
-            .send_to(&open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params), peer)
-            .unwrap();
-
-        loop {
-            let (packet, peer) = recv_request(&socket);
-            let flags = packet[3];
-            if flags & FLAG_CLOSE != 0 {
-                break;
-            }
-            let seq = u32::from_le_bytes(packet[12..16].try_into().unwrap());
-            socket
-                .send_to(
-                    &echo_reply_packet(
-                        TOKEN,
-                        seq,
-                        &params,
-                        &TimestampFields::default(),
-                        FLAG_REPLY,
-                    ),
-                    peer,
-                )
-                .unwrap();
-        }
-    });
-    FakeServer { addr, done }
-}
-
-fn recv_request(socket: &UdpSocket) -> (Vec<u8>, SocketAddr) {
-    let mut buf = [0_u8; 2048];
-    let (size, peer) = socket.recv_from(&mut buf).unwrap();
-    (buf[..size].to_vec(), peer)
-}
-
-fn open_reply(flags: u8, token: u64, params: &Params) -> Vec<u8> {
-    let mut packet = Vec::new();
-    packet.extend_from_slice(&MAGIC);
-    packet.push(flags);
-    packet.extend_from_slice(&token.to_le_bytes());
-    packet.extend_from_slice(&params.encode());
-    packet
-}
-
-fn echo_reply_packet(
-    token: u64,
-    seq: u32,
-    params: &Params,
-    timestamps: &TimestampFields,
-    flags: u8,
-) -> Vec<u8> {
-    let layout = PacketLayout::echo(false, params);
-    let packet_len = echo_packet_len(false, params).unwrap();
-    let mut packet = Vec::with_capacity(packet_len);
-
-    packet.extend_from_slice(&MAGIC);
-    packet.push(flags);
-    packet.extend_from_slice(&token.to_le_bytes());
-    packet.extend_from_slice(&seq.to_le_bytes());
-
-    if layout.recv_count {
-        packet.extend_from_slice(&42_u32.to_le_bytes());
-    }
-    if layout.recv_window {
-        packet.extend_from_slice(&0_u64.to_le_bytes());
-    }
-    if layout.recv_wall {
-        packet.extend_from_slice(&timestamps.recv_wall.unwrap_or(0).to_le_bytes());
-    }
-    if layout.recv_mono {
-        packet.extend_from_slice(&timestamps.recv_mono.unwrap_or(0).to_le_bytes());
-    }
-    if layout.midpoint_wall {
-        packet.extend_from_slice(&timestamps.midpoint_wall.unwrap_or(0).to_le_bytes());
-    }
-    if layout.midpoint_mono {
-        packet.extend_from_slice(&timestamps.midpoint_mono.unwrap_or(0).to_le_bytes());
-    }
-    if layout.send_wall {
-        packet.extend_from_slice(&timestamps.send_wall.unwrap_or(0).to_le_bytes());
-    }
-    if layout.send_mono {
-        packet.extend_from_slice(&timestamps.send_mono.unwrap_or(0).to_le_bytes());
-    }
-
-    packet.resize(packet_len, 0);
-    packet
-}
-
-fn test_params(duration: Option<Duration>, interval: Duration) -> Params {
-    Params {
-        protocol_version: PROTOCOL_VERSION,
-        duration_ns: duration.map_or(0, duration_ns_i64),
-        interval_ns: duration_ns_i64(interval),
-        length: 0,
-        received_stats: ReceivedStats::Both,
-        stamp_at: StampAt::Both,
-        clock: Clock::Both,
-        dscp: 0,
-        server_fill: None,
-    }
-}
-
-fn duration_ns_i64(duration: Duration) -> i64 {
-    i64::try_from(duration.as_nanos()).unwrap()
-}

crates/irtt-client/AGENTS.md

@@ -0,0 +1,170 @@
+# `irtt-client` guidance
+
+Repository-wide guidance in the root `AGENTS.md` also applies here.
+
+## Linux kernel TX timestamp capture
+
+On Linux, with the `ancillary` feature, the client best-effort upgrades its
+socket from RX-only `SO_TIMESTAMPING` to RX+TX immediately after a successful
+Open, before the first Echo probe can be sent:
+
+```
+socket created
+    -> RX timestamping configured (RX_SOFTWARE | SOFTWARE)
+    -> Open attempts/retries (untimestamped)
+    -> successful Open
+    -> best-effort enable TX timestamping (+ TX_SOFTWARE | OPT_ID | OPT_TSONLY)
+    -> first Echo probe
+```
+
+`TX_SOFTWARE` asks the kernel for a software send timestamp; `OPT_ID` asks it
+to tag each notification with an automatically incrementing per-socket ID;
+`OPT_TSONLY` means the notification never needs to carry the original
+payload, so a zero-length receive buffer is enough. The upgrade is entirely
+best-effort: if it fails, the client keeps operating on the original RX-only
+configuration (`try_enable_tx_timestamping` restores it explicitly) and
+timing falls back to userspace `sent_at` as it always has. TX capability
+failure is never a public error and is never logged from the library.
+
+### Best-effort kernel-ID correlation
+
+The client uses the kernel's automatic `OPT_ID` as the probe's wire-sequence
+correlation ID — no separate correlation map. On the normal successful-send
+path, both counters start at zero after Open and advance together. This is
+not a permanent identity: a kernel ID can theoretically be consumed while a
+send is being prepared and then survive a subsequent send failure, leaving
+kernel IDs one or more steps ahead of `next_wire_seq`. Do not restore an
+assumption that failed or nonblocking sends cannot cause that desynchrony.
+
+The effect is confined to the optional timing enhancement. A kernel timestamp
+whose ID cannot be matched to a pending or retained timed-out probe is
+discarded, as is any implausible timestamp; `sent_at` remains the ordinary
+userspace fallback. **After every failed probe submission, disable kernel-ID
+correlation for the rest of that session.** A gap means an otherwise plausible
+later ID can name the wrong probe, so subsequent error-queue timestamps must
+be discarded rather than attached by ID. This is safe because:
+
+- **Normal successful sends track together.** `wire_seq` starts at 0 on every
+  successful Open (`SessionMachine::commit_open` builds a fresh
+  `ActiveSession` with `next_wire_seq: 0`) and advances by exactly 1 only via
+  `commit_probe_sent`, after a confirmed successful socket send. TX
+  timestamping is enabled after that same successful Open and before any probe
+  is sent, so the normal zero points line up.
+- **One socket, one session, no reopen.** `SessionMachine`'s state machine
+  only reaches `Open` from `Connected`, and `commit_open`/`commit_local_close`
+  never route back to `Connected`. A `Client`/`AsyncClient` cannot reopen a
+  second session on the same socket, so there is no second epoch of wire
+  sequence numbers to collide with a stale kernel ID.
+- **The one extra send (Close) is harmless.** `Close` sends one datagram
+  after TX timestamping is already enabled, generating one TX timestamp
+  record with no corresponding `wire_seq` (`Close` does not advance
+  `next_wire_seq`). Because the session is terminal immediately after,
+  nothing will ever look up that ID; `record_kernel_tx_timestamp`'s
+  "unknown ID -> ignore" rule discards it safely.
+
+## MSG_ERRQUEUE drains
+
+`receive::linux::error_queue` decodes one `MSG_ERRQUEUE` record at a time
+(`try_recv_error_queue_record`) and classifies it: a genuine send-timestamp
+completion (`TxTimestamp`), a timestamp-origin record that is not a usable
+`SND` completion (`MalformedOrUnsupportedTimestamp` — never treated as
+fatal, since this client only ever requests `TX_SOFTWARE`/`SND`, so anything
+else on that origin is unexpected metadata, not a network error), a genuine
+non-timestamp socket/network error (`SocketError`), or nothing (`Ignored`).
+Origin (`SO_EE_ORIGIN_TIMESTAMPING` or not) is the only thing that decides
+between the last two categories.
+
+`receive::linux::drain_tx_timestamps` reads up to
+`MAX_TX_TIMESTAMP_RECORDS_PER_DRAIN` (32) records per call: nonblocking, one
+record at a time, no heap allocation, stopping early once the queue is
+empty. It is a starvation guard, not a queue-capacity promise — one TX
+timestamp is generated per successful probe, and drains happen at several
+natural choke points, so a modest constant comfortably covers realistic
+backlog. `Client`/`AsyncClient` call it after a successful probe send,
+before processing an inbound reply, and before evaluating timeouts; it never
+waits for a timestamp; an absent timestamp after all of those opportunities
+simply stays absent. A genuine `SocketError` record stops the drain and is
+surfaced through the ordinary `ClientError::Socket` path.
+
+The Tokio adapter uses the same raw nonblocking `recvmsg(MSG_ERRQUEUE |
+MSG_DONTWAIT)` rather than `try_io`/`poll_recv_ready`: error-queue readiness
+is not ordinary read readiness, and driving it through the Tokio reactor
+risks clearing readiness state that the normal Echo receive path depends on.
+There is no background task or second `AsyncFd` around the Tokio-owned
+socket.
+
+## Retained state
+
+`PendingProbe` carries an optional `kernel_tx_timestamp: Option<SystemTime>`
+alongside the userspace `sent_at`. It survives pending -> timed-out retention
+(`SessionMachine::record_kernel_tx_timestamp` updates whichever of
+`PendingMap`/`TimedOutMap` still holds the probe) and is otherwise bounded by
+the same limits those maps already enforce — no new unbounded state. First
+valid observation wins on duplicates.
+
+### Pre-send anchor vs. post-send `sent_at` (F-04)
+
+The probe send transaction splits into two timestamps around the socket
+send, not one:
+
+- A **private pre-send anchor**, sampled immediately before the fallible
+  commit preflight (`SessionMachine::finalize_probe_commit`) that must
+  happen before the socket send: timeout deadline `checked_add` arithmetic
+  (so `DurationOverflow` still guarantees nothing was transmitted) and the
+  kernel TX lower-plausibility bound. Its monotonic half becomes
+  `PendingProbe::timeout_at`'s basis; its wall half becomes
+  `PendingProbe::tx_not_before_wall`. It is never exposed publicly.
+- The **public `sent_at`**, a paired wall/monotonic `ClientTimestamp`
+  captured immediately after the socket send returns successfully
+  (`SessionMachine::commit_probe_sent`, which is infallible — all fallible
+  work already happened against the pre-send anchor). This is the RTT
+  endpoint, the userspace upstream-OWD fallback endpoint, `timer_error`'s
+  basis, and the value surfaced on `EchoSent`/`EchoReply`/`EchoLoss`/
+  `LateReply`.
+
+So `timeout_at` is deliberately **not** derived from `sent_at.mono` — it
+remains anchored to before the send, on purpose, so the existing pre-send
+timeout/overflow/no-send contract is unchanged. Only the *measurement*
+`sent_at` moved to after the send. A `WouldBlock` `try_send` (Tokio) never
+samples a `sent_at`, never calls `finalize_probe_commit`'s matching
+`commit_probe_sent`, and never advances the machine or schedule; each retry
+gets its own fresh pre-send anchor, and only a successful attempt's anchor
+and `sent_at` are ever retained.
+
+**The kernel TX timestamp is eligible for exactly one measurement: the
+upstream (`client_to_server`) one-way delay send endpoint.**
+`compute_one_way`'s private `preferred_send_wall` helper prefers it over the
+userspace `sent_at.wall` sample when
+
+    tx_not_before_wall <= kernel_tx_timestamp <= reply_received_at.wall
+
+(inclusive, compared only against the client's own wall clock — never
+against the remote server's wall timestamp). The lower bound is the
+pre-send `tx_not_before_wall`, not the post-send `sent_at.wall`: a
+legitimate `TX_SOFTWARE` timestamp can be generated while the send syscall
+is still in flight, so it can legitimately precede the post-send `sent_at`
+sample without being implausible. Otherwise, including when no kernel
+timestamp was observed, the upstream endpoint falls back to `sent_at.wall`
+(the post-send sample); a rejected observation is never erased from
+`PendingProbe`, only skipped for that measurement. There is no
+maximum-lag bound: unlike the kernel receive side, legitimate client
+send-to-reply time can exceed a second.
+
+`sent_at` remains the RTT endpoint and the userspace fallback for the
+upstream (`client_to_server`) one-way delay, exactly as before this
+capability existed. It is not an input to the downstream
+(`server_to_client`) one-way delay, which is derived solely from
+`ReceiveMeta::preferred_receive_wall` and the negotiated server send
+timestamp — unaffected by this capability or by F-04. `TX_SOFTWARE` is
+still a software kernel timestamp near the driver handoff, not a NIC
+hardware transmit time. `irtt-stats`'s `ReplySample`
+copies public `sent_at` straight into `client_send_mono`/`client_send_wall_ns`,
+which `send_ipdv_ns` compares across probes for the upstream IPDV component —
+so that component shifts endpoint along with `sent_at` itself (pre-send vs.
+post-send) exactly as RTT and the upstream OWD fallback do; it is not a
+separate invariant. A normal
+reply and a measurable late reply (one whose `PendingProbe` is still
+retained in `TimedOutMap`) apply the identical selection policy; an
+untracked late reply has no retained probe and stays unmeasurable, and a
+kernel timestamp that arrives after a reply has already been processed is
+simply never observed by that reply.

crates/irtt-client/Cargo.toml

@@ -1,25 +1,51 @@
 [package]
 name = "irtt-client"
-version = "0.4.0"
+version = "0.5.1"
 description = "IRTT-compatible Rust client library"
 edition.workspace = true
 license.workspace = true
 rust-version.workspace = true
 repository.workspace = true
 homepage.workspace = true
-readme.workspace = true
+readme = "README.md"
 keywords = ["irtt", "networking", "latency", "rtt"]
 categories = ["network-programming"]
 
 [dependencies]
 irtt-proto.workspace = true
-libc = { version = "0.2.186", optional = true }
-socket2 = { version = "0.6.4", features = ["all"] }
-thiserror = "2.0.18"
+socket2 = { version = "0.6.5", features = ["all"] }
+thiserror = "2.0.20"
+tokio = { version = "1.53.1", default-features = false, features = ["rt", "net", "time", "sync"], optional = true}
+
+[target.'cfg(target_os = "linux")'.dependencies]
+nix = { version = "0.31.3", default-features = false, features = ["net", "uio"], optional = true }
 
 [features]
 default = []
-ancillary = ["dep:libc"]
+ancillary = ["dep:nix"]
+tokio = ["dep:tokio"]
 
 [package.metadata.docs.rs]
 all-features = true
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
+
+[[example]]
+name = "blocking_client"
+doc-scrape-examples = true
+
+[[example]]
+name = "tokio_client"
+required-features = ["tokio"]
+doc-scrape-examples = true
+
+[[example]]
+name = "managed_client"
+required-features = ["tokio"]
+doc-scrape-examples = true
+
+[dev-dependencies]
+# Keep the packaged client testable against the latest published server while
+# workspace tests continue to exercise the local source through this path.
+irtt-server = { version = "0.5.1", path = "../irtt-server" }
+proptest = "1.11.0"
+tokio = { version = "1.53.1", default-features = false, features = ["rt", "sync"] }

crates/irtt-client/README.md

@@ -0,0 +1,37 @@
+# irtt-client
+
+Reusable client/session library for IRTT-compatible round-trip-time probing:
+socket lifecycle, open negotiation, probe send/receive, loss/duplicate/late
+classification, and a typed event stream.
+
+## Looking for the CLI?
+
+If you just want to run probes from the command line, use the
+[`irtt-rs`](https://crates.io/crates/irtt-rs) application package instead,
+which installs the `irtt-client` binary. This crate is the library the
+binaries are built on.
+
+## API tiers
+
+- `Client` — runtime-free blocking adapter. No Tokio dependency; this is the
+  default build.
+- `AsyncClient` (feature `tokio`) — low-level Tokio adapter for callers that
+  own a runtime and drive readiness directly.
+- `managed` (feature `tokio`) — a unified managed driver: `ManagedClientTask`
+  / `ManagedClientHandle` for multi-target orchestration under a Tokio
+  runtime, and `BlockingManagedClient` for synchronous callers, which owns its
+  own dedicated current-thread runtime.
+
+Tokio stays optional: the default build has no runtime and no Tokio
+dependency at all.
+
+See `examples/` in the repository for runnable examples of each tier.
+
+## Documentation
+
+Full API documentation is on [docs.rs/irtt-client](https://docs.rs/irtt-client).
+
+## Project
+
+Part of [irtt-rs](https://github.com/Lochnair/irtt-rs), an independent Rust
+implementation of an IRTT-compatible protocol stack.

crates/irtt-client/examples/blocking_client.rs

@@ -0,0 +1,110 @@
+//! Runtime-free blocking client example.
+//!
+//! Opens a session against a local IRTT-compatible server, sends a few
+//! probes, and prints the events observed. Uses only [`Client`], which has no
+//! Tokio dependency and works in a default (`--no-default-features`) build.
+//!
+//! Run a server first, then run this example:
+//!
+//! ```text
+//! cargo run -p irtt-rs --bin irtt-server --features server
+//! cargo run -p irtt-client --example blocking_client
+//! ```
+//!
+//! Without a reachable server this exits quickly with an open-timeout error
+//! instead of hanging, because the example shortens `open_timeouts` for a
+//! fast demonstration; a real caller would normally keep the default retry
+//! schedule.
+
+use std::time::{Duration, Instant};
+
+use irtt_client::{Client, ClientConfig, ClientEvent};
+
+const RUN_DURATION: Duration = Duration::from_secs(2);
+
+fn main() {
+    let config = ClientConfig {
+        server_addr: "127.0.0.1:2112".to_owned(),
+        duration: Some(RUN_DURATION),
+        interval: Duration::from_millis(200),
+        // A single short attempt keeps this example fast when no server is
+        // reachable; production callers should generally keep the default.
+        open_timeouts: vec![Duration::from_millis(300)],
+        socket_config: irtt_client::SocketConfig {
+            recv_timeout: Some(Duration::from_millis(100)),
+            ..Default::default()
+        },
+        ..Default::default()
+    };
+
+    let mut client = match Client::connect(config) {
+        Ok(client) => client,
+        Err(err) => {
+            eprintln!("failed to prepare client socket: {err}");
+            return;
+        }
+    };
+
+    match client.open() {
+        Ok(outcome) => println!("session opened: {outcome:?}"),
+        Err(err) => {
+            eprintln!("open failed (is a server running at 127.0.0.1:2112?): {err}");
+            return;
+        }
+    }
+
+    // The run itself lasts `duration`, but a lost probe isn't classified as
+    // `EchoLoss` until `probe_timeout()` after it was sent; wait at least
+    // that much past the run's own end so a loss near the end can still be
+    // observed and printed before this example gives up and closes.
+    let deadline = Instant::now() + RUN_DURATION + client.probe_timeout();
+    while Instant::now() < deadline && !client.is_run_complete() {
+        // send_probe is caller-paced: only call it once its own schedule
+        // says a probe is due, rather than as fast as the loop spins.
+        if client
+            .next_send_deadline()
+            .is_some_and(|send_at| Instant::now() >= send_at)
+        {
+            // A failed send retains its prepared probe without advancing the
+            // schedule, so a persistent error (e.g. the interface going
+            // down) would otherwise make this loop retry silently until the
+            // safety deadline instead of reporting it.
+            match client.send_probe() {
+                Ok(events) => events.iter().for_each(print_event),
+                Err(err) => {
+                    eprintln!("send failed: {err}");
+                    break;
+                }
+            }
+        }
+        match client.recv_once() {
+            Ok(events) => events.iter().for_each(print_event),
+            Err(err) => {
+                eprintln!("receive failed: {err}");
+                break;
+            }
+        }
+        match client.poll_timeouts() {
+            Ok(events) => events.iter().for_each(print_event),
+            Err(err) => {
+                eprintln!("timeout polling failed: {err}");
+                break;
+            }
+        }
+    }
+
+    match client.close() {
+        Ok(events) => events.iter().for_each(print_event),
+        Err(err) => eprintln!("close failed: {err}"),
+    }
+}
+
+fn print_event(event: &ClientEvent) {
+    match event {
+        ClientEvent::EchoReply { seq, rtt, .. } => {
+            println!("seq {seq}: rtt {:?}", rtt.effective);
+        }
+        ClientEvent::EchoLoss { seq, .. } => println!("seq {seq}: lost"),
+        other => println!("{other:?}"),
+    }
+}

crates/irtt-client/examples/managed_client.rs

@@ -0,0 +1,73 @@
+//! Managed multi-target client example (`tokio` feature).
+//!
+//! [`BlockingManagedClient`] runs one or more targets under a dedicated
+//! current-thread Tokio runtime and exposes a synchronous handle, so a caller
+//! that does not want to touch Tokio directly can still get managed
+//! multi-target orchestration, retries, and a lossy event stream.
+//!
+//! Run a server first, then run this example:
+//!
+//! ```text
+//! cargo run -p irtt-rs --bin irtt-server --features server
+//! cargo run -p irtt-client --example managed_client --features tokio
+//! ```
+//!
+//! This example does not wait for the managed run to finish naturally: it
+//! requests a stop after a fixed short window so it exits promptly even
+//! without a reachable server.
+
+use std::time::Duration;
+
+use irtt_client::managed::{
+    BlockingManagedClient, ManagedClientConfig, ManagedCompletionPolicy, ManagedEvent,
+    ManagedTargetConfig,
+};
+use irtt_client::ClientConfig;
+
+fn main() {
+    let config = ManagedClientConfig {
+        client: ClientConfig {
+            duration: None,
+            interval: Duration::from_millis(200),
+            open_timeouts: vec![Duration::from_millis(300)],
+            ..Default::default()
+        },
+        completion: ManagedCompletionPolicy::ExplicitStop,
+        ..Default::default()
+    };
+    let targets = vec![ManagedTargetConfig::new("local", "127.0.0.1:2112")];
+
+    let (owner, mut events) = match BlockingManagedClient::start_with_subscription(config, targets)
+    {
+        Ok(started) => started,
+        Err(err) => {
+            eprintln!("failed to start managed client: {err}");
+            return;
+        }
+    };
+
+    let stop_after = Duration::from_secs(1);
+    let deadline = std::time::Instant::now() + stop_after;
+    while std::time::Instant::now() < deadline {
+        match events.try_recv() {
+            Ok(event) => print_event(&event),
+            Err(_) => std::thread::sleep(Duration::from_millis(50)),
+        }
+    }
+
+    // `stop()` requests the stop synchronously; the returned receipt is only
+    // useful for awaiting durable acknowledgement, which this blocking
+    // example does not need.
+    std::mem::drop(owner.handle().stop());
+    match owner.join() {
+        Ok(outcome) => println!("managed run ended: {:?}", outcome.end_reason),
+        Err(err) => eprintln!("managed worker did not join cleanly: {err}"),
+    }
+}
+
+fn print_event(event: &ManagedEvent) {
+    match event {
+        ManagedEvent::Client { target, event } => println!("{}: {event:?}", target.id),
+        other => println!("{other:?}"),
+    }
+}

crates/irtt-client/examples/tokio_client.rs

@@ -0,0 +1,133 @@
+//! Low-level Tokio client example (`tokio` feature).
+//!
+//! Drives [`AsyncClient`] directly on a caller-owned runtime. This is the
+//! adapter to reach for when you already have a Tokio runtime and want to
+//! await sends/receives yourself, rather than use the higher-level `managed`
+//! driver (see the `managed_client` example).
+//!
+//! Run a server first, then run this example:
+//!
+//! ```text
+//! cargo run -p irtt-rs --bin irtt-server --features server
+//! cargo run -p irtt-client --example tokio_client --features tokio
+//! ```
+//!
+//! Without a reachable server this exits quickly with an open-timeout error
+//! instead of hanging, because the example shortens `open_timeouts` for a
+//! fast demonstration.
+
+use std::time::{Duration, Instant};
+
+use irtt_client::{AsyncClient, ClientConfig, ClientEvent};
+
+/// Upper bound on how long the receive wait can go without also calling
+/// `poll_timeouts()`. `AsyncClient` does not expose the earliest pending
+/// probe's own timeout deadline, so this example polls on a short fixed
+/// cadence instead of waiting for the full `probe_timeout()` from whenever
+/// this loop last ran — that would let poll_timeouts() classify a lost
+/// probe (and its dependent statistics/session state) far later than it
+/// actually became lost.
+const TIMEOUT_POLL_INTERVAL: Duration = Duration::from_millis(50);
+
+fn main() {
+    let runtime = tokio::runtime::Builder::new_current_thread()
+        .enable_io()
+        .enable_time()
+        .build()
+        .expect("failed to build Tokio runtime");
+
+    runtime.block_on(run());
+}
+
+async fn run() {
+    let config = ClientConfig {
+        server_addr: "127.0.0.1:2112".to_owned(),
+        duration: Some(Duration::from_secs(2)),
+        interval: Duration::from_millis(200),
+        // A single short attempt keeps this example fast when no server is
+        // reachable; production callers should generally keep the default.
+        open_timeouts: vec![Duration::from_millis(300)],
+        ..Default::default()
+    };
+
+    let mut client = match AsyncClient::connect(config).await {
+        Ok(client) => client,
+        Err(err) => {
+            eprintln!("failed to prepare client socket: {err}");
+            return;
+        }
+    };
+
+    match client.open().await {
+        Ok(outcome) => println!("session opened: {outcome:?}"),
+        Err(err) => {
+            eprintln!("open failed (is a server running at 127.0.0.1:2112?): {err}");
+            return;
+        }
+    }
+
+    while !client.is_run_complete() {
+        // Bound the receive wait by the next send/timeout deadline, rather
+        // than awaiting recv() unconditionally: a lost or rate-limited reply
+        // must not stall pacing or timeout classification indefinitely.
+        let wake_at = client
+            .next_send_deadline()
+            .into_iter()
+            .chain(std::iter::once(Instant::now() + TIMEOUT_POLL_INTERVAL))
+            .min()
+            .expect("the fixed poll-interval deadline is always present");
+
+        let recv_result = tokio::select! {
+            events = client.recv() => Some(events),
+            () = tokio::time::sleep_until(tokio::time::Instant::from_std(wake_at)) => None,
+        };
+        if let Some(result) = recv_result {
+            match result {
+                Ok(events) => events.iter().for_each(print_event),
+                Err(err) => {
+                    eprintln!("receive failed: {err}");
+                    break;
+                }
+            }
+        }
+
+        if client
+            .next_send_deadline()
+            .is_some_and(|send_at| Instant::now() >= send_at)
+        {
+            // A failed send retains its prepared probe without advancing the
+            // schedule, so a persistent error (e.g. the interface going
+            // down) would otherwise make this loop retry forever instead of
+            // reporting it.
+            match client.send_probe().await {
+                Ok(events) => events.iter().for_each(print_event),
+                Err(err) => {
+                    eprintln!("send failed: {err}");
+                    break;
+                }
+            }
+        }
+        match client.poll_timeouts() {
+            Ok(events) => events.iter().for_each(print_event),
+            Err(err) => {
+                eprintln!("timeout polling failed: {err}");
+                break;
+            }
+        }
+    }
+
+    match client.close().await {
+        Ok(events) => events.iter().for_each(print_event),
+        Err(err) => eprintln!("close failed: {err}"),
+    }
+}
+
+fn print_event(event: &ClientEvent) {
+    match event {
+        ClientEvent::EchoReply { seq, rtt, .. } => {
+            println!("seq {seq}: rtt {:?}", rtt.effective);
+        }
+        ClientEvent::EchoLoss { seq, .. } => println!("seq {seq}: lost"),
+        other => println!("{other:?}"),
+    }
+}

crates/irtt-client/src/async_client/in_tree_server_support.rs

@@ -0,0 +1,82 @@
+//! A real `irtt-server` running in-process, for tests that need to prove
+//! `AsyncClient` and the blocking `Client` are equivalent against a real peer.
+//!
+//! This duplicates `crates/irtt-integration-tests/tests/support/in_tree_server.rs`
+//! rather than depending on it: this module backs private (`super::*`) unit
+//! tests here, while the integration crate covers black-box client/server
+//! behavior, and neither can depend on the other's test-only code.
+
+use std::{
+    net::{IpAddr, Ipv4Addr, SocketAddr},
+    sync::mpsc,
+    thread::{self, JoinHandle},
+    time::Duration,
+};
+
+use irtt_server::{Server, ServerConfig};
+use tokio::sync::oneshot;
+
+const STARTUP_TIMEOUT: Duration = Duration::from_secs(2);
+
+pub struct InTreeServer {
+    pub addr: SocketAddr,
+    shutdown: Option<oneshot::Sender<()>>,
+    done: Option<JoinHandle<Result<(), irtt_server::ServerRuntimeError>>>,
+}
+
+impl InTreeServer {
+    pub fn start(config: ServerConfig) -> Self {
+        let (startup_tx, startup_rx) = mpsc::sync_channel(1);
+        let (shutdown_tx, shutdown_rx) = oneshot::channel();
+        let done = thread::spawn(move || {
+            let runtime = tokio::runtime::Builder::new_current_thread()
+                .enable_all()
+                .build()
+                .expect("failed to build in-tree test server runtime");
+            runtime.block_on(async move {
+                let bind_addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 0);
+                let mut server = Server::bind(bind_addr, config).await?;
+                startup_tx
+                    .send(server.local_addr()?)
+                    .expect("test stopped waiting for in-tree server startup");
+                server
+                    .run(async {
+                        let _ = shutdown_rx.await;
+                    })
+                    .await
+            })
+        });
+
+        let addr = match startup_rx.recv_timeout(STARTUP_TIMEOUT) {
+            Ok(addr) => addr,
+            Err(error) => {
+                let _ = shutdown_tx.send(());
+                let result = done.join().expect("in-tree test server thread panicked");
+                panic!("in-tree test server failed before startup ({error}): {result:?}");
+            }
+        };
+
+        Self {
+            addr,
+            shutdown: Some(shutdown_tx),
+            done: Some(done),
+        }
+    }
+
+    fn stop_inner(&mut self) {
+        if let Some(shutdown) = self.shutdown.take() {
+            let _ = shutdown.send(());
+        }
+        if let Some(done) = self.done.take() {
+            done.join()
+                .expect("in-tree test server thread panicked")
+                .expect("in-tree test server stopped with an error");
+        }
+    }
+}
+
+impl Drop for InTreeServer {
+    fn drop(&mut self) {
+        self.stop_inner();
+    }
+}

crates/irtt-client/src/client.rs

@@ -4,6 +4,9 @@ use std::{
     time::{Duration, Instant},
 };
 
+#[cfg(test)]
+use std::cell::Cell;
+
 #[cfg(test)]
 use irtt_proto::{flags, Params, TimestampFields, PROTOCOL_VERSION};
 
@@ -11,16 +14,82 @@ use crate::{
     config::{ClientConfig, RecvBudget},
     error::ClientError,
     event::{ClientEvent, OpenOutcome},
-    receive::recv_datagram,
-    runtime::{recv_buffer_size, SendProbeResult, SessionRuntime, MAX_OPEN_PACKET_SIZE},
+    receive::{drain_tx_timestamps, recv_datagram, try_enable_tx_timestamping, ReceivedDatagram},
+    session::machine::{
+        recv_buffer_size, OpenDatagramDisposition, PreparedOpenAcceptance, ProbeSent,
+        SessionMachine, MAX_OPEN_PACKET_SIZE,
+    },
     socket::{connect_udp_socket, resolve_remote, validate_open_timeouts},
-    socket_options::{apply_dscp_to_socket, clear_dscp_on_socket},
+    socket_options::{apply_traffic_class_to_socket, clear_dscp_on_socket},
     timing::ClientTimestamp,
 };
 
+pub(crate) mod schedule;
+
+use schedule::{instant_abs_diff, ProbeSchedule};
+
+#[derive(Debug, Clone, Copy)]
+enum ProbeScheduleMode {
+    CallerPaced,
+    #[cfg(test)]
+    Managed {
+        scheduled_at: Instant,
+    },
+}
+
+#[derive(Debug)]
+struct PreparedClientOpen {
+    machine: PreparedOpenAcceptance,
+    schedule: Option<ProbeSchedule>,
+    recv_buffer_len: Option<usize>,
+    negotiated_traffic_class: Option<u8>,
+    previous_traffic_class: Option<u8>,
+    post_open_recv_timeout: Option<Duration>,
+}
+
+#[derive(Debug)]
+struct PreparedClientOpenFailure {
+    primary: ClientError,
+    machine: PreparedOpenAcceptance,
+}
+
+#[cfg(test)]
+#[derive(Debug, Default)]
+struct ClientTestHooks {
+    fail_open_dscp: Cell<bool>,
+    fail_open_timeout_restore: Cell<bool>,
+    fail_close_event_reserve: Cell<bool>,
+    fail_close_dscp_clear: Cell<bool>,
+    fail_close_send: Cell<bool>,
+    close_reported_len: Cell<Option<usize>>,
+    close_send_attempts: Cell<usize>,
+    close_sent_at: Cell<Option<ClientTimestamp>>,
+    fail_cleanup_send: Cell<bool>,
+    recv_buffer_len_override: Cell<Option<usize>>,
+    fail_dscp_restore: Cell<bool>,
+    last_restored_read_timeout: Cell<Option<Duration>>,
+    prepared_active_session_before_dscp: Cell<bool>,
+    /// Number of subsequent receive attempts that should report
+    /// `io::ErrorKind::Interrupted` before a real receive is attempted.
+    /// Decremented on every injected receive; `0` means inject nothing.
+    inject_recv_interrupted: Cell<usize>,
+}
+
+#[cfg(test)]
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct ProbeSendTimestamps {
+    pub(crate) permission_at: Instant,
+    /// Private pre-send anchor: timeout deadline / kernel TX lower bound.
+    pub(crate) send_anchor: ClientTimestamp,
+    pub(crate) send_call_start: Instant,
+    pub(crate) send_finished_at: Instant,
+    /// Public post-send measurement: RTT / OWD fallback / timer_error.
+    pub(crate) sent_at: ClientTimestamp,
+}
+
 #[cfg(test)]
 use crate::{
-    runtime::{
+    session::machine::{
         compute_one_way, compute_rtt, params_from_config, sequence_is_after, sequence_is_before,
         unix_epoch_ns_i64, update_highest_received,
     },
@@ -32,14 +101,31 @@ use crate::{
 ///
 /// `Client` exposes the protocol steps directly: connect a UDP socket, open a
 /// session, send probes, receive replies, poll timeouts, and close. Callers
-/// that do not need to own this loop can use [`ManagedClient`](crate::ManagedClient)
-/// instead.
+/// that do not need to own this loop can use the unified managed API in
+/// [`crate::managed`] when the `tokio` feature is enabled.
 #[derive(Debug)]
 pub struct Client {
-    runtime: SessionRuntime,
+    runtime: SessionMachine,
+    schedule: Option<ProbeSchedule>,
     socket: UdpSocket,
     remote: SocketAddr,
     recv_buffer: Vec<u8>,
+    applied_traffic_class: Option<u8>,
+    /// Whether the socket's `SO_TIMESTAMPING` flags carry `TX_SOFTWARE` +
+    /// `OPT_ID` + `OPT_TSONLY`. Always `false` off Linux, without the
+    /// `ancillary` feature, or before the best-effort post-Open upgrade;
+    /// tracked here (adapter-owned capability, not protocol state) so
+    /// unnecessary error-queue drains are skipped once it is known there is
+    /// nothing to drain.
+    tx_timestamping_enabled: bool,
+    #[cfg(test)]
+    test_hooks: ClientTestHooks,
+    #[cfg(test)]
+    probe_reported_len: Option<usize>,
+    #[cfg(test)]
+    probe_send_error: bool,
+    #[cfg(test)]
+    probe_send_timestamps: Option<ProbeSendTimestamps>,
 }
 
 impl Client {
@@ -51,14 +137,25 @@ impl Client {
     pub fn connect(config: ClientConfig) -> Result<Self, ClientError> {
         validate_open_timeouts(&config.open_timeouts)?;
         let remote = resolve_remote(&config)?;
-        let runtime = SessionRuntime::new(config.clone(), remote)?;
+        let runtime = SessionMachine::new(config.clone(), remote)?;
         let socket = connect_udp_socket(&config.socket_config, remote)?;
 
         Ok(Self {
             runtime,
+            schedule: None,
             socket,
             remote,
             recv_buffer: vec![0_u8; recv_buffer_size(false, None)?],
+            applied_traffic_class: None,
+            tx_timestamping_enabled: false,
+            #[cfg(test)]
+            test_hooks: ClientTestHooks::default(),
+            #[cfg(test)]
+            probe_reported_len: None,
+            #[cfg(test)]
+            probe_send_error: false,
+            #[cfg(test)]
+            probe_send_timestamps: None,
         })
     }
 
@@ -66,82 +163,86 @@ impl Client {
     ///
     /// On success, returns the negotiated open outcome and transitions the
     /// client into either an open probe session or completed no-test state.
-    /// Open attempts use [`ClientConfig::open_timeouts`].
+    /// Open attempts use [`ClientConfig::open_timeouts`]. Malformed or
+    /// unrelated datagrams are ignored until the current attempt's absolute
+    /// deadline, so one attempt may consume several datagrams without
+    /// retransmitting. Silence or ignored traffic eventually produces
+    /// [`ClientError::OpenTimeout`]. A structurally recognizable malformed or
+    /// incompatible Open reply from the connected peer is terminal; when HMAC
+    /// is configured, that recognition additionally requires authentication.
+    ///
+    /// When a trusted reply allocates a token but later negotiation or socket
+    /// preparation fails, the client sends a best-effort cleanup close and
+    /// preserves the original failure. Failed opening never leaves the session
+    /// machine open.
     pub fn open(&mut self) -> Result<OpenOutcome, ClientError> {
-        let outcome = (|| -> Result<OpenOutcome, ClientError> {
-            let packet = self.runtime.open_packet()?;
-            let mut buf = [0_u8; MAX_OPEN_PACKET_SIZE];
-
-            for timeout in &self.runtime.config().open_timeouts {
-                self.socket.set_read_timeout(Some(*timeout))?;
-                self.socket.send(&packet)?;
-
-                match self.socket.recv(&mut buf) {
-                    Ok(size) => {
-                        let reply = self.runtime.decode_open_reply(&buf[..size])?;
-                        let remote = self.remote;
-                        let has_hmac = self.runtime.has_hmac();
-                        let socket = &self.socket;
-                        let recv_buffer = &mut self.recv_buffer;
-
-                        return self.runtime.accept_open_reply(
-                            reply,
-                            ClientTimestamp::now(),
-                            |negotiated| {
-                                let size = recv_buffer_size(has_hmac, Some(negotiated))?;
-                                let negotiated_dscp = u8::try_from(negotiated.params.dscp)
-                                    .map_err(|_| ClientError::InvalidConfig {
-                                        reason: "negotiated dscp must be in range 0..=63"
-                                            .to_owned(),
-                                    })?;
-                                apply_dscp_to_socket(socket, remote, negotiated_dscp)?;
-                                recv_buffer.resize(size, 0);
-                                Ok(())
-                            },
-                        );
-                    }
-                    Err(err)
-                        if matches!(
-                            err.kind(),
-                            io::ErrorKind::WouldBlock | io::ErrorKind::TimedOut
-                        ) => {}
-                    Err(err) => return Err(ClientError::Socket(err)),
-                }
-            }
-
-            Err(ClientError::OpenTimeout)
-        })();
-
-        let restore = self
-            .socket
-            .set_read_timeout(self.runtime.config().socket_config.recv_timeout);
-
-        match (outcome, restore) {
-            (Ok(outcome), Ok(())) => Ok(outcome),
-            (Ok(_), Err(source)) => Err(ClientError::ReadTimeoutRestore { source }),
-            (Err(err), Ok(())) => Err(err),
-            (Err(err), Err(_)) => Err(err),
+        let result = self.open_transaction();
+        if result.is_err() {
+            let _ =
+                self.restore_open_read_timeout(self.runtime.config().socket_config.recv_timeout);
         }
+        result
     }
 
     /// Send a close request and emit a [`ClientEvent::SessionClosed`] event.
     ///
     /// The close event means the client has sent its close packet and stopped
-    /// tracking the session locally; it is not a server acknowledgement.
+    /// tracking the session locally; it is not a server acknowledgement. If the
+    /// send fails, the negotiated DSCP is restored best-effort and the session
+    /// and probe schedule remain open.
     pub fn close(&mut self) -> Result<Vec<ClientEvent>, ClientError> {
-        let socket = &self.socket;
-        let remote = self.remote;
-        self.runtime.close_with(|packet| {
-            clear_dscp_on_socket(socket, remote)?;
-            socket.send(packet)?;
-            Ok(())
-        })
+        let prepared = self.runtime.prepare_close()?;
+        let mut events = Vec::new();
+        #[cfg(test)]
+        if self.test_hooks.fail_close_event_reserve.replace(false) {
+            events
+                .try_reserve(usize::MAX)
+                .map_err(|source| ClientError::AllocationFailed {
+                    operation: "close event result",
+                    source,
+                })?;
+        }
+        events
+            .try_reserve(1)
+            .map_err(|source| ClientError::AllocationFailed {
+                operation: "close event result",
+                source,
+            })?;
+        let previous_traffic_class = self.applied_traffic_class;
+        let expected_bytes = prepared.bytes.len();
+
+        self.clear_close_dscp()?;
+        let bytes = match self.send_close_datagram(prepared.bytes) {
+            Ok(bytes) => bytes,
+            Err(err) => {
+                self.restore_dscp_best_effort(previous_traffic_class);
+                return Err(ClientError::Socket(err));
+            }
+        };
+        #[cfg(not(test))]
+        let sent_at = ClientTimestamp::now();
+        #[cfg(test)]
+        let sent_at = self
+            .test_hooks
+            .close_sent_at
+            .take()
+            .unwrap_or_else(ClientTimestamp::now);
+        let event = self.runtime.commit_local_close(prepared.commit, sent_at);
+        self.schedule = None;
+        self.applied_traffic_class = None;
+
+        validate_datagram_length(expected_bytes, bytes)?;
+        events.push(event);
+        Ok(events)
     }
 
     /// Return the monotonic deadline for the next probe send, if another probe
     /// is scheduled.
     pub fn next_send_deadline(&self) -> Option<Instant> {
-        self.runtime.next_send_deadline()
+        if !self.runtime.is_open() {
+            return None;
+        }
+        self.schedule.as_ref()?.next_send_deadline()
     }
 
     /// Return the local timeout used to classify pending probes as lost.
@@ -155,7 +256,7 @@ impl Client {
     /// list when the run duration has elapsed and no further probe should be
     /// sent.
     pub fn send_probe(&mut self) -> Result<Vec<ClientEvent>, ClientError> {
-        self.send_probe_inner(None)
+        self.send_probe_transaction(ProbeScheduleMode::CallerPaced)
     }
 
     /// Receive and classify at most one datagram from the socket.
@@ -163,32 +264,139 @@ impl Client {
     /// Returns an empty event list when the socket read would block or times
     /// out. Malformed or unrelated datagrams are reported as warning events.
     pub fn recv_once(&mut self) -> Result<Vec<ClientEvent>, ClientError> {
-        let datagram = match recv_datagram(&self.socket, &mut self.recv_buffer) {
-            Ok(datagram) => datagram,
-            Err(err)
-                if matches!(
-                    err.kind(),
-                    io::ErrorKind::WouldBlock | io::ErrorKind::TimedOut
-                ) =>
-            {
-                return Ok(vec![]);
+        self.socket
+            .set_read_timeout(self.runtime.config().socket_config.recv_timeout)?;
+        self.recv_once_inner()
+    }
+
+    /// Receive one datagram into `self.recv_buffer`. In test builds, a
+    /// pending `inject_recv_interrupted` count reports
+    /// `io::ErrorKind::Interrupted` instead of performing a real receive,
+    /// deterministically exercising interrupted-syscall retry behavior.
+    fn recv_datagram_once(&mut self) -> Result<ReceivedDatagram, io::Error> {
+        #[cfg(test)]
+        {
+            let remaining = self.test_hooks.inject_recv_interrupted.get();
+            if remaining > 0 {
+                self.test_hooks.inject_recv_interrupted.set(remaining - 1);
+                return Err(io::Error::from(io::ErrorKind::Interrupted));
             }
-            Err(err) => return Err(ClientError::Socket(err)),
+        }
+        recv_datagram(&self.socket, &mut self.recv_buffer)
+    }
+
+    /// Same as [`Self::recv_datagram_once`], receiving into a caller-supplied
+    /// buffer instead of `self.recv_buffer` (used before the negotiated
+    /// receive buffer size is known, i.e. during Open).
+    fn recv_datagram_once_into(&self, buf: &mut [u8]) -> Result<ReceivedDatagram, io::Error> {
+        #[cfg(test)]
+        {
+            let remaining = self.test_hooks.inject_recv_interrupted.get();
+            if remaining > 0 {
+                self.test_hooks.inject_recv_interrupted.set(remaining - 1);
+                return Err(io::Error::from(io::ErrorKind::Interrupted));
+            }
+        }
+        recv_datagram(&self.socket, buf)
+    }
+
+    fn recv_once_inner(&mut self) -> Result<Vec<ClientEvent>, ClientError> {
+        let Some(datagram) = self.recv_datagram_retrying_interrupted()? else {
+            return Ok(vec![]);
         };
 
-        self.runtime.process_received_echo_packet(
+        // One final bounded drain before processing the reply, so a TX
+        // timestamp that raced the reply is still associated with its probe
+        // before that probe is looked up and possibly removed below.
+        self.drain_tx_timestamps()?;
+
+        let events = self.runtime.process_received_echo_packet(
             &self.recv_buffer[..datagram.len],
             datagram.received_at,
             datagram.meta,
-        )
+        )?;
+        if self.runtime.is_peer_closed() {
+            self.schedule = None;
+            if self.clear_close_dscp().is_ok() {
+                self.applied_traffic_class = None;
+            }
+        }
+        Ok(events)
+    }
+
+    /// Receive one datagram, transparently retrying an interrupted syscall
+    /// (`io::ErrorKind::Interrupted`, e.g. `EINTR`) without treating it as a
+    /// genuine socket error, timeout, or empty receive.
+    ///
+    /// One logical receive keeps one timeout budget: when a receive timeout
+    /// is configured, an absolute deadline is computed once here and each
+    /// retry after an interruption restores the socket's remaining time
+    /// against that same deadline, so repeated interruptions cannot extend
+    /// this receive past its configured timeout. An unconfigured timeout
+    /// (`None`) keeps blocking indefinitely after an interruption, matching
+    /// its no-timeout contract. The socket's read timeout is restored to the
+    /// caller-configured value before returning, so a later call in the same
+    /// `recv_available` budget is unaffected by an earlier interruption here.
+    fn recv_datagram_retrying_interrupted(
+        &mut self,
+    ) -> Result<Option<ReceivedDatagram>, ClientError> {
+        let configured_timeout = self.runtime.config().socket_config.recv_timeout;
+        let deadline = match configured_timeout {
+            Some(timeout) => Some(
+                Instant::now()
+                    .checked_add(timeout)
+                    .ok_or(ClientError::DurationOverflow)?,
+            ),
+            None => None,
+        };
+        let mut timeout_narrowed = false;
+
+        let result = loop {
+            match self.recv_datagram_once() {
+                Ok(datagram) => break Ok(Some(datagram)),
+                Err(err)
+                    if matches!(
+                        err.kind(),
+                        io::ErrorKind::WouldBlock | io::ErrorKind::TimedOut
+                    ) =>
+                {
+                    break Ok(None);
+                }
+                Err(err) if err.kind() == io::ErrorKind::Interrupted => {
+                    if let Some(deadline) = deadline {
+                        let Some(remaining) = deadline.checked_duration_since(Instant::now())
+                        else {
+                            break Ok(None);
+                        };
+                        if remaining.is_zero() {
+                            break Ok(None);
+                        }
+                        if let Err(err) = self.socket.set_read_timeout(Some(remaining)) {
+                            break Err(ClientError::Socket(err));
+                        }
+                        timeout_narrowed = true;
+                    }
+                }
+                Err(err) => break Err(ClientError::Socket(err)),
+            }
+        };
+
+        if timeout_narrowed {
+            if let Err(err) = self.socket.set_read_timeout(configured_timeout) {
+                return Err(ClientError::Socket(err));
+            }
+        }
+        result
     }
 
     /// Receive and classify datagrams until a receive produces no events or the
     /// receive budget is exhausted.
     pub fn recv_available(&mut self, budget: RecvBudget) -> Result<Vec<ClientEvent>, ClientError> {
+        self.socket
+            .set_read_timeout(self.runtime.config().socket_config.recv_timeout)?;
         let mut all_events = Vec::new();
         for _ in 0..budget.max_packets {
-            let events = self.recv_once()?;
+            let events = self.recv_once_inner()?;
             if events.is_empty() {
                 break;
             }
@@ -213,6 +421,7 @@ impl Client {
     ///
     /// `now` is monotonic time only; wall-clock time is not used for timeout expiry.
     pub fn poll_timeouts_at(&mut self, now: Instant) -> Result<Vec<ClientEvent>, ClientError> {
+        self.drain_tx_timestamps()?;
         self.runtime.poll_timeouts_at(now)
     }
 
@@ -222,7 +431,11 @@ impl Client {
     /// pending probes have either replied or timed out. No-test and closed
     /// sessions are also considered complete.
     pub fn is_run_complete(&self) -> bool {
-        self.runtime.is_run_complete()
+        self.runtime.is_terminal()
+            || self
+                .schedule
+                .as_ref()
+                .is_some_and(|schedule| schedule.is_finished() && self.runtime.pending_is_empty())
     }
 
     /// Return whether the session was closed by a peer close-flagged reply.
@@ -235,39 +448,485 @@ impl Client {
         self.runtime.is_peer_closed()
     }
 
-    pub(crate) fn has_timed_out_metadata(&self) -> bool {
-        self.runtime.has_timed_out_metadata()
-    }
-
-    pub(crate) fn packets_sent(&self) -> u64 {
-        self.runtime.packets_sent()
-    }
-
-    fn send_probe_inner(
+    #[cfg(test)]
+    pub(crate) fn send_managed_probe(
         &mut self,
-        override_ts: Option<ClientTimestamp>,
+        scheduled_at: Instant,
     ) -> Result<Vec<ClientEvent>, ClientError> {
-        let socket = &self.socket;
-        self.runtime.send_probe_with(override_ts, |packet| {
-            let sent_at = override_ts.unwrap_or_else(ClientTimestamp::now);
-            let send_call_start = Instant::now();
-            let bytes = socket.send(packet)?;
-            let send_call = send_call_start.elapsed();
-            Ok(SendProbeResult {
-                sent_at,
-                bytes,
-                send_call,
-            })
+        self.send_probe_transaction(ProbeScheduleMode::Managed { scheduled_at })
+    }
+
+    fn send_probe_transaction(
+        &mut self,
+        mode: ProbeScheduleMode,
+    ) -> Result<Vec<ClientEvent>, ClientError> {
+        self.runtime.ensure_open()?;
+        #[cfg(test)]
+        let test_timestamps = self.probe_send_timestamps.take();
+        #[cfg(test)]
+        let fail_send = std::mem::take(&mut self.probe_send_error);
+        let remote = self.remote;
+        let (runtime, schedule, socket) = (&mut self.runtime, &mut self.schedule, &self.socket);
+        let schedule = schedule
+            .as_mut()
+            .expect("open sessions always have a probe schedule");
+        #[cfg(not(test))]
+        let permission_at = Instant::now();
+        #[cfg(test)]
+        let permission_at = test_timestamps
+            .map(|timestamps| timestamps.permission_at)
+            .unwrap_or_else(Instant::now);
+        if !schedule.permit_probe_at(permission_at) {
+            return Ok(Vec::new());
+        }
+
+        let Some(prepared) = runtime.prepare_probe()? else {
+            return Ok(Vec::new());
+        };
+        let machine_preflight = runtime.preflight_probe_commit(&prepared)?;
+        let schedule_commit = match mode {
+            ProbeScheduleMode::CallerPaced => {
+                schedule.preflight_caller_commit(machine_preflight.next_packets_sent)?
+            }
+            #[cfg(test)]
+            ProbeScheduleMode::Managed { scheduled_at } => {
+                schedule.preflight_managed_commit(scheduled_at, permission_at)?
+            }
+        };
+        let mut events = Vec::new();
+        events
+            .try_reserve(1)
+            .map_err(|source| ClientError::AllocationFailed {
+                operation: "probe event result",
+                source,
+            })?;
+
+        let expected_bytes = prepared.bytes.len();
+        let scheduled_at = schedule_commit.scheduled_at;
+        #[cfg(test)]
+        let reported_bytes = self.probe_reported_len.take();
+        // All fallible probe-commit preflight (timeout deadline arithmetic,
+        // capacity/collision checks already done above) is finalized from
+        // this PRIVATE pre-send anchor, before the socket send. It is not
+        // the public measurement `sent_at` captured further below.
+        #[cfg(not(test))]
+        let send_anchor = ClientTimestamp::now();
+        #[cfg(test)]
+        let send_anchor = test_timestamps
+            .map(|timestamps| timestamps.send_anchor)
+            .unwrap_or_else(ClientTimestamp::now);
+        let machine_commit = runtime.finalize_probe_commit(machine_preflight, send_anchor)?;
+        #[cfg(not(test))]
+        let send_call_start = Instant::now();
+        #[cfg(test)]
+        let send_call_start = test_timestamps
+            .map(|timestamps| timestamps.send_call_start)
+            .unwrap_or_else(Instant::now);
+        #[cfg(test)]
+        if fail_send {
+            runtime.invalidate_kernel_tx_correlation();
+            return Err(ClientError::Socket(io::Error::other(
+                "injected probe send failure",
+            )));
+        }
+        let bytes = match socket.send(&prepared.bytes) {
+            Ok(bytes) => bytes,
+            Err(error) => {
+                runtime.invalidate_kernel_tx_correlation();
+                return Err(ClientError::Socket(error));
+            }
+        };
+        #[cfg(not(test))]
+        let send_finished_at = Instant::now();
+        #[cfg(test)]
+        let send_finished_at = test_timestamps
+            .map(|timestamps| timestamps.send_finished_at)
+            .unwrap_or_else(Instant::now);
+        // The public measurement timestamp: paired wall/monotonic sample
+        // captured immediately after the successful socket send completed.
+        // This, not `send_anchor` above, is the RTT/OWD-fallback/timer_error
+        // endpoint. The infallible machine/schedule commit below never fails.
+        #[cfg(not(test))]
+        let sent_at = ClientTimestamp::now();
+        #[cfg(test)]
+        let sent_at = test_timestamps
+            .map(|timestamps| timestamps.sent_at)
+            .unwrap_or_else(ClientTimestamp::now);
+        let sent = runtime.commit_probe_sent(machine_commit, sent_at, bytes);
+        schedule.commit(schedule_commit);
+
+        let send_call = send_finished_at.saturating_duration_since(send_call_start);
+        let timer_error = instant_abs_diff(sent_at.mono, scheduled_at);
+        #[cfg(test)]
+        let bytes = reported_bytes.unwrap_or(bytes);
+        validate_datagram_length(expected_bytes, bytes)?;
+        self.drain_tx_timestamps()?;
+
+        events.push(echo_sent_event(
+            remote,
+            sent,
+            send_call,
+            scheduled_at,
+            timer_error,
+        ));
+        Ok(events)
+    }
+
+    fn open_transaction(&mut self) -> Result<OpenOutcome, ClientError> {
+        let request = self.runtime.prepare_open_request()?;
+        let mut buf = [0_u8; MAX_OPEN_PACKET_SIZE];
+        let attempt_count = self.runtime.config().open_timeouts.len();
+
+        for attempt in 0..attempt_count {
+            let timeout = self.runtime.config().open_timeouts[attempt];
+            let deadline = Instant::now()
+                .checked_add(timeout)
+                .ok_or(ClientError::DurationOverflow)?;
+            self.socket.set_read_timeout(Some(timeout))?;
+            self.socket.send(&request.bytes)?;
+
+            loop {
+                let now = Instant::now();
+                let Some(remaining) = deadline.checked_duration_since(now) else {
+                    break;
+                };
+                if remaining.is_zero() {
+                    break;
+                }
+                self.socket.set_read_timeout(Some(remaining))?;
+
+                let datagram = match self.recv_datagram_once_into(&mut buf) {
+                    Ok(datagram) => datagram,
+                    // WouldBlock/TimedOut mean the attempt's own deadline
+                    // elapsed; Interrupted (EINTR) means the syscall was
+                    // merely interrupted and carries no timing information of
+                    // its own. Both retry through the same loop, which
+                    // recomputes `remaining` and re-applies it as the read
+                    // timeout on every iteration — so an interruption resumes
+                    // within this same absolute deadline rather than
+                    // resetting or extending it.
+                    Err(err)
+                        if matches!(
+                            err.kind(),
+                            io::ErrorKind::WouldBlock
+                                | io::ErrorKind::TimedOut
+                                | io::ErrorKind::Interrupted
+                        ) =>
+                    {
+                        if Instant::now() >= deadline {
+                            break;
+                        }
+                        continue;
+                    }
+                    Err(err) => return Err(ClientError::Socket(err)),
+                };
+                if datagram.received_at.mono > deadline {
+                    break;
+                }
+
+                let reply = match self.runtime.inspect_open_datagram(&buf[..datagram.len])? {
+                    OpenDatagramDisposition::Ignore => continue,
+                    OpenDatagramDisposition::Trusted(reply) => reply,
+                };
+                let machine = match self
+                    .runtime
+                    .prepare_open_acceptance(reply, datagram.received_at)
+                {
+                    Ok(machine) => machine,
+                    Err(failure) => {
+                        self.send_cleanup_close_best_effort(failure.cleanup_close.as_deref());
+                        return Err(failure.primary);
+                    }
+                };
+                let prepared = match self.prepare_client_open(machine, datagram.received_at) {
+                    Ok(prepared) => prepared,
+                    Err(failure) => {
+                        self.send_cleanup_close_best_effort(failure.machine.cleanup_close_packet());
+                        return Err(failure.primary);
+                    }
+                };
+                return self.apply_prepared_open(prepared);
+            }
+        }
+
+        Err(ClientError::OpenTimeout)
+    }
+
+    fn prepare_client_open(
+        &self,
+        machine: PreparedOpenAcceptance,
+        opened_at: ClientTimestamp,
+    ) -> Result<PreparedClientOpen, Box<PreparedClientOpenFailure>> {
+        let Some(negotiated) = machine.normal_negotiated() else {
+            return Ok(PreparedClientOpen {
+                machine,
+                schedule: None,
+                recv_buffer_len: None,
+                negotiated_traffic_class: None,
+                previous_traffic_class: self.applied_traffic_class,
+                post_open_recv_timeout: self.runtime.config().socket_config.recv_timeout,
+            });
+        };
+        let schedule = match ProbeSchedule::new(opened_at.mono, negotiated) {
+            Ok(schedule) => schedule,
+            Err(primary) => return Err(Box::new(PreparedClientOpenFailure { primary, machine })),
+        };
+        let recv_buffer_len = match recv_buffer_size(self.runtime.has_hmac(), Some(negotiated)) {
+            Ok(size) => size,
+            Err(primary) => return Err(Box::new(PreparedClientOpenFailure { primary, machine })),
+        };
+        #[cfg(test)]
+        let recv_buffer_len = self
+            .test_hooks
+            .recv_buffer_len_override
+            .get()
+            .unwrap_or(recv_buffer_len);
+        let negotiated_traffic_class = match u8::try_from(negotiated.params.dscp) {
+            Ok(traffic_class) => traffic_class,
+            Err(_) => {
+                return Err(Box::new(PreparedClientOpenFailure {
+                    primary: ClientError::InvalidConfig {
+                        reason: "negotiated dscp must be in range 0..=255".to_owned(),
+                    },
+                    machine,
+                }));
+            }
+        };
+
+        Ok(PreparedClientOpen {
+            machine,
+            schedule: Some(schedule),
+            recv_buffer_len: Some(recv_buffer_len),
+            negotiated_traffic_class: Some(negotiated_traffic_class),
+            previous_traffic_class: self.applied_traffic_class,
+            post_open_recv_timeout: self.runtime.config().socket_config.recv_timeout,
         })
     }
+
+    fn apply_prepared_open(
+        &mut self,
+        prepared: PreparedClientOpen,
+    ) -> Result<OpenOutcome, ClientError> {
+        let PreparedClientOpen {
+            machine,
+            schedule,
+            recv_buffer_len,
+            negotiated_traffic_class,
+            previous_traffic_class,
+            post_open_recv_timeout,
+        } = prepared;
+
+        if let (Some(recv_buffer_len), Some(negotiated_traffic_class)) =
+            (recv_buffer_len, negotiated_traffic_class)
+        {
+            let previous_len = self.recv_buffer.len();
+            let additional = recv_buffer_len.saturating_sub(previous_len);
+            if let Err(source) = self.recv_buffer.try_reserve(additional) {
+                self.send_cleanup_close_best_effort(machine.cleanup_close_packet());
+                return Err(ClientError::AllocationFailed {
+                    operation: "negotiated receive buffer",
+                    source,
+                });
+            }
+            self.recv_buffer.resize(recv_buffer_len, 0);
+
+            #[cfg(test)]
+            self.test_hooks
+                .prepared_active_session_before_dscp
+                .set(machine.has_prepared_active_session());
+            if let Err(primary) = self.apply_open_dscp(negotiated_traffic_class) {
+                self.recv_buffer.truncate(previous_len);
+                self.restore_dscp_best_effort(previous_traffic_class);
+                self.send_cleanup_close_best_effort(machine.cleanup_close_packet());
+                return Err(primary);
+            }
+            if let Err(source) = self.restore_open_read_timeout(post_open_recv_timeout) {
+                let primary = ClientError::ReadTimeoutRestore { source };
+                self.recv_buffer.truncate(previous_len);
+                self.restore_dscp_best_effort(previous_traffic_class);
+                self.send_cleanup_close_best_effort(machine.cleanup_close_packet());
+                return Err(primary);
+            }
+
+            let outcome = self.runtime.commit_open(machine);
+            self.schedule = schedule;
+            self.applied_traffic_class = Some(negotiated_traffic_class);
+            self.tx_timestamping_enabled = try_enable_tx_timestamping(&self.socket);
+            Ok(outcome)
+        } else {
+            debug_assert!(schedule.is_none());
+            if let Err(source) = self.restore_open_read_timeout(post_open_recv_timeout) {
+                return Err(ClientError::ReadTimeoutRestore { source });
+            }
+            let outcome = self.runtime.commit_open(machine);
+            self.schedule = None;
+            self.applied_traffic_class = None;
+            self.tx_timestamping_enabled = try_enable_tx_timestamping(&self.socket);
+            Ok(outcome)
+        }
+    }
+
+    /// Best-effort, bounded, nonblocking drain of the socket's
+    /// `MSG_ERRQUEUE`. A no-op unless [`Self::apply_prepared_open`]
+    /// successfully upgraded the socket to TX timestamping. Any TX
+    /// timestamp found is handed to the session machine to attach to its
+    /// matching probe; a genuine socket/network error found on the queue is
+    /// surfaced through the normal socket-error path.
+    fn drain_tx_timestamps(&mut self) -> Result<(), ClientError> {
+        if !self.tx_timestamping_enabled {
+            return Ok(());
+        }
+        let runtime = &mut self.runtime;
+        drain_tx_timestamps(&self.socket, |id, timestamp| {
+            runtime.record_kernel_tx_timestamp(id, timestamp);
+        })
+        .map_err(ClientError::Socket)
+    }
+
+    fn restore_dscp_best_effort(&self, previous_traffic_class: Option<u8>) {
+        #[cfg(test)]
+        if self.test_hooks.fail_dscp_restore.replace(false) {
+            return;
+        }
+        let _ = match previous_traffic_class {
+            Some(traffic_class) => {
+                apply_traffic_class_to_socket(&self.socket, self.remote, traffic_class)
+            }
+            None => clear_dscp_on_socket(&self.socket, self.remote),
+        };
+    }
+
+    fn clear_close_dscp(&self) -> Result<(), ClientError> {
+        #[cfg(test)]
+        if self.test_hooks.fail_close_dscp_clear.replace(false) {
+            return Err(ClientError::SocketOption {
+                operation: "clear negotiated DSCP",
+                remote: self.remote,
+                source: io::Error::other("injected negotiated DSCP clear failure"),
+            });
+        }
+        clear_dscp_on_socket(&self.socket, self.remote)
+    }
+
+    fn send_cleanup_close_best_effort(&self, packet: Option<&[u8]>) {
+        if let Some(packet) = packet {
+            #[cfg(test)]
+            if self.test_hooks.fail_cleanup_send.replace(false) {
+                return;
+            }
+            let _ = self.socket.send(packet);
+        }
+    }
+
+    fn apply_open_dscp(&self, traffic_class: u8) -> Result<(), ClientError> {
+        #[cfg(test)]
+        if self.test_hooks.fail_open_dscp.replace(false) {
+            return Err(ClientError::SocketOption {
+                operation: "set negotiated DSCP",
+                remote: self.remote,
+                source: io::Error::other("injected negotiated DSCP failure"),
+            });
+        }
+        apply_traffic_class_to_socket(&self.socket, self.remote, traffic_class)
+    }
+
+    fn restore_open_read_timeout(&self, timeout: Option<Duration>) -> io::Result<()> {
+        #[cfg(test)]
+        self.test_hooks.last_restored_read_timeout.set(timeout);
+        #[cfg(test)]
+        if self.test_hooks.fail_open_timeout_restore.replace(false) {
+            return Err(io::Error::other(
+                "injected configured read timeout restoration failure",
+            ));
+        }
+        self.socket.set_read_timeout(timeout)
+    }
+
+    fn send_close_datagram(&self, packet: &[u8]) -> io::Result<usize> {
+        #[cfg(test)]
+        {
+            self.test_hooks
+                .close_send_attempts
+                .set(self.test_hooks.close_send_attempts.get() + 1);
+            if self.test_hooks.fail_close_send.replace(false) {
+                return Err(io::Error::other("injected close send failure"));
+            }
+        }
+        let bytes = self.socket.send(packet)?;
+        #[cfg(test)]
+        if let Some(reported) = self.test_hooks.close_reported_len.take() {
+            return Ok(reported);
+        }
+        Ok(bytes)
+    }
+}
+
+pub(crate) fn echo_sent_event(
+    remote: SocketAddr,
+    sent: ProbeSent,
+    send_call: Duration,
+    scheduled_at: Instant,
+    timer_error: Duration,
+) -> ClientEvent {
+    ClientEvent::EchoSent {
+        seq: sent.seq,
+        remote,
+        scheduled_at,
+        sent_at: sent.sent_at,
+        bytes: sent.bytes,
+        send_call,
+        timer_error,
+    }
+}
+
+pub(crate) fn validate_datagram_length(expected: usize, actual: usize) -> Result<(), ClientError> {
+    if actual == expected {
+        Ok(())
+    } else {
+        Err(ClientError::DatagramLengthMismatch { expected, actual })
+    }
 }
 
 #[cfg(test)]
 impl Client {
-    fn send_probe_at(&mut self, ts: ClientTimestamp) -> Result<Vec<ClientEvent>, ClientError> {
-        self.send_probe_inner(Some(ts))
+    fn send_probe_at(
+        &mut self,
+        timestamps: ProbeSendTimestamps,
+    ) -> Result<Vec<ClientEvent>, ClientError> {
+        self.probe_send_timestamps = Some(timestamps);
+        self.send_probe()
+    }
+
+    fn send_managed_probe_at(
+        &mut self,
+        scheduled_at: Instant,
+        timestamps: ProbeSendTimestamps,
+    ) -> Result<Vec<ClientEvent>, ClientError> {
+        self.probe_send_timestamps = Some(timestamps);
+        self.send_managed_probe(scheduled_at)
     }
 }
 
+#[cfg(test)]
+fn bounded_receive_timeout(
+    deadline: Option<Instant>,
+    configured_timeout: Option<Duration>,
+    max_wait: Duration,
+    now: Instant,
+) -> Option<Duration> {
+    if max_wait.is_zero() {
+        return None;
+    }
+    let mut timeout = configured_timeout.unwrap_or(max_wait).min(max_wait);
+    if let Some(deadline) = deadline {
+        let remaining = deadline.checked_duration_since(now)?;
+        if remaining.is_zero() {
+            return None;
+        }
+        timeout = timeout.min(remaining);
+    }
+    (!timeout.is_zero()).then_some(timeout)
+}
+
 #[cfg(test)]
 mod tests;

crates/irtt-client/src/client/schedule.rs

@@ -0,0 +1,318 @@
+use std::time::{Duration, Instant};
+
+use crate::{error::ClientError, session::NegotiatedParams};
+
+#[derive(Debug)]
+pub(crate) struct ProbeSchedule {
+    start_at: Instant,
+    end_at: Option<Instant>,
+    interval: Duration,
+    next_send_at: Option<Instant>,
+}
+
+#[derive(Debug)]
+pub(crate) struct ScheduleCommit {
+    pub(crate) scheduled_at: Instant,
+    pub(crate) next_send_at: Option<Instant>,
+}
+
+impl ProbeSchedule {
+    pub(crate) fn new(
+        start_at: Instant,
+        negotiated: &NegotiatedParams,
+    ) -> Result<Self, ClientError> {
+        let interval_ns = u64::try_from(negotiated.params.interval_ns)
+            .expect("validated positive negotiated interval");
+        let interval = Duration::from_nanos(interval_ns);
+        let end_at = if negotiated.params.duration_ns > 0 {
+            let duration_ns = u64::try_from(negotiated.params.duration_ns)
+                .expect("validated positive negotiated duration");
+            Some(
+                start_at
+                    .checked_add(Duration::from_nanos(duration_ns))
+                    .ok_or_else(|| ClientError::NegotiationRejected {
+                        reason: "duration is too large to schedule".to_owned(),
+                    })?,
+            )
+        } else {
+            None
+        };
+
+        Ok(Self {
+            start_at,
+            end_at,
+            interval,
+            next_send_at: Some(start_at),
+        })
+    }
+
+    pub(crate) fn next_send_deadline(&self) -> Option<Instant> {
+        self.next_send_at
+    }
+
+    #[cfg(feature = "tokio")]
+    pub(crate) fn interval(&self) -> Duration {
+        self.interval
+    }
+
+    pub(crate) fn permit_probe_at(&mut self, now: Instant) -> bool {
+        if self.next_send_at.is_none() {
+            return false;
+        }
+        if self.end_at.is_some_and(|end| now >= end) {
+            self.next_send_at = None;
+            return false;
+        }
+        true
+    }
+
+    pub(crate) fn preflight_caller_commit(
+        &self,
+        next_packets_sent: u64,
+    ) -> Result<ScheduleCommit, ClientError> {
+        let scheduled_at = self
+            .next_send_at
+            .expect("a caller schedule commit requires a permitted probe");
+        let interval_ns =
+            u64::try_from(self.interval.as_nanos()).map_err(|_| ClientError::DurationOverflow)?;
+        let next_send_at = next_probe_deadline(self.start_at, interval_ns, next_packets_sent)?;
+        Ok(self.finish_commit(scheduled_at, next_send_at))
+    }
+
+    #[cfg(any(feature = "tokio", test))]
+    pub(crate) fn preflight_managed_commit(
+        &self,
+        scheduled_at: Instant,
+        permission_at: Instant,
+    ) -> Result<ScheduleCommit, ClientError> {
+        let (scheduled_at, next_send_at, _) =
+            advance_cadence(scheduled_at, self.interval, permission_at)?;
+        Ok(self.finish_commit(scheduled_at, next_send_at))
+    }
+
+    pub(crate) fn commit(&mut self, commit: ScheduleCommit) {
+        self.next_send_at = commit.next_send_at;
+    }
+
+    pub(crate) fn is_finished(&self) -> bool {
+        self.next_send_at.is_none()
+    }
+
+    fn finish_commit(&self, scheduled_at: Instant, next_send_at: Instant) -> ScheduleCommit {
+        ScheduleCommit {
+            scheduled_at,
+            next_send_at: if self.end_at.is_some_and(|end| next_send_at >= end) {
+                None
+            } else {
+                Some(next_send_at)
+            },
+        }
+    }
+}
+
+fn next_probe_deadline(
+    start: Instant,
+    interval_ns: u64,
+    packets_sent: u64,
+) -> Result<Instant, ClientError> {
+    let offset_ns = interval_ns
+        .checked_mul(packets_sent)
+        .ok_or(ClientError::DurationOverflow)?;
+    start
+        .checked_add(Duration::from_nanos(offset_ns))
+        .ok_or(ClientError::DurationOverflow)
+}
+
+#[cfg(any(feature = "tokio", test))]
+pub(crate) fn advance_cadence(
+    deadline: Instant,
+    interval: Duration,
+    now: Instant,
+) -> Result<(Instant, Instant, u128), ClientError> {
+    if interval.is_zero() {
+        return Err(ClientError::InvalidConfig {
+            reason: "probe interval must be greater than zero".to_owned(),
+        });
+    }
+
+    let elapsed_slots = now
+        .checked_duration_since(deadline)
+        .map_or(0, |elapsed| elapsed.as_nanos() / interval.as_nanos());
+    let scheduled_offset = duration_from_nanos(
+        interval
+            .as_nanos()
+            .checked_mul(elapsed_slots)
+            .ok_or(ClientError::DurationOverflow)?,
+    )?;
+    let next_offset = duration_from_nanos(
+        interval
+            .as_nanos()
+            .checked_mul(
+                elapsed_slots
+                    .checked_add(1)
+                    .ok_or(ClientError::DurationOverflow)?,
+            )
+            .ok_or(ClientError::DurationOverflow)?,
+    )?;
+    let scheduled_at = deadline
+        .checked_add(scheduled_offset)
+        .ok_or(ClientError::DurationOverflow)?;
+    let next_at = deadline
+        .checked_add(next_offset)
+        .ok_or(ClientError::DurationOverflow)?;
+    Ok((scheduled_at, next_at, elapsed_slots))
+}
+
+#[cfg(any(feature = "tokio", test))]
+fn duration_from_nanos(nanos: u128) -> Result<Duration, ClientError> {
+    const NANOS_PER_SECOND: u128 = 1_000_000_000;
+    let seconds =
+        u64::try_from(nanos / NANOS_PER_SECOND).map_err(|_| ClientError::DurationOverflow)?;
+    let subsec_nanos = u32::try_from(nanos % NANOS_PER_SECOND)
+        .expect("nanosecond remainder is always less than one second");
+    Ok(Duration::new(seconds, subsec_nanos))
+}
+
+pub(crate) fn instant_abs_diff(left: Instant, right: Instant) -> Duration {
+    left.checked_duration_since(right)
+        .or_else(|| right.checked_duration_since(left))
+        .unwrap_or(Duration::ZERO)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use irtt_proto::Params;
+
+    fn negotiated(interval_ns: i64, duration_ns: i64) -> NegotiatedParams {
+        NegotiatedParams {
+            params: Params {
+                interval_ns,
+                duration_ns,
+                ..Params::default()
+            },
+            restrictions: Vec::new(),
+        }
+    }
+
+    #[test]
+    fn initial_deadline_is_the_opening_time() {
+        let opened_at = Instant::now();
+
+        let schedule = ProbeSchedule::new(opened_at, &negotiated(10_000_000, 0)).unwrap();
+
+        assert_eq!(schedule.next_send_deadline(), Some(opened_at));
+        assert!(!schedule.is_finished());
+    }
+
+    #[test]
+    fn caller_preflight_keeps_absolute_cadence_without_mutation() {
+        let start = Instant::now();
+        let schedule = ProbeSchedule::new(start, &negotiated(10_000_000, 0)).unwrap();
+
+        let commit = schedule.preflight_caller_commit(3).unwrap();
+
+        assert_eq!(commit.scheduled_at, start);
+        assert_eq!(commit.next_send_at, Some(start + Duration::from_millis(30)));
+        assert_eq!(schedule.next_send_deadline(), Some(start));
+    }
+
+    #[test]
+    fn caller_commit_advances_exactly_one_cadence_slot() {
+        let start = Instant::now();
+        let mut schedule = ProbeSchedule::new(start, &negotiated(10_000_000, 0)).unwrap();
+
+        let commit = schedule.preflight_caller_commit(1).unwrap();
+        assert_eq!(schedule.next_send_deadline(), Some(start));
+
+        schedule.commit(commit);
+        assert_eq!(
+            schedule.next_send_deadline(),
+            Some(start + Duration::from_millis(10))
+        );
+    }
+
+    #[test]
+    fn finite_duration_uses_an_exclusive_end_boundary() {
+        let start = Instant::now();
+        let mut schedule = ProbeSchedule::new(start, &negotiated(10_000_000, 20_000_000)).unwrap();
+
+        let first = schedule.preflight_caller_commit(1).unwrap();
+        schedule.commit(first);
+        assert_eq!(
+            schedule.next_send_deadline(),
+            Some(start + Duration::from_millis(10))
+        );
+
+        let second = schedule.preflight_caller_commit(2).unwrap();
+        schedule.commit(second);
+
+        assert!(schedule.is_finished());
+        assert_eq!(schedule.next_send_deadline(), None);
+        assert!(!schedule.permit_probe_at(start + Duration::from_millis(20)));
+    }
+
+    #[test]
+    fn permit_at_exclusive_end_finishes_schedule_without_a_send() {
+        let start = Instant::now();
+        let mut schedule = ProbeSchedule::new(start, &negotiated(10_000_000, 20_000_000)).unwrap();
+
+        assert!(!schedule.permit_probe_at(start + Duration::from_millis(20)));
+        assert!(schedule.is_finished());
+        assert_eq!(schedule.next_send_deadline(), None);
+    }
+
+    #[test]
+    fn managed_preflight_skips_missed_slots_without_mutation() {
+        let start = Instant::now();
+        let schedule = ProbeSchedule::new(start, &negotiated(10_000_000, 0)).unwrap();
+        let sent_at = start + Duration::from_millis(45);
+
+        let commit = schedule.preflight_managed_commit(start, sent_at).unwrap();
+
+        assert_eq!(commit.scheduled_at, start + Duration::from_millis(40));
+        assert_eq!(commit.next_send_at, Some(start + Duration::from_millis(50)));
+        assert_eq!(schedule.next_send_deadline(), Some(start));
+    }
+
+    #[test]
+    fn delayed_managed_commit_does_not_replay_catch_up_slots() {
+        let start = Instant::now();
+        let mut schedule = ProbeSchedule::new(start, &negotiated(10_000_000, 0)).unwrap();
+        let delayed_send = start + Duration::from_millis(45);
+
+        let commit = schedule
+            .preflight_managed_commit(start, delayed_send)
+            .unwrap();
+        schedule.commit(commit);
+
+        assert_eq!(
+            schedule.next_send_deadline(),
+            Some(start + Duration::from_millis(50))
+        );
+        assert!(schedule.next_send_deadline().unwrap() > delayed_send);
+    }
+
+    #[test]
+    fn deadline_arithmetic_overflow_is_detected_before_commit() {
+        let start = Instant::now();
+        let schedule = ProbeSchedule::new(start, &negotiated(2, 0)).unwrap();
+
+        assert!(matches!(
+            schedule.preflight_caller_commit(u64::MAX),
+            Err(ClientError::DurationOverflow)
+        ));
+        assert_eq!(schedule.next_send_deadline(), Some(start));
+    }
+
+    #[test]
+    fn timer_error_is_adapter_owned() {
+        let scheduled_at = Instant::now();
+        let sent_at = scheduled_at + Duration::from_millis(7);
+
+        assert_eq!(
+            instant_abs_diff(sent_at, scheduled_at),
+            Duration::from_millis(7)
+        );
+    }
+}

crates/irtt-client/src/client/tests/close.rs

@@ -29,8 +29,23 @@ fn close_sends_one_close_packet_with_negotiated_token() {
     });
     let mut client = Client::connect(default_test_config(server.addr)).unwrap();
     assert_open_started(client.open().unwrap());
+    let sent_at = ClientTimestamp {
+        wall: SystemTime::UNIX_EPOCH + Duration::from_secs(1_234),
+        mono: Instant::now() + Duration::from_secs(5),
+    };
+    client.test_hooks.close_sent_at.set(Some(sent_at));
     let events = client.close().unwrap();
-    assert_eq!(events.len(), 1);
+    assert!(matches!(
+        events.as_slice(),
+        [ClientEvent::SessionClosed {
+            token: TOKEN,
+            at,
+            ..
+        }] if *at == sent_at
+    ));
+    assert!(!client.runtime.is_open());
+    assert!(client.schedule.is_none());
+    assert_eq!(client.applied_traffic_class, None);
     let packets: Vec<_> = server.rx.iter().take(2).collect();
     let close = &packets[1];
     assert_eq!(close[3], flags::FLAG_CLOSE);
@@ -38,6 +53,155 @@ fn close_sends_one_close_packet_with_negotiated_token() {
     server.join();
 }
 
+#[test]
+fn close_event_reservation_failure_precedes_dscp_clear_and_send() {
+    let params = default_params();
+    let server = start_fake_server(move |socket, tx| {
+        let (_, peer) = recv_request(&socket, &tx);
+        socket
+            .send_to(
+                &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None),
+                peer,
+            )
+            .unwrap();
+        let _ = recv_request(&socket, &tx);
+    });
+    let mut client = Client::connect(default_test_config(server.addr)).unwrap();
+    assert_open_started(client.open().unwrap());
+    client.test_hooks.fail_close_event_reserve.set(true);
+    client.test_hooks.fail_close_dscp_clear.set(true);
+
+    assert!(matches!(
+        client.close(),
+        Err(ClientError::AllocationFailed {
+            operation: "close event result",
+            ..
+        })
+    ));
+    assert_eq!(client.test_hooks.close_send_attempts.get(), 0);
+    assert!(client.test_hooks.fail_close_dscp_clear.get());
+    assert!(client.runtime.is_open());
+    assert!(client.schedule.is_some());
+    assert_eq!(client.applied_traffic_class, Some(0));
+
+    client.test_hooks.fail_close_dscp_clear.set(false);
+    client.close().unwrap();
+    assert_eq!(client.test_hooks.close_send_attempts.get(), 1);
+    server.join();
+}
+
+#[test]
+fn close_dscp_clear_failure_precedes_send_and_preserves_open_state() {
+    let params = default_params();
+    let server = start_fake_server(move |socket, tx| {
+        let (_, peer) = recv_request(&socket, &tx);
+        socket
+            .send_to(
+                &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None),
+                peer,
+            )
+            .unwrap();
+        let _ = recv_request(&socket, &tx);
+    });
+    let mut client = Client::connect(default_test_config(server.addr)).unwrap();
+    assert_open_started(client.open().unwrap());
+    client.test_hooks.fail_close_dscp_clear.set(true);
+
+    assert!(matches!(
+        client.close(),
+        Err(ClientError::SocketOption { .. })
+    ));
+    assert_eq!(client.test_hooks.close_send_attempts.get(), 0);
+    assert!(client.runtime.is_open());
+    assert!(client.schedule.is_some());
+    assert_eq!(client.applied_traffic_class, Some(0));
+
+    client.close().unwrap();
+    assert_eq!(client.test_hooks.close_send_attempts.get(), 1);
+    server.join();
+}
+
+#[test]
+fn close_send_failure_leaves_machine_and_schedule_open_for_retry() {
+    let params = default_params();
+    let server = start_fake_server(move |socket, tx| {
+        let (_, peer) = recv_request(&socket, &tx);
+        socket
+            .send_to(
+                &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None),
+                peer,
+            )
+            .unwrap();
+        let _ = recv_request(&socket, &tx);
+    });
+    let mut client = Client::connect(default_test_config(server.addr)).unwrap();
+    assert_open_started(client.open().unwrap());
+    let sent_at = ClientTimestamp {
+        wall: SystemTime::UNIX_EPOCH + Duration::from_secs(2_345),
+        mono: Instant::now() + Duration::from_secs(6),
+    };
+    client.test_hooks.close_sent_at.set(Some(sent_at));
+    client.test_hooks.fail_close_send.set(true);
+
+    assert!(matches!(client.close(), Err(ClientError::Socket(_))));
+    assert_eq!(client.test_hooks.close_sent_at.get(), Some(sent_at));
+    assert!(client.runtime.is_open());
+    assert!(client.schedule.is_some());
+    assert_eq!(client.applied_traffic_class, Some(0));
+    assert_eq!(client.test_hooks.close_send_attempts.get(), 1);
+
+    assert!(matches!(
+        client.close().unwrap().as_slice(),
+        [ClientEvent::SessionClosed {
+            token: TOKEN,
+            at,
+            ..
+        }] if *at == sent_at
+    ));
+    assert_eq!(client.test_hooks.close_sent_at.get(), None);
+    assert_eq!(client.test_hooks.close_send_attempts.get(), 2);
+    assert!(matches!(client.close(), Err(ClientError::AlreadyClosed)));
+    server.join();
+}
+
+#[test]
+fn short_successful_close_commits_before_length_mismatch() {
+    let params = default_params();
+    let server = start_fake_server(move |socket, tx| {
+        let (_, peer) = recv_request(&socket, &tx);
+        socket
+            .send_to(
+                &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None),
+                peer,
+            )
+            .unwrap();
+        let _ = recv_request(&socket, &tx);
+    });
+    let mut client = Client::connect(default_test_config(server.addr)).unwrap();
+    assert_open_started(client.open().unwrap());
+    let expected = client.runtime.prepare_close().unwrap().bytes.len();
+    let sent_at = ClientTimestamp {
+        wall: SystemTime::UNIX_EPOCH + Duration::from_secs(3_456),
+        mono: Instant::now() + Duration::from_secs(7),
+    };
+    client.test_hooks.close_sent_at.set(Some(sent_at));
+    client.test_hooks.close_reported_len.set(Some(expected - 1));
+
+    assert!(matches!(
+        client.close(),
+        Err(ClientError::DatagramLengthMismatch {
+            expected: error_expected,
+            actual,
+        }) if error_expected == expected && actual + 1 == expected
+    ));
+    assert!(!client.runtime.is_open());
+    assert!(client.schedule.is_none());
+    assert_eq!(client.applied_traffic_class, None);
+    assert_eq!(client.test_hooks.close_sent_at.get(), None);
+    assert!(matches!(client.close(), Err(ClientError::AlreadyClosed)));
+    server.join();
+}
+
 #[test]
 fn send_probe_fails_after_close() {
     let params = default_params();
@@ -118,6 +282,7 @@ fn close_flagged_echo_reply_emits_reply_then_closes_without_sending_close() {
     ));
     assert_eq!(events.len(), 2);
     assert!(client.next_send_deadline().is_none());
+    assert!(client.schedule.is_none());
     assert!(matches!(
         client.send_probe(),
         Err(ClientError::AlreadyClosed)
@@ -131,6 +296,117 @@ fn close_flagged_echo_reply_emits_reply_then_closes_without_sending_close() {
     server.join();
 }
 
+#[test]
+fn peer_close_dscp_cleanup_failure_preserves_events_and_closed_state() {
+    let params = default_params();
+    let server = start_fake_server({
+        let params = params.clone();
+        move |socket, tx| {
+            let (_, peer) = recv_request(&socket, &tx);
+            socket
+                .send_to(
+                    &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None),
+                    peer,
+                )
+                .unwrap();
+            let (request, _) = recv_request(&socket, &tx);
+            let seq = u32::from_le_bytes(request[12..16].try_into().unwrap());
+            socket
+                .send_to(
+                    &echo_reply_packet_with_flags(
+                        TOKEN,
+                        seq,
+                        &params,
+                        &TimestampFields::default(),
+                        None,
+                        FLAG_REPLY | flags::FLAG_CLOSE,
+                    ),
+                    peer,
+                )
+                .unwrap();
+            socket
+                .set_read_timeout(Some(Duration::from_millis(250)))
+                .unwrap();
+            while recv_request_timeout(&socket, &tx).is_some() {}
+        }
+    });
+    let mut client = Client::connect(ClientConfig {
+        socket_config: crate::SocketConfig {
+            recv_timeout: Some(Duration::from_millis(200)),
+            ..Default::default()
+        },
+        ..default_test_config(server.addr)
+    })
+    .unwrap();
+    assert_open_started(client.open().unwrap());
+    client.send_probe().unwrap();
+    client.test_hooks.fail_close_dscp_clear.set(true);
+
+    assert!(matches!(
+        client.recv_once().unwrap().as_slice(),
+        [
+            ClientEvent::EchoReply { .. },
+            ClientEvent::SessionClosed { token: TOKEN, .. }
+        ]
+    ));
+    assert!(client.is_peer_closed());
+    assert!(client.schedule.is_none());
+    assert_eq!(client.applied_traffic_class, Some(0));
+    assert_eq!(client.test_hooks.close_send_attempts.get(), 0);
+    let open = server.rx.recv_timeout(Duration::from_millis(100)).unwrap();
+    let echo = server.rx.recv_timeout(Duration::from_millis(100)).unwrap();
+    assert_ne!(open[3] & FLAG_OPEN, 0);
+    assert_eq!(echo[3] & flags::FLAG_CLOSE, 0);
+    assert!(server.rx.recv_timeout(Duration::from_millis(400)).is_err());
+    server.join();
+}
+
+#[test]
+fn recv_available_stops_after_peer_close() {
+    let params = default_params();
+    let server = start_fake_server({
+        let params = params.clone();
+        move |socket, tx| {
+            let (_, peer) = recv_request(&socket, &tx);
+            socket
+                .send_to(
+                    &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None),
+                    peer,
+                )
+                .unwrap();
+            let (request, _) = recv_request(&socket, &tx);
+            let seq = u32::from_le_bytes(request[12..16].try_into().unwrap());
+            let close = echo_reply_packet_with_flags(
+                TOKEN,
+                seq,
+                &params,
+                &TimestampFields::default(),
+                None,
+                FLAG_REPLY | flags::FLAG_CLOSE,
+            );
+            socket.send_to(&close, peer).unwrap();
+            socket.send_to(&close, peer).unwrap();
+        }
+    });
+    let mut client = Client::connect(default_test_config(server.addr)).unwrap();
+    assert_open_started(client.open().unwrap());
+    client.send_probe().unwrap();
+
+    let events = client
+        .recv_available(RecvBudget { max_packets: 8 })
+        .unwrap();
+
+    assert!(matches!(
+        events.as_slice(),
+        [
+            ClientEvent::EchoReply { .. },
+            ClientEvent::SessionClosed { token: TOKEN, .. }
+        ]
+    ));
+    assert!(client.is_peer_closed());
+    server.join();
+}
+
 #[test]
 fn normal_echo_reply_does_not_close_session() {
     let params = default_params();
@@ -145,3 +421,334 @@ fn normal_echo_reply_does_not_close_session() {
     client.close().unwrap();
     server.join();
 }
+
+#[test]
+fn close_flagged_duplicate_emits_duplicate_then_closes() {
+    let params = default_params();
+    let server = start_fake_server({
+        let params = params.clone();
+        move |socket, tx| {
+            let (_, peer) = recv_request(&socket, &tx);
+            socket
+                .send_to(
+                    &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None),
+                    peer,
+                )
+                .unwrap();
+
+            let (request, _) = recv_request(&socket, &tx);
+            let seq = u32::from_le_bytes(request[12..16].try_into().unwrap());
+            let normal = echo_reply_packet(TOKEN, seq, &params, &TimestampFields::default(), None);
+            let close = echo_reply_packet_with_flags(
+                TOKEN,
+                seq,
+                &params,
+                &TimestampFields::default(),
+                None,
+                FLAG_REPLY | flags::FLAG_CLOSE,
+            );
+            socket.send_to(&normal, peer).unwrap();
+            socket.send_to(&close, peer).unwrap();
+        }
+    });
+    let mut client = Client::connect(ClientConfig {
+        socket_config: crate::SocketConfig {
+            recv_timeout: Some(Duration::from_millis(200)),
+            ..Default::default()
+        },
+        ..default_test_config(server.addr)
+    })
+    .unwrap();
+    assert_open_started(client.open().unwrap());
+    client.send_probe().unwrap();
+
+    assert!(matches!(
+        client.recv_once().unwrap().as_slice(),
+        [ClientEvent::EchoReply { seq: 0, .. }]
+    ));
+    assert!(matches!(
+        client.recv_once().unwrap().as_slice(),
+        [
+            ClientEvent::DuplicateReply { seq: 0, .. },
+            ClientEvent::SessionClosed { token: TOKEN, .. }
+        ]
+    ));
+    assert!(client.is_peer_closed());
+    server.join();
+}
+
+#[test]
+fn close_flagged_retained_timeout_emits_late_then_closes() {
+    let params = default_params();
+    let server = start_fake_server({
+        let params = params.clone();
+        move |socket, tx| {
+            let (_, peer) = recv_request(&socket, &tx);
+            socket
+                .send_to(
+                    &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None),
+                    peer,
+                )
+                .unwrap();
+
+            let (request, _) = recv_request(&socket, &tx);
+            let seq = u32::from_le_bytes(request[12..16].try_into().unwrap());
+            socket
+                .send_to(
+                    &echo_reply_packet_with_flags(
+                        TOKEN,
+                        seq,
+                        &params,
+                        &TimestampFields::default(),
+                        None,
+                        FLAG_REPLY | flags::FLAG_CLOSE,
+                    ),
+                    peer,
+                )
+                .unwrap();
+        }
+    });
+    let mut client = Client::connect(ClientConfig {
+        probe_timeout: Duration::from_millis(50),
+        socket_config: crate::SocketConfig {
+            recv_timeout: Some(Duration::from_millis(200)),
+            ..Default::default()
+        },
+        ..default_test_config(server.addr)
+    })
+    .unwrap();
+    assert_open_started(client.open().unwrap());
+    let sent = client.send_probe().unwrap();
+    let ClientEvent::EchoSent { sent_at, .. } = &sent[0] else {
+        panic!("expected EchoSent");
+    };
+    assert!(matches!(
+        client
+            .poll_timeouts_at(sent_at.mono + client.probe_timeout())
+            .unwrap()
+            .as_slice(),
+        [ClientEvent::EchoLoss { seq: 0, .. }]
+    ));
+
+    assert!(matches!(
+        client.recv_once().unwrap().as_slice(),
+        [
+            ClientEvent::LateReply {
+                seq: 0,
+                sent_at: Some(_),
+                ..
+            },
+            ClientEvent::SessionClosed { token: TOKEN, .. }
+        ]
+    ));
+    assert!(client.is_peer_closed());
+    server.join();
+}
+
+#[test]
+fn close_flagged_evicted_sequence_emits_late_then_closes() {
+    let params = default_params();
+    let server = start_fake_server({
+        let params = params.clone();
+        move |socket, tx| {
+            let (_, peer) = recv_request(&socket, &tx);
+            socket
+                .send_to(
+                    &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None),
+                    peer,
+                )
+                .unwrap();
+
+            let (first, _) = recv_request(&socket, &tx);
+            let first_seq = u32::from_le_bytes(first[12..16].try_into().unwrap());
+            socket
+                .send_to(
+                    &echo_reply_packet(
+                        TOKEN,
+                        first_seq,
+                        &params,
+                        &TimestampFields::default(),
+                        None,
+                    ),
+                    peer,
+                )
+                .unwrap();
+
+            let (second, _) = recv_request(&socket, &tx);
+            let second_seq = u32::from_le_bytes(second[12..16].try_into().unwrap());
+            socket
+                .send_to(
+                    &echo_reply_packet(
+                        TOKEN,
+                        second_seq,
+                        &params,
+                        &TimestampFields::default(),
+                        None,
+                    ),
+                    peer,
+                )
+                .unwrap();
+            socket
+                .send_to(
+                    &echo_reply_packet_with_flags(
+                        TOKEN,
+                        first_seq,
+                        &params,
+                        &TimestampFields::default(),
+                        None,
+                        FLAG_REPLY | flags::FLAG_CLOSE,
+                    ),
+                    peer,
+                )
+                .unwrap();
+        }
+    });
+    let mut client = Client::connect(ClientConfig {
+        max_pending_probes: 1,
+        socket_config: crate::SocketConfig {
+            recv_timeout: Some(Duration::from_millis(200)),
+            ..Default::default()
+        },
+        ..default_test_config(server.addr)
+    })
+    .unwrap();
+    assert_open_started(client.open().unwrap());
+
+    client.send_probe().unwrap();
+    assert!(matches!(
+        client.recv_once().unwrap().as_slice(),
+        [ClientEvent::EchoReply { seq: 0, .. }]
+    ));
+    client.send_probe().unwrap();
+    assert!(matches!(
+        client.recv_once().unwrap().as_slice(),
+        [ClientEvent::EchoReply { seq: 1, .. }]
+    ));
+    assert!(matches!(
+        client.recv_once().unwrap().as_slice(),
+        [
+            ClientEvent::LateReply {
+                seq: 0,
+                sent_at: None,
+                rtt: None,
+                ..
+            },
+            ClientEvent::SessionClosed { token: TOKEN, .. }
+        ]
+    ));
+    assert!(client.is_peer_closed());
+    server.join();
+}
+
+#[test]
+fn close_flagged_untracked_sequence_emits_warning_then_closes() {
+    let params = default_params();
+    let server = start_fake_server({
+        let params = params.clone();
+        move |socket, tx| {
+            let (_, peer) = recv_request(&socket, &tx);
+            socket
+                .send_to(
+                    &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None),
+                    peer,
+                )
+                .unwrap();
+            socket
+                .send_to(
+                    &echo_reply_packet_with_flags(
+                        TOKEN,
+                        42,
+                        &params,
+                        &TimestampFields::default(),
+                        None,
+                        FLAG_REPLY | flags::FLAG_CLOSE,
+                    ),
+                    peer,
+                )
+                .unwrap();
+        }
+    });
+    let mut client = Client::connect(ClientConfig {
+        socket_config: crate::SocketConfig {
+            recv_timeout: Some(Duration::from_millis(200)),
+            ..Default::default()
+        },
+        ..default_test_config(server.addr)
+    })
+    .unwrap();
+    assert_open_started(client.open().unwrap());
+
+    assert!(matches!(
+        client.recv_once().unwrap().as_slice(),
+        [
+            ClientEvent::Warning {
+                kind: WarningKind::UntrackedReply,
+                ..
+            },
+            ClientEvent::SessionClosed { token: TOKEN, .. }
+        ]
+    ));
+    assert!(client.is_peer_closed());
+    server.join();
+}
+
+#[test]
+fn wrong_token_close_flag_does_not_close_session() {
+    let params = default_params();
+    let server = start_fake_server({
+        let params = params.clone();
+        move |socket, tx| {
+            let (_, peer) = recv_request(&socket, &tx);
+            socket
+                .send_to(
+                    &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None),
+                    peer,
+                )
+                .unwrap();
+
+            let (request, _) = recv_request(&socket, &tx);
+            let seq = u32::from_le_bytes(request[12..16].try_into().unwrap());
+            socket
+                .send_to(
+                    &echo_reply_packet_with_flags(
+                        TOKEN.wrapping_add(1),
+                        seq,
+                        &params,
+                        &TimestampFields::default(),
+                        None,
+                        FLAG_REPLY | flags::FLAG_CLOSE,
+                    ),
+                    peer,
+                )
+                .unwrap();
+
+            let _ = recv_request(&socket, &tx);
+            let _ = recv_request(&socket, &tx);
+        }
+    });
+    let mut client = Client::connect(ClientConfig {
+        socket_config: crate::SocketConfig {
+            recv_timeout: Some(Duration::from_millis(200)),
+            ..Default::default()
+        },
+        ..default_test_config(server.addr)
+    })
+    .unwrap();
+    assert_open_started(client.open().unwrap());
+    client.send_probe().unwrap();
+
+    assert!(matches!(
+        client.recv_once().unwrap().as_slice(),
+        [ClientEvent::Warning {
+            kind: WarningKind::WrongToken,
+            ..
+        }]
+    ));
+    assert!(!client.is_peer_closed());
+    assert!(matches!(
+        client.send_probe().unwrap().as_slice(),
+        [ClientEvent::EchoSent { seq: 1, .. }]
+    ));
+    client.close().unwrap();
+    server.join();
+}

crates/irtt-client/src/client/tests/config.rs

@@ -42,7 +42,10 @@ fn params_from_config_maps_compatibility_fields() {
     assert_eq!(params.received_stats, ReceivedStats::Window);
     assert_eq!(params.stamp_at, StampAt::Midpoint);
     assert_eq!(params.clock, Clock::Wall);
-    assert_eq!(params.dscp, 46, "config DSCP codepoint must not be shifted");
+    assert_eq!(
+        params.dscp, 184,
+        "config DSCP codepoint 46 must be shifted into raw wire byte 184"
+    );
     assert_eq!(
         params.server_fill.as_ref().map(|fill| fill.value.as_str()),
         Some("rand")
@@ -67,7 +70,11 @@ fn params_from_config_accepts_boundary_values() {
         dscp: 63,
         ..ClientConfig::default()
     };
-    assert_eq!(params_from_config(&config).unwrap().dscp, 63);
+    assert_eq!(
+        params_from_config(&config).unwrap().dscp,
+        252,
+        "boundary codepoint 63 must be shifted into raw wire byte 252"
+    );
 }
 
 #[test]
@@ -132,6 +139,16 @@ fn params_from_config_rejects_invalid_values() {
             },
             "dscp",
         ),
+        (
+            // The unspecified clock is the absent-tag wire default, not a
+            // client mode; a client that needs timestamps must name a clock.
+            "unspecified clock",
+            ClientConfig {
+                clock: Clock::Unspecified,
+                ..ClientConfig::default()
+            },
+            "clock must be wall, monotonic, or both",
+        ),
         (
             "empty server fill",
             ClientConfig {

crates/irtt-client/src/client/tests/dscp.rs

@@ -9,9 +9,11 @@ use crate::socket_options::socket_traffic_class;
     target_os = "illumos",
     target_os = "haiku",
 )))]
-fn normal_open_applies_negotiated_dscp_after_open_and_close_clears_it() {
+fn normal_open_applies_negotiated_traffic_class_after_open_and_close_clears_it() {
     let mut params = default_params();
-    params.dscp = 46;
+    // Raw wire TOS/Traffic Class byte for DSCP codepoint 46 (EF): a
+    // compliant server echoes back the raw byte it received, unchanged.
+    params.dscp = 184;
     let server = start_fake_server(move |socket, tx| {
         let (_, peer) = recv_request(&socket, &tx);
         let reply = open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None);
@@ -48,7 +50,7 @@ fn normal_open_applies_negotiated_dscp_after_open_and_close_clears_it() {
     target_os = "illumos",
     target_os = "haiku",
 )))]
-fn normal_open_uses_negotiated_dscp_not_requested_dscp() {
+fn normal_open_uses_negotiated_traffic_class_not_requested_dscp() {
     let mut returned = default_params();
     returned.dscp = 0;
     let server = open_success_server(returned);
@@ -73,3 +75,134 @@ fn normal_open_uses_negotiated_dscp_not_requested_dscp() {
     );
     server.join();
 }
+
+#[test]
+#[cfg(not(any(
+    target_os = "fuchsia",
+    target_os = "redox",
+    target_os = "solaris",
+    target_os = "illumos",
+    target_os = "haiku",
+)))]
+fn failed_close_send_restores_negotiated_traffic_class_and_keeps_session_open() {
+    let mut params = default_params();
+    // Raw wire TOS/Traffic Class byte for DSCP codepoint 46 (EF).
+    params.dscp = 184;
+    let server = start_fake_server(move |socket, tx| {
+        let (_, peer) = recv_request(&socket, &tx);
+        socket
+            .send_to(
+                &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None),
+                peer,
+            )
+            .unwrap();
+        let _ = recv_request(&socket, &tx);
+    });
+    let mut config = default_test_config(server.addr);
+    config.dscp = 46;
+    let mut client = Client::connect(config).unwrap();
+    assert_open_started(client.open().unwrap());
+    client.test_hooks.fail_close_send.set(true);
+
+    let error = client.close().unwrap_err();
+
+    assert!(matches!(error, ClientError::Socket(_)));
+    assert!(client.runtime.is_open());
+    assert!(client.schedule.is_some());
+    assert_eq!(client.applied_traffic_class, Some(184));
+    assert_eq!(
+        socket_traffic_class(&client.socket, client.remote).unwrap() & 0xfc,
+        184
+    );
+    client.close().unwrap();
+    server.join();
+}
+
+#[test]
+fn failed_close_keeps_send_error_primary_when_dscp_restoration_also_fails() {
+    let params = default_params();
+    let server = start_fake_server(move |socket, tx| {
+        let (_, peer) = recv_request(&socket, &tx);
+        socket
+            .send_to(
+                &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None),
+                peer,
+            )
+            .unwrap();
+        let _ = recv_request(&socket, &tx);
+    });
+    let mut client = Client::connect(default_test_config(server.addr)).unwrap();
+    assert_open_started(client.open().unwrap());
+    client.test_hooks.fail_close_send.set(true);
+    client.test_hooks.fail_dscp_restore.set(true);
+
+    let error = client.close().unwrap_err();
+
+    assert!(matches!(error, ClientError::Socket(_)));
+    assert!(error.to_string().contains("injected close send failure"));
+    assert!(client.runtime.is_open());
+    assert!(client.schedule.is_some());
+    assert_eq!(client.applied_traffic_class, Some(0));
+    client.close().unwrap();
+    server.join();
+}
+
+#[test]
+#[cfg(not(any(
+    target_os = "fuchsia",
+    target_os = "redox",
+    target_os = "solaris",
+    target_os = "illumos",
+    target_os = "haiku",
+)))]
+fn authenticated_peer_close_clears_schedule_and_negotiated_traffic_class() {
+    let mut params = default_params();
+    // Raw wire TOS/Traffic Class byte for DSCP codepoint 46 (EF).
+    params.dscp = 184;
+    let server = start_fake_server(move |socket, tx| {
+        let (_, peer) = recv_request(&socket, &tx);
+        socket
+            .send_to(
+                &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None),
+                peer,
+            )
+            .unwrap();
+        let (request, _) = recv_request(&socket, &tx);
+        let seq = u32::from_le_bytes(request[12..16].try_into().unwrap());
+        socket
+            .send_to(
+                &echo_reply_packet_with_flags(
+                    TOKEN,
+                    seq,
+                    &params,
+                    &TimestampFields::default(),
+                    None,
+                    FLAG_REPLY | flags::FLAG_CLOSE,
+                ),
+                peer,
+            )
+            .unwrap();
+    });
+    let mut config = default_test_config(server.addr);
+    config.dscp = 46;
+    let mut client = Client::connect(config).unwrap();
+    assert_open_started(client.open().unwrap());
+    client.send_probe().unwrap();
+
+    let events = client.recv_once().unwrap();
+
+    assert!(matches!(
+        events.as_slice(),
+        [
+            ClientEvent::EchoReply { .. },
+            ClientEvent::SessionClosed { .. }
+        ]
+    ));
+    assert!(client.schedule.is_none());
+    assert_eq!(client.applied_traffic_class, None);
+    assert_eq!(
+        socket_traffic_class(&client.socket, client.remote).unwrap(),
+        0
+    );
+    server.join();
+}

crates/irtt-client/src/client/tests/hmac.rs

@@ -8,7 +8,7 @@ fn hmac_open_success() {
     let params = params_from_config(&config).unwrap();
     let server = start_fake_server(move |socket, tx| {
         let (request, peer) = recv_request(&socket, &tx);
-        verify_hmac(&key, &request, HMAC_OFFSET).unwrap();
+        verify_packet_hmac(&key, &request).unwrap();
         let reply = open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, Some(&key));
         socket.send_to(&reply, peer).unwrap();
     });
@@ -19,45 +19,77 @@ fn hmac_open_success() {
 }
 
 #[test]
-fn hmac_open_rejects_missing_hmac() {
+fn hmac_open_ignores_missing_hmac_before_valid_reply() {
     let key = b"secret".to_vec();
     let mut config = default_test_config(SocketAddr::from(([127, 0, 0, 1], 1)));
-    config.hmac_key = Some(key);
+    config.hmac_key = Some(key.clone());
     let params = params_from_config(&config).unwrap();
     let server = start_fake_server(move |socket, tx| {
         let (_, peer) = recv_request(&socket, &tx);
-        let reply = open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None);
-        socket.send_to(&reply, peer).unwrap();
+        let missing = open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None);
+        let valid = open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, Some(&key));
+        socket.send_to(&missing, peer).unwrap();
+        socket.send_to(&valid, peer).unwrap();
     });
     config.server_addr = server.addr.to_string();
     let mut client = Client::connect(config).unwrap();
-    assert!(matches!(
-        client.open(),
-        Err(ClientError::Protocol(
-            irtt_proto::ProtoError::HmacPresenceMismatch
-        ))
-    ));
+    assert_open_started(client.open().unwrap());
+    assert_eq!(server.rx.iter().take(1).count(), 1);
+    assert!(server.rx.try_recv().is_err());
     server.join();
 }
 
 #[test]
-fn hmac_open_rejects_bad_hmac() {
+fn hmac_open_ignores_bad_hmac_before_valid_reply() {
     let key = b"secret".to_vec();
     let wrong_key = b"wrong".to_vec();
     let mut config = default_test_config(SocketAddr::from(([127, 0, 0, 1], 1)));
-    config.hmac_key = Some(key);
+    config.hmac_key = Some(key.clone());
     let params = params_from_config(&config).unwrap();
     let server = start_fake_server(move |socket, tx| {
         let (_, peer) = recv_request(&socket, &tx);
-        let reply = open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, Some(&wrong_key));
-        socket.send_to(&reply, peer).unwrap();
+        let bad = open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, Some(&wrong_key));
+        let valid = open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, Some(&key));
+        socket.send_to(&bad, peer).unwrap();
+        socket.send_to(&valid, peer).unwrap();
     });
     config.server_addr = server.addr.to_string();
     let mut client = Client::connect(config).unwrap();
+    assert_open_started(client.open().unwrap());
+    assert_eq!(server.rx.iter().take(1).count(), 1);
+    assert!(server.rx.try_recv().is_err());
+    server.join();
+}
+
+#[test]
+fn post_token_hmac_negotiation_failure_sends_authenticated_cleanup_close() {
+    let key = b"secret".to_vec();
+    let mut config = default_test_config(SocketAddr::from(([127, 0, 0, 1], 1)));
+    config.hmac_key = Some(key.clone());
+    let mut returned = params_from_config(&config).unwrap();
+    returned.interval_ns += 1;
+    let server_key = key.clone();
+    let server = start_fake_server(move |socket, tx| {
+        let (_, peer) = recv_request(&socket, &tx);
+        let reply = open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &returned, Some(&server_key));
+        socket.send_to(&reply, peer).unwrap();
+        let _ = recv_request(&socket, &tx);
+    });
+    config.server_addr = server.addr.to_string();
+    let mut client = Client::connect(config).unwrap();
+
     assert!(matches!(
         client.open(),
-        Err(ClientError::Protocol(irtt_proto::ProtoError::BadHmac))
+        Err(ClientError::NegotiationRejected { .. })
     ));
+    let packets: Vec<_> = server.rx.iter().take(2).collect();
+    let cleanup = &packets[1];
+    assert_eq!(cleanup[3], flags::FLAG_CLOSE | FLAG_HMAC);
+    verify_packet_hmac(&key, cleanup).unwrap();
+    assert_eq!(
+        u64::from_le_bytes(cleanup[4 + HMAC_SIZE..12 + HMAC_SIZE].try_into().unwrap()),
+        TOKEN
+    );
     server.join();
 }
 
@@ -81,7 +113,7 @@ fn hmac_close_packet_includes_valid_hmac() {
     let packets: Vec<_> = server.rx.iter().take(2).collect();
     let close = &packets[1];
     assert_eq!(close[3], flags::FLAG_CLOSE | FLAG_HMAC);
-    verify_hmac(&key, close, HMAC_OFFSET).unwrap();
+    verify_packet_hmac(&key, close).unwrap();
     assert_eq!(
         u64::from_le_bytes(close[4 + HMAC_SIZE..12 + HMAC_SIZE].try_into().unwrap()),
         TOKEN
@@ -112,7 +144,14 @@ fn bad_hmac_reply_is_dropped() {
                     .unwrap(),
             );
             let ts = TimestampFields::default();
-            let reply_packet = echo_reply_packet(TOKEN, seq, &params, &ts, Some(&wrong_key));
+            let reply_packet = echo_reply_packet_with_flags(
+                TOKEN,
+                seq,
+                &params,
+                &ts,
+                Some(&wrong_key),
+                FLAG_REPLY | flags::FLAG_CLOSE,
+            );
             socket.send_to(&reply_packet, peer).unwrap();
         }
     });
@@ -131,6 +170,8 @@ fn bad_hmac_reply_is_dropped() {
     let events = client.recv_once().unwrap();
     assert_eq!(events.len(), 1);
     assert!(matches!(&events[0], ClientEvent::Warning { .. }));
+    assert!(!client.is_peer_closed());
+    client.close().unwrap();
     server.join();
 }
 
@@ -150,7 +191,7 @@ fn hmac_echo_request_reply_works() {
         let mut buf = [0_u8; 2048];
         if let Ok((size, _)) = socket.recv_from(&mut buf) {
             tx.send(buf[..size].to_vec()).unwrap();
-            verify_hmac(&server_key, &buf[..size], HMAC_OFFSET).unwrap();
+            verify_packet_hmac(&server_key, &buf[..size]).unwrap();
             let seq = u32::from_le_bytes(
                 buf[4 + HMAC_SIZE + 8..4 + HMAC_SIZE + 12]
                     .try_into()

crates/irtt-client/src/client/tests/mod.rs

@@ -1,8 +1,8 @@
 use super::*;
 use crate::config::{NegotiationPolicy, DEFAULT_OPEN_TIMEOUTS};
 use irtt_proto::{
-    flags::FLAG_HMAC, flags::FLAG_OPEN, flags::FLAG_REPLY, verify_hmac, Clock, ReceivedStats,
-    StampAt, HMAC_SIZE, MAGIC,
+    flags::FLAG_HMAC, flags::FLAG_OPEN, flags::FLAG_REPLY, verify_packet_hmac, Clock,
+    ReceivedStats, StampAt, HMAC_SIZE, MAGIC,
 };
 use std::{thread, time::SystemTime};
 

crates/irtt-client/src/client/tests/negotiation.rs

@@ -33,13 +33,17 @@ fn strict_negotiation_rejects_changed_params() {
         ..ClientConfig::default()
     };
     let requested = params_from_config(&config).unwrap();
+    assert_eq!(
+        requested.dscp, 184,
+        "codepoint 46 must become raw wire byte 184"
+    );
     let mut returned = requested.clone();
     returned.dscp = 0;
     assert_eq!(
         rejection_reason(&requested, &returned, NegotiationPolicy::Strict),
         NegotiationRestriction::DscpChanged {
-            requested: requested.dscp,
-            negotiated: returned.dscp,
+            requested: 46,
+            negotiated: 0,
         }
         .message()
     );
@@ -183,17 +187,34 @@ fn strict_negotiation_rejects_negative_returned_length() {
 
 #[test]
 fn loose_negotiation_rejects_runtime_invalid_returned_dscp() {
-    let config = ClientConfig::default();
+    let config = ClientConfig {
+        dscp: 46,
+        ..ClientConfig::default()
+    };
     let requested = params_from_config(&config).unwrap();
+    assert_eq!(
+        requested.dscp, 184,
+        "codepoint 46 must become raw wire byte 184"
+    );
 
-    for dscp in [-1, 64] {
+    for dscp in [-1, 256] {
         let mut returned = requested.clone();
         returned.dscp = dscp;
         assert_eq!(
             rejection_reason(&requested, &returned, NegotiationPolicy::Loose),
-            "dscp must be in range 0..=63"
+            "dscp must be in range 0..=255"
         );
     }
+
+    // A raw returned value of 184 must be accepted even though it exceeds the
+    // 0..=63 codepoint range; it is the correctly negotiated wire value for
+    // codepoint 46 and is not subject to the codepoint bound at all.
+    let returned = requested.clone();
+    assert!(
+        assert_negotiates(&requested, &returned, NegotiationPolicy::Loose)
+            .restrictions
+            .is_empty()
+    );
 }
 
 #[test]

crates/irtt-client/src/client/tests/no_test.rs

@@ -8,8 +8,12 @@ fn no_test_success_validates_params() {
     let server = no_test_server(params.clone(), 0);
     config.server_addr = server.addr.to_string();
     let mut client = Client::connect(config).unwrap();
+    assert!(client.next_send_deadline().is_none());
     let negotiated = assert_no_test_completed(client.open().unwrap());
     assert_eq!(negotiated.params, params);
+    assert!(client.next_send_deadline().is_none());
+    assert!(client.schedule.is_none());
+    assert_eq!(client.applied_traffic_class, None);
     server.join();
 }
 
@@ -18,13 +22,55 @@ fn no_test_rejects_non_close_open_reply() {
     let mut config = default_test_config(SocketAddr::from(([127, 0, 0, 1], 1)));
     config.run_mode = RunMode::NoTest;
     let params = params_from_config(&config).unwrap();
-    let server = open_success_server(params);
+    let server = start_fake_server(move |socket, tx| {
+        let (_, peer) = recv_request(&socket, &tx);
+        socket
+            .send_to(
+                &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None),
+                peer,
+            )
+            .unwrap();
+        let _ = recv_request(&socket, &tx);
+    });
     config.server_addr = server.addr.to_string();
     let mut client = Client::connect(config).unwrap();
     assert!(matches!(
         client.open(),
         Err(ClientError::UnexpectedNoTestReply)
     ));
+    let packets: Vec<_> = server.rx.iter().take(2).collect();
+    assert_eq!(packets[1][3], flags::FLAG_CLOSE);
+    assert_eq!(
+        u64::from_le_bytes(packets[1][4..12].try_into().unwrap()),
+        TOKEN
+    );
+    assert!(client.runtime.prepare_open_request().is_ok());
+    server.join();
+}
+
+#[test]
+fn no_test_cleanup_send_failure_preserves_unexpected_reply() {
+    let mut config = default_test_config(SocketAddr::from(([127, 0, 0, 1], 1)));
+    config.run_mode = RunMode::NoTest;
+    let params = params_from_config(&config).unwrap();
+    let server = start_fake_server(move |socket, tx| {
+        let (_, peer) = recv_request(&socket, &tx);
+        socket
+            .send_to(
+                &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None),
+                peer,
+            )
+            .unwrap();
+    });
+    config.server_addr = server.addr.to_string();
+    let mut client = Client::connect(config).unwrap();
+    client.test_hooks.fail_cleanup_send.set(true);
+
+    assert!(matches!(
+        client.open(),
+        Err(ClientError::UnexpectedNoTestReply)
+    ));
+    assert!(client.runtime.prepare_open_request().is_ok());
     server.join();
 }
 

crates/irtt-client/src/client/tests/open.rs

@@ -9,6 +9,26 @@ fn successful_open_handshake() {
 
     let negotiated = assert_open_started(client.open().unwrap());
     assert_eq!(negotiated.params, params);
+    assert!(client.schedule.is_some());
+    assert_eq!(client.applied_traffic_class, Some(0));
+    server.join();
+}
+
+#[test]
+fn successful_open_restores_configured_receive_timeout() {
+    let config = default_test_config(SocketAddr::from(([127, 0, 0, 1], 1)));
+    let params = params_from_config(&config).unwrap();
+    let server = open_success_server(params);
+    let mut config = default_test_config(server.addr);
+    config.socket_config.recv_timeout = Some(Duration::from_millis(75));
+    let mut client = Client::connect(config).unwrap();
+
+    assert_open_started(client.open().unwrap());
+
+    assert_eq!(
+        client.test_hooks.last_restored_read_timeout.get(),
+        Some(Duration::from_millis(75))
+    );
     server.join();
 }
 
@@ -44,16 +64,81 @@ fn open_retries_after_first_timeout() {
     server.join();
 }
 
+#[test]
+fn open_survives_interrupted_receive_within_same_attempt() {
+    let server = start_fake_server(|socket, tx| {
+        let (first, peer) = recv_request(&socket, &tx);
+        let params = Params::decode(&first[4..]).unwrap();
+        let reply = open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None);
+        socket.send_to(&reply, peer).unwrap();
+    });
+    let config = ClientConfig {
+        open_timeouts: vec![Duration::from_millis(500)],
+        ..default_test_config(server.addr)
+    };
+    let mut client = Client::connect(config).unwrap();
+    // Several interrupted receive attempts before the real reply arrives
+    // must not be treated as a timeout, must not retransmit the open
+    // request, and must not advance to a next configured attempt.
+    client.test_hooks.inject_recv_interrupted.set(5);
+
+    let outcome = client.open().unwrap();
+    assert_open_started(outcome);
+    // Exactly one request reached the server: interruptions were absorbed
+    // inside the single configured attempt.
+    assert_eq!(server.rx.iter().take(1).count(), 1);
+    server.join();
+}
+
+#[test]
+fn open_interrupted_receive_does_not_extend_the_attempt_deadline() {
+    // A fake server that never replies: with a short attempt timeout, the
+    // real question is whether interruptions can push the effective wait
+    // past the configured deadline. They must not: the deadline stays
+    // absolute across any number of interruptions.
+    let server = start_fake_server(|socket, tx| {
+        let _ = recv_request(&socket, &tx);
+    });
+    let config = ClientConfig {
+        open_timeouts: vec![Duration::from_millis(200)],
+        ..default_test_config(server.addr)
+    };
+    let mut client = Client::connect(config).unwrap();
+    // Each interruption carries no timing information of its own, so the
+    // loop must keep re-checking the real deadline rather than treating an
+    // interruption as "more time available" or a reason to fail outright.
+    client.test_hooks.inject_recv_interrupted.set(20);
+
+    let started = Instant::now();
+    let result = client.open();
+    let elapsed = started.elapsed();
+
+    assert!(matches!(result, Err(ClientError::OpenTimeout)));
+    assert!(
+        elapsed < Duration::from_millis(800),
+        "interrupted receives must not extend the attempt deadline, took {elapsed:?}"
+    );
+    server.join();
+}
+
 #[test]
 fn open_timeout_after_all_timeouts() {
     let server = timeout_server(Duration::from_millis(700));
     let config = ClientConfig {
         open_timeouts: vec![Duration::from_millis(200), Duration::from_millis(200)],
+        socket_config: crate::SocketConfig {
+            recv_timeout: Some(Duration::from_millis(50)),
+            ..Default::default()
+        },
         ..default_test_config(server.addr)
     };
     let mut client = Client::connect(config).unwrap();
     assert!(matches!(client.open(), Err(ClientError::OpenTimeout)));
     assert_eq!(server.rx.iter().take(2).count(), 2);
+    assert_eq!(
+        client.test_hooks.last_restored_read_timeout.get(),
+        Some(Duration::from_millis(50))
+    );
     server.join();
 }
 
@@ -69,6 +154,8 @@ fn protocol_version_mismatch_fails() {
         client.open(),
         Err(ClientError::ProtocolVersionMismatch { received: 2, .. })
     ));
+    assert_eq!(server.rx.iter().take(1).count(), 1);
+    assert!(client.runtime.prepare_open_request().is_ok());
     server.join();
 }
 
@@ -83,5 +170,353 @@ fn server_rejection_fails_in_normal_mode() {
     });
     let mut client = Client::connect(default_test_config(server.addr)).unwrap();
     assert!(matches!(client.open(), Err(ClientError::ServerRejected)));
+    assert_eq!(server.rx.iter().take(1).count(), 1);
+    assert!(client.runtime.prepare_open_request().is_ok());
+    server.join();
+}
+
+#[test]
+fn multiple_untrusted_datagrams_before_valid_reply_use_one_attempt() {
+    let params = default_params();
+    let server = start_fake_server(move |socket, tx| {
+        let (_, peer) = recv_request(&socket, &tx);
+        let valid = open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None);
+        let mut wrong_type = valid.clone();
+        wrong_type[3] = FLAG_REPLY;
+        let mut reserved_flags = valid.clone();
+        reserved_flags[3] |= 0x10;
+        let mut bad_magic = valid.clone();
+        bad_magic[0] ^= 0xff;
+        let unexpected_hmac =
+            open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, Some(b"unexpected"));
+
+        for packet in [
+            vec![0_u8],
+            bad_magic,
+            wrong_type,
+            reserved_flags,
+            unexpected_hmac,
+            valid,
+        ] {
+            socket.send_to(&packet, peer).unwrap();
+        }
+    });
+    let mut client = Client::connect(default_test_config(server.addr)).unwrap();
+
+    assert_open_started(client.open().unwrap());
+    assert_eq!(server.rx.iter().take(1).count(), 1);
+    assert!(server.rx.try_recv().is_err());
+    assert!(client.schedule.is_some());
+    server.join();
+}
+
+#[test]
+fn ignored_datagrams_do_not_restart_the_attempt_deadline() {
+    let server = start_fake_server(move |socket, tx| {
+        let (_, peer) = recv_request(&socket, &tx);
+        thread::sleep(Duration::from_millis(150));
+        socket.send_to(&[0_u8], peer).unwrap();
+        thread::sleep(Duration::from_millis(150));
+        socket.send_to(&[0_u8], peer).unwrap();
+        let _ = recv_request(&socket, &tx);
+    });
+    let config = ClientConfig {
+        open_timeouts: vec![Duration::from_millis(250), Duration::from_millis(250)],
+        ..default_test_config(server.addr)
+    };
+    let mut client = Client::connect(config).unwrap();
+    let started = Instant::now();
+
+    assert!(matches!(client.open(), Err(ClientError::OpenTimeout)));
+    let requests: Vec<_> = server.rx.iter().take(2).collect();
+    assert_eq!(requests.len(), 2);
+    assert!(
+        started.elapsed() < Duration::from_millis(700),
+        "ignored datagrams restarted an attempt deadline"
+    );
+    server.join();
+}
+
+#[test]
+fn only_ignored_open_datagrams_eventually_time_out() {
+    let server = start_fake_server(move |socket, tx| {
+        for _ in 0..2 {
+            let (_, peer) = recv_request(&socket, &tx);
+            socket.send_to(&[0_u8], peer).unwrap();
+            socket.send_to(&MAGIC, peer).unwrap();
+        }
+        thread::sleep(Duration::from_millis(300));
+    });
+    let config = ClientConfig {
+        open_timeouts: vec![Duration::from_millis(200), Duration::from_millis(200)],
+        socket_config: crate::SocketConfig {
+            recv_timeout: Some(Duration::from_millis(50)),
+            ..Default::default()
+        },
+        ..default_test_config(server.addr)
+    };
+    let mut client = Client::connect(config).unwrap();
+
+    assert!(matches!(client.open(), Err(ClientError::OpenTimeout)));
+    assert_eq!(server.rx.iter().take(2).count(), 2);
+    assert!(server.rx.try_recv().is_err());
+    assert_eq!(
+        client.test_hooks.last_restored_read_timeout.get(),
+        Some(Duration::from_millis(50))
+    );
+    server.join();
+}
+
+#[test]
+fn trusted_zero_token_normal_reply_is_terminal() {
+    let params = default_params();
+    let server = start_fake_server(move |socket, tx| {
+        let (_, peer) = recv_request(&socket, &tx);
+        // encode_open_reply rejects a zero token without FLAG_CLOSE, so this
+        // deliberately non-compliant reply is built by encoding a normal
+        // reply with a placeholder token and then zeroing the token field.
+        let mut reply = open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None);
+        reply[HMAC_OFFSET..HMAC_OFFSET + 8].copy_from_slice(&0_u64.to_le_bytes());
+        socket.send_to(&reply, peer).unwrap();
+    });
+    let mut client = Client::connect(default_test_config(server.addr)).unwrap();
+
+    assert!(matches!(
+        client.open(),
+        Err(ClientError::Protocol(irtt_proto::ProtoError::ZeroToken))
+    ));
+    assert_eq!(server.rx.iter().take(1).count(), 1);
+    assert!(client.runtime.prepare_open_request().is_ok());
+    assert!(client.schedule.is_none());
+    server.join();
+}
+
+#[test]
+fn opening_deadline_overflow_occurs_before_send() {
+    let server = timeout_server(Duration::from_millis(250));
+    let config = ClientConfig {
+        open_timeouts: vec![Duration::MAX],
+        ..default_test_config(server.addr)
+    };
+    let mut client = Client::connect(config).unwrap();
+
+    assert!(matches!(client.open(), Err(ClientError::DurationOverflow)));
+    assert!(server.rx.try_recv().is_err());
+    server.join();
+}
+
+#[test]
+fn schedule_duration_overflow_cannot_partially_open() {
+    let server = start_fake_server(|_socket, _tx| {});
+    let client = Client::connect(default_test_config(server.addr)).unwrap();
+    let reply = irtt_proto::OpenReply {
+        flags: FLAG_OPEN | FLAG_REPLY,
+        token: TOKEN,
+        params: params_from_config(client.runtime.config()).unwrap(),
+    };
+    let mut latest = Instant::now();
+    let mut step = Duration::MAX;
+    while !step.is_zero() {
+        if let Some(candidate) = latest.checked_add(step) {
+            latest = candidate;
+        }
+        step /= 2;
+    }
+    let opened_at = ClientTimestamp {
+        mono: latest,
+        wall: SystemTime::now(),
+    };
+    let machine = client
+        .runtime
+        .prepare_open_acceptance(reply, opened_at)
+        .unwrap();
+    let previous_recv_len = client.recv_buffer.len();
+
+    let failure = client.prepare_client_open(machine, opened_at).unwrap_err();
+
+    assert!(matches!(
+        failure.primary,
+        ClientError::NegotiationRejected { .. }
+    ));
+    assert!(failure.machine.cleanup_close_packet().is_some());
+    assert!(client.runtime.prepare_open_request().is_ok());
+    assert!(client.schedule.is_none());
+    assert_eq!(client.applied_traffic_class, None);
+    assert_eq!(client.recv_buffer.len(), previous_recv_len);
+    server.join();
+}
+
+#[test]
+fn post_token_negotiation_failure_sends_cleanup_close() {
+    let mut returned = default_params();
+    returned.interval_ns += 1;
+    let server = start_fake_server(move |socket, tx| {
+        let (_, peer) = recv_request(&socket, &tx);
+        socket
+            .send_to(
+                &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &returned, None),
+                peer,
+            )
+            .unwrap();
+        let _ = recv_request(&socket, &tx);
+    });
+    let mut client = Client::connect(default_test_config(server.addr)).unwrap();
+
+    assert!(matches!(
+        client.open(),
+        Err(ClientError::NegotiationRejected { .. })
+    ));
+    let packets: Vec<_> = server.rx.iter().take(2).collect();
+    assert_eq!(packets[1][3], flags::FLAG_CLOSE);
+    assert_eq!(
+        u64::from_le_bytes(packets[1][4..12].try_into().unwrap()),
+        TOKEN
+    );
+    assert!(client.runtime.prepare_open_request().is_ok());
+    server.join();
+}
+
+#[test]
+fn cleanup_send_failure_does_not_replace_primary_open_error() {
+    let mut returned = default_params();
+    returned.interval_ns += 1;
+    let server = start_fake_server(move |socket, tx| {
+        let (_, peer) = recv_request(&socket, &tx);
+        socket
+            .send_to(
+                &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &returned, None),
+                peer,
+            )
+            .unwrap();
+    });
+    let mut client = Client::connect(default_test_config(server.addr)).unwrap();
+    client.test_hooks.fail_cleanup_send.set(true);
+
+    assert!(matches!(
+        client.open(),
+        Err(ClientError::NegotiationRejected { .. })
+    ));
+    assert!(client.runtime.prepare_open_request().is_ok());
+    server.join();
+}
+
+#[test]
+fn receive_buffer_reservation_failure_precedes_dscp_application() {
+    let mut returned = default_params();
+    // Raw wire TOS/Traffic Class byte for DSCP codepoint 46 (EF), matching
+    // what the client below requests so negotiation succeeds unchanged.
+    returned.dscp = 184;
+    let server = start_fake_server(move |socket, tx| {
+        let (_, peer) = recv_request(&socket, &tx);
+        socket
+            .send_to(
+                &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &returned, None),
+                peer,
+            )
+            .unwrap();
+        let _ = recv_request(&socket, &tx);
+    });
+    let mut config = default_test_config(server.addr);
+    config.dscp = 46;
+    let mut client = Client::connect(config).unwrap();
+    client
+        .test_hooks
+        .recv_buffer_len_override
+        .set(Some(usize::MAX));
+    client.test_hooks.fail_open_dscp.set(true);
+
+    assert!(matches!(
+        client.open(),
+        Err(ClientError::AllocationFailed {
+            operation: "negotiated receive buffer",
+            ..
+        })
+    ));
+    assert!(client.test_hooks.fail_open_dscp.get());
+    assert!(client.runtime.prepare_open_request().is_ok());
+    assert!(client.schedule.is_none());
+    assert_eq!(client.applied_traffic_class, None);
+    server.join();
+}
+
+#[test]
+fn dscp_application_failure_leaves_machine_connected() {
+    let params = default_params();
+    let server = start_fake_server(move |socket, tx| {
+        let (_, peer) = recv_request(&socket, &tx);
+        socket
+            .send_to(
+                &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None),
+                peer,
+            )
+            .unwrap();
+        let _ = recv_request(&socket, &tx);
+    });
+    let mut client = Client::connect(default_test_config(server.addr)).unwrap();
+    client.test_hooks.fail_open_dscp.set(true);
+
+    assert!(matches!(
+        client.open(),
+        Err(ClientError::SocketOption {
+            operation: "set negotiated DSCP",
+            ..
+        })
+    ));
+    assert!(client.test_hooks.prepared_active_session_before_dscp.get());
+    assert!(client.runtime.prepare_open_request().is_ok());
+    assert!(client.schedule.is_none());
+    assert_eq!(client.applied_traffic_class, None);
+    server.join();
+}
+
+#[test]
+fn read_timeout_restoration_failure_leaves_machine_connected() {
+    let params = default_params();
+    let server = start_fake_server(move |socket, tx| {
+        let (_, peer) = recv_request(&socket, &tx);
+        socket
+            .send_to(
+                &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None),
+                peer,
+            )
+            .unwrap();
+        let _ = recv_request(&socket, &tx);
+    });
+    let mut client = Client::connect(default_test_config(server.addr)).unwrap();
+    client.test_hooks.fail_open_timeout_restore.set(true);
+
+    assert!(matches!(
+        client.open(),
+        Err(ClientError::ReadTimeoutRestore { .. })
+    ));
+    assert!(client.runtime.prepare_open_request().is_ok());
+    assert!(client.schedule.is_none());
+    assert_eq!(client.applied_traffic_class, None);
+    server.join();
+}
+
+#[test]
+fn dscp_rollback_failure_keeps_timeout_restoration_primary() {
+    let params = default_params();
+    let server = start_fake_server(move |socket, tx| {
+        let (_, peer) = recv_request(&socket, &tx);
+        socket
+            .send_to(
+                &open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None),
+                peer,
+            )
+            .unwrap();
+        let _ = recv_request(&socket, &tx);
+    });
+    let mut client = Client::connect(default_test_config(server.addr)).unwrap();
+    client.test_hooks.fail_open_timeout_restore.set(true);
+    client.test_hooks.fail_dscp_restore.set(true);
+
+    let error = client.open().unwrap_err();
+
+    assert!(matches!(error, ClientError::ReadTimeoutRestore { .. }));
+    assert!(client.runtime.prepare_open_request().is_ok());
+    assert!(client.schedule.is_none());
+    assert_eq!(client.applied_traffic_class, None);
     server.join();
 }

crates/irtt-client/src/client/tests/probes_replies/interrupted_receive.rs

@@ -0,0 +1,80 @@
+use super::*;
+
+/// An interrupted receive (`io::ErrorKind::Interrupted`, e.g. `EINTR`) must be
+/// invisible to the caller: retried transparently, with the eventual reply
+/// classified exactly as if no interruption had occurred.
+#[test]
+fn interrupted_receive_is_retried_and_the_reply_is_still_classified() {
+    let params = default_params();
+    let server = start_fake_server(move |socket, tx| {
+        let (_, peer) = recv_request(&socket, &tx);
+        let reply = open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params, None);
+        socket.send_to(&reply, peer).unwrap();
+
+        let mut buf = [0_u8; 2048];
+        let (size, _) = socket.recv_from(&mut buf).unwrap();
+        let seq = u32::from_le_bytes(buf[12..16].try_into().unwrap());
+        let _ = size;
+        let ts = TimestampFields::default();
+        let reply_packet = echo_reply_packet(TOKEN, seq, &params, &ts, None);
+        socket.send_to(&reply_packet, peer).unwrap();
+    });
+    let config = ClientConfig {
+        socket_config: crate::SocketConfig {
+            recv_timeout: Some(Duration::from_secs(2)),
+            ..Default::default()
+        },
+        ..default_test_config(server.addr)
+    };
+    let mut client = Client::connect(config).unwrap();
+    assert_open_started(client.open().unwrap());
+
+    client.send_probe().unwrap();
+    thread::sleep(Duration::from_millis(50));
+
+    client.test_hooks.inject_recv_interrupted.set(10);
+    let events = client.recv_once().unwrap();
+
+    assert_eq!(events.len(), 1);
+    assert!(
+        matches!(&events[0], ClientEvent::EchoReply { seq: 0, .. }),
+        "expected a normal EchoReply despite interrupted receive attempts, got {:?}",
+        events[0]
+    );
+
+    client.close().unwrap();
+    server.join();
+}
+
+/// One logical receive keeps one timeout budget: repeated interruptions must
+/// not extend a `recv_once` call past its configured receive timeout.
+#[test]
+fn interrupted_receive_does_not_extend_the_configured_timeout() {
+    let params = default_params();
+    let server = silent_open_server(params);
+    let config = ClientConfig {
+        socket_config: crate::SocketConfig {
+            recv_timeout: Some(Duration::from_millis(100)),
+            ..Default::default()
+        },
+        ..default_test_config(server.addr)
+    };
+    let mut client = Client::connect(config).unwrap();
+    assert_open_started(client.open().unwrap());
+
+    // No reply is ever coming; only interrupted attempts occur before the
+    // real socket takes over and legitimately times out.
+    client.test_hooks.inject_recv_interrupted.set(20);
+    let started = Instant::now();
+    let events = client.recv_once().unwrap();
+    let elapsed = started.elapsed();
+
+    assert!(events.is_empty());
+    assert!(
+        elapsed < Duration::from_millis(500),
+        "interrupted receives must not extend the configured receive timeout, took {elapsed:?}"
+    );
+
+    client.close().unwrap();
+    server.join();
+}

crates/irtt-client/src/client/tests/probes_replies/mod.rs

@@ -20,6 +20,7 @@ fn kernel_rx_timestamp_unavailable_skip(test_name: &str) {
 }
 
 mod burst_recv;
+mod interrupted_receive;
 mod packet_length;
 mod probe_schedule;
 mod reply_classification;

crates/irtt-client/src/client/tests/probes_replies/probe_schedule.rs

@@ -1,5 +1,15 @@
 use super::*;
 
+fn probe_timestamps(permission_at: Instant, sent_at: ClientTimestamp) -> ProbeSendTimestamps {
+    ProbeSendTimestamps {
+        permission_at,
+        send_anchor: sent_at,
+        sent_at,
+        send_call_start: sent_at.mono,
+        send_finished_at: sent_at.mono,
+    }
+}
+
 #[test]
 fn send_probe_fails_before_open() {
     let server = start_fake_server(|_socket, _tx| {});
@@ -20,6 +30,7 @@ fn send_probe_sends_valid_echo_request() {
         ..default_test_config(server.addr)
     };
     let mut client = Client::connect(config).unwrap();
+    assert!(client.next_send_deadline().is_none());
     assert_open_started(client.open().unwrap());
     let events = client.send_probe().unwrap();
     assert_eq!(events.len(), 1);
@@ -50,6 +61,216 @@ fn send_probe_sends_valid_echo_request() {
     server.join();
 }
 
+#[test]
+fn blocking_short_probe_commits_before_presentation_length_error() {
+    let params = default_params();
+    let server = silent_open_server(params.clone());
+    let mut client = Client::connect(default_test_config(server.addr)).unwrap();
+    assert_open_started(client.open().unwrap());
+
+    let expected = echo_packet_len(false, &params);
+    let initial_deadline = client.next_send_deadline().unwrap();
+    client.probe_reported_len = Some(expected - 1);
+
+    assert!(matches!(
+        client.send_probe(),
+        Err(ClientError::DatagramLengthMismatch {
+            expected: error_expected,
+            actual,
+        }) if error_expected == expected && actual + 1 == expected
+    ));
+    assert_eq!(client.runtime.packets_sent(), 1);
+    assert_eq!(
+        client.next_send_deadline(),
+        Some(initial_deadline + client.runtime.config().interval)
+    );
+
+    client.close().unwrap();
+    server.join();
+}
+
+#[test]
+fn blocking_failed_probe_send_preserves_machine_and_schedule() {
+    let params = default_params();
+    let server = silent_open_server(params);
+    let mut client = Client::connect(default_test_config(server.addr)).unwrap();
+    assert_open_started(client.open().unwrap());
+
+    let initial_deadline = client.next_send_deadline().unwrap();
+    client.probe_send_error = true;
+
+    assert!(matches!(client.send_probe(), Err(ClientError::Socket(_))));
+    assert_eq!(client.runtime.packets_sent(), 0);
+    assert_eq!(client.next_send_deadline(), Some(initial_deadline));
+
+    assert!(matches!(
+        client.send_probe().unwrap().as_slice(),
+        [ClientEvent::EchoSent { seq: 0, .. }]
+    ));
+
+    client.close().unwrap();
+    server.join();
+}
+
+#[test]
+fn blocking_timeout_finalization_overflow_does_not_send_or_commit() {
+    let params = default_params();
+    let server = silent_open_server(params);
+    let config = ClientConfig {
+        probe_timeout: Duration::MAX,
+        ..default_test_config(server.addr)
+    };
+    let mut client = Client::connect(config).unwrap();
+    assert_open_started(client.open().unwrap());
+
+    let initial_deadline = client.next_send_deadline().unwrap();
+    let sent_at = ClientTimestamp {
+        mono: Instant::now(),
+        wall: SystemTime::now(),
+    };
+
+    assert!(matches!(
+        client.send_probe_at(probe_timestamps(initial_deadline, sent_at)),
+        Err(ClientError::DurationOverflow)
+    ));
+    assert_eq!(client.runtime.packets_sent(), 0);
+    assert_eq!(client.next_send_deadline(), Some(initial_deadline));
+    thread::sleep(Duration::from_millis(30));
+    assert!(server
+        .rx
+        .try_iter()
+        .all(|packet| packet.len() >= 4 && packet[3] & FLAG_OPEN != 0));
+
+    client.close().unwrap();
+    server.join();
+}
+
+#[test]
+fn blocking_probe_separates_permission_committed_send_and_send_call_timing() {
+    let duration = Duration::from_secs(1);
+    let interval = Duration::from_millis(100);
+    let params = Params {
+        duration_ns: 1_000_000_000,
+        interval_ns: 100_000_000,
+        ..default_params()
+    };
+    let server = silent_open_server(params.clone());
+    let config = ClientConfig {
+        duration: Some(duration),
+        interval,
+        ..default_test_config(server.addr)
+    };
+    let mut client = Client::connect(config).unwrap();
+    assert_open_started(client.open().unwrap());
+
+    let opened_mono = Instant::now()
+        .checked_sub(Duration::from_secs(2))
+        .expect("test host monotonic clock has at least two seconds of history");
+    client.schedule = Some(
+        ProbeSchedule::new(
+            opened_mono,
+            &NegotiatedParams {
+                params,
+                restrictions: Vec::new(),
+            },
+        )
+        .unwrap(),
+    );
+    let permission_at = opened_mono + Duration::from_millis(500);
+    // Distinct pre-send anchor and post-send `sent_at`: the anchor drives
+    // the operational timeout deadline, while `sent_at` (captured after the
+    // send call) is the public measurement/timer_error endpoint. They are
+    // deliberately decoupled by this PR.
+    let send_anchor = ClientTimestamp {
+        wall: SystemTime::now(),
+        mono: opened_mono + Duration::from_millis(525),
+    };
+    let sent_at = ClientTimestamp {
+        wall: SystemTime::now(),
+        mono: opened_mono + Duration::from_millis(534),
+    };
+    let timestamps = ProbeSendTimestamps {
+        permission_at,
+        send_anchor,
+        sent_at,
+        send_call_start: opened_mono + Duration::from_millis(526),
+        send_finished_at: opened_mono + Duration::from_millis(533),
+    };
+
+    let events = client.send_probe_at(timestamps).unwrap();
+
+    assert!(matches!(
+        events.as_slice(),
+        [ClientEvent::EchoSent {
+            scheduled_at,
+            sent_at: event_sent_at,
+            send_call,
+            timer_error,
+            ..
+        }] if *scheduled_at == opened_mono
+            && *event_sent_at == sent_at
+            && *send_call == Duration::from_millis(7)
+            && *timer_error == Duration::from_millis(534)
+    ));
+    assert_eq!(client.next_send_deadline(), Some(opened_mono + interval));
+    assert_eq!(client.runtime.packets_sent(), 1);
+    // The timeout deadline is anchored to the pre-send `send_anchor`, not
+    // to the post-send `sent_at` captured 9ms later.
+    let timeout_at = send_anchor.mono + client.probe_timeout();
+    assert_ne!(timeout_at, sent_at.mono + client.probe_timeout());
+    assert!(client
+        .poll_timeouts_at(timeout_at - Duration::from_nanos(1))
+        .unwrap()
+        .is_empty());
+    assert!(matches!(
+        client.poll_timeouts_at(timeout_at).unwrap().as_slice(),
+        [ClientEvent::EchoLoss {
+            sent_at: loss_sent_at,
+            ..
+        }] if *loss_sent_at == sent_at
+    ));
+
+    client.close().unwrap();
+    server.join();
+}
+
+#[test]
+fn blocking_send_call_excludes_wrapped_history_cleanup() {
+    let params = default_params();
+    let server = silent_open_server(params);
+    let mut client = Client::connect(default_test_config(server.addr)).unwrap();
+    assert_open_started(client.open().unwrap());
+
+    let scheduled_at = client.next_send_deadline().unwrap();
+    let sent_at = ClientTimestamp {
+        wall: SystemTime::now(),
+        mono: scheduled_at + Duration::from_millis(5),
+    };
+    client.runtime.seed_wrapped_probe_history_for_test(sent_at);
+    let timestamps = ProbeSendTimestamps {
+        permission_at: scheduled_at,
+        send_anchor: sent_at,
+        sent_at,
+        send_call_start: scheduled_at + Duration::from_millis(6),
+        send_finished_at: scheduled_at + Duration::from_millis(13),
+    };
+
+    let events = client.send_probe_at(timestamps).unwrap();
+
+    assert!(matches!(
+        events.as_slice(),
+        [ClientEvent::EchoSent {
+            seq: 0,
+            send_call,
+            ..
+        }] if *send_call == Duration::from_millis(7)
+    ));
+    assert!(!client.runtime.has_timed_out_metadata());
+
+    client.close().unwrap();
+    server.join();
+}
+
 #[test]
 fn send_probe_respects_finite_duration_exclusive_end() {
     let params = Params {
@@ -81,19 +302,25 @@ fn send_probe_respects_finite_duration_exclusive_end() {
         mono: start,
         wall: SystemTime::now(),
     };
-    assert!(client.send_probe_at(now0).is_ok());
+    assert!(client
+        .send_probe_at(probe_timestamps(now0.mono, now0))
+        .is_ok());
 
     let now1 = ClientTimestamp {
         mono: start + interval,
         wall: SystemTime::now(),
     };
-    assert!(client.send_probe_at(now1).is_ok());
+    assert!(client
+        .send_probe_at(probe_timestamps(now1.mono, now1))
+        .is_ok());
 
     let now2 = ClientTimestamp {
         mono: start + Duration::from_secs(1),
         wall: SystemTime::now(),
     };
-    let events = client.send_probe_at(now2).unwrap();
+    let events = client
+        .send_probe_at(probe_timestamps(now2.mono, now2))
+        .unwrap();
     assert!(events.is_empty());
     assert!(client.next_send_deadline().is_none());
 
@@ -101,6 +328,145 @@ fn send_probe_respects_finite_duration_exclusive_end() {
     server.join();
 }
 
+#[test]
+fn managed_probe_skips_missed_schedule_slots() {
+    let interval = Duration::from_millis(10);
+    let params = Params {
+        protocol_version: 1,
+        duration_ns: 0,
+        interval_ns: 10_000_000,
+        received_stats: ReceivedStats::Both,
+        stamp_at: StampAt::Both,
+        clock: Clock::Both,
+        ..Params::default()
+    };
+    let server = echo_server(params);
+    let config = ClientConfig {
+        duration: None,
+        interval,
+        ..default_test_config(server.addr)
+    };
+    let mut client = Client::connect(config).unwrap();
+    assert_open_started(client.open().unwrap());
+
+    let first_deadline = client.next_send_deadline().unwrap();
+    let permission_at = first_deadline + Duration::from_millis(45);
+    let delayed_send = ClientTimestamp {
+        mono: first_deadline + Duration::from_millis(48),
+        wall: SystemTime::now(),
+    };
+    let timestamps = ProbeSendTimestamps {
+        permission_at,
+        send_anchor: delayed_send,
+        sent_at: delayed_send,
+        send_call_start: first_deadline + Duration::from_millis(49),
+        send_finished_at: first_deadline + Duration::from_millis(55),
+    };
+    let events = client
+        .send_managed_probe_at(first_deadline, timestamps)
+        .unwrap();
+
+    assert_eq!(events.len(), 1);
+    assert!(matches!(
+        events[0],
+        ClientEvent::EchoSent {
+            seq: 0,
+            scheduled_at,
+            sent_at,
+            send_call,
+            timer_error,
+            ..
+        } if scheduled_at == first_deadline + Duration::from_millis(40)
+            && sent_at == delayed_send
+            && send_call == Duration::from_millis(6)
+            && timer_error == Duration::from_millis(8)
+    ));
+    assert_eq!(
+        client.next_send_deadline(),
+        Some(first_deadline + Duration::from_millis(50))
+    );
+
+    client.close().unwrap();
+    server.join();
+}
+
+#[test]
+fn managed_probe_skip_preserves_finite_run_end() {
+    let interval = Duration::from_millis(10);
+    let duration = Duration::from_millis(50);
+    let params = Params {
+        protocol_version: 1,
+        duration_ns: 50_000_000,
+        interval_ns: 10_000_000,
+        received_stats: ReceivedStats::Both,
+        stamp_at: StampAt::Both,
+        clock: Clock::Both,
+        ..Params::default()
+    };
+    let server = echo_server(params);
+    let config = ClientConfig {
+        duration: Some(duration),
+        interval,
+        ..default_test_config(server.addr)
+    };
+    let mut client = Client::connect(config).unwrap();
+    assert_open_started(client.open().unwrap());
+
+    let first_deadline = client.next_send_deadline().unwrap();
+    let delayed_send = ClientTimestamp {
+        mono: first_deadline + Duration::from_millis(45),
+        wall: SystemTime::now(),
+    };
+    let first = client
+        .send_managed_probe_at(
+            first_deadline,
+            probe_timestamps(delayed_send.mono, delayed_send),
+        )
+        .unwrap();
+    let second_sent_at = ClientTimestamp {
+        mono: first_deadline + Duration::from_millis(46),
+        wall: SystemTime::now(),
+    };
+    let second = client
+        .send_managed_probe_at(
+            first_deadline + duration,
+            probe_timestamps(second_sent_at.mono, second_sent_at),
+        )
+        .unwrap();
+
+    assert_eq!(first.len(), 1);
+    assert!(second.is_empty());
+    assert!(client.next_send_deadline().is_none());
+
+    client.close().unwrap();
+    server.join();
+}
+
+#[test]
+fn receive_wait_is_bounded_by_next_ten_millisecond_deadline() {
+    let now = Instant::now();
+    let deadline = now + Duration::from_millis(10);
+
+    assert_eq!(
+        bounded_receive_timeout(
+            Some(deadline),
+            Some(Duration::from_millis(20)),
+            Duration::from_millis(20),
+            now,
+        ),
+        Some(Duration::from_millis(10))
+    );
+    assert_eq!(
+        bounded_receive_timeout(
+            Some(now),
+            Some(Duration::from_millis(20)),
+            Duration::from_millis(20),
+            now,
+        ),
+        None
+    );
+}
+
 #[test]
 fn connect_rejects_invalid_probe_limits() {
     for config in [

crates/irtt-client/src/client/tests/probes_replies/reply_metadata.rs

@@ -14,7 +14,7 @@ fn echo_reply_metadata_propagates_observed_dscp_with_ancillary() {
         let (size, _) = socket.recv_from(&mut buf).unwrap();
         tx.send(buf[..size].to_vec()).unwrap();
         let seq = u32::from_le_bytes(buf[12..16].try_into().unwrap());
-        crate::socket_options::apply_dscp_to_socket(&socket, peer, 46).unwrap();
+        crate::socket_options::apply_traffic_class_to_socket(&socket, peer, 184).unwrap();
         let reply_packet =
             echo_reply_packet(TOKEN, seq, &params, &TimestampFields::default(), None);
         socket.send_to(&reply_packet, peer).unwrap();

crates/irtt-client/src/client/tests/probes_replies/timing_math.rs

@@ -1,4 +1,5 @@
 use super::*;
+use crate::metadata::ReceiveMeta;
 
 #[test]
 fn server_processing_greater_than_raw_does_not_underflow() {
@@ -70,7 +71,17 @@ fn compute_one_way_omits_samples_when_client_wall_time_overflows_i64() {
         ..Default::default()
     };
 
-    assert_eq!(compute_one_way(&sent_at, &received_at, &ts), None);
+    assert_eq!(
+        compute_one_way(
+            &sent_at,
+            sent_at.wall,
+            &received_at,
+            None,
+            &ReceiveMeta::default(),
+            &ts
+        ),
+        None
+    );
 }
 
 #[test]
@@ -89,7 +100,15 @@ fn compute_one_way_returns_available_direction_samples() {
         ..Default::default()
     };
 
-    let sample = compute_one_way(&sent_at, &received_at, &ts).unwrap();
+    let sample = compute_one_way(
+        &sent_at,
+        sent_at.wall,
+        &received_at,
+        None,
+        &ReceiveMeta::default(),
+        &ts,
+    )
+    .unwrap();
     assert_eq!(
         sample.client_to_server,
         Some(SignedDuration::from_nanos(15_000_000))
@@ -116,7 +135,15 @@ fn compute_one_way_preserves_negative_client_to_server_delay() {
         ..Default::default()
     };
 
-    let sample = compute_one_way(&sent_at, &received_at, &ts).unwrap();
+    let sample = compute_one_way(
+        &sent_at,
+        sent_at.wall,
+        &received_at,
+        None,
+        &ReceiveMeta::default(),
+        &ts,
+    )
+    .unwrap();
 
     assert_eq!(
         sample.client_to_server,
@@ -144,7 +171,15 @@ fn compute_one_way_preserves_negative_server_to_client_delay() {
         ..Default::default()
     };
 
-    let sample = compute_one_way(&sent_at, &received_at, &ts).unwrap();
+    let sample = compute_one_way(
+        &sent_at,
+        sent_at.wall,
+        &received_at,
+        None,
+        &ReceiveMeta::default(),
+        &ts,
+    )
+    .unwrap();
 
     assert_eq!(
         sample.client_to_server,

crates/irtt-client/src/client/tests/support.rs

@@ -1,8 +1,8 @@
 use super::*;
 use irtt_proto::{
-    compute_hmac_in_place, echo_packet_len as checked_echo_packet_len, flags::FLAG_HMAC,
-    flags::FLAG_OPEN, flags::FLAG_REPLY, layout::PacketLayout, Clock, ReceivedStats, StampAt,
-    HMAC_SIZE, MAGIC,
+    echo_packet_len as checked_echo_packet_len, encode_echo_reply, encode_open_reply,
+    flags::FLAG_OPEN, flags::FLAG_REPLY, layout::PacketLayout, Clock, EchoReply, OpenReply,
+    ReceivedStats, StampAt,
 };
 use std::{
     net::UdpSocket,
@@ -61,23 +61,21 @@ pub(super) fn open_reply(
     params: &Params,
     hmac_key: Option<&[u8]>,
 ) -> Vec<u8> {
-    let mut packet = Vec::new();
-    packet.extend_from_slice(&MAGIC);
-    packet.push(flags | hmac_key.map_or(0, |_| FLAG_HMAC));
-    if hmac_key.is_some() {
-        packet.extend_from_slice(&[0_u8; HMAC_SIZE]);
-    }
-    packet.extend_from_slice(&token.to_le_bytes());
-    packet.extend_from_slice(&params.encode());
-    if let Some(key) = hmac_key {
-        compute_hmac_in_place(key, &mut packet, HMAC_OFFSET).unwrap();
-    }
-    packet
+    encode_open_reply(
+        &OpenReply {
+            flags,
+            token,
+            params: params.clone(),
+        },
+        hmac_key,
+    )
+    .unwrap()
 }
 
+/// Test params always name a representable length, so the platform
+/// representability check cannot fire here.
 pub(crate) fn echo_packet_len(hmac: bool, params: &Params) -> usize {
-    checked_echo_packet_len(hmac, params)
-        .expect("test params must have a non-negative packet length")
+    checked_echo_packet_len(hmac, params).expect("test params must have a representable length")
 }
 
 pub(super) fn echo_reply_packet(
@@ -98,55 +96,28 @@ pub(super) fn echo_reply_packet_with_flags(
     hmac_key: Option<&[u8]>,
     flags: u8,
 ) -> Vec<u8> {
-    let has_hmac = hmac_key.is_some();
-    let layout = PacketLayout::echo(has_hmac, params);
-    let packet_len = echo_packet_len(has_hmac, params);
-    let mut packet = Vec::with_capacity(packet_len);
-
-    let mut flags = flags;
-    if has_hmac {
-        flags |= FLAG_HMAC;
-    }
-    packet.extend_from_slice(&MAGIC);
-    packet.push(flags);
-    if has_hmac {
-        packet.extend_from_slice(&[0_u8; HMAC_SIZE]);
-    }
-    packet.extend_from_slice(&token.to_le_bytes());
-    packet.extend_from_slice(&seq.to_le_bytes());
-
-    if layout.recv_count {
-        packet.extend_from_slice(&42_u32.to_le_bytes());
-    }
-    if layout.recv_window {
-        packet.extend_from_slice(&0x07_u64.to_le_bytes());
-    }
-
-    if layout.recv_wall {
-        packet.extend_from_slice(&timestamps.recv_wall.unwrap_or(0).to_le_bytes());
-    }
-    if layout.recv_mono {
-        packet.extend_from_slice(&timestamps.recv_mono.unwrap_or(0).to_le_bytes());
-    }
-    if layout.midpoint_wall {
-        packet.extend_from_slice(&timestamps.midpoint_wall.unwrap_or(0).to_le_bytes());
-    }
-    if layout.midpoint_mono {
-        packet.extend_from_slice(&timestamps.midpoint_mono.unwrap_or(0).to_le_bytes());
-    }
-    if layout.send_wall {
-        packet.extend_from_slice(&timestamps.send_wall.unwrap_or(0).to_le_bytes());
-    }
-    if layout.send_mono {
-        packet.extend_from_slice(&timestamps.send_mono.unwrap_or(0).to_le_bytes());
-    }
-
-    packet.resize(packet_len, 0);
-
-    if let Some(key) = hmac_key {
-        compute_hmac_in_place(key, &mut packet, HMAC_OFFSET).unwrap();
-    }
-    packet
+    let layout = PacketLayout::echo(hmac_key.is_some(), params);
+    let reply = EchoReply {
+        flags,
+        token,
+        sequence: seq,
+        recv_count: layout.recv_count.then_some(42),
+        recv_window: layout.recv_window.then_some(0x07),
+        timestamps: TimestampFields {
+            recv_wall: layout.recv_wall.then(|| timestamps.recv_wall.unwrap_or(0)),
+            recv_mono: layout.recv_mono.then(|| timestamps.recv_mono.unwrap_or(0)),
+            midpoint_wall: layout
+                .midpoint_wall
+                .then(|| timestamps.midpoint_wall.unwrap_or(0)),
+            midpoint_mono: layout
+                .midpoint_mono
+                .then(|| timestamps.midpoint_mono.unwrap_or(0)),
+            send_wall: layout.send_wall.then(|| timestamps.send_wall.unwrap_or(0)),
+            send_mono: layout.send_mono.then(|| timestamps.send_mono.unwrap_or(0)),
+        },
+        payload: Vec::new(),
+    };
+    encode_echo_reply(&reply, params, hmac_key).unwrap()
 }
 
 pub(super) fn open_success_server(params: Params) -> FakeServer {

crates/irtt-client/src/config.rs

@@ -12,8 +12,10 @@ use irtt_proto::{Clock, ReceivedStats, StampAt};
 pub(crate) const DEFAULT_PORT: u16 = 2112;
 /// Largest valid DSCP codepoint accepted by client configuration.
 ///
-/// DSCP is a six-bit value in the range `0..=63`. The client maps it into the
-/// socket traffic-class field when configuring packet priority.
+/// DSCP is a six-bit value in the range `0..=63`. The client shifts it left
+/// by two bits into the raw IP TOS / Traffic Class byte carried by
+/// [`irtt_proto::Params::dscp`] and applied to the socket during the active
+/// test phase.
 pub const MAX_DSCP_CODEPOINT: u8 = 63;
 /// Largest IPv4 TTL or IPv6 hop-limit value accepted by client configuration.
 ///
@@ -75,6 +77,10 @@ pub struct ClientConfig {
     /// Requested timestamp placement in echo replies.
     pub stamp_at: StampAt,
     /// Requested server clock sources for timestamp fields.
+    ///
+    /// [`Clock::Unspecified`] is the wire default meaning "no clock tag was
+    /// sent" and is not a client mode; opening a session with it is rejected.
+    /// Request [`Clock::Wall`], [`Clock::Monotonic`], or [`Clock::Both`].
     pub clock: Clock,
     /// Requested DSCP codepoint.
     ///

crates/irtt-client/src/error.rs

@@ -1,4 +1,4 @@
-use std::{io, time::Duration};
+use std::{collections::TryReserveError, io, time::Duration};
 
 use thiserror::Error;
 
@@ -12,6 +12,10 @@ use thiserror::Error;
 #[derive(Debug, Error)]
 #[non_exhaustive]
 pub enum ClientError {
+    /// A Tokio-backed client operation was polled without a current runtime.
+    #[cfg(feature = "tokio")]
+    #[error("Tokio AsyncClient requires a current Tokio runtime")]
+    NoTokioRuntime,
     /// The configured server address could not be resolved to a socket address.
     ///
     /// Check the host, port, address-family restrictions, and name service
@@ -38,8 +42,8 @@ pub enum ClientError {
     },
     /// Restoring the configured read timeout after open negotiation failed.
     ///
-    /// The session may have opened successfully, but the socket could not be
-    /// returned to the caller's requested receive-timeout behavior.
+    /// The prepared session was not committed, and the client remains
+    /// connected rather than partially open.
     #[error("failed to restore configured socket read timeout after open negotiation: {source}")]
     ReadTimeoutRestore { source: io::Error },
     /// A packet failed IRTT protocol parsing or authentication.
@@ -146,32 +150,40 @@ pub enum ClientError {
     /// sending again.
     #[error("pending probe limit exceeded ({limit})")]
     PendingLimitExceeded { limit: usize },
+    /// A wrapping wire sequence is still represented by an in-flight probe.
+    ///
+    /// The existing probe must be replied to or timed out before that sequence
+    /// can be reused.
+    #[error("wire sequence {seq} is still pending")]
+    PendingSequenceCollision { seq: u32 },
+    /// A prepared probe no longer matches the session's next wire sequence.
+    ///
+    /// Prepare the probe again after any intervening successful send.
+    #[error(
+        "prepared probe sequence {prepared_seq} is stale; next wire sequence is {next_wire_seq}"
+    )]
+    StalePreparedProbe {
+        prepared_seq: u32,
+        next_wire_seq: u32,
+    },
+    /// Reserving memory required by an operation failed before any datagram was
+    /// sent or logical protocol state was changed.
+    #[error("failed to reserve memory for {operation}: {source}")]
+    AllocationFailed {
+        operation: &'static str,
+        #[source]
+        source: TryReserveError,
+    },
+    /// UDP reported successful acceptance of a datagram with an unexpected
+    /// byte count.
+    ///
+    /// The send is committed locally before this transport invariant failure
+    /// is returned because the kernel reported success.
+    #[error("UDP accepted {actual} bytes for a {expected}-byte datagram")]
+    DatagramLengthMismatch { expected: usize, actual: usize },
     /// Client configuration failed validation before the requested operation.
     ///
     /// The reported reason names a value that must be changed before retrying.
     #[error("invalid configuration: {reason}")]
     InvalidConfig { reason: String },
-    /// A managed-session worker thread panicked before producing an outcome.
-    ///
-    /// This is a runtime failure from joining the managed session, not a
-    /// protocol response from the server.
-    #[error("managed client worker thread panicked")]
-    WorkerPanicked,
-}
-
-/// Failure reported while setting up or receiving from an event subscription.
-///
-/// Zero-capacity subscriber queues are rejected when subscriptions are created.
-/// Once a subscription exists, this error type reports delivery failures observed
-/// by [`EventSubscription`](crate::EventSubscription).
-#[derive(Debug, Error, Clone, Copy, PartialEq, Eq)]
-pub enum EventSubscriptionError {
-    /// The subscription can no longer receive new events.
-    ///
-    /// Already queued events are delivered first. After the queue is drained,
-    /// `recv` and `try_recv` return this error when the hub disconnects the
-    /// subscriber, the hub is shut down, or the subscription is disconnected by
-    /// its overflow policy.
-    #[error("event subscription is disconnected")]
-    Disconnected,
 }

crates/irtt-client/src/event.rs

@@ -66,9 +66,10 @@ pub enum ClientEvent {
         /// Client timestamp when the open reply was accepted.
         at: ClientTimestamp,
     },
-    /// The client sent a close request and considers the session closed.
+    /// The session closed locally or through an authenticated peer close.
     ///
-    /// This is a local lifecycle event, not an acknowledgement from the server.
+    /// For a peer close-flagged echo reply, the reply's measurement or
+    /// classification event is emitted immediately before this event.
     /// Managed sessions disconnect event subscribers after the worker exits,
     /// while leaving already queued events available to drain.
     SessionClosed {
@@ -93,14 +94,19 @@ pub enum ClientEvent {
         remote: SocketAddr,
         /// Monotonic deadline at which the probe was scheduled to be sent.
         scheduled_at: Instant,
-        /// Client wall/monotonic timestamp captured for the send.
+        /// Paired client wall/monotonic timestamp captured immediately after
+        /// the successful UDP send completed. This is the RTT and userspace
+        /// upstream one-way-delay fallback endpoint. The operational probe
+        /// timeout deadline is computed from an earlier, private, pre-send
+        /// timestamp instead — see the client crate's `AGENTS.md`.
         sent_at: ClientTimestamp,
         /// Number of bytes passed to the UDP socket.
         bytes: usize,
-        /// Elapsed time spent in the socket send call.
+        /// Elapsed time spent in the socket send call, excluding protocol and
+        /// scheduler commit work.
         send_call: Duration,
-        /// Absolute difference between the scheduled send time and actual send
-        /// timestamp.
+        /// Absolute difference between the scheduled send time and the
+        /// post-send `sent_at` timestamp above.
         timer_error: Duration,
     },
 
@@ -114,7 +120,8 @@ pub enum ClientEvent {
         seq: u32,
         /// Resolved remote socket address.
         remote: SocketAddr,
-        /// Client timestamp recorded when the matching request was sent.
+        /// Client timestamp recorded immediately after the matching request
+        /// finished sending (see `ClientEvent::EchoSent::sent_at`).
         sent_at: ClientTimestamp,
         /// Client timestamp recorded when the reply was received.
         received_at: ClientTimestamp,
@@ -140,7 +147,10 @@ pub enum ClientEvent {
     EchoLoss {
         /// Wire sequence number that timed out.
         seq: u32,
-        /// Client timestamp recorded when the request was sent.
+        /// Client timestamp recorded immediately after the request finished
+        /// sending (see `ClientEvent::EchoSent::sent_at`). The timeout
+        /// deadline below is anchored to an earlier, private, pre-send
+        /// timestamp, not to this one.
         sent_at: ClientTimestamp,
         /// Monotonic deadline at which the probe was declared lost.
         timeout_at: std::time::Instant,
@@ -175,7 +185,8 @@ pub enum ClientEvent {
         highest_seen: u32,
         /// Resolved remote socket address.
         remote: SocketAddr,
-        /// Original client send timestamp, when still retained.
+        /// Original post-send client timestamp, when still retained (see
+        /// `ClientEvent::EchoSent::sent_at`).
         sent_at: Option<ClientTimestamp>,
         /// Client timestamp recorded when the late reply was received.
         received_at: ClientTimestamp,
@@ -340,12 +351,31 @@ pub struct OneWayDelaySample {
     /// Client-to-server delay.
     ///
     /// This is computed from the client send wall time and the server receive
-    /// wall time when both are available.
+    /// wall time when both are available. The client send endpoint is the
+    /// correlated Linux kernel TX timestamp for this send when one is
+    /// available and plausible for this send, and the userspace post-send wall
+    /// time otherwise. The server receive endpoint is whatever wall time the
+    /// peer reported; against this crate's own Tokio server runtime on Linux
+    /// (the `irtt-server` applet), that is its kernel receive timestamp when
+    /// one is available and plausible, and its userspace receive wall time
+    /// otherwise. Against another IRTT-compatible peer, or an application
+    /// driving `irtt_server::ServerCore::handle_datagram` directly, the
+    /// client has no way to know which clock source produced it — the public
+    /// `ServerCore` API never supplies a kernel timestamp of its own accord.
+    /// `RttSample::raw` is unaffected and remains a userspace
+    /// monotonic measurement, but `adjusted` and `effective` can still shift:
+    /// when the session negotiated wall-clock timing rather than monotonic,
+    /// server processing time is derived from this same server receive
+    /// endpoint.
     pub client_to_server: Option<SignedDuration>,
     /// Server-to-client delay.
     ///
     /// This is computed from the server send wall time and the client receive
-    /// wall time when both are available.
+    /// wall time when both are available. The client receive endpoint is the
+    /// kernel receive timestamp reported with the datagram when one is
+    /// available and plausible for this receive, and the userspace receive wall
+    /// time otherwise. RTT is unaffected and remains a userspace monotonic
+    /// measurement.
     pub server_to_client: Option<SignedDuration>,
 }
 
@@ -358,7 +388,10 @@ pub struct OneWayDelaySample {
 pub struct ReceivedStatsSample {
     /// Server-reported count of received packets, when available.
     pub count: Option<u32>,
-    /// Server-reported receive window value, when available.
+    /// Raw server-reported receive window bitmap, when available.
+    ///
+    /// The bitmap is preserved exactly as it appeared on the wire; the client
+    /// does not interpret its bits.
     pub window: Option<u64>,
 }
 
@@ -371,5 +404,11 @@ pub struct PacketMeta {
     pub traffic_class: Option<u8>,
     pub dscp: Option<u8>,
     pub ecn: Option<u8>,
+    /// Kernel software receive timestamp reported with the datagram, where the
+    /// platform provides one.
+    ///
+    /// This is the raw observed value, reported whether or not it was accepted
+    /// as the downstream one-way delay endpoint. It is a kernel software
+    /// timestamp, not a NIC hardware ingress time.
     pub kernel_rx_timestamp: Option<std::time::SystemTime>,
 }

crates/irtt-client/src/lib.rs

@@ -3,6 +3,8 @@
 //! `irtt-client` opens IRTT-compatible sessions, sends echo probes, receives
 //! replies, classifies loss/late/duplicate packets, and emits [`ClientEvent`]
 //! values for callers to consume directly or aggregate with `irtt-stats`.
+//! With the `tokio` feature enabled, `AsyncClient` provides the same low-level
+//! lifecycle for callers that own a Tokio runtime and drive readiness directly.
 //!
 //! Timing values intentionally preserve signed measurement semantics. When
 //! server timing is available, [`RttSample::effective`] is adjusted for server
@@ -11,76 +13,48 @@
 //! also signed when the required wall-clock timestamps are available; negative
 //! values usually indicate client/server clock skew.
 //!
-//! A managed session can drive the socket loop on a worker thread and publish
-//! events through a subscription:
+//! [`Client`] is the runtime-free low-level blocking adapter and requires no
+//! Tokio dependency at all; it is what a caller without a runtime, or that
+//! wants full control over its own event loop, should start from. With the
+//! `tokio` feature, `AsyncClient` provides the corresponding low-level Tokio
+//! adapter for a caller that owns a runtime and drives socket readiness
+//! itself. [`managed`] sits above both: `ManagedClientTask` /
+//! `ManagedClientHandle` (`tokio` feature) run and control one or more
+//! targets under a Tokio runtime, and `BlockingManagedClient` (`tokio`
+//! feature) wraps that in a synchronous owner backed by its own dedicated
+//! current-thread runtime for callers that want managed multi-target
+//! behavior without touching Tokio themselves.
 //!
-//! ```no_run
-//! use std::time::Duration;
+//! See `examples/` in the repository for a runnable example of each tier.
 //!
-//! use irtt_client::{ClientConfig, ClientEvent, ManagedClient, SubscriberConfig};
-//!
-//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
-//! let config = ClientConfig {
-//!     server_addr: "127.0.0.1:2112".to_owned(),
-//!     duration: Some(Duration::from_secs(10)),
-//!     interval: Duration::from_secs(1),
-//!     ..ClientConfig::default()
-//! };
-//!
-//! let (session, events) =
-//!     ManagedClient::start_with_subscription(config, SubscriberConfig::default())?;
-//!
-//! while let Ok(event) = events.recv() {
-//!     match event {
-//!         ClientEvent::EchoReply { seq, rtt, .. } => {
-//!             println!("seq={seq} effective_rtt_us={}", rtt.effective.as_micros());
-//!         }
-//!         ClientEvent::SessionClosed { .. } => break,
-//!         _ => {}
-//!     }
-//! }
-//!
-//! let _outcome = session.join()?;
-//! # Ok(())
-//! # }
-//! ```
-//!
-#![cfg_attr(
-    not(all(target_os = "linux", feature = "ancillary")),
-    forbid(unsafe_code)
-)]
-#![cfg_attr(all(target_os = "linux", feature = "ancillary"), deny(unsafe_code))]
+#![forbid(unsafe_code)]
 
+#[cfg(feature = "tokio")]
+mod async_client;
 mod client;
 mod config;
 mod error;
 mod event;
-mod managed;
+pub mod managed;
 mod metadata;
 mod probe;
 mod receive;
-mod runtime;
 mod session;
 mod socket;
 mod socket_options;
 mod timing;
 
+#[cfg(feature = "tokio")]
+pub use async_client::AsyncClient;
 pub use client::Client;
 pub use config::{
     ClientAuthConfig, ClientConfig, NegotiationPolicy, RecvBudget, RunMode, SocketConfig,
     MAX_DSCP_CODEPOINT, MAX_SERVER_FILL_BYTES, MAX_TTL, MAX_UDP_PAYLOAD_LENGTH,
 };
-pub use error::{ClientError, EventSubscriptionError};
+pub use error::ClientError;
 pub use event::{
     ClientEvent, OneWayDelaySample, OpenOutcome, PacketMeta, ReceivedStatsSample, RttSample,
     ServerTiming, SignedDuration, WarningKind,
 };
-pub use managed::{
-    CancellationToken, EventHub, EventSubscription, ManagedClient, ManagedClientGroup,
-    ManagedClientGroupConfig, ManagedClientGroupSession, ManagedClientSession,
-    ManagedGroupEndReason, ManagedGroupOutcome, ManagedGroupPacing, ManagedTargetConfig,
-    ManagedTargetEndReason, ManagedTargetOutcome, SessionEndReason, SessionOutcome,
-    SubscriberConfig, SubscriberOverflow, TargetEvent, TargetEventSubscription, TargetId,
-};
 pub use session::{NegotiatedParams, NegotiationRestriction};
 pub use timing::ClientTimestamp;

crates/irtt-client/src/managed/blocking.rs

@@ -0,0 +1,183 @@
+use std::{
+    thread::{self, JoinHandle},
+    time::Duration,
+};
+
+use thiserror::Error;
+use tokio::runtime::{Builder, Runtime};
+
+use super::{
+    ManagedClient, ManagedClientConfig, ManagedClientHandle, ManagedClientTask, ManagedConfigError,
+    ManagedEventSubscription, ManagedOutcome, ManagedSubscribeError, ManagedTargetConfig,
+};
+
+const BLOCKING_RUNTIME_SHUTDOWN_TIMEOUT: Duration = Duration::from_millis(100);
+
+/// Owns the runtime used exclusively by the blocking managed worker.
+pub(super) struct WorkerRuntime {
+    runtime: Option<Runtime>,
+}
+
+impl WorkerRuntime {
+    pub(super) fn new(runtime: Runtime) -> Self {
+        Self {
+            runtime: Some(runtime),
+        }
+    }
+
+    fn block_on<F: std::future::Future>(&self, task: F) -> F::Output {
+        self.runtime
+            .as_ref()
+            .expect("worker runtime is available until shutdown")
+            .block_on(task)
+    }
+
+    /// Shut down residual runtime work without delaying managed completion indefinitely.
+    pub(super) fn shutdown(mut self) {
+        self.runtime
+            .take()
+            .expect("worker runtime is available until shutdown")
+            .shutdown_timeout(BLOCKING_RUNTIME_SHUTDOWN_TIMEOUT);
+    }
+}
+
+impl Drop for WorkerRuntime {
+    fn drop(&mut self) {
+        if let Some(runtime) = self.runtime.take() {
+            runtime.shutdown_background();
+        }
+    }
+}
+
+/// Failure to start a blocking managed client owner.
+#[derive(Debug, Error)]
+pub enum BlockingManagedStartError {
+    /// The managed task configuration was invalid.
+    #[error(transparent)]
+    Config(#[from] ManagedConfigError),
+
+    /// The managed event subscription could not be created before startup.
+    #[error(transparent)]
+    Subscribe(#[from] ManagedSubscribeError),
+
+    /// The dedicated Tokio runtime could not be created.
+    #[error("failed to create blocking managed Tokio runtime: {source}")]
+    Runtime {
+        #[source]
+        source: std::io::Error,
+    },
+
+    /// The dedicated worker thread could not be spawned.
+    #[error("failed to spawn blocking managed worker thread: {source}")]
+    ThreadSpawn {
+        #[source]
+        source: std::io::Error,
+    },
+}
+
+/// Failure to obtain completion from a blocking managed client owner.
+#[derive(Debug, Error, Eq, PartialEq)]
+pub enum BlockingManagedJoinError {
+    /// The dedicated managed worker thread panicked.
+    #[error("blocking managed worker thread panicked")]
+    WorkerPanicked,
+}
+
+/// Blocking completion owner for one unified managed Tokio task.
+///
+/// This owner runs exactly one [`ManagedClient`] task on one dedicated OS thread
+/// with its own current-thread Tokio runtime. Dropping a live owner requests a
+/// graceful stop and synchronously joins that worker, so drop may block while
+/// bounded managed cleanup completes.
+#[must_use = "dropping the blocking managed owner requests stop and joins its worker"]
+pub struct BlockingManagedClient {
+    handle: ManagedClientHandle,
+    worker: Option<JoinHandle<ManagedOutcome>>,
+}
+
+impl BlockingManagedClient {
+    /// Validate configuration, create a dedicated runtime, and start its worker.
+    pub fn start(
+        config: ManagedClientConfig,
+        targets: Vec<ManagedTargetConfig>,
+    ) -> Result<Self, BlockingManagedStartError> {
+        let (task, handle) = ManagedClient::task(config, targets)?;
+        Self::start_task(task, handle)
+    }
+
+    /// Validate configuration, subscribe to presentation events, and start a
+    /// dedicated managed worker.
+    ///
+    /// The returned subscription exists before the managed task receives its
+    /// first poll, so it cannot miss startup events because of subscription
+    /// ordering.
+    pub fn start_with_subscription(
+        config: ManagedClientConfig,
+        targets: Vec<ManagedTargetConfig>,
+    ) -> Result<(Self, ManagedEventSubscription), BlockingManagedStartError> {
+        let (task, handle) = ManagedClient::task(config, targets)?;
+        let subscription = handle.subscribe()?;
+        let owner = Self::start_task(task, handle)?;
+        Ok((owner, subscription))
+    }
+
+    fn start_task(
+        task: ManagedClientTask,
+        handle: ManagedClientHandle,
+    ) -> Result<Self, BlockingManagedStartError> {
+        let runtime = Builder::new_current_thread()
+            .enable_io()
+            .enable_time()
+            .build()
+            .map_err(|source| BlockingManagedStartError::Runtime { source })?;
+        let runtime = WorkerRuntime::new(runtime);
+        let worker = thread::Builder::new()
+            .name("irtt-managed".to_owned())
+            .spawn(move || {
+                let outcome = runtime.block_on(task);
+                runtime.shutdown();
+                outcome
+            })
+            .map_err(|source| BlockingManagedStartError::ThreadSpawn { source })?;
+
+        Ok(Self {
+            handle,
+            worker: Some(worker),
+        })
+    }
+
+    /// Return a cloned managed control and observation capability.
+    pub fn handle(&self) -> ManagedClientHandle {
+        self.handle.clone()
+    }
+
+    /// Wait synchronously for the managed task's authoritative outcome.
+    pub fn join(mut self) -> Result<ManagedOutcome, BlockingManagedJoinError> {
+        self.join_worker()
+    }
+
+    fn join_worker(&mut self) -> Result<ManagedOutcome, BlockingManagedJoinError> {
+        join_worker(
+            self.worker
+                .take()
+                .expect("blocking managed worker is joined at most once"),
+        )
+    }
+}
+
+pub(super) fn join_worker(
+    worker: JoinHandle<ManagedOutcome>,
+) -> Result<ManagedOutcome, BlockingManagedJoinError> {
+    worker
+        .join()
+        .map_err(|_| BlockingManagedJoinError::WorkerPanicked)
+}
+
+impl Drop for BlockingManagedClient {
+    fn drop(&mut self) {
+        if self.worker.is_some() {
+            let _receipt = self.handle.stop();
+            let _ = self.join_worker();
+        }
+    }
+}

crates/irtt-client/src/managed/blocking_tests.rs

@@ -0,0 +1,389 @@
+use std::{
+    net::{SocketAddr, UdpSocket},
+    sync::{mpsc::sync_channel, Arc, Condvar, Mutex},
+    thread::{self, JoinHandle},
+    time::{Duration, Instant},
+};
+
+use irtt_proto::{
+    decode_request, encode_echo_reply, encode_open_reply, flags, DecodedRequestKind, EchoReply,
+    OpenReply, Params, ReceivedStats, StampAt, TimestampFields,
+};
+use tokio::{runtime::Builder, time::timeout};
+
+use super::{
+    blocking::{join_worker, WorkerRuntime},
+    BlockingManagedClient, BlockingManagedJoinError, ManagedClientConfig, ManagedCompletionPolicy,
+    ManagedEndReason, ManagedEvent, ManagedLifecycle, ManagedPacing, ManagedTargetConfig,
+    ManagedTargetEndReason,
+};
+use crate::ClientConfig;
+
+const TOKEN: u64 = 0x1234_5678_90ab_cdef;
+
+struct Signal {
+    value: Mutex<bool>,
+    ready: Condvar,
+}
+
+impl Signal {
+    fn set(&self) {
+        *self.value.lock().unwrap() = true;
+        self.ready.notify_all();
+    }
+
+    fn wait(&self) {
+        let value = self.value.lock().unwrap();
+        let (value, timeout) = self
+            .ready
+            .wait_timeout_while(value, Duration::from_secs(2), |value| !*value)
+            .unwrap();
+        assert!(*value && !timeout.timed_out());
+    }
+}
+
+struct EchoServer {
+    addr: SocketAddr,
+    probe: Arc<Signal>,
+    close: Arc<Signal>,
+    worker: JoinHandle<()>,
+}
+
+impl EchoServer {
+    fn start() -> Self {
+        let socket = UdpSocket::bind("127.0.0.1:0").unwrap();
+        socket
+            .set_read_timeout(Some(Duration::from_secs(3)))
+            .unwrap();
+        let addr = socket.local_addr().unwrap();
+        let probe = Arc::new(Signal {
+            value: Mutex::new(false),
+            ready: Condvar::new(),
+        });
+        let close = Arc::new(Signal {
+            value: Mutex::new(false),
+            ready: Condvar::new(),
+        });
+        let worker_probe = Arc::clone(&probe);
+        let worker_close = Arc::clone(&close);
+        let worker = thread::spawn(move || {
+            let mut buffer = [0_u8; 8192];
+            let (open_len, peer) = socket.recv_from(&mut buffer).unwrap();
+            let negotiated = match decode_request(&buffer[..open_len]).unwrap().kind {
+                DecodedRequestKind::Open { params, .. } => Params::decode(params).unwrap(),
+                other => panic!("expected an open request, got {other:?}"),
+            };
+            let reply = encode_open_reply(
+                &OpenReply {
+                    flags: flags::FLAG_OPEN | flags::FLAG_REPLY,
+                    token: TOKEN,
+                    params: negotiated.clone(),
+                },
+                None,
+            )
+            .unwrap();
+            socket.send_to(&reply, peer).unwrap();
+
+            loop {
+                let (len, packet_peer) = socket.recv_from(&mut buffer).unwrap();
+                let Ok(request) = decode_request(&buffer[..len]) else {
+                    continue;
+                };
+                match request.kind {
+                    DecodedRequestKind::Echo { sequence, .. } => {
+                        worker_probe.set();
+                        let reply = encode_echo_reply(
+                            &EchoReply {
+                                flags: flags::FLAG_REPLY,
+                                token: TOKEN,
+                                sequence,
+                                recv_count: None,
+                                recv_window: None,
+                                timestamps: TimestampFields::default(),
+                                payload: Vec::new(),
+                            },
+                            &negotiated,
+                            None,
+                        )
+                        .unwrap();
+                        socket.send_to(&reply, packet_peer).unwrap();
+                    }
+                    DecodedRequestKind::Close { .. } => {
+                        worker_close.set();
+                        return;
+                    }
+                    DecodedRequestKind::Open { .. } => {}
+                }
+            }
+        });
+        Self {
+            addr,
+            probe,
+            close,
+            worker,
+        }
+    }
+
+    fn wait_probe(&self) {
+        self.probe.wait();
+    }
+
+    fn wait_close(&self) {
+        self.close.wait();
+    }
+
+    fn finish(self) {
+        self.worker.join().unwrap();
+    }
+}
+
+fn test_runtime() -> tokio::runtime::Runtime {
+    Builder::new_current_thread()
+        .enable_io()
+        .enable_time()
+        .build()
+        .unwrap()
+}
+
+fn config(completion: ManagedCompletionPolicy) -> ManagedClientConfig {
+    ManagedClientConfig {
+        client: ClientConfig {
+            duration: Some(Duration::from_millis(120)),
+            interval: Duration::from_millis(20),
+            probe_timeout: Duration::from_millis(40),
+            open_timeouts: vec![Duration::from_millis(200)],
+            received_stats: ReceivedStats::None,
+            stamp_at: StampAt::None,
+            ..ClientConfig::default()
+        },
+        pacing: ManagedPacing::Burst,
+        completion,
+        final_drain: Duration::from_millis(5),
+        ..ManagedClientConfig::default()
+    }
+}
+
+fn target(server: &EchoServer) -> ManagedTargetConfig {
+    ManagedTargetConfig::new("target", server.addr.to_string())
+}
+
+fn assert_stopped(outcome: &super::ManagedOutcome) {
+    assert_eq!(outcome.end_reason, ManagedEndReason::StopRequested);
+}
+
+#[test]
+fn starts_without_caller_runtime_and_finishes_naturally() {
+    let server = EchoServer::start();
+    let owner = BlockingManagedClient::start(
+        config(ManagedCompletionPolicy::FinishWhenQuiescent),
+        vec![target(&server)],
+    )
+    .unwrap();
+
+    server.wait_probe();
+    let outcome = owner.join().unwrap();
+    assert_eq!(outcome.end_reason, ManagedEndReason::TargetsComplete);
+    assert_eq!(outcome.recent_target_outcomes.len(), 1);
+    assert_eq!(
+        outcome.recent_target_outcomes[0].end_reason,
+        ManagedTargetEndReason::TestComplete
+    );
+    server.wait_close();
+    server.finish();
+}
+
+#[test]
+fn subscribed_start_captures_events_from_a_short_run() {
+    let server = EchoServer::start();
+    let (owner, mut events) = BlockingManagedClient::start_with_subscription(
+        config(ManagedCompletionPolicy::FinishWhenQuiescent),
+        vec![target(&server)],
+    )
+    .unwrap();
+
+    server.wait_probe();
+    let outcome = owner.join().unwrap();
+    assert_eq!(outcome.end_reason, ManagedEndReason::TargetsComplete);
+
+    let mut saw_started = false;
+    let mut saw_finished = false;
+    let mut saw_completed = false;
+    while let Ok(event) = events.try_recv() {
+        match event {
+            ManagedEvent::Started => saw_started = true,
+            ManagedEvent::TargetFinished { .. } => saw_finished = true,
+            ManagedEvent::Completed { .. } => saw_completed = true,
+            _ => {}
+        }
+    }
+    assert!(saw_started && saw_finished && saw_completed);
+    server.wait_close();
+    server.finish();
+}
+
+#[test]
+fn external_handle_stop_ends_with_graceful_close() {
+    let server = EchoServer::start();
+    let owner = BlockingManagedClient::start(
+        config(ManagedCompletionPolicy::ExplicitStop),
+        vec![target(&server)],
+    )
+    .unwrap();
+    let handle = owner.handle();
+
+    server.wait_probe();
+    test_runtime().block_on(async {
+        timeout(Duration::from_secs(2), handle.stop())
+            .await
+            .unwrap();
+    });
+    let outcome = owner.join().unwrap();
+    assert_stopped(&outcome);
+    server.wait_close();
+    server.finish();
+}
+
+#[test]
+fn dynamic_update_reaches_background_worker() {
+    let server = EchoServer::start();
+    let owner = BlockingManagedClient::start(config(ManagedCompletionPolicy::ExplicitStop), vec![])
+        .unwrap();
+    let handle = owner.handle();
+
+    let acknowledgement = handle
+        .update_targets(vec![target(&server)])
+        .unwrap()
+        .blocking_wait()
+        .unwrap();
+    assert_eq!(acknowledgement.sequence, 1);
+    server.wait_probe();
+    test_runtime().block_on(async {
+        timeout(Duration::from_secs(2), owner.handle().stop())
+            .await
+            .unwrap();
+    });
+    assert_stopped(&owner.join().unwrap());
+    server.wait_close();
+    server.finish();
+}
+
+#[test]
+fn dropping_external_handles_does_not_stop_owner() {
+    let server = EchoServer::start();
+    let owner = BlockingManagedClient::start(
+        config(ManagedCompletionPolicy::FinishWhenQuiescent),
+        vec![target(&server)],
+    )
+    .unwrap();
+    drop(owner.handle());
+    drop(owner.handle());
+
+    server.wait_probe();
+    assert_eq!(
+        owner.join().unwrap().end_reason,
+        ManagedEndReason::TargetsComplete
+    );
+    server.wait_close();
+    server.finish();
+}
+
+#[test]
+fn dropping_owner_stops_and_joins_worker() {
+    let server = EchoServer::start();
+    let owner = BlockingManagedClient::start(
+        config(ManagedCompletionPolicy::ExplicitStop),
+        vec![target(&server)],
+    )
+    .unwrap();
+    let handle = owner.handle();
+
+    server.wait_probe();
+    drop(owner);
+    let status = handle.status();
+    assert_eq!(status.lifecycle, ManagedLifecycle::Completed);
+    assert_eq!(
+        status.final_outcome.as_ref().unwrap().end_reason,
+        ManagedEndReason::StopRequested
+    );
+    server.wait_close();
+    server.finish();
+}
+
+#[test]
+fn worker_panic_is_a_join_error() {
+    let worker = thread::spawn(|| -> super::ManagedOutcome { panic!("test worker panic") });
+    assert_eq!(
+        join_worker(worker),
+        Err(BlockingManagedJoinError::WorkerPanicked)
+    );
+}
+
+#[test]
+fn dropping_worker_runtime_inside_async_context_does_not_panic() {
+    test_runtime().block_on(async {
+        let runtime = Builder::new_current_thread()
+            .enable_io()
+            .enable_time()
+            .build()
+            .unwrap();
+        drop(WorkerRuntime::new(runtime));
+    });
+}
+
+#[test]
+fn worker_runtime_shutdown_is_bounded_with_blocking_work() {
+    let runtime = Builder::new_current_thread()
+        .enable_io()
+        .enable_time()
+        .build()
+        .unwrap();
+    let (started_send, started_receive) = sync_channel(0);
+    let (release_send, release_receive) = sync_channel(0);
+
+    runtime.block_on(async move {
+        tokio::task::spawn_blocking(move || {
+            started_send.send(()).unwrap();
+            release_receive.recv().unwrap();
+        });
+    });
+    started_receive
+        .recv_timeout(Duration::from_secs(2))
+        .unwrap();
+
+    let started = Instant::now();
+    WorkerRuntime::new(runtime).shutdown();
+    assert!(started.elapsed() < Duration::from_secs(2));
+    release_send.send(()).unwrap();
+}
+
+#[test]
+fn drop_after_natural_completion_preserves_outcome() {
+    let server = EchoServer::start();
+    let owner = BlockingManagedClient::start(
+        config(ManagedCompletionPolicy::FinishWhenQuiescent),
+        vec![target(&server)],
+    )
+    .unwrap();
+    let handle = owner.handle();
+    server.wait_probe();
+    server.wait_close();
+    let deadline = Instant::now() + Duration::from_secs(2);
+    let status = loop {
+        let status = handle.status();
+        if status.lifecycle == ManagedLifecycle::Completed && status.final_outcome.is_some() {
+            break status;
+        }
+        assert!(Instant::now() < deadline, "managed worker did not complete");
+        thread::sleep(Duration::from_millis(5));
+    };
+    assert_eq!(
+        status.final_outcome.as_ref().unwrap().end_reason,
+        ManagedEndReason::TargetsComplete
+    );
+    drop(owner);
+    assert_eq!(
+        handle.status().final_outcome.as_ref().unwrap().end_reason,
+        ManagedEndReason::TargetsComplete
+    );
+    server.finish();
+}

crates/irtt-client/src/managed/cancellation.rs

@@ -1,52 +0,0 @@
-use std::sync::{
-    atomic::{AtomicBool, Ordering},
-    Arc,
-};
-
-/// Cloneable cooperative cancellation flag.
-///
-/// Managed sessions use this internally to ask their worker loop to stop. It is
-/// exported for callers that want the same simple cancellation primitive in
-/// code built around `irtt-client`.
-#[derive(Debug, Clone, Default)]
-pub struct CancellationToken {
-    cancelled: Arc<AtomicBool>,
-}
-
-impl CancellationToken {
-    /// Create a token in the non-cancelled state.
-    pub fn new() -> Self {
-        Self::default()
-    }
-
-    /// Mark the token as cancelled.
-    ///
-    /// Cancellation is idempotent and is visible through all clones of the
-    /// token.
-    pub fn cancel(&self) {
-        self.cancelled.store(true, Ordering::SeqCst);
-    }
-
-    /// Return whether cancellation has been requested.
-    #[must_use]
-    pub fn is_cancelled(&self) -> bool {
-        self.cancelled.load(Ordering::SeqCst)
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn cancel_is_idempotent_and_visible_through_clones() {
-        let token = CancellationToken::new();
-        let clone = token.clone();
-
-        token.cancel();
-        token.cancel();
-
-        assert!(token.is_cancelled());
-        assert!(clone.is_cancelled());
-    }
-}

crates/irtt-client/src/managed/hub.rs

@@ -1,460 +0,0 @@
-use std::{
-    collections::{HashMap, VecDeque},
-    sync::{
-        atomic::{AtomicU64, Ordering},
-        Arc, Condvar, Mutex, Weak,
-    },
-};
-
-use crate::{error::EventSubscriptionError, event::ClientEvent};
-
-/// Configuration for one managed event subscriber.
-///
-/// Each subscriber has an independent bounded queue. The queue bounds memory
-/// growth when event production is faster than that subscriber's consumer.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct SubscriberConfig {
-    /// Maximum number of events buffered for this subscriber.
-    ///
-    /// Must be greater than zero.
-    pub capacity: usize,
-    /// Policy applied when publishing to a full subscriber queue.
-    pub overflow: SubscriberOverflow,
-}
-
-impl Default for SubscriberConfig {
-    fn default() -> Self {
-        Self {
-            capacity: 1024,
-            overflow: SubscriberOverflow::DropNewest,
-        }
-    }
-}
-
-/// Overflow behavior for a bounded event subscription queue.
-///
-/// These policies are applied independently per subscriber when that
-/// subscriber's queue is full.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum SubscriberOverflow {
-    /// Leave the existing queue unchanged and discard the newly published event.
-    DropNewest,
-    /// Remove the oldest queued event and enqueue the newly published event.
-    DropOldest,
-    /// Disconnect the subscriber and clear its queue.
-    Disconnect,
-}
-
-/// Publish/subscribe fan-out for managed event values.
-///
-/// `EventHub` is used by managed sessions internally and is also exported for
-/// callers that want the same bounded subscription behavior around their own
-/// event producer. Publishing clones each event once per subscriber.
-#[derive(Debug)]
-pub struct EventHub<T = ClientEvent> {
-    inner: Arc<HubInner<T>>,
-}
-
-#[derive(Debug)]
-struct HubInner<T> {
-    next_id: AtomicU64,
-    subscribers: Mutex<HashMap<u64, Arc<SubscriberInner<T>>>>,
-}
-
-/// Handle for receiving managed client events.
-///
-/// Each subscription has its own bounded queue configured by
-/// [`SubscriberConfig`]. The configured [`SubscriberOverflow`] policy applies
-/// when that queue is full. Dropping the handle unregisters the subscriber.
-#[must_use = "dropping the subscription unregisters it"]
-#[derive(Debug)]
-pub struct EventSubscription<T = ClientEvent> {
-    id: u64,
-    hub: Weak<HubInner<T>>,
-    inner: Arc<SubscriberInner<T>>,
-}
-
-#[derive(Debug)]
-struct SubscriberInner<T> {
-    state: Mutex<SubscriberState<T>>,
-    available: Condvar,
-    config: SubscriberConfig,
-}
-
-#[derive(Debug)]
-struct SubscriberState<T> {
-    queue: VecDeque<T>,
-    connected: bool,
-}
-
-impl<T> Clone for EventHub<T> {
-    fn clone(&self) -> Self {
-        Self {
-            inner: self.inner.clone(),
-        }
-    }
-}
-
-impl<T> EventHub<T> {
-    /// Create an empty event hub with no subscribers.
-    pub fn new() -> Self {
-        Self {
-            inner: Arc::new(HubInner {
-                next_id: AtomicU64::new(1),
-                subscribers: Mutex::new(HashMap::new()),
-            }),
-        }
-    }
-
-    /// Register a new subscriber with its own bounded queue.
-    ///
-    /// Returns an error when `config.capacity` is zero.
-    pub fn subscribe(
-        &self,
-        config: SubscriberConfig,
-    ) -> Result<EventSubscription<T>, crate::ClientError> {
-        if config.capacity == 0 {
-            return Err(crate::ClientError::InvalidConfig {
-                reason: "subscriber capacity must be greater than zero".to_owned(),
-            });
-        }
-
-        let id = self.inner.next_id.fetch_add(1, Ordering::Relaxed);
-        let inner = Arc::new(SubscriberInner {
-            state: Mutex::new(SubscriberState {
-                queue: VecDeque::with_capacity(config.capacity),
-                connected: true,
-            }),
-            available: Condvar::new(),
-            config,
-        });
-        self.inner
-            .subscribers
-            .lock()
-            .expect("event hub mutex poisoned")
-            .insert(id, inner.clone());
-
-        Ok(EventSubscription {
-            id,
-            hub: Arc::downgrade(&self.inner),
-            inner,
-        })
-    }
-
-    /// Disconnect all subscribers after leaving their already queued events
-    /// available to drain.
-    pub fn disconnect_all(&self) {
-        let subscribers: Vec<Arc<SubscriberInner<T>>> = self
-            .inner
-            .subscribers
-            .lock()
-            .expect("event hub mutex poisoned")
-            .drain()
-            .map(|(_, subscriber)| subscriber)
-            .collect();
-
-        for subscriber in subscribers {
-            subscriber.disconnect();
-        }
-    }
-
-    #[cfg(test)]
-    fn subscriber_count(&self) -> usize {
-        self.inner
-            .subscribers
-            .lock()
-            .expect("event hub mutex poisoned")
-            .len()
-    }
-}
-
-impl<T: Clone> EventHub<T> {
-    /// Publish an event to all currently connected subscribers.
-    ///
-    /// Slow subscribers are handled according to their
-    /// [`SubscriberOverflow`] policy. Publishing does not block waiting for a
-    /// subscriber to consume queued events.
-    pub fn publish(&self, event: T) {
-        let subscribers: Vec<(u64, Arc<SubscriberInner<T>>)> = self
-            .inner
-            .subscribers
-            .lock()
-            .expect("event hub mutex poisoned")
-            .iter()
-            .map(|(id, subscriber)| (*id, subscriber.clone()))
-            .collect();
-
-        let mut disconnected = Vec::new();
-        for (id, subscriber) in subscribers {
-            // Events are cloned per subscriber; bounded queues keep slow
-            // consumers from causing unbounded memory growth.
-            if !subscriber.publish(event.clone()) {
-                disconnected.push(id);
-            }
-        }
-
-        if disconnected.is_empty() {
-            return;
-        }
-
-        let mut subscribers = self
-            .inner
-            .subscribers
-            .lock()
-            .expect("event hub mutex poisoned");
-        for id in disconnected {
-            subscribers.remove(&id);
-        }
-    }
-}
-
-impl<T> Default for EventHub<T> {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-impl<T> EventSubscription<T> {
-    /// Block until the next queued event is available.
-    ///
-    /// If the subscription is disconnected, this returns
-    /// [`EventSubscriptionError::Disconnected`] after any already queued events
-    /// have been drained.
-    pub fn recv(&self) -> Result<T, EventSubscriptionError> {
-        let mut state = self.inner.state.lock().expect("subscriber mutex poisoned");
-        loop {
-            if let Some(event) = state.queue.pop_front() {
-                return Ok(event);
-            }
-            if !state.connected {
-                return Err(EventSubscriptionError::Disconnected);
-            }
-            state = self
-                .inner
-                .available
-                .wait(state)
-                .expect("subscriber mutex poisoned");
-        }
-    }
-
-    /// Try to receive one queued event without blocking.
-    ///
-    /// Returns `Ok(None)` when the subscription is still connected but no event
-    /// is queued. If the subscription is disconnected, this returns
-    /// [`EventSubscriptionError::Disconnected`] after any already queued events
-    /// have been drained.
-    pub fn try_recv(&self) -> Result<Option<T>, EventSubscriptionError> {
-        let mut state = self.inner.state.lock().expect("subscriber mutex poisoned");
-        if let Some(event) = state.queue.pop_front() {
-            return Ok(Some(event));
-        }
-        if !state.connected {
-            return Err(EventSubscriptionError::Disconnected);
-        }
-        Ok(None)
-    }
-}
-
-impl<T> Drop for EventSubscription<T> {
-    fn drop(&mut self) {
-        self.inner.disconnect();
-        if let Some(hub) = self.hub.upgrade() {
-            hub.subscribers
-                .lock()
-                .expect("event hub mutex poisoned")
-                .remove(&self.id);
-        }
-    }
-}
-
-impl<T> SubscriberInner<T> {
-    fn publish(&self, event: T) -> bool {
-        let mut state = self.state.lock().expect("subscriber mutex poisoned");
-        if !state.connected {
-            return false;
-        }
-
-        if state.queue.len() < self.config.capacity {
-            state.queue.push_back(event);
-            self.available.notify_one();
-            return true;
-        }
-
-        match self.config.overflow {
-            SubscriberOverflow::DropNewest => true,
-            SubscriberOverflow::DropOldest => {
-                state.queue.pop_front();
-                state.queue.push_back(event);
-                self.available.notify_one();
-                true
-            }
-            SubscriberOverflow::Disconnect => {
-                state.queue.clear();
-                state.connected = false;
-                self.available.notify_all();
-                false
-            }
-        }
-    }
-
-    fn disconnect(&self) {
-        let mut state = self.state.lock().expect("subscriber mutex poisoned");
-        state.connected = false;
-        self.available.notify_all();
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::{ClientTimestamp, WarningKind};
-
-    fn event(n: usize) -> ClientEvent {
-        ClientEvent::Warning {
-            kind: WarningKind::UntrackedReply,
-            message: format!("event-{n}"),
-            at: ClientTimestamp::now(),
-        }
-    }
-
-    fn event_message(event: ClientEvent) -> String {
-        match event {
-            ClientEvent::Warning { message, .. } => message,
-            other => panic!("unexpected event: {other:?}"),
-        }
-    }
-
-    fn assert_next(
-        sub: &EventSubscription,
-        expected: Result<Option<&str>, EventSubscriptionError>,
-    ) {
-        match (sub.try_recv(), expected) {
-            (Ok(Some(event)), Ok(Some(message))) => assert_eq!(event_message(event), message),
-            (Ok(None), Ok(None)) => {}
-            (Err(actual), Err(expected)) => assert_eq!(actual, expected),
-            (actual, expected) => panic!("expected {expected:?}, got {actual:?}"),
-        }
-    }
-
-    #[test]
-    fn publishes_to_multiple_subscribers() {
-        let hub = EventHub::new();
-        let a = hub.subscribe(SubscriberConfig::default()).unwrap();
-        let b = hub.subscribe(SubscriberConfig::default()).unwrap();
-
-        hub.publish(event(1));
-
-        assert_eq!(event_message(a.try_recv().unwrap().unwrap()), "event-1");
-        assert_eq!(event_message(b.try_recv().unwrap().unwrap()), "event-1");
-    }
-
-    #[test]
-    fn full_subscriber_overflow_policy_is_applied() {
-        let cases = [
-            (
-                SubscriberOverflow::DropNewest,
-                Ok(Some("event-1")),
-                Ok(None),
-            ),
-            (
-                SubscriberOverflow::DropOldest,
-                Ok(Some("event-2")),
-                Ok(None),
-            ),
-            (
-                SubscriberOverflow::Disconnect,
-                Err(EventSubscriptionError::Disconnected),
-                Err(EventSubscriptionError::Disconnected),
-            ),
-        ];
-
-        for (overflow, first_expected, second_expected) in cases {
-            let hub = EventHub::new();
-            let sub = hub
-                .subscribe(SubscriberConfig {
-                    capacity: 1,
-                    overflow,
-                })
-                .unwrap();
-
-            hub.publish(event(1));
-            hub.publish(event(2));
-
-            assert_next(&sub, first_expected);
-            assert_next(&sub, second_expected);
-        }
-    }
-
-    #[test]
-    fn full_subscriber_does_not_prevent_other_delivery() {
-        let hub = EventHub::new();
-        let slow = hub
-            .subscribe(SubscriberConfig {
-                capacity: 1,
-                overflow: SubscriberOverflow::DropNewest,
-            })
-            .unwrap();
-        let fast = hub
-            .subscribe(SubscriberConfig {
-                capacity: 4,
-                overflow: SubscriberOverflow::DropNewest,
-            })
-            .unwrap();
-
-        hub.publish(event(1));
-        hub.publish(event(2));
-
-        assert_eq!(event_message(slow.try_recv().unwrap().unwrap()), "event-1");
-        assert_eq!(event_message(fast.try_recv().unwrap().unwrap()), "event-1");
-        assert_eq!(event_message(fast.try_recv().unwrap().unwrap()), "event-2");
-    }
-
-    #[test]
-    fn subscribing_after_events_does_not_replay() {
-        let hub = EventHub::new();
-        hub.publish(event(1));
-
-        let sub = hub.subscribe(SubscriberConfig::default()).unwrap();
-
-        assert!(sub.try_recv().unwrap().is_none());
-    }
-
-    #[test]
-    fn dropping_subscription_unregisters_from_hub() {
-        let hub: EventHub = EventHub::new();
-        let sub = hub.subscribe(SubscriberConfig::default()).unwrap();
-        assert_eq!(hub.subscriber_count(), 1);
-
-        drop(sub);
-
-        assert_eq!(hub.subscriber_count(), 0);
-    }
-
-    #[test]
-    fn disconnect_all_wakes_blocking_receivers() {
-        let hub: EventHub = EventHub::new();
-        let sub = hub.subscribe(SubscriberConfig::default()).unwrap();
-        hub.disconnect_all();
-
-        assert_eq!(
-            sub.recv().unwrap_err(),
-            EventSubscriptionError::Disconnected
-        );
-    }
-
-    #[test]
-    fn session_closed_event_can_be_queued() {
-        let hub = EventHub::new();
-        let sub = hub.subscribe(SubscriberConfig::default()).unwrap();
-        hub.publish(ClientEvent::SessionClosed {
-            remote: "127.0.0.1:1".parse().unwrap(),
-            token: 1,
-            at: ClientTimestamp::now(),
-        });
-
-        assert!(matches!(
-            sub.recv().unwrap(),
-            ClientEvent::SessionClosed { token: 1, .. }
-        ));
-    }
-}

crates/irtt-client/src/managed/mod.rs

@@ -1,13 +1,20 @@
-mod cancellation;
-mod group;
-mod hub;
-mod runner;
+mod target_id;
 
-pub use cancellation::CancellationToken;
-pub use group::{
-    ManagedClientGroup, ManagedClientGroupConfig, ManagedClientGroupSession, ManagedGroupEndReason,
-    ManagedGroupOutcome, ManagedGroupPacing, ManagedTargetConfig, ManagedTargetEndReason,
-    ManagedTargetOutcome, TargetEvent, TargetEventSubscription, TargetId,
-};
-pub use hub::{EventHub, EventSubscription, SubscriberConfig, SubscriberOverflow};
-pub use runner::{ManagedClient, ManagedClientSession, SessionEndReason, SessionOutcome};
+pub use target_id::TargetId;
+
+#[cfg(feature = "tokio")]
+mod blocking;
+#[cfg(feature = "tokio")]
+mod model;
+#[cfg(feature = "tokio")]
+mod task;
+
+#[cfg(feature = "tokio")]
+pub use blocking::*;
+#[cfg(feature = "tokio")]
+pub use model::*;
+#[cfg(feature = "tokio")]
+pub use task::*;
+
+#[cfg(all(feature = "tokio", test))]
+mod blocking_tests;

crates/irtt-client/src/managed/model.rs

@@ -0,0 +1,647 @@
+use std::{fmt, net::SocketAddr, sync::Arc, time::Duration};
+
+use thiserror::Error;
+
+use crate::{ClientAuthConfig, ClientConfig, ClientError, ClientEvent};
+
+use super::TargetId;
+
+/// Default capacity of the lossy managed event channel.
+pub const DEFAULT_MANAGED_EVENT_CAPACITY: usize = 256;
+/// Default capacity of the bounded managed control queue.
+pub const DEFAULT_MANAGED_COMMAND_CAPACITY: usize = 64;
+/// Default number of recent target outcomes retained in status and output.
+pub const DEFAULT_MANAGED_OUTCOME_HISTORY_LIMIT: usize = 256;
+/// Default maximum number of simultaneously live target generations.
+pub const DEFAULT_MANAGED_MAX_LIVE_TARGET_GENERATIONS: usize = 256;
+/// Default time retained for late replies after the final committed timeout.
+pub const DEFAULT_MANAGED_FINAL_DRAIN: Duration = Duration::from_millis(100);
+
+/// One globally allocated incarnation of a target within a managed task.
+///
+/// Generations increase globally across the task, not independently per ID.
+#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+pub struct TargetInstance {
+    pub id: TargetId,
+    pub generation: u64,
+}
+
+/// Endpoint and optional authentication override for one managed target.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ManagedTargetConfig {
+    pub id: TargetId,
+    pub server_addr: String,
+    pub auth: Option<ClientAuthConfig>,
+}
+
+impl ManagedTargetConfig {
+    pub fn new(id: impl Into<TargetId>, server_addr: impl Into<String>) -> Self {
+        Self {
+            id: id.into(),
+            server_addr: server_addr.into(),
+            auth: None,
+        }
+    }
+}
+
+/// Coordination mode for sends across active targets.
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub enum ManagedPacing {
+    #[default]
+    Staggered,
+    Burst,
+}
+
+/// Policy controlling top-level natural completion.
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub enum ManagedCompletionPolicy {
+    #[default]
+    FinishWhenQuiescent,
+    ExplicitStop,
+}
+
+/// Shared configuration for one managed task.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ManagedClientConfig {
+    pub client: ClientConfig,
+    pub pacing: ManagedPacing,
+    pub completion: ManagedCompletionPolicy,
+    pub event_capacity: usize,
+    pub command_capacity: usize,
+    pub outcome_history_limit: usize,
+    pub max_live_target_generations: usize,
+    pub final_drain: Duration,
+}
+
+impl Default for ManagedClientConfig {
+    fn default() -> Self {
+        Self {
+            client: ClientConfig::default(),
+            pacing: ManagedPacing::default(),
+            completion: ManagedCompletionPolicy::default(),
+            event_capacity: DEFAULT_MANAGED_EVENT_CAPACITY,
+            command_capacity: DEFAULT_MANAGED_COMMAND_CAPACITY,
+            outcome_history_limit: DEFAULT_MANAGED_OUTCOME_HISTORY_LIMIT,
+            max_live_target_generations: DEFAULT_MANAGED_MAX_LIVE_TARGET_GENERATIONS,
+            final_drain: DEFAULT_MANAGED_FINAL_DRAIN,
+        }
+    }
+}
+
+/// Durable top-level lifecycle.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ManagedLifecycle {
+    NotStarted,
+    Running,
+    Stopping,
+    Completed,
+    Failed,
+    Abandoned,
+}
+
+/// Durable lifecycle for one target generation.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ManagedTargetLifecycle {
+    Pending,
+    Connecting,
+    Opening,
+    Active,
+    Draining,
+    Closing,
+    Terminal,
+}
+
+/// Status for one target generation.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ManagedTargetStatus {
+    pub target: TargetInstance,
+    pub desired: bool,
+    pub lifecycle: ManagedTargetLifecycle,
+    pub server_addr: Arc<str>,
+    pub remote: Option<SocketAddr>,
+}
+
+/// Authoritative immutable managed status snapshot.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ManagedStatus {
+    pub lifecycle: ManagedLifecycle,
+    pub stop_requested: bool,
+    pub applied_command_sequence: u64,
+    pub desired_target_count: usize,
+    pub connecting_target_count: usize,
+    pub opening_target_count: usize,
+    pub active_target_count: usize,
+    pub draining_target_count: usize,
+    pub closing_target_count: usize,
+    pub terminal_target_count: usize,
+    pub total_target_outcomes: u64,
+    pub successful_target_outcomes: u64,
+    pub failed_target_outcomes: u64,
+    pub peer_closed_target_outcomes: u64,
+    pub discarded_target_outcomes: u64,
+    pub targets: Arc<[ManagedTargetStatus]>,
+    pub recent_target_outcomes: Arc<[ManagedTargetOutcome]>,
+    pub final_outcome: Option<Arc<ManagedOutcome>>,
+}
+
+/// Lossy presentation event emitted by the managed task.
+#[allow(clippy::large_enum_variant)]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum ManagedEvent {
+    Started,
+    TargetStateChanged {
+        target: TargetInstance,
+        lifecycle: ManagedTargetLifecycle,
+    },
+    Client {
+        target: TargetInstance,
+        event: ClientEvent,
+    },
+    TargetFinished {
+        outcome: Arc<ManagedTargetOutcome>,
+    },
+    Stopping,
+    Completed {
+        outcome: Arc<ManagedOutcome>,
+    },
+    Failed {
+        outcome: Arc<ManagedOutcome>,
+    },
+    Abandoned,
+}
+
+/// Receiving half of the lossy managed event stream.
+pub type ManagedEventSubscription = tokio::sync::broadcast::Receiver<ManagedEvent>;
+
+/// Immediate result of attempting to receive a managed presentation event.
+pub type ManagedEventTryRecvError = tokio::sync::broadcast::error::TryRecvError;
+
+/// Final authoritative outcome returned by the task.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ManagedOutcome {
+    pub end_reason: ManagedEndReason,
+    pub applied_command_sequence: u64,
+    pub total_target_outcomes: u64,
+    pub successful_target_outcomes: u64,
+    pub failed_target_outcomes: u64,
+    pub peer_closed_target_outcomes: u64,
+    pub discarded_target_outcomes: u64,
+    pub recent_target_outcomes: Arc<[ManagedTargetOutcome]>,
+}
+
+/// Why the managed task ended.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum ManagedEndReason {
+    TargetsComplete,
+    StopRequested,
+    DriverFailed(ManagedDriverFailure),
+}
+
+/// Durable outcome for one target generation.
+///
+/// These counters are durable: unlike [`ManagedEvent`], which is a lossy
+/// presentation stream, they account for everything the target observed.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ManagedTargetOutcome {
+    pub target: TargetInstance,
+    pub server_addr: Arc<str>,
+    pub remote: Option<SocketAddr>,
+    pub end_reason: ManagedTargetEndReason,
+    /// Probes the underlying client reported as sent.
+    pub packets_sent: u64,
+    /// Unique echo replies that arrived in order and before their probe timed
+    /// out.
+    ///
+    /// A unique reply that arrives behind an already-received sequence, or
+    /// after its own probe timed out, is counted by `late` instead.
+    pub replies_received: u64,
+    /// Replies for a sequence that had already been answered.
+    pub duplicates: u64,
+    /// Late replies: those arriving behind an already-received sequence
+    /// (reordering) or after their own probe timed out.
+    ///
+    /// This counts every late reply, whether or not the client could still
+    /// match it to retained send state.
+    pub late: u64,
+    /// Warning events observed for this target.
+    pub warning_events: u64,
+    pub cleanup_failure: Option<ManagedTargetFailure>,
+}
+
+/// Why one target generation ended.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum ManagedTargetEndReason {
+    TestComplete,
+    NoTestComplete,
+    PeerClosed,
+    Removed,
+    Replaced,
+    Stopped,
+    Failed(ManagedTargetFailure),
+}
+
+/// Phase in which a target-local failure occurred.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ManagedTargetFailurePhase {
+    Connecting,
+    Opening,
+    Sending,
+    Receiving,
+    Timing,
+    Closing,
+}
+
+impl fmt::Display for ManagedTargetFailurePhase {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let text = match self {
+            Self::Connecting => "connecting",
+            Self::Opening => "opening",
+            Self::Sending => "sending",
+            Self::Receiving => "receiving",
+            Self::Timing => "timing",
+            Self::Closing => "closing",
+        };
+        f.write_str(text)
+    }
+}
+
+/// Stable category for a target-local failure.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ManagedTargetFailureKind {
+    Resolve,
+    Socket,
+    SocketOption,
+    Protocol,
+    Timeout,
+    Configuration,
+    ResourceExhausted,
+    InvalidState,
+    /// A failure that deliberately has no more specific category.
+    ///
+    /// This is a classification decision, not a fallback: every current
+    /// [`ClientError`] variant is classified explicitly, so nothing reaches
+    /// this category by default.
+    Other,
+}
+
+impl fmt::Display for ManagedTargetFailureKind {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let text = match self {
+            Self::Resolve => "resolve",
+            Self::Socket => "socket",
+            Self::SocketOption => "socket option",
+            Self::Protocol => "protocol",
+            Self::Timeout => "timeout",
+            Self::Configuration => "configuration",
+            Self::ResourceExhausted => "resource exhausted",
+            Self::InvalidState => "invalid state",
+            Self::Other => "other",
+        };
+        f.write_str(text)
+    }
+}
+
+/// Durable target-local failure details.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ManagedTargetFailure {
+    pub phase: ManagedTargetFailurePhase,
+    pub kind: ManagedTargetFailureKind,
+    pub message: Arc<str>,
+}
+
+/// Configuration failure detected before any runtime work begins.
+#[derive(Debug, Error)]
+pub enum ManagedConfigError {
+    #[error("FinishWhenQuiescent requires at least one initial target")]
+    EmptyInitialTargets,
+    #[error("duplicate managed target id {id}")]
+    DuplicateTargetId { id: TargetId },
+    #[error("configured {configured} targets exceeds live-generation limit {limit}")]
+    TooManyTargets { configured: usize, limit: usize },
+    #[error("managed event capacity must be greater than zero")]
+    ZeroEventCapacity,
+    #[error("managed event capacity {configured} exceeds Tokio's maximum {maximum}")]
+    EventCapacityTooLarge { configured: usize, maximum: usize },
+    #[error("managed command capacity must be greater than zero")]
+    ZeroCommandCapacity,
+    #[error("managed command capacity {configured} exceeds Tokio's maximum {maximum}")]
+    CommandCapacityTooLarge { configured: usize, maximum: usize },
+    #[error("managed live-generation limit must be greater than zero")]
+    ZeroLiveGenerationLimit,
+    #[error("managed final drain {duration:?} cannot be scheduled from the current instant")]
+    UnschedulableFinalDrain { duration: Duration },
+    #[error("invalid managed target {id}: {source}")]
+    InvalidTarget {
+        id: TargetId,
+        #[source]
+        source: ClientError,
+    },
+    #[error("managed target generation space is exhausted")]
+    GenerationExhausted,
+}
+
+/// Immediate failure to submit a managed target update.
+#[derive(Clone, Debug, Eq, Error, PartialEq)]
+pub enum ManagedCommandError {
+    #[error("managed target updates are no longer accepted")]
+    Stopping,
+    #[error("managed target update contains {configured} targets but the limit is {limit}")]
+    TooManyTargets { configured: usize, limit: usize },
+    #[error("managed command queue is full")]
+    QueueFull,
+    #[error("managed command receiver is closed")]
+    DriverClosed,
+}
+
+/// Failure while applying an accepted managed target update.
+#[derive(Debug, Error)]
+pub enum ManagedCommandApplyError {
+    #[error("managed target updates are no longer accepted")]
+    Stopping,
+    #[error("duplicate target id {id}")]
+    DuplicateTargetId { id: TargetId },
+    #[error("invalid configuration for target {id}: {source}")]
+    InvalidTarget {
+        id: TargetId,
+        #[source]
+        source: ClientError,
+    },
+    #[error("target update requires {required} live generations but limit is {limit}")]
+    LiveGenerationLimitExceeded { required: usize, limit: usize },
+    #[error("managed target generation space is exhausted")]
+    GenerationExhausted,
+    #[error("managed command sequence is exhausted")]
+    CommandSequenceExhausted,
+    #[error("managed task ended before command acknowledgement")]
+    AcknowledgementDisconnected,
+    #[error("managed driver failed before command application: {0}")]
+    DriverFailed(ManagedDriverFailure),
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ManagedCommandAcknowledgement {
+    pub sequence: u64,
+    pub status: Arc<ManagedStatus>,
+}
+
+/// Failure to create a new event subscription.
+#[derive(Clone, Debug, Eq, Error, PartialEq)]
+pub enum ManagedSubscribeError {
+    #[error("managed event stream is closed")]
+    Closed,
+}
+
+/// Whole-driver failure.
+#[derive(Clone, Debug, Eq, Error, PartialEq)]
+pub enum ManagedDriverFailure {
+    #[error("ManagedClientTask requires a current Tokio runtime")]
+    NoTokioRuntime,
+    #[error("managed driver exhausted resources for {operation}")]
+    ResourceExhausted { operation: &'static str },
+    #[error("managed driver invariant failed: {message}")]
+    Internal { message: Arc<str> },
+}
+
+/// Map a [`ClientError`] onto its durable managed failure classification.
+///
+/// The match is deliberately exhaustive over every [`ClientError`] variant. A
+/// new variant must fail to compile here until its real classification is
+/// chosen, rather than silently degrading to
+/// [`ManagedTargetFailureKind::Other`].
+pub(crate) fn classify_client_error(
+    phase: ManagedTargetFailurePhase,
+    error: &ClientError,
+) -> ManagedTargetFailure {
+    let kind = match error {
+        ClientError::Resolve { .. } => ManagedTargetFailureKind::Resolve,
+        ClientError::Socket(_) => ManagedTargetFailureKind::Socket,
+        ClientError::SocketOption { .. } | ClientError::ReadTimeoutRestore { .. } => {
+            ManagedTargetFailureKind::SocketOption
+        }
+        ClientError::Protocol(_)
+        | ClientError::ProtocolVersionMismatch { .. }
+        | ClientError::ZeroToken
+        | ClientError::UnexpectedNoTestReply
+        | ClientError::NonZeroNoTestToken { .. }
+        | ClientError::ServerRejected
+        | ClientError::NegotiationRejected { .. } => ManagedTargetFailureKind::Protocol,
+        ClientError::OpenTimeout => ManagedTargetFailureKind::Timeout,
+        ClientError::InvalidConfig { .. }
+        | ClientError::OpenTimeoutTooSmall { .. }
+        | ClientError::NoOpenTimeouts => ManagedTargetFailureKind::Configuration,
+        ClientError::AllocationFailed { .. }
+        | ClientError::CounterOverflow { .. }
+        | ClientError::DurationOverflow
+        | ClientError::PendingLimitExceeded { .. } => ManagedTargetFailureKind::ResourceExhausted,
+        ClientError::DatagramLengthMismatch { .. } => ManagedTargetFailureKind::Socket,
+        #[cfg(feature = "tokio")]
+        ClientError::NoTokioRuntime => ManagedTargetFailureKind::InvalidState,
+        ClientError::NotOpen
+        | ClientError::AlreadyOpen
+        | ClientError::AlreadyCompleted
+        | ClientError::AlreadyClosed
+        | ClientError::StalePreparedProbe { .. }
+        | ClientError::PendingSequenceCollision { .. } => ManagedTargetFailureKind::InvalidState,
+    };
+    ManagedTargetFailure {
+        phase,
+        kind,
+        message: Arc::from(error.to_string()),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::{collections::TryReserveError, io};
+
+    use super::*;
+
+    fn io_error() -> io::Error {
+        io::Error::other("boom")
+    }
+
+    fn try_reserve_error() -> TryReserveError {
+        Vec::<u8>::new().try_reserve(usize::MAX).unwrap_err()
+    }
+
+    fn classification_cases() -> Vec<(ClientError, ManagedTargetFailureKind)> {
+        vec![
+            (
+                ClientError::Resolve {
+                    addr: "example.invalid:2112".to_owned(),
+                },
+                ManagedTargetFailureKind::Resolve,
+            ),
+            (
+                ClientError::Socket(io_error()),
+                ManagedTargetFailureKind::Socket,
+            ),
+            (
+                ClientError::DatagramLengthMismatch {
+                    expected: 64,
+                    actual: 32,
+                },
+                ManagedTargetFailureKind::Socket,
+            ),
+            (
+                ClientError::SocketOption {
+                    operation: "set read timeout",
+                    remote: "127.0.0.1:2112".parse().unwrap(),
+                    source: io_error(),
+                },
+                ManagedTargetFailureKind::SocketOption,
+            ),
+            (
+                ClientError::ReadTimeoutRestore { source: io_error() },
+                ManagedTargetFailureKind::SocketOption,
+            ),
+            (
+                ClientError::Protocol(irtt_proto::ProtoError::BadMagic),
+                ManagedTargetFailureKind::Protocol,
+            ),
+            (
+                ClientError::ProtocolVersionMismatch {
+                    requested: 1,
+                    received: 2,
+                },
+                ManagedTargetFailureKind::Protocol,
+            ),
+            (ClientError::ZeroToken, ManagedTargetFailureKind::Protocol),
+            (
+                ClientError::UnexpectedNoTestReply,
+                ManagedTargetFailureKind::Protocol,
+            ),
+            (
+                ClientError::NonZeroNoTestToken { token: 7 },
+                ManagedTargetFailureKind::Protocol,
+            ),
+            (
+                ClientError::ServerRejected,
+                ManagedTargetFailureKind::Protocol,
+            ),
+            (
+                ClientError::NegotiationRejected {
+                    reason: "duration".to_owned(),
+                },
+                ManagedTargetFailureKind::Protocol,
+            ),
+            (ClientError::OpenTimeout, ManagedTargetFailureKind::Timeout),
+            (
+                ClientError::InvalidConfig {
+                    reason: "interval".to_owned(),
+                },
+                ManagedTargetFailureKind::Configuration,
+            ),
+            (
+                ClientError::OpenTimeoutTooSmall {
+                    timeout: Duration::from_millis(1),
+                    minimum: Duration::from_millis(10),
+                },
+                ManagedTargetFailureKind::Configuration,
+            ),
+            (
+                ClientError::NoOpenTimeouts,
+                ManagedTargetFailureKind::Configuration,
+            ),
+            (
+                ClientError::AllocationFailed {
+                    operation: "pending probes",
+                    source: try_reserve_error(),
+                },
+                ManagedTargetFailureKind::ResourceExhausted,
+            ),
+            (
+                ClientError::CounterOverflow {
+                    counter: "packets_sent",
+                },
+                ManagedTargetFailureKind::ResourceExhausted,
+            ),
+            (
+                ClientError::DurationOverflow,
+                ManagedTargetFailureKind::ResourceExhausted,
+            ),
+            (
+                ClientError::PendingLimitExceeded { limit: 8 },
+                ManagedTargetFailureKind::ResourceExhausted,
+            ),
+            (
+                ClientError::NoTokioRuntime,
+                ManagedTargetFailureKind::InvalidState,
+            ),
+            (ClientError::NotOpen, ManagedTargetFailureKind::InvalidState),
+            (
+                ClientError::AlreadyOpen,
+                ManagedTargetFailureKind::InvalidState,
+            ),
+            (
+                ClientError::AlreadyCompleted,
+                ManagedTargetFailureKind::InvalidState,
+            ),
+            (
+                ClientError::AlreadyClosed,
+                ManagedTargetFailureKind::InvalidState,
+            ),
+            (
+                ClientError::StalePreparedProbe {
+                    prepared_seq: 3,
+                    next_wire_seq: 4,
+                },
+                ManagedTargetFailureKind::InvalidState,
+            ),
+            (
+                ClientError::PendingSequenceCollision { seq: 9 },
+                ManagedTargetFailureKind::InvalidState,
+            ),
+        ]
+    }
+
+    #[test]
+    fn every_client_error_classifies_to_its_documented_kind() {
+        for (error, expected) in classification_cases() {
+            let failure = classify_client_error(ManagedTargetFailurePhase::Opening, &error);
+            assert_eq!(
+                failure.kind, expected,
+                "unexpected classification for {error:?}"
+            );
+            assert_eq!(failure.phase, ManagedTargetFailurePhase::Opening);
+            assert_eq!(&*failure.message, error.to_string());
+        }
+    }
+
+    #[test]
+    fn classification_preserves_the_reported_phase() {
+        for phase in [
+            ManagedTargetFailurePhase::Connecting,
+            ManagedTargetFailurePhase::Opening,
+            ManagedTargetFailurePhase::Sending,
+            ManagedTargetFailurePhase::Receiving,
+            ManagedTargetFailurePhase::Timing,
+            ManagedTargetFailurePhase::Closing,
+        ] {
+            let failure = classify_client_error(phase, &ClientError::OpenTimeout);
+            assert_eq!(failure.phase, phase);
+        }
+    }
+
+    #[test]
+    fn phase_and_kind_display_without_debug_spelling() {
+        assert_eq!(
+            ManagedTargetFailurePhase::Connecting.to_string(),
+            "connecting"
+        );
+        assert_eq!(ManagedTargetFailurePhase::Closing.to_string(), "closing");
+        assert_eq!(
+            ManagedTargetFailureKind::SocketOption.to_string(),
+            "socket option"
+        );
+        assert_eq!(
+            ManagedTargetFailureKind::ResourceExhausted.to_string(),
+            "resource exhausted"
+        );
+        assert_eq!(
+            ManagedTargetFailureKind::InvalidState.to_string(),
+            "invalid state"
+        );
+        assert_eq!(ManagedTargetFailureKind::Other.to_string(), "other");
+    }
+}

crates/irtt-client/src/managed/runner.rs

@@ -1,838 +0,0 @@
-use std::{
-    thread::{self, JoinHandle},
-    time::{Duration, Instant},
-};
-
-use crate::{
-    config::{ClientConfig, RecvBudget},
-    error::ClientError,
-    event::{ClientEvent, OpenOutcome},
-    Client,
-};
-
-use super::{
-    cancellation::CancellationToken,
-    hub::{EventHub, EventSubscription, SubscriberConfig},
-};
-
-const MANAGED_RECV_TIMEOUT: Duration = Duration::from_millis(20);
-const MANAGED_RECV_BUDGET: RecvBudget = RecvBudget { max_packets: 64 };
-const MANAGED_FINAL_DRAIN: Duration = Duration::from_millis(100);
-const IDLE_SLEEP: Duration = Duration::from_millis(1);
-const MAX_SLEEP: Duration = Duration::from_millis(20);
-
-/// Entry point for running a client session on a worker thread.
-///
-/// The managed API owns the lower-level [`Client`](crate::Client) loop: it
-/// opens the session, sends probes at the negotiated interval, receives
-/// datagrams, publishes [`ClientEvent`] values, and closes the session when the
-/// run completes or is cancelled.
-#[derive(Debug)]
-pub struct ManagedClient;
-
-/// Running managed client session.
-///
-/// [`ManagedClientSession::join`] waits for the worker and returns the session
-/// outcome or client error. Dropping the session requests cooperative
-/// cancellation; callers that need the outcome should explicitly join instead
-/// of relying on drop.
-#[must_use = "dropping the session cancels the managed client; call join() to wait for completion"]
-#[derive(Debug)]
-pub struct ManagedClientSession {
-    hub: EventHub,
-    cancellation: CancellationToken,
-    worker: Option<JoinHandle<Result<SessionOutcome, ClientError>>>,
-}
-
-/// Outcome returned by a completed managed client session.
-///
-/// These are runner-level lifecycle counters, not statistical summaries. Use
-/// `irtt-stats` with emitted `ClientEvent` values for RTT, loss, IPDV, and
-/// related summaries.
-#[must_use = "managed session outcomes contain completion status and counters"]
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct SessionOutcome {
-    /// Why the managed loop stopped.
-    pub end_reason: SessionEndReason,
-    /// Number of echo requests sent by the client.
-    pub packets_sent: u64,
-    /// Number of first in-window echo replies received.
-    pub replies_received: u64,
-    /// Number of duplicate reply events emitted.
-    pub duplicates: u64,
-    /// Number of late reply events emitted.
-    pub late: u64,
-    /// Number of warning events emitted.
-    pub warning_events: u64,
-}
-
-/// Reason a managed client session ended.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum SessionEndReason {
-    /// The negotiated finite test duration completed and the client closed the
-    /// session normally.
-    TestComplete,
-    /// Cancellation was requested through [`ManagedClientSession::stop`] or by
-    /// dropping the session handle.
-    Cancelled,
-    /// The session was opened in [`RunMode::NoTest`](crate::RunMode) and
-    /// completed after negotiation.
-    NoTestComplete,
-}
-
-impl ManagedClient {
-    /// Start a managed session without creating an initial event subscription.
-    ///
-    /// The returned [`ManagedClientSession`] can still create subscriptions via
-    /// [`ManagedClientSession::subscribe`], but events emitted before a
-    /// subscriber is registered are not replayed.
-    pub fn start(config: ClientConfig) -> Result<ManagedClientSession, ClientError> {
-        Self::start_inner(config, None).map(|(session, _)| session)
-    }
-
-    /// Start a managed session and subscribe to events before the worker runs.
-    ///
-    /// The initial subscription receives the open lifecycle event and
-    /// subsequent session events, subject to its queue capacity and overflow
-    /// policy.
-    pub fn start_with_subscription(
-        config: ClientConfig,
-        subscriber_config: SubscriberConfig,
-    ) -> Result<(ManagedClientSession, EventSubscription), ClientError> {
-        let (session, subscription) = Self::start_inner(config, Some(subscriber_config))?;
-        Ok((
-            session,
-            subscription.expect("initial subscription must be present"),
-        ))
-    }
-
-    fn start_inner(
-        mut config: ClientConfig,
-        subscriber_config: Option<SubscriberConfig>,
-    ) -> Result<(ManagedClientSession, Option<EventSubscription>), ClientError> {
-        if config.socket_config.recv_timeout.is_none()
-            || config.socket_config.recv_timeout > Some(MANAGED_RECV_TIMEOUT)
-        {
-            config.socket_config.recv_timeout = Some(MANAGED_RECV_TIMEOUT);
-        }
-
-        let hub = EventHub::new();
-        let initial_subscription = subscriber_config
-            .map(|config| hub.subscribe(config))
-            .transpose()?;
-
-        let mut client = Client::connect(config)?;
-        let outcome = client.open()?;
-        publish_open_outcome(&hub, &outcome);
-
-        let cancellation = CancellationToken::new();
-        let worker_hub = hub.clone();
-        let worker_cancellation = cancellation.clone();
-        let worker =
-            thread::spawn(move || run_client_with_cleanup(client, worker_hub, worker_cancellation));
-
-        Ok((
-            ManagedClientSession {
-                hub,
-                cancellation,
-                worker: Some(worker),
-            },
-            initial_subscription,
-        ))
-    }
-}
-
-impl ManagedClientSession {
-    /// Add another event subscriber to this running managed session.
-    ///
-    /// The subscription receives only events published after it is registered.
-    pub fn subscribe(&self, config: SubscriberConfig) -> Result<EventSubscription, ClientError> {
-        self.hub.subscribe(config)
-    }
-
-    /// Request cooperative cancellation of the managed session.
-    ///
-    /// Cancellation is observed by the worker loop between socket receive,
-    /// timeout polling, and send scheduling steps. Call [`join`](Self::join) to
-    /// wait for the worker and obtain the final [`SessionOutcome`].
-    pub fn stop(&self) {
-        self.cancellation.cancel();
-    }
-
-    /// Wait for the managed worker thread to finish.
-    ///
-    /// On success, returns lifecycle counters for the completed session. If the
-    /// worker panicked, this returns [`ClientError::WorkerPanicked`]. Joining
-    /// also disconnects all event subscriptions while leaving already queued
-    /// events available to drain.
-    pub fn join(mut self) -> Result<SessionOutcome, ClientError> {
-        let worker = self
-            .worker
-            .take()
-            .expect("ManagedClientSession invariant violated: worker handle missing before join");
-        match worker.join() {
-            Ok(outcome) => {
-                self.hub.disconnect_all();
-                outcome
-            }
-            Err(_) => {
-                self.hub.disconnect_all();
-                Err(ClientError::WorkerPanicked)
-            }
-        }
-    }
-}
-
-impl Drop for ManagedClientSession {
-    fn drop(&mut self) {
-        self.cancellation.cancel();
-    }
-}
-
-fn publish_open_outcome(hub: &EventHub, outcome: &OpenOutcome) {
-    match outcome {
-        OpenOutcome::Started { event, .. } | OpenOutcome::NoTestCompleted { event, .. } => {
-            hub.publish(event.clone());
-        }
-    }
-}
-
-fn run_client(
-    mut client: Client,
-    hub: EventHub,
-    cancellation: CancellationToken,
-) -> Result<SessionOutcome, ClientError> {
-    if client.is_run_complete() {
-        return Ok(SessionOutcome {
-            end_reason: SessionEndReason::NoTestComplete,
-            packets_sent: 0,
-            replies_received: 0,
-            duplicates: 0,
-            late: 0,
-            warning_events: 0,
-        });
-    }
-
-    let mut counters = OutcomeCounters::default();
-    let mut cancelled = false;
-
-    loop {
-        if cancellation.is_cancelled() {
-            cancelled = true;
-            publish_events(
-                &hub,
-                &mut counters,
-                client.recv_available(MANAGED_RECV_BUDGET)?,
-            );
-            if !client.is_peer_closed() {
-                publish_events(&hub, &mut counters, client.poll_timeouts()?);
-            }
-            break;
-        }
-
-        let now = Instant::now();
-        if client
-            .next_send_deadline()
-            .is_some_and(|deadline| deadline <= now)
-        {
-            let events = client.send_probe()?;
-            publish_events(&hub, &mut counters, events);
-            continue;
-        }
-
-        publish_events(
-            &hub,
-            &mut counters,
-            client.recv_available(MANAGED_RECV_BUDGET)?,
-        );
-        if client.is_peer_closed() {
-            break;
-        }
-        publish_events(&hub, &mut counters, client.poll_timeouts()?);
-
-        if client.is_run_complete() {
-            break;
-        }
-
-        sleep_until_next_wakeup(client.next_send_deadline());
-    }
-
-    if !cancelled {
-        drain_final_late_replies(&mut client, &hub, &mut counters)?;
-    }
-
-    let packets_sent = client.packets_sent();
-    if !client.is_peer_closed() {
-        let close_events = client.close()?;
-        publish_events(&hub, &mut counters, close_events);
-    }
-
-    Ok(SessionOutcome {
-        end_reason: if cancelled {
-            SessionEndReason::Cancelled
-        } else {
-            SessionEndReason::TestComplete
-        },
-        packets_sent,
-        replies_received: counters.replies_received,
-        duplicates: counters.duplicates,
-        late: counters.late,
-        warning_events: counters.warning_events,
-    })
-}
-
-fn run_client_with_cleanup(
-    client: Client,
-    hub: EventHub,
-    cancellation: CancellationToken,
-) -> Result<SessionOutcome, ClientError> {
-    let outcome = run_client(client, hub.clone(), cancellation);
-    hub.disconnect_all();
-    outcome
-}
-
-fn drain_final_late_replies(
-    client: &mut Client,
-    hub: &EventHub,
-    counters: &mut OutcomeCounters,
-) -> Result<(), ClientError> {
-    if !client.has_timed_out_metadata() {
-        return Ok(());
-    }
-
-    let deadline = Instant::now() + MANAGED_FINAL_DRAIN;
-    while Instant::now() < deadline && client.has_timed_out_metadata() {
-        if client.is_peer_closed() {
-            break;
-        }
-
-        let mut published = false;
-
-        let events = client.recv_available(MANAGED_RECV_BUDGET)?;
-        published |= !events.is_empty();
-        publish_events(hub, counters, events);
-
-        if client.is_peer_closed() {
-            break;
-        }
-
-        let events = client.poll_timeouts()?;
-        published |= !events.is_empty();
-        publish_events(hub, counters, events);
-
-        if !published {
-            thread::sleep(IDLE_SLEEP);
-        }
-    }
-    Ok(())
-}
-
-fn publish_events(hub: &EventHub, counters: &mut OutcomeCounters, events: Vec<ClientEvent>) {
-    for event in events {
-        counters.observe(&event);
-        hub.publish(event);
-    }
-}
-
-fn sleep_until_next_wakeup(deadline: Option<Instant>) {
-    let sleep_for = deadline
-        .and_then(|deadline| deadline.checked_duration_since(Instant::now()))
-        .map(|duration| duration.min(MAX_SLEEP))
-        .unwrap_or(IDLE_SLEEP);
-    if sleep_for > Duration::ZERO {
-        thread::sleep(sleep_for);
-    }
-}
-
-#[derive(Debug, Default)]
-struct OutcomeCounters {
-    replies_received: u64,
-    duplicates: u64,
-    late: u64,
-    warning_events: u64,
-}
-
-impl OutcomeCounters {
-    fn observe(&mut self, event: &ClientEvent) {
-        match event {
-            ClientEvent::EchoReply { .. } => self.replies_received += 1,
-            ClientEvent::DuplicateReply { .. } => self.duplicates += 1,
-            ClientEvent::LateReply { .. } => self.late += 1,
-            ClientEvent::Warning { .. } => self.warning_events += 1,
-            _ => {}
-        }
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::{config::NegotiationPolicy, SubscriberOverflow};
-    use irtt_proto::{
-        echo_packet_len,
-        flags::{self, FLAG_OPEN, FLAG_REPLY},
-        layout::PacketLayout,
-        Clock, Params, ReceivedStats, StampAt, TimestampFields, MAGIC, PROTOCOL_VERSION,
-    };
-    use std::{
-        net::{SocketAddr, UdpSocket},
-        sync::mpsc,
-    };
-
-    const TOKEN: u64 = 0x1234_5678_90ab_cdef;
-    struct FakeServer {
-        addr: SocketAddr,
-        done: JoinHandle<()>,
-    }
-
-    impl FakeServer {
-        fn join(self) {
-            self.done.join().unwrap();
-        }
-    }
-
-    fn test_echo_packet_len(hmac: bool, params: &Params) -> usize {
-        echo_packet_len(hmac, params)
-            .expect("managed runner test params must have a non-negative packet length")
-    }
-
-    fn test_params(duration: Option<Duration>, interval: Duration) -> Params {
-        Params {
-            protocol_version: PROTOCOL_VERSION,
-            duration_ns: duration.map_or(0, test_duration_ns_i64),
-            interval_ns: test_duration_ns_i64(interval),
-            length: 0,
-            received_stats: ReceivedStats::Both,
-            stamp_at: StampAt::Both,
-            clock: Clock::Both,
-            dscp: 0,
-            server_fill: None,
-        }
-    }
-
-    fn test_duration_ns_i64(duration: Duration) -> i64 {
-        i64::try_from(duration.as_nanos()).expect("test duration fits i64 nanoseconds")
-    }
-
-    fn config(addr: SocketAddr, duration: Option<Duration>) -> ClientConfig {
-        ClientConfig {
-            server_addr: addr.to_string(),
-            duration,
-            interval: Duration::from_millis(10),
-            negotiation_policy: NegotiationPolicy::Strict,
-            open_timeouts: vec![Duration::from_millis(200)],
-            probe_timeout: Duration::from_millis(40),
-            ..ClientConfig::default()
-        }
-    }
-
-    fn start_echo_server(params: Params) -> FakeServer {
-        let socket = UdpSocket::bind("127.0.0.1:0").unwrap();
-        let addr = socket.local_addr().unwrap();
-        let done = thread::spawn(move || {
-            let (_, peer) = recv_request(&socket);
-            socket
-                .send_to(&open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params), peer)
-                .unwrap();
-            socket
-                .set_read_timeout(Some(Duration::from_millis(500)))
-                .unwrap();
-
-            while let Some((packet, peer)) = recv_request_timeout(&socket) {
-                if packet[3] & flags::FLAG_CLOSE != 0 {
-                    break;
-                }
-
-                let seq = u32::from_le_bytes(packet[12..16].try_into().unwrap());
-                let ts = TimestampFields {
-                    recv_wall: Some(1_000_000_000),
-                    recv_mono: Some(100_000),
-                    send_wall: Some(1_000_000_000),
-                    send_mono: Some(100_000),
-                    ..Default::default()
-                };
-                socket
-                    .send_to(&echo_reply_packet(TOKEN, seq, &params, &ts), peer)
-                    .unwrap();
-            }
-        });
-        FakeServer { addr, done }
-    }
-
-    fn start_delayed_reply_server(params: Params, delay: Duration) -> FakeServer {
-        let socket = UdpSocket::bind("127.0.0.1:0").unwrap();
-        let addr = socket.local_addr().unwrap();
-        let done = thread::spawn(move || {
-            let (_, peer) = recv_request(&socket);
-            socket
-                .send_to(&open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params), peer)
-                .unwrap();
-            socket
-                .set_read_timeout(Some(Duration::from_millis(500)))
-                .unwrap();
-
-            let Some((packet, peer)) = recv_request_timeout(&socket) else {
-                return;
-            };
-            let seq = u32::from_le_bytes(packet[12..16].try_into().unwrap());
-            thread::sleep(delay);
-            let ts = TimestampFields {
-                recv_wall: Some(1_000_000_000),
-                recv_mono: Some(100_000),
-                send_wall: Some(1_001_000_000),
-                send_mono: Some(1_100_000),
-                ..Default::default()
-            };
-            socket
-                .send_to(&echo_reply_packet(TOKEN, seq, &params, &ts), peer)
-                .unwrap();
-
-            while let Some((packet, _)) = recv_request_timeout(&socket) {
-                if packet[3] & flags::FLAG_CLOSE != 0 {
-                    break;
-                }
-            }
-        });
-        FakeServer { addr, done }
-    }
-
-    fn start_peer_close_server(params: Params) -> FakeServer {
-        let socket = UdpSocket::bind("127.0.0.1:0").unwrap();
-        let addr = socket.local_addr().unwrap();
-        let done = thread::spawn(move || {
-            let (_, peer) = recv_request(&socket);
-            socket
-                .send_to(&open_reply(FLAG_OPEN | FLAG_REPLY, TOKEN, &params), peer)
-                .unwrap();
-            socket
-                .set_read_timeout(Some(Duration::from_millis(500)))
-                .unwrap();
-
-            let Some((packet, peer)) = recv_request_timeout(&socket) else {
-                return;
-            };
-            let seq = u32::from_le_bytes(packet[12..16].try_into().unwrap());
-            let ts = TimestampFields {
-                recv_wall: Some(1_000_000_000),
-                recv_mono: Some(100_000),
-                send_wall: Some(1_000_000_000),
-                send_mono: Some(100_000),
-                ..Default::default()
-            };
-            socket
-                .send_to(
-                    &echo_reply_packet_with_flags(
-                        TOKEN,
-                        seq,
-                        &params,
-                        &ts,
-                        FLAG_REPLY | flags::FLAG_CLOSE,
-                    ),
-                    peer,
-                )
-                .unwrap();
-
-            if let Some((packet, _)) = recv_request_timeout(&socket) {
-                panic!(
-                    "managed cleanup must not send any packet after peer close; flags={:?} len={}",
-                    packet.get(3).copied(),
-                    packet.len()
-                );
-            }
-        });
-        FakeServer { addr, done }
-    }
-
-    fn recv_request(socket: &UdpSocket) -> (Vec<u8>, SocketAddr) {
-        let mut buf = [0_u8; 2048];
-        let (size, peer) = socket.recv_from(&mut buf).unwrap();
-        (buf[..size].to_vec(), peer)
-    }
-
-    fn recv_request_timeout(socket: &UdpSocket) -> Option<(Vec<u8>, SocketAddr)> {
-        let mut buf = [0_u8; 2048];
-        socket
-            .recv_from(&mut buf)
-            .ok()
-            .map(|(size, peer)| (buf[..size].to_vec(), peer))
-    }
-
-    fn open_reply(flags: u8, token: u64, params: &Params) -> Vec<u8> {
-        let mut packet = Vec::new();
-        packet.extend_from_slice(&MAGIC);
-        packet.push(flags);
-        packet.extend_from_slice(&token.to_le_bytes());
-        packet.extend_from_slice(&params.encode());
-        packet
-    }
-
-    fn echo_reply_packet(
-        token: u64,
-        seq: u32,
-        params: &Params,
-        timestamps: &TimestampFields,
-    ) -> Vec<u8> {
-        echo_reply_packet_with_flags(token, seq, params, timestamps, FLAG_REPLY)
-    }
-
-    fn echo_reply_packet_with_flags(
-        token: u64,
-        seq: u32,
-        params: &Params,
-        timestamps: &TimestampFields,
-        flags: u8,
-    ) -> Vec<u8> {
-        let layout = PacketLayout::echo(false, params);
-        let packet_len = test_echo_packet_len(false, params);
-        let mut packet = Vec::with_capacity(packet_len);
-
-        packet.extend_from_slice(&MAGIC);
-        packet.push(flags);
-        packet.extend_from_slice(&token.to_le_bytes());
-        packet.extend_from_slice(&seq.to_le_bytes());
-
-        if layout.recv_count {
-            packet.extend_from_slice(&42_u32.to_le_bytes());
-        }
-        if layout.recv_window {
-            packet.extend_from_slice(&0x07_u64.to_le_bytes());
-        }
-        if layout.recv_wall {
-            packet.extend_from_slice(&timestamps.recv_wall.unwrap_or(0).to_le_bytes());
-        }
-        if layout.recv_mono {
-            packet.extend_from_slice(&timestamps.recv_mono.unwrap_or(0).to_le_bytes());
-        }
-        if layout.midpoint_wall {
-            packet.extend_from_slice(&timestamps.midpoint_wall.unwrap_or(0).to_le_bytes());
-        }
-        if layout.midpoint_mono {
-            packet.extend_from_slice(&timestamps.midpoint_mono.unwrap_or(0).to_le_bytes());
-        }
-        if layout.send_wall {
-            packet.extend_from_slice(&timestamps.send_wall.unwrap_or(0).to_le_bytes());
-        }
-        if layout.send_mono {
-            packet.extend_from_slice(&timestamps.send_mono.unwrap_or(0).to_le_bytes());
-        }
-
-        packet.resize(packet_len, 0);
-        packet
-    }
-
-    fn recv_event_with_timeout(sub: &EventSubscription) -> ClientEvent {
-        let deadline = Instant::now() + Duration::from_secs(2);
-        loop {
-            match sub.try_recv() {
-                Ok(Some(event)) => return event,
-                Ok(None) if Instant::now() < deadline => {
-                    thread::sleep(Duration::from_millis(1));
-                }
-                Ok(None) => panic!("timed out waiting for managed client event"),
-                Err(err) => panic!("subscription ended while waiting for event: {err}"),
-            }
-        }
-    }
-
-    fn collect_until_closed(sub: &EventSubscription) -> Vec<ClientEvent> {
-        let mut events = Vec::new();
-        let deadline = Instant::now() + Duration::from_secs(2);
-        while Instant::now() < deadline {
-            match sub.try_recv() {
-                Ok(Some(event)) => {
-                    let closed = matches!(event, ClientEvent::SessionClosed { .. });
-                    events.push(event);
-                    if closed {
-                        return events;
-                    }
-                }
-                Ok(None) => thread::sleep(Duration::from_millis(1)),
-                Err(_) => return events,
-            }
-        }
-        panic!("timed out waiting for session close event");
-    }
-
-    #[test]
-    fn stop_is_idempotent() {
-        let server = start_echo_server(test_params(None, Duration::from_millis(10)));
-        let session = ManagedClient::start(config(server.addr, None)).unwrap();
-        session.stop();
-        session.stop();
-        let outcome = session.join().unwrap();
-        server.join();
-
-        assert_eq!(outcome.end_reason, SessionEndReason::Cancelled);
-    }
-
-    #[test]
-    fn finite_managed_run_emits_session_probe_and_close_events() {
-        let duration = Duration::from_millis(35);
-        let server = start_echo_server(test_params(Some(duration), Duration::from_millis(10)));
-        let (session, sub) = ManagedClient::start_with_subscription(
-            config(server.addr, Some(duration)),
-            SubscriberConfig {
-                capacity: 16,
-                overflow: SubscriberOverflow::DropNewest,
-            },
-        )
-        .unwrap();
-
-        let events = collect_until_closed(&sub);
-        let outcome = session.join().unwrap();
-        server.join();
-
-        assert_eq!(outcome.end_reason, SessionEndReason::TestComplete);
-        assert!(events
-            .iter()
-            .any(|event| matches!(event, ClientEvent::SessionStarted { .. })));
-        assert!(events
-            .iter()
-            .any(|event| matches!(event, ClientEvent::EchoReply { .. })));
-        assert!(events
-            .iter()
-            .any(|event| matches!(event, ClientEvent::SessionClosed { .. })));
-    }
-
-    #[test]
-    fn finite_managed_run_drains_late_reply_after_timeout_before_close() {
-        let duration = Duration::from_millis(1);
-        let params = test_params(Some(duration), Duration::from_millis(10));
-        let server = start_delayed_reply_server(params, Duration::from_millis(60));
-        let mut cfg = config(server.addr, Some(duration));
-        cfg.probe_timeout = Duration::from_millis(20);
-
-        let (session, sub) = ManagedClient::start_with_subscription(
-            cfg,
-            SubscriberConfig {
-                capacity: 16,
-                overflow: SubscriberOverflow::DropNewest,
-            },
-        )
-        .unwrap();
-
-        let events = collect_until_closed(&sub);
-        let outcome = session.join().unwrap();
-        server.join();
-
-        assert_eq!(outcome.end_reason, SessionEndReason::TestComplete);
-        assert!(events
-            .iter()
-            .any(|event| matches!(event, ClientEvent::EchoLoss { seq: 0, .. })));
-        assert!(events.iter().any(|event| matches!(
-            event,
-            ClientEvent::LateReply {
-                seq: 0,
-                sent_at: Some(_),
-                rtt: Some(_),
-                ..
-            }
-        )));
-        let late_before_close = events
-            .iter()
-            .position(|event| matches!(event, ClientEvent::LateReply { rtt: Some(_), .. }));
-        let close = events
-            .iter()
-            .position(|event| matches!(event, ClientEvent::SessionClosed { .. }));
-        let late_before_close = late_before_close.expect("missing stats-eligible LateReply");
-        let close = close.expect("missing SessionClosed");
-        assert!(late_before_close < close);
-    }
-
-    #[test]
-    fn peer_close_during_managed_run_is_successful() {
-        let server = start_peer_close_server(test_params(None, Duration::from_millis(10)));
-        let (session, sub) = ManagedClient::start_with_subscription(
-            config(server.addr, None),
-            SubscriberConfig {
-                capacity: 16,
-                overflow: SubscriberOverflow::DropNewest,
-            },
-        )
-        .unwrap();
-
-        let events = collect_until_closed(&sub);
-        let outcome = session.join().unwrap();
-        server.join();
-
-        assert_eq!(outcome.end_reason, SessionEndReason::TestComplete);
-        assert!(events
-            .iter()
-            .any(|event| matches!(event, ClientEvent::EchoReply { .. })));
-        assert!(events
-            .iter()
-            .any(|event| matches!(event, ClientEvent::SessionClosed { .. })));
-    }
-
-    #[test]
-    fn continuous_managed_run_can_be_stopped_cleanly() {
-        let server = start_echo_server(test_params(None, Duration::from_millis(10)));
-        let session = ManagedClient::start(config(server.addr, None)).unwrap();
-        let sub = session
-            .subscribe(SubscriberConfig {
-                capacity: 16,
-                overflow: SubscriberOverflow::DropNewest,
-            })
-            .unwrap();
-
-        loop {
-            if matches!(recv_event_with_timeout(&sub), ClientEvent::EchoReply { .. }) {
-                break;
-            }
-        }
-        session.stop();
-        let events = collect_until_closed(&sub);
-        let outcome = session.join().unwrap();
-        server.join();
-
-        assert_eq!(outcome.end_reason, SessionEndReason::Cancelled);
-        assert!(events
-            .iter()
-            .any(|event| matches!(event, ClientEvent::SessionClosed { .. })));
-    }
-
-    #[test]
-    fn join_reports_worker_panic() {
-        let hub = EventHub::new();
-        let cancellation = CancellationToken::new();
-        let worker = thread::spawn(|| -> Result<SessionOutcome, ClientError> {
-            panic!("intentional managed worker panic")
-        });
-        let session = ManagedClientSession {
-            hub,
-            cancellation,
-            worker: Some(worker),
-        };
-
-        assert!(matches!(session.join(), Err(ClientError::WorkerPanicked)));
-    }
-
-    #[test]
-    fn no_test_managed_run_returns_no_test_outcome() {
-        use crate::RunMode;
-
-        let params = test_params(Some(Duration::from_millis(10)), Duration::from_millis(10));
-        let socket = UdpSocket::bind("127.0.0.1:0").unwrap();
-        let addr = socket.local_addr().unwrap();
-        let (tx, rx) = mpsc::channel();
-        let done = thread::spawn(move || {
-            let (request, peer) = recv_request(&socket);
-            tx.send(request[3] & flags::FLAG_CLOSE != 0).unwrap();
-            socket
-                .send_to(
-                    &open_reply(FLAG_OPEN | FLAG_REPLY | flags::FLAG_CLOSE, 0, &params),
-                    peer,
-                )
-                .unwrap();
-        });
-
-        let mut cfg = config(addr, Some(Duration::from_millis(10)));
-        cfg.run_mode = RunMode::NoTest;
-        let session = ManagedClient::start(cfg).unwrap();
-        assert!(rx.recv_timeout(Duration::from_secs(2)).unwrap());
-        let outcome = session.join().unwrap();
-        done.join().unwrap();
-
-        assert_eq!(outcome.end_reason, SessionEndReason::NoTestComplete);
-    }
-}

crates/irtt-client/src/managed/target_id.rs

@@ -0,0 +1,47 @@
+use std::{fmt, sync::Arc};
+
+/// Caller-owned stable target identity.
+#[derive(Clone, Eq, Hash, Ord, PartialEq, PartialOrd)]
+pub struct TargetId(Arc<str>);
+
+impl TargetId {
+    /// Construct a target identifier.
+    pub fn new(value: impl Into<Arc<str>>) -> Self {
+        Self(value.into())
+    }
+
+    /// Borrow the identifier as a string slice.
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Debug for TargetId {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_tuple("TargetId").field(&self.0).finish()
+    }
+}
+
+impl fmt::Display for TargetId {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+impl From<&str> for TargetId {
+    fn from(value: &str) -> Self {
+        Self::new(value)
+    }
+}
+
+impl From<String> for TargetId {
+    fn from(value: String) -> Self {
+        Self::new(value)
+    }
+}
+
+impl AsRef<str> for TargetId {
+    fn as_ref(&self) -> &str {
+        self.as_str()
+    }
+}