Merge pull request #10424 from manaflow-ai/feat/coderouter-status-session-counts

Expose per-account session counts and cooldowns in account listing
2026-08-19 04:13:14 -07:00 · 2026-08-19 03:59:50 -07:00 · 2026-08-18 23:44:59 -07:00 · 2026-08-18 23:21:33 -07:00 · 2026-08-18 21:57:20 -07:00 · 2026-08-18 21:46:09 -07:00
2241 changed files with 214372 additions and 22988 deletions
@@ -19,4 +19,5 @@ self-hosted-runner:
    # Linux: Blacksmith primary (LINUX_RUNNER), WarpBuild overflow fallback.
    - blacksmith-4vcpu-ubuntu-2404
    - blacksmith-8vcpu-ubuntu-2404
+    - blacksmith-32vcpu-ubuntu-2404
    - warp-ubuntu-latest-x64-4x
@@ -0,0 +1,57 @@
+name: Set up cmux-tui Rust
+description: Install the repository-pinned cmux-tui Rust toolchain.
+
+runs:
+  using: composite
+  steps:
+    - name: Install pinned Rust toolchain
+      shell: bash
+      env:
+        TOOLCHAIN_FILE: ${{ github.action_path }}/../../../cmux-tui/rust-toolchain.toml
+      run: |
+        if command -v python3 >/dev/null 2>&1; then
+          python_cmd=python3
+        elif command -v python >/dev/null 2>&1; then
+          python_cmd=python
+        else
+          echo "::error::Python is required to read the pinned Rust toolchain" >&2
+          exit 1
+        fi
+        "$python_cmd" <<'PY'
+        import os
+        import pathlib
+        import re
+        import subprocess
+
+        contents = pathlib.Path(os.environ["TOOLCHAIN_FILE"]).read_text(encoding="utf-8")
+
+        def value(name):
+            match = re.search(rf'^\s*{name}\s*=\s*"([^"]+)"', contents, re.MULTILINE)
+            if match is None:
+                raise SystemExit(f"missing {name} in cmux-tui/rust-toolchain.toml")
+            return match.group(1)
+
+        channel = value("channel")
+        profile = value("profile")
+        components_match = re.search(r"^\s*components\s*=\s*\[([^]]*)\]", contents, re.MULTILINE)
+        if components_match is None:
+            raise SystemExit("missing components in cmux-tui/rust-toolchain.toml")
+        components = re.findall(r'"([^"]+)"', components_match.group(1))
+
+        command = ["rustup", "toolchain", "install", channel, "--profile", profile]
+        for component in components:
+            command.extend(["--component", component])
+        subprocess.run(command, check=True)
+        subprocess.run(["rustup", "default", channel], check=True)
+
+        cargo = subprocess.run(
+            ["rustup", "which", "cargo"],
+            check=True,
+            capture_output=True,
+            text=True,
+        ).stdout.strip()
+        with open(os.environ["GITHUB_PATH"], "a", encoding="utf-8") as path_file:
+            print(pathlib.Path(cargo).parent, file=path_file)
+        PY
+        cargo --version
+        rustc --version
@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""Run each cmux-tui-core Rust test in a fresh process."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import subprocess
+import sys
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("cargo_messages", type=Path)
+    parser.add_argument("core_root", type=Path)
+    return parser.parse_args()
+
+
+def is_below(path: Path, root: Path) -> bool:
+    try:
+        path.relative_to(root)
+    except ValueError:
+        return False
+    return True
+
+
+def test_binaries(cargo_messages: Path, core_root: Path) -> list[Path]:
+    binaries: dict[Path, set[str]] = {}
+    with cargo_messages.open(encoding="utf-8") as messages:
+        for line in messages:
+            try:
+                message = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if message.get("reason") != "compiler-artifact":
+                continue
+            if not message.get("profile", {}).get("test"):
+                continue
+
+            target = message.get("target", {})
+            kinds = set(target.get("kind", []))
+            if not kinds.intersection({"lib", "test"}):
+                continue
+            source = target.get("src_path")
+            executable = message.get("executable")
+            if not source or not executable:
+                continue
+            if not is_below(Path(source).resolve(), core_root):
+                continue
+            binaries.setdefault(Path(executable).resolve(), set()).update(kinds)
+
+    library_binaries = [path for path, kinds in binaries.items() if "lib" in kinds]
+    if len(library_binaries) != 1:
+        raise SystemExit(
+            "expected one cmux-tui-core library test binary, "
+            f"found {len(library_binaries)}"
+        )
+    if not binaries:
+        raise SystemExit("cargo did not report any cmux-tui-core test binaries")
+    return sorted(binaries)
+
+
+def tests_in(binary: Path) -> list[str]:
+    result = subprocess.run(
+        [str(binary), "--list"],
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    )
+    tests = []
+    for line in result.stdout.splitlines():
+        name, separator, kind = line.rpartition(": ")
+        if separator and kind == "test":
+            tests.append(name)
+    if not tests:
+        raise SystemExit(f"{binary.name} did not list any tests")
+    if len(tests) != len(set(tests)):
+        raise SystemExit(f"{binary.name} listed duplicate test names")
+    return tests
+
+
+def main() -> int:
+    args = parse_args()
+    core_root = args.core_root.resolve()
+    binaries = test_binaries(args.cargo_messages, core_root)
+    total = 0
+    for binary in binaries:
+        tests = tests_in(binary)
+        print(f"Running {len(tests)} tests from {binary.name} in fresh processes")
+        for index, test_name in enumerate(tests, start=1):
+            print(f"[{index}/{len(tests)}] {test_name}", flush=True)
+            subprocess.run(
+                [str(binary), test_name, "--exact", "--test-threads=1"],
+                check=True,
+            )
+            total += 1
+    print(f"Passed {total} isolated cmux-tui-core tests")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -9,25 +9,37 @@ jobs:
      fail-fast: false
      matrix:
        include:
-          - os: macos-14-large
+          - os: macos-14
            timeout: 60
            run_unit_tests: false
+            run_mobile_transport_tests: true
+            startup_smoke: true
+            virtual_display: true
+            skip_zig: false
+            expected_arch: arm64
+            expected_os_major: "14"
+          - os: macos-15-intel
+            timeout: 90
+            run_unit_tests: false
+            run_mobile_transport_tests: true
            startup_smoke: true
            virtual_display: true
            skip_zig: false
            expected_arch: x86_64
-            expected_os_major: "14"
+            expected_os_major: "15"
          - os: ${{ vars.MACOS_RUNNER_15 || 'blacksmith-6vcpu-macos-15' }}
-            timeout: 60
-            run_unit_tests: true
+            timeout: 120
+            run_unit_tests: false
+            run_mobile_transport_tests: true
            startup_smoke: true
            virtual_display: true
            skip_zig: false
            expected_arch: ""
            expected_os_major: ""
          - os: ${{ vars.MACOS_RUNNER_26 || 'blacksmith-6vcpu-macos-26' }}
-            timeout: 60
-            run_unit_tests: true
+            timeout: 120
+            run_unit_tests: false
+            run_mobile_transport_tests: true
            startup_smoke: true
            virtual_display: false
            skip_zig: true  # zig 0.15.2 MachO linker can't resolve libSystem on macOS 26
@@ -147,14 +159,14 @@ jobs:
            sleep $((attempt * 5))
          done

-      - name: Run mobile transport package tests on Intel Sonoma
-        if: matrix.expected_arch == 'x86_64'
+      - name: Run mobile transport package tests on compatibility hosts
+        if: matrix.run_mobile_transport_tests
        run: |
          ./scripts/ci/run-swift-testing-suites.sh Packages/Shared/CMUXMobileCore
          ./scripts/ci/run-swift-testing-suites.sh Packages/Shared/CmuxIrohTransport

-      - name: Run mobile transport tests in x86_64 iOS Simulator on Intel Sonoma
-        if: matrix.expected_arch == 'x86_64'
+      - name: Run mobile transport tests in the compatibility iOS Simulator
+        if: matrix.run_mobile_transport_tests
        env:
          CMUX_EXPECTED_SIMULATOR_ARCH: ${{ matrix.expected_arch }}
        run: ./scripts/ci/run-iroh-ios-simulator-package-tests.sh
@@ -124,6 +124,9 @@ jobs:
      - name: Install workflow guard Python dependencies
        run: python3 -m pip install --disable-pip-version-check --no-input PyYAML==6.0.3 bashlex==0.18

+      - name: Validate Blacksmith Testbox broker trust boundary
+        run: python3 tests/test_ci_testbox_broker_guard.py
+
      - name: Validate nightly prune Python compatibility
        run: PYTHON_BIN=python3.9 bash ./tests/test_ci_nightly_prune_python_compat.sh

@@ -258,6 +261,9 @@ jobs:
      - name: Validate pbxproj test-wiring lint
        run: ./tests/test_ci_pbxproj_test_wiring.sh

+      - name: Initialize Bonsplit for deferred-work ownership guard
+        run: git submodule update --init --depth 1 vendor/bonsplit
+
      - name: Validate stored DispatchWorkItem ownership
        run: |
          python3 tests/test_lint_stored_dispatch_work_items.py
@@ -342,6 +348,12 @@ jobs:
      - name: Web tests
        run: bun run test

+      - name: Install browser for instant navigation tests
+        run: bunx playwright install --with-deps chromium
+
+      - name: Instant navigation tests
+        run: bun run test:instant
+
  # Checks for in-app React webviews (currently the diff viewer; more cmux React
  # surfaces will live alongside it).
  react-apps-check:
@@ -625,6 +637,29 @@ jobs:
            echo "::warning::Passwordless sudo unavailable; XCTest will use its default automation-mode setup"
          fi

+      - name: Run bundled command PATH regression
+        if: ${{ matrix.shard == fromJSON(env.CMUX_APP_HOST_FOCUSED_REGRESSION_SHARD) }}
+        run: |
+          # The tolerant full-suite step accepts ordinary Swift Testing failures.
+          # Keep the shell-resolution integration test non-tolerant so losing
+          # cmux's bundled commands from PATH cannot pass a shard.
+          set -euo pipefail
+          SOURCE_PACKAGES_DIR="$PWD/.ci-source-packages"
+          if ! command -v fish >/dev/null 2>&1; then
+            HOMEBREW_NO_AUTO_UPDATE=1 brew install fish
+          fi
+          command -v fish >/dev/null 2>&1
+          scripts/ci/run-in-console-session.sh \
+            scripts/ci/run-app-host-xcodebuild.sh \
+            -project cmux.xcodeproj -scheme cmux-unit -configuration Debug \
+            -derivedDataPath "$CMUX_DERIVED_DATA_PATH" \
+            -clonedSourcePackagesDirPath "$SOURCE_PACKAGES_DIR" \
+            -disableAutomaticPackageResolution \
+            -destination "platform=macOS" \
+            CMUX_SKIP_ZIG_BUILD=1 \
+            -only-testing:cmuxTests/CmuxBundledBinPathIntegrationTests \
+            test
+
      - name: Run agent chat transcript lifecycle regressions
        if: ${{ matrix.shard == fromJSON(env.CMUX_APP_HOST_FOCUSED_REGRESSION_SHARD) }}
        run: |
@@ -943,6 +978,45 @@ jobs:
            -only-testing:cmuxTests/NotificationScrollRestoreRecoveryTests \
            test

+      - name: Run sidebar workspace-switch layout regression
+        if: ${{ matrix.shard == fromJSON(env.CMUX_APP_HOST_FOCUSED_REGRESSION_SHARD) }}
+        run: |
+          # The tolerant full-suite step can accept Swift Testing assertion
+          # failures when XCTest reports "0 unexpected". Keep #9612's real
+          # window-switch workload non-tolerant so NSHostingView layout
+          # reentry cannot silently return.
+          set -euo pipefail
+          SOURCE_PACKAGES_DIR="$PWD/.ci-source-packages"
+          scripts/ci/run-in-console-session.sh \
+            scripts/ci/run-app-host-xcodebuild.sh \
+            -project cmux.xcodeproj -scheme cmux-unit -configuration Debug \
+            -derivedDataPath "$CMUX_DERIVED_DATA_PATH" \
+            -clonedSourcePackagesDirPath "$SOURCE_PACKAGES_DIR" \
+            -disableAutomaticPackageResolution \
+            -destination "platform=macOS" \
+            CMUX_SKIP_ZIG_BUILD=1 \
+            -only-testing:cmuxTests/SidebarWorkspaceSwitchLayoutFaultTests \
+            test
+
+      - name: Run terminal portal visibility regressions
+        if: ${{ matrix.shard == fromJSON(env.CMUX_APP_HOST_FOCUSED_REGRESSION_SHARD) }}
+        run: |
+          # These tests mutate the process-wide terminal portal registry and
+          # include Swift Testing assertions that the tolerant broad shard can
+          # otherwise classify as expected. Give them a dedicated app host.
+          set -euo pipefail
+          SOURCE_PACKAGES_DIR="$PWD/.ci-source-packages"
+          scripts/ci/run-in-console-session.sh \
+            scripts/ci/run-app-host-xcodebuild.sh \
+            -project cmux.xcodeproj -scheme cmux-unit -configuration Debug \
+            -derivedDataPath "$CMUX_DERIVED_DATA_PATH" \
+            -clonedSourcePackagesDirPath "$SOURCE_PACKAGES_DIR" \
+            -disableAutomaticPackageResolution \
+            -destination "platform=macOS" \
+            CMUX_SKIP_ZIG_BUILD=1 \
+            -only-testing:cmuxTests/GhosttyTerminalViewVisibilityPolicyTests \
+            test
+
      - name: Run unit tests
        run: |
          set -euo pipefail
@@ -1093,6 +1167,7 @@ jobs:
          CMUX_CLI_BIN="$CLI_BIN" python3 tests/test_cli_socket_autodiscovery.py
          python3 tests/test_codex_wrapper_resume_hooks.py
          python3 tests/test_claude_wrapper_hooks.py
+          python3 tests/test_hermes_wrapper_hooks.py
          python3 tests/test_claude_wrapper_mutual_shim_loop.py
          python3 tests/test_claude_wrapper_shim_root_survives_tmpdir_change.py
          python3 tests/test_claude_wrapper_user_binary_resolution.py
@@ -1328,6 +1403,29 @@ jobs:
        run: |
          ./scripts/install-rust-ci.sh

+      - name: Run Bonsplit package tests
+        run: |
+          set -euo pipefail
+          # Blacksmith macOS runners intermittently abort a package's test
+          # runner at startup. Retry exactly once only for the known signal
+          # 5/6 crash immediately after build and before test output, matching
+          # the package loop below.
+          test_status=0
+          output="$(swift test --package-path vendor/bonsplit 2>&1)" || test_status=$?
+          printf '%s\n' "$output"
+          if [ "$test_status" -ne 0 ] \
+            && printf '%s\n' "$output" | grep -Fq 'Build complete!' \
+            && printf '%s\n' "$output" | grep -Eq 'Exited with unexpected signal code [56]([^0-9]|$)' \
+            && ! printf '%s\n' "$output" | grep -Eq '^(Test Suite|Test Case|◇ |↳ |✔ |✘ )'; then
+            echo "Test runner crashed at startup (runner flake); retrying Bonsplit once."
+            test_status=0
+            output="$(swift test --package-path vendor/bonsplit 2>&1)" || test_status=$?
+            printf '%s\n' "$output"
+          fi
+          if [ "$test_status" -ne 0 ]; then
+            exit "$test_status"
+          fi
+
      - name: Run Swift package unit tests
        run: |
          set -euo pipefail
@@ -1414,13 +1512,14 @@ jobs:
              # test runner at startup (signal 5/6 immediately after "Build
              # complete!", zero test output). That is a runner flake, not a
              # test failure: retry exactly once, and only when no test
-              # failures were reported.
+              # output was emitted.
              test_status=0
              output="$(swift test --package-path "$pkgdir" 2>&1)" || test_status=$?
              printf '%s\n' "$output"
              if [ "$test_status" -ne 0 ] \
-                && printf '%s\n' "$output" | grep -q 'Exited with unexpected signal code' \
-                && ! printf '%s\n' "$output" | grep -Eq 'with [1-9][0-9]* failures?'; then
+                && printf '%s\n' "$output" | grep -Fq 'Build complete!' \
+                && printf '%s\n' "$output" | grep -Eq 'Exited with unexpected signal code [56]([^0-9]|$)' \
+                && ! printf '%s\n' "$output" | grep -Eq '^(Test Suite|Test Case|◇ |↳ |✔ |✘ )'; then
                echo "Test runner crashed at startup (runner flake); retrying $pkg once."
                test_status=0
                output="$(swift test --package-path "$pkgdir" 2>&1)" || test_status=$?
@@ -140,9 +140,29 @@ jobs:
          legacy_assets="assets-legacy"
          mkdir -p "$legacy_assets"
          for file in assets/cmux-tui/cmux-tui-*; do
+            if [[ "$(basename "$file")" == cmux-tui-hook-* ]]; then
+              continue
+            fi
            cp "$file" "$legacy_assets/$(basename "$file" | sed 's/^cmux-tui-/cmux-mux-/')"
          done
-          cp assets/cmux-tui/manifest.json "$legacy_assets/manifest.json"
+          python3 - "$GITHUB_SHA" "$legacy_assets" <<'PY'
+          import hashlib
+          import json
+          import pathlib
+          import sys
+          from datetime import datetime, timezone
+
+          root = pathlib.Path(sys.argv[2])
+          files = sorted(path for path in root.glob("cmux-mux-*") if path.is_file())
+          manifest = {
+              "commit": sys.argv[1],
+              "builtAt": datetime.now(timezone.utc).isoformat(),
+              "binaries": {
+                  path.name: hashlib.sha256(path.read_bytes()).hexdigest() for path in files
+              },
+          }
+          (root / "manifest.json").write_text(json.dumps(manifest, indent=2) + "\n")
+          PY
          publish_legacy_prefix() {
            local prefix="$1"
            local cache="$2"
@@ -27,6 +27,36 @@ on:
        required: false
        default: false
        type: boolean
+      target_set:
+        description: "Binary targets to build: all or macos-arm64"
+        required: false
+        default: all
+        type: string
+      build_cloudflare_relay:
+        description: "Build and verify the Cloudflare relay"
+        required: false
+        default: true
+        type: boolean
+      verify_linux_arm64:
+        description: "Run package entrypoint verification on native Linux ARM64"
+        required: false
+        default: true
+        type: boolean
+      macos_runner:
+        description: "Optional macOS runner label override"
+        required: false
+        default: ""
+        type: string
+      linux_runner:
+        description: "Optional Linux x64 runner label override"
+        required: false
+        default: ""
+        type: string
+      windows_runner:
+        description: "Optional Windows runner label override"
+        required: false
+        default: ""
+        type: string
      checkout_ref:
        description: "Optional git ref to build instead of the caller ref"
        required: false
@@ -35,44 +65,114 @@ on:

 permissions: {}

-env:
-  RUST_TOOLCHAIN: "1.95.0"
-
 jobs:
+  plan-build:
+    name: select binary targets
+    runs-on: ${{ inputs.linux_runner != '' && inputs.linux_runner || vars.LINUX_RUNNER || 'blacksmith-4vcpu-ubuntu-2404' }}
+    timeout-minutes: 5
+    outputs:
+      matrix: ${{ steps.targets.outputs.matrix }}
+      linux_package_matrix: ${{ steps.targets.outputs.linux_package_matrix }}
+    steps:
+      - name: Select binary targets
+        id: targets
+        env:
+          TARGET_SET: ${{ inputs.target_set }}
+          PACKAGE_NPM: ${{ inputs.package_npm }}
+          PACKAGE_PYPI: ${{ inputs.package_pypi }}
+          MACOS_RUNNER: ${{ inputs.macos_runner != '' && inputs.macos_runner || vars.MACOS_RUNNER_15 || 'blacksmith-6vcpu-macos-15' }}
+          LINUX_RUNNER: ${{ inputs.linux_runner != '' && inputs.linux_runner || vars.LINUX_RUNNER || 'blacksmith-4vcpu-ubuntu-2404' }}
+          LINUX_ARM64_RUNNER: ${{ vars.LINUX_ARM64_RUNNER || 'ubuntu-24.04-arm' }}
+          VERIFY_LINUX_ARM64: ${{ inputs.verify_linux_arm64 }}
+        shell: bash
+        run: |
+          python3 <<'PY' >> "$GITHUB_OUTPUT"
+          import json
+          import os
+
+          targets = [
+              {
+                  "target": "aarch64-apple-darwin",
+                  "build_target": "aarch64-apple-darwin",
+                  "runner": os.environ["MACOS_RUNNER"],
+                  "cross": False,
+                  "ext": "",
+                  "compatibility_target": "",
+              },
+              {
+                  "target": "x86_64-apple-darwin",
+                  "build_target": "x86_64-apple-darwin",
+                  "runner": os.environ["MACOS_RUNNER"],
+                  "cross": True,
+                  "ext": "",
+                  "compatibility_target": "",
+              },
+              {
+                  "target": "x86_64-unknown-linux-musl",
+                  "build_target": "x86_64-unknown-linux-musl",
+                  "runner": os.environ["LINUX_RUNNER"],
+                  "cross": True,
+                  "ext": "",
+                  "compatibility_target": "x86_64-unknown-linux-gnu",
+              },
+              {
+                  "target": "aarch64-unknown-linux-musl",
+                  "build_target": "aarch64-unknown-linux-musl",
+                  "runner": os.environ["LINUX_RUNNER"],
+                  "cross": True,
+                  "ext": "",
+                  "compatibility_target": "aarch64-unknown-linux-gnu",
+              },
+          ]
+          target_set = os.environ["TARGET_SET"]
+          if target_set == "all":
+              selected = targets
+          elif target_set == "macos-arm64":
+              selected = [
+                  target for target in targets
+                  if target["target"] == "aarch64-apple-darwin"
+              ]
+          else:
+              raise SystemExit(f"unsupported target_set: {target_set!r}")
+
+          packages_requested = (
+              os.environ["PACKAGE_NPM"] == "true"
+              or os.environ["PACKAGE_PYPI"] == "true"
+          )
+          if packages_requested and target_set != "all":
+              raise SystemExit("npm and PyPI packaging require target_set=all")
+
+          print("matrix=" + json.dumps({"include": selected}, separators=(",", ":")))
+
+          linux_package_targets = [
+              {
+                  "architecture": "x64",
+                  "runner": os.environ["LINUX_RUNNER"],
+              }
+          ]
+          if os.environ["VERIFY_LINUX_ARM64"] == "true":
+              linux_package_targets.append(
+                  {
+                      "architecture": "arm64",
+                      "runner": os.environ["LINUX_ARM64_RUNNER"],
+                  }
+              )
+          print(
+              "linux_package_matrix="
+              + json.dumps({"include": linux_package_targets}, separators=(",", ":"))
+          )
+          PY
+
  build:
    name: build ${{ matrix.target }}
+    needs: plan-build
    runs-on: ${{ matrix.runner }}
    timeout-minutes: 60
    permissions:
      contents: read
    strategy:
      fail-fast: false
-      matrix:
-        include:
-          - target: aarch64-apple-darwin
-            build_target: aarch64-apple-darwin
-            runner: ${{ vars.MACOS_RUNNER_15 || 'blacksmith-6vcpu-macos-15' }}
-            cross: false
-            ext: ""
-            compatibility_target: ""
-          - target: x86_64-apple-darwin
-            build_target: x86_64-apple-darwin
-            runner: ${{ vars.MACOS_RUNNER_15 || 'blacksmith-6vcpu-macos-15' }}
-            cross: true
-            ext: ""
-            compatibility_target: ""
-          - target: x86_64-unknown-linux-musl
-            build_target: x86_64-unknown-linux-musl
-            runner: ${{ vars.LINUX_RUNNER || 'blacksmith-4vcpu-ubuntu-2404' }}
-            cross: true
-            ext: ""
-            compatibility_target: x86_64-unknown-linux-gnu
-          - target: aarch64-unknown-linux-musl
-            build_target: aarch64-unknown-linux-musl
-            runner: ${{ vars.LINUX_RUNNER || 'blacksmith-4vcpu-ubuntu-2404' }}
-            cross: true
-            ext: ""
-            compatibility_target: aarch64-unknown-linux-gnu
+      matrix: ${{ fromJSON(needs.plan-build.outputs.matrix) }}
    steps:
      - name: Checkout caller ref
        if: inputs.checkout_ref == ''
@@ -108,12 +208,8 @@ jobs:
        with:
          version: ${{ steps.ghostty-zig-version.outputs.version }}

-      - name: Install Rust toolchain
-        shell: bash
-        run: |
-          rustup toolchain install "$RUST_TOOLCHAIN" --profile minimal
-          rustup default "$RUST_TOOLCHAIN"
-          rustc --version
+      - name: Set up pinned Rust
+        uses: ./.github/actions/setup-cmux-tui-rust

      - name: Install Rust target
        shell: bash
@@ -142,7 +238,7 @@ jobs:
            CMUX_TUI_NPM_BOOTSTRAP_VERSION="$CMUX_TUI_DISTRIBUTION_VERSION"
            export CMUX_TUI_NPM_BOOTSTRAP_VERSION
          fi
-          cargo build -p cmux-tui --bin cmux-tui --release --locked --target ${{ matrix.build_target }}
+          cargo build -p cmux-tui --bin cmux-tui --bin cmux-tui-hook --release --locked --target ${{ matrix.build_target }}
          cargo build -p cmux-relay --bin cmux-relay --release --locked --target ${{ matrix.build_target }}

      - name: Build cmux-tui (Linux cross)
@@ -163,7 +259,7 @@ jobs:
            CMUX_TUI_NPM_BOOTSTRAP_VERSION="$CMUX_TUI_DISTRIBUTION_VERSION"
            export CMUX_TUI_NPM_BOOTSTRAP_VERSION
          fi
-          cargo zigbuild -p cmux-tui --bin cmux-tui --release --locked --target ${{ matrix.build_target }}
+          cargo zigbuild -p cmux-tui --bin cmux-tui --bin cmux-tui-hook --release --locked --target ${{ matrix.build_target }}
          cargo zigbuild -p cmux-relay --bin cmux-relay --release --locked --target ${{ matrix.build_target }}

      - name: Build cmux-tui (macOS cross)
@@ -184,7 +280,7 @@ jobs:
            CMUX_TUI_NPM_BOOTSTRAP_VERSION="$CMUX_TUI_DISTRIBUTION_VERSION"
            export CMUX_TUI_NPM_BOOTSTRAP_VERSION
          fi
-          cargo build -p cmux-tui --bin cmux-tui --release --locked --target ${{ matrix.build_target }}
+          cargo build -p cmux-tui --bin cmux-tui --bin cmux-tui-hook --release --locked --target ${{ matrix.build_target }}
          cargo build -p cmux-relay --bin cmux-relay --release --locked --target ${{ matrix.build_target }}

      - name: Stage binary
@@ -192,11 +288,14 @@ jobs:
        run: |
          mkdir -p dist
          binary="dist/cmux-tui-${{ matrix.target }}${{ matrix.ext }}"
+          hook_binary="dist/cmux-tui-hook-${{ matrix.target }}${{ matrix.ext }}"
          relay_binary="dist/cmux-relay-${{ matrix.target }}${{ matrix.ext }}"
          cp "cmux-tui/target/${{ matrix.target }}/release/cmux-tui${{ matrix.ext }}" "$binary"
+          cp "cmux-tui/target/${{ matrix.target }}/release/cmux-tui-hook${{ matrix.ext }}" "$hook_binary"
          cp "cmux-tui/target/${{ matrix.target }}/release/cmux-relay${{ matrix.ext }}" "$relay_binary"
          if [[ -n "${{ matrix.compatibility_target }}" ]]; then
            cp "$binary" "dist/cmux-tui-${{ matrix.compatibility_target }}${{ matrix.ext }}"
+            cp "$hook_binary" "dist/cmux-tui-hook-${{ matrix.compatibility_target }}${{ matrix.ext }}"
            cp "$relay_binary" "dist/cmux-relay-${{ matrix.compatibility_target }}${{ matrix.ext }}"
          fi
          ls -la dist
@@ -255,7 +354,8 @@ jobs:

  cloudflare-relay:
    name: Cloudflare Durable Object relay
-    runs-on: ${{ vars.LINUX_RUNNER || 'blacksmith-4vcpu-ubuntu-2404' }}
+    if: inputs.build_cloudflare_relay
+    runs-on: ${{ inputs.linux_runner != '' && inputs.linux_runner || vars.LINUX_RUNNER || 'blacksmith-4vcpu-ubuntu-2404' }}
    timeout-minutes: 30
    env:
      RUSTUP_TOOLCHAIN: "1.91.0"
@@ -311,8 +411,10 @@ jobs:
  build-windows:
    name: build x86_64-pc-windows-gnu
    if: inputs.include_windows
-    runs-on: ${{ vars.WINDOWS_RUNNER || 'windows-latest' }}
+    runs-on: ${{ inputs.windows_runner != '' && inputs.windows_runner || vars.WINDOWS_RUNNER || 'windows-latest' }}
    timeout-minutes: 60
+    env:
+      CARGO_TARGET_X86_64_PC_WINDOWS_GNU_RUSTFLAGS: -C link-arg=-fuse-ld=lld
    permissions:
      contents: read
    steps:
@@ -344,12 +446,8 @@ jobs:
        with:
          version: ${{ steps.ghostty-zig-version.outputs.version }}

-      - name: Install Rust toolchain
-        shell: bash
-        run: |
-          rustup toolchain install "$RUST_TOOLCHAIN" --profile minimal
-          rustup default "$RUST_TOOLCHAIN"
-          rustc --version
+      - name: Set up pinned Rust
+        uses: ./.github/actions/setup-cmux-tui-rust

      - name: Install Rust target
        shell: bash
@@ -357,6 +455,10 @@ jobs:
          rustup target add x86_64-pc-windows-gnu
          printf '%s\n' 'C:\msys64\mingw64\bin' >> "$GITHUB_PATH"

+      - name: Verify LLVM GNU linker
+        shell: bash
+        run: ld.lld --version
+
      - name: Build libghostty-vt + cmux-tui (Windows GNU)
        env:
          CMUX_TUI_DISTRIBUTION_VERSION: ${{ inputs.version }}
@@ -376,7 +478,32 @@ jobs:
          cd ghostty
          zig build -Demit-lib-vt=true -Demit-xcframework=false -Doptimize=ReleaseFast -Dtarget=x86_64-windows-gnu --prefix "$RUNNER_TEMP/ghostty-vt-win-gnu"
          cd ../cmux-tui
-          cargo build -p cmux-tui --bin cmux-tui --release --locked --target x86_64-pc-windows-gnu
+          cargo build -p cmux-tui --bin cmux-tui --bin cmux-tui-hook --release --locked --target x86_64-pc-windows-gnu
+
+      - name: Verify long Windows state path
+        shell: bash
+        run: |
+          python cmux-tui/scripts/smoke-windows-long-state-path.py \
+            --binary cmux-tui/target/x86_64-pc-windows-gnu/release/cmux-tui.exe
+
+      - name: Verify Windows terminal process exit
+        shell: bash
+        run: |
+          python cmux-tui/scripts/smoke-windows-process-wait.py \
+            --binary cmux-tui/target/x86_64-pc-windows-gnu/release/cmux-tui.exe
+
+      - name: Set up Python for ConPTY verification
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.12.10"
+
+      - name: Verify Windows ConPTY resize
+        shell: bash
+        run: |
+          python -m pip install --disable-pip-version-check --require-hashes \
+            -r cmux-tui/scripts/requirements-windows-conpty.txt
+          python cmux-tui/scripts/smoke-windows-conpty-resize.py \
+            --binary cmux-tui/target/x86_64-pc-windows-gnu/release/cmux-tui.exe

      - name: Verify remote commands fail clearly on Windows
        shell: bash
@@ -394,20 +521,23 @@ jobs:
        run: |
          mkdir -p dist
          cp "cmux-tui/target/x86_64-pc-windows-gnu/release/cmux-tui.exe" "dist/cmux-tui-x86_64-pc-windows-gnu.exe"
+          cp "cmux-tui/target/x86_64-pc-windows-gnu/release/cmux-tui-hook.exe" "dist/cmux-tui-hook-x86_64-pc-windows-gnu.exe"
          ls -la dist

      - name: Upload binary artifact
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: cmux-tui-x86_64-pc-windows-gnu
-          path: dist/cmux-tui-x86_64-pc-windows-gnu.exe
+          path: |
+            dist/cmux-tui-x86_64-pc-windows-gnu.exe
+            dist/cmux-tui-hook-x86_64-pc-windows-gnu.exe
          if-no-files-found: error

  package:
    name: package distributions
    needs: build
    if: inputs.package_npm || inputs.package_pypi
-    runs-on: ${{ vars.LINUX_RUNNER || 'blacksmith-4vcpu-ubuntu-2404' }}
+    runs-on: ${{ inputs.linux_runner != '' && inputs.linux_runner || vars.LINUX_RUNNER || 'blacksmith-4vcpu-ubuntu-2404' }}
    timeout-minutes: 30
    permissions:
      contents: read
@@ -501,6 +631,9 @@ jobs:
              binary = root / name / "bin" / "cmux-tui"
              if not binary.stat().st_mode & stat.S_IXUSR:
                  raise SystemExit(f"{binary} is not executable")
+              hook = root / name / "bin" / "cmux-tui-hook"
+              if not hook.stat().st_mode & stat.S_IXUSR:
+                  raise SystemExit(f"{hook} is not executable")
          PY
          chmod +x dist/binaries/cmux-tui-x86_64-unknown-linux-musl
          dist/binaries/cmux-tui-x86_64-unknown-linux-musl --version >/tmp/cmux-tui-version.txt 2>&1 || \
@@ -544,6 +677,18 @@ jobs:
          for wheel in dist/pypi-wheels/*.whl; do
            python3 -m zipfile -l "$wheel" >"/tmp/$(basename "$wheel").list"
          done
+          python3 - <<'PY'
+          import glob
+          import stat
+          import zipfile
+
+          for path in glob.glob("dist/pypi-wheels/*.whl"):
+              with zipfile.ZipFile(path) as wheel:
+                  info = wheel.getinfo("cmux_tui/bin/cmux-tui-hook")
+                  mode = info.external_attr >> 16
+                  if not mode & stat.S_IXUSR:
+                      raise SystemExit(f"{path}: bundled cmux-tui-hook is not executable")
+          PY
          chmod +x dist/binaries/cmux-tui-x86_64-unknown-linux-musl
          dist/binaries/cmux-tui-x86_64-unknown-linux-musl --version >/tmp/cmux-tui-version.txt 2>&1 || \
            dist/binaries/cmux-tui-x86_64-unknown-linux-musl --help >/tmp/cmux-tui-version.txt 2>&1
@@ -570,7 +715,9 @@ jobs:

  verify-linux-packages:
    name: verify Linux package entrypoints (${{ matrix.architecture }})
-    needs: package
+    needs:
+      - plan-build
+      - package
    if: ${{ inputs.package_npm || inputs.package_pypi }}
    runs-on: ${{ matrix.runner }}
    timeout-minutes: 30
@@ -578,15 +725,7 @@ jobs:
      contents: read
    strategy:
      fail-fast: false
-      matrix:
-        include:
-          - architecture: x64
-            runner: ${{ vars.LINUX_RUNNER || 'blacksmith-4vcpu-ubuntu-2404' }}
-          # Run ARM64 containers on native hardware. QEMU registration is not
-          # persistent on every third-party x64 runner and can disappear
-          # between setup and the package smoke test.
-          - architecture: arm64
-            runner: ${{ vars.LINUX_ARM64_RUNNER || 'ubuntu-24.04-arm' }} # github-hosted-required: package smoke tests need native ARM64 execution
+      matrix: ${{ fromJSON(needs.plan-build.outputs.linux_package_matrix) }}
    env:
      PYPI_VERSION: ${{ inputs.pypi_version != '' && inputs.pypi_version || inputs.version }}
    steps:
@@ -6,6 +6,7 @@ on:
      - main
    paths:
      - "cmux-tui/**"
+      - ".github/actions/setup-cmux-tui-rust/**"
      - ".github/workflows/cmux-tui-nightly.yml"
      - ".github/workflows/cmux-tui-release-cut.yml"
      - ".github/workflows/cmux-tui-release.yml"
@@ -26,6 +27,7 @@ on:
  pull_request:
    paths:
      - "cmux-tui/**"
+      - ".github/actions/setup-cmux-tui-rust/**"
      - ".github/workflows/cmux-tui-nightly.yml"
      - ".github/workflows/cmux-tui-release-cut.yml"
      - ".github/workflows/cmux-tui-release.yml"
@@ -486,11 +488,8 @@ jobs:
          cache: npm
          cache-dependency-path: cmux-tui/bindings/typescript/package-lock.json

-      - name: Set up Rust 1.95
-        run: |
-          rustup toolchain install 1.95.0 --profile minimal
-          cargo +1.95.0 --version
-          rustc +1.95.0 --version
+      - name: Set up pinned cmux-tui Rust
+        uses: ./.github/actions/setup-cmux-tui-rust

      - name: Set up Go
        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
@@ -519,7 +518,7 @@ jobs:
        working-directory: cmux-tui
        run: |
          test "$(zig version)" = "0.16.0"
-          cargo +1.95.0 build -p cmux-tui --bin cmux-tui --locked
+          cargo build -p cmux-tui --bin cmux-tui --locked

      - name: Set up Zig for SDK conformance
        uses: mlugg/setup-zig@8d6198c65fb0feaa111df26e6b467fea8345e46f # v2.0.5
@@ -532,7 +531,6 @@ jobs:
          CXX: clang++
          CMUX_ZIG: zig
          NODE_OPTIONS: --experimental-websocket
-          RUSTUP_TOOLCHAIN: 1.95.0
        run: |
          test "$(zig version)" = "0.15.2"
          test "$(node -p 'typeof WebSocket')" = "function"
@@ -0,0 +1,366 @@
+name: cmux-tui Rust Testbox setup
+
+# Main-controlled broker. This workflow runs only from refs/heads/main and
+# hydrates only main, so no candidate branch can edit the guards that run
+# before begin-testbox exposes its auth token, and no candidate build script
+# executes inside this token-bearing job. A candidate revision reaches the
+# Testbox later, through `blacksmith testbox run`, which synchronizes a
+# maintainer's local worktree onto the already-warm VM.
+on:
+  workflow_dispatch:
+    inputs:
+      testbox_id:
+        description: "Testbox session ID supplied by blacksmith testbox warmup"
+        required: true
+        type: string
+
+permissions: {}
+
+concurrency:
+  # A Testbox is a mutable shared workspace. Serialize every request for the
+  # same ID so two dispatches cannot corrupt one cache.
+  group: cmux-tui-testbox-${{ inputs.testbox_id }}
+  cancel-in-progress: false
+
+jobs:
+  cmux-tui-rust:
+    name: cmux-tui Rust setup
+    runs-on: blacksmith-32vcpu-ubuntu-2404
+    environment:
+      # Configure this environment with required reviewers, no secrets, and a
+      # deployment branch rule of exactly `main`. Approval is evaluated before
+      # the first step, so it precedes begin-testbox.
+      name: blacksmith-testbox-trusted
+    permissions:
+      contents: read
+    # Hydration plus three sequential 20-minute bounded remote builds happen
+    # after setup. Keep the GitHub job alive long enough for all stages and
+    # cleanup; the Testbox itself still has its separate idle timeout.
+    timeout-minutes: 120
+    steps:
+      # Every check here is main-controlled. `blacksmith testbox warmup`
+      # resolves both this file and the hydrated source from the same --ref, so
+      # refusing any ref other than refs/heads/main is what keeps a candidate
+      # branch outside the trust boundary.
+      - name: Validate broker ref
+        env:
+          DISPATCH_REF: ${{ github.ref }}
+          EVENT_NAME: ${{ github.event_name }}
+          REPOSITORY: ${{ github.repository }}
+          TESTBOX_ID: ${{ inputs.testbox_id }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          [[ "$REPOSITORY" == "manaflow-ai/cmux" ]] || {
+            echo "::error::this Testbox lane is only valid for manaflow-ai/cmux" >&2
+            exit 1
+          }
+          [[ "$EVENT_NAME" == "workflow_dispatch" ]] || {
+            echo "::error::Testbox setup must be dispatched manually, never from a PR event" >&2
+            exit 1
+          }
+          [[ "$DISPATCH_REF" == "refs/heads/main" ]] || {
+            echo "::error::this broker lane runs only from refs/heads/main, got $DISPATCH_REF; warm up with --ref main and sync the candidate through blacksmith testbox run" >&2
+            exit 1
+          }
+          [[ "$TESTBOX_ID" =~ ^tbx_[A-Za-z0-9_-]+$ ]] || {
+            echo "::error::malformed Testbox ID" >&2
+            exit 1
+          }
+
+      - name: Begin Testbox
+        uses: useblacksmith/begin-testbox@233448af4bfdc6fca509a7f0974411ac6d8a8043 # v2
+        with:
+          testbox_id: ${{ inputs.testbox_id }}
+
+      # main can move while a reviewer approves the deployment. Record which
+      # commit this job actually hydrates and fail closed if the dispatch ref
+      # changed under it.
+      - name: Revalidate broker identity after token exposure
+        env:
+          DISPATCH_REF: ${{ github.ref }}
+          DISPATCH_SHA: ${{ github.sha }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          [[ "$DISPATCH_REF" == "refs/heads/main" ]] || {
+            echo "::error::broker ref changed during setup" >&2
+            exit 1
+          }
+          [[ "$DISPATCH_SHA" =~ ^[0-9a-f]{40}$ ]] || {
+            echo "::error::dispatch SHA is malformed" >&2
+            exit 1
+          }
+          printf 'hydrating main at %s\n' "$DISPATCH_SHA"
+
+      - name: Checkout hydration commit
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+          ref: ${{ github.sha }}
+
+      - name: Require exact checkout and clean source
+        env:
+          EXPECTED_SHA: ${{ github.sha }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          actual_sha="$(git rev-parse HEAD)"
+          [[ "$actual_sha" == "$EXPECTED_SHA" ]] || {
+            echo "::error::checked out $actual_sha, expected hydration SHA $EXPECTED_SHA" >&2
+            exit 1
+          }
+          [[ -z "$(git status --porcelain=v1 --untracked-files=normal)" ]] || {
+            echo "::error::source checkout is dirty before hydration" >&2
+            git status --short >&2
+            exit 1
+          }
+          source_tree_sha="$(git rev-parse 'HEAD^{tree}')"
+          ghostty_entry="$(git ls-tree HEAD ghostty)"
+          [[ "$ghostty_entry" =~ ^160000[[:space:]]commit[[:space:]][0-9a-f]{40}[[:space:]]ghostty$ ]] || {
+            echo "::error::HEAD:ghostty is not a gitlink" >&2
+            exit 1
+          }
+          ghostty_gitlink_sha="$(git rev-parse 'HEAD:ghostty')"
+          printf 'source_sha=%s\nsource_tree_sha=%s\nghostty_gitlink_sha=%s\n' \
+            "$actual_sha" "$source_tree_sha" "$ghostty_gitlink_sha"
+
+      - name: Initialize Ghostty source submodule
+        shell: bash
+        run: |
+          set -euo pipefail
+          git submodule update --init --depth 1 ghostty
+          [[ "$(git -C ghostty rev-parse --show-toplevel)" == "$GITHUB_WORKSPACE/ghostty" ]] || {
+            echo "::error::ghostty did not initialize as its own submodule checkout" >&2
+            exit 1
+          }
+          ghostty_entry="$(git ls-tree HEAD ghostty)"
+          [[ "$ghostty_entry" =~ ^160000[[:space:]]commit[[:space:]][0-9a-f]{40}[[:space:]]ghostty$ ]] || {
+            echo "::error::HEAD:ghostty is not a gitlink" >&2
+            exit 1
+          }
+          expected_ghostty_sha="$(git rev-parse HEAD:ghostty)"
+          actual_ghostty_sha="$(git -C ghostty rev-parse HEAD)"
+          [[ "$actual_ghostty_sha" == "$expected_ghostty_sha" ]] || {
+            echo "::error::Ghostty checkout $actual_ghostty_sha does not match gitlink $expected_ghostty_sha" >&2
+            exit 1
+          }
+          [[ -z "$(git -C ghostty status --porcelain=v1 --untracked-files=normal)" ]] || {
+            echo "::error::Ghostty submodule is dirty after initialization" >&2
+            git -C ghostty status --short >&2
+            exit 1
+          }
+          test -f ghostty/build.zig.zon
+
+      - name: Install Linux build dependencies
+        shell: bash
+        run: |
+          set -euo pipefail
+          sudo apt-get update
+          sudo apt-get install -y clang libclang-dev pkg-config
+
+      - name: Cache Zig package downloads
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: ~/.cache/zig
+          key: cmux-tui-zig-${{ hashFiles('ghostty/build.zig.zon', 'ghostty/build.zig.zon.json') }}
+          restore-keys: |
+            cmux-tui-zig-
+
+      - name: Install repository-pinned Zig
+        shell: bash
+        run: ./scripts/install-zig-ci.sh
+
+      - name: Fetch Ghostty Zig dependencies without compiling
+        working-directory: ghostty
+        shell: bash
+        run: |
+          set -euo pipefail
+          # `--fetch` hydrates the package cache and exits before a build.
+          "$CMUX_ZIG" build --fetch
+
+      - name: Cache Cargo registry and git dependencies
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+          key: cmux-tui-cargo-${{ runner.os }}-${{ hashFiles('cmux-tui/Cargo.lock', 'cmux-tui/rust-toolchain.toml') }}
+          restore-keys: |
+            cmux-tui-cargo-${{ runner.os }}-
+
+      - name: Set up repository-pinned cmux-tui Rust
+        uses: ./.github/actions/setup-cmux-tui-rust
+
+      - name: Fetch Cargo dependencies without compiling
+        working-directory: cmux-tui
+        shell: bash
+        run: |
+          set -euo pipefail
+          cargo fetch --locked
+
+      - name: Record runner, toolchain, and Ghostty identity
+        env:
+          SOURCE_SHA: ${{ github.sha }}
+          SOURCE_REF: ${{ github.ref }}
+          TESTBOX_ID: ${{ inputs.testbox_id }}
+          RUNNER_LABEL: blacksmith-32vcpu-ubuntu-2404
+        shell: bash
+        run: |
+          set -euo pipefail
+          source_tree_sha="$(git rev-parse 'HEAD^{tree}')"
+          ghostty_entry="$(git ls-tree HEAD ghostty)"
+          [[ "$ghostty_entry" =~ ^160000[[:space:]]commit[[:space:]][0-9a-f]{40}[[:space:]]ghostty$ ]] || exit 1
+          ghostty_gitlink_sha="$(git rev-parse 'HEAD:ghostty')"
+          ghostty_head_sha="$(git -C ghostty rev-parse HEAD)"
+          [[ "$SOURCE_SHA" == "$(git rev-parse HEAD)" ]] || exit 1
+          [[ "$ghostty_gitlink_sha" == "$ghostty_head_sha" ]] || exit 1
+          [[ -z "$(git status --porcelain=v1 --untracked-files=normal)" ]] || exit 1
+          [[ -z "$(git -C ghostty status --porcelain=v1 --untracked-files=normal)" ]] || exit 1
+          pushd cmux-tui >/dev/null
+          cargo metadata --locked --no-deps --format-version 1 > "$RUNNER_TEMP/cmux-tui-cargo-metadata.json"
+          test -s "$RUNNER_TEMP/cmux-tui-cargo-metadata.json"
+          RUST_TOOLCHAIN="$(rustup show active-toolchain)"
+          RUSTC_VERSION="$(rustc --version)"
+          CARGO_VERSION="$(cargo --version)"
+          popd >/dev/null
+          mkdir -p testbox-benchmark
+          SOURCE_TREE_SHA="$source_tree_sha"
+          GHOSTTY_GITLINK_SHA="$ghostty_gitlink_sha"
+          GHOSTTY_HEAD_SHA="$ghostty_head_sha"
+          ZIG_VERSION="$("$CMUX_ZIG" version)"
+          ZIG_PATH="$CMUX_ZIG"
+          RUNNER_UNAME="$(uname -a)"
+          RUNNER_CPU_COUNT="$(nproc)"
+          [[ "$RUNNER_ARCH" == "X64" && "$RUNNER_CPU_COUNT" == "32" ]] || {
+            echo "::error::expected x64 32-vCPU runner, got arch=$RUNNER_ARCH cpu_count=$RUNNER_CPU_COUNT" >&2
+            exit 1
+          }
+          CARGO_METADATA_SHA256="$(sha256sum "$RUNNER_TEMP/cmux-tui-cargo-metadata.json" | cut -d ' ' -f 1)"
+          RUST_TOOLCHAIN_FILE_SHA256="$(sha256sum cmux-tui/rust-toolchain.toml | cut -d ' ' -f 1)"
+          CARGO_LOCK_SHA256="$(sha256sum cmux-tui/Cargo.lock | cut -d ' ' -f 1)"
+          GHOSTTY_ZON_SHA256="$(sha256sum ghostty/build.zig.zon | cut -d ' ' -f 1)"
+          export SOURCE_TREE_SHA GHOSTTY_GITLINK_SHA GHOSTTY_HEAD_SHA RUST_TOOLCHAIN RUSTC_VERSION CARGO_VERSION ZIG_VERSION ZIG_PATH RUNNER_UNAME RUNNER_CPU_COUNT CARGO_METADATA_SHA256 RUST_TOOLCHAIN_FILE_SHA256 CARGO_LOCK_SHA256 GHOSTTY_ZON_SHA256
+          python3 - <<'PY' > testbox-benchmark/setup-identity.json
+          import json
+          import os
+          import platform
+
+          print(json.dumps({
+              "schema": 3,
+              "source": {
+                  "ref": os.environ["SOURCE_REF"],
+                  "commit_sha": os.environ["SOURCE_SHA"],
+                  "tree_sha": os.environ["SOURCE_TREE_SHA"],
+                  "ghostty_gitlink_sha": os.environ["GHOSTTY_GITLINK_SHA"],
+                  "ghostty_head_sha": os.environ["GHOSTTY_HEAD_SHA"],
+              },
+              "broker": {
+                  "workflow_ref": os.environ["GITHUB_REF"],
+                  "workflow_sha": os.environ["SOURCE_SHA"],
+              },
+              "testbox": {
+                  "id": os.environ["TESTBOX_ID"],
+                  "setup_workflow_run_id": os.environ["GITHUB_RUN_ID"],
+              },
+              "runner": {
+                  "label": os.environ["RUNNER_LABEL"],
+                  "name": os.environ.get("RUNNER_NAME"),
+                  "os": os.environ.get("RUNNER_OS"),
+                  "arch": os.environ.get("RUNNER_ARCH"),
+                  "hostname": platform.node(),
+                  "uname": os.environ["RUNNER_UNAME"],
+                  "cpu_count": int(os.environ["RUNNER_CPU_COUNT"]),
+              },
+              "toolchain": {
+                  "rust_toolchain": os.environ["RUST_TOOLCHAIN"],
+                  "rustc": os.environ["RUSTC_VERSION"],
+                  "cargo": os.environ["CARGO_VERSION"],
+                  "rust_toolchain_file_sha256": os.environ["RUST_TOOLCHAIN_FILE_SHA256"],
+                  "cargo_lock_sha256": os.environ["CARGO_LOCK_SHA256"],
+                  "cargo_metadata_sha256": os.environ["CARGO_METADATA_SHA256"],
+                  "zig_path": os.environ["ZIG_PATH"],
+                  "zig": os.environ["ZIG_VERSION"],
+                  "ghostty_build_zig_zon_sha256": os.environ["GHOSTTY_ZON_SHA256"],
+              },
+          }, sort_keys=True, indent=2))
+          PY
+          test -s testbox-benchmark/setup-identity.json
+          cat testbox-benchmark/setup-identity.json
+
+      - name: Require clean hydrated source
+        shell: bash
+        run: |
+          set -euo pipefail
+          [[ -z "$(git status --porcelain=v1 --untracked-files=normal)" ]] || {
+            echo "::error::source became dirty during hydration" >&2
+            git status --short >&2
+            exit 1
+          }
+          [[ -z "$(git -C ghostty status --porcelain=v1 --untracked-files=normal)" ]] || {
+            echo "::error::Ghostty became dirty during hydration" >&2
+            git -C ghostty status --short >&2
+            exit 1
+          }
+
+      - name: Upload setup identity JSON
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: cmux-tui-testbox-setup-${{ github.run_id }}
+          path: testbox-benchmark/setup-identity.json
+          if-no-files-found: warn
+          retention-days: 14
+
+      # Missing `/tmp/.testbox` means begin-testbox could not register the VM.
+      # No auth token or API URL exists, so neither this workflow nor the pinned
+      # action can report hydration_failed. Fail explicitly; the CLI's bounded
+      # readiness wait and receipt-aware cleanup remain the only safe recovery.
+      - name: Require Testbox registration state
+        if: always()
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [[ ! -d /tmp/.testbox ]]; then
+            echo "::error::begin-testbox produced no registration state; hydration failure cannot be reported from this runner" >&2
+            exit 1
+          fi
+
+      - name: Confirm Testbox registration and mark setup ready
+        if: success()
+        env:
+          EXPECTED_TESTBOX_ID: ${{ inputs.testbox_id }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          state=/tmp/.testbox
+          rm -f /tmp/.testbox/cmux-tui-rust-setup-identity.json
+          for required_file in testbox_id installation_model_id auth_token api_url runner_host runner_ssh_port adopted_run_id ssh_public_key; do
+            test -s "$state/$required_file"
+          done
+          test -s "$state/working_directory"
+          test "$(<"$state/testbox_id")" = "$EXPECTED_TESTBOX_ID"
+          installation_model_id="$(<"$state/installation_model_id")"
+          [[ "$installation_model_id" =~ ^[0-9]+$ ]]
+          test -s "$state/ssh_public_key"
+          # begin-testbox deliberately continues after degraded phone-home.
+          # Validate the SSH handoff and install the identity marker before the
+          # pinned run-testbox action publishes ready. That action remains the
+          # sole readiness publisher, so a CLI run cannot race this marker.
+          marker="$state/cmux-tui-rust-setup-identity.json"
+          rm -f "$marker"
+          install -m 600 testbox-benchmark/setup-identity.json "$marker"
+          test -s "$marker"
+
+      # Keepalive is checked into this main-controlled workflow instead of
+      # importing an upstream composite that performs an unbounded duplicate
+      # ready curl. It reports
+      # hydration_failed on any failed setup or readiness path and bounds every
+      # phone-home request before entering its idle loop.
+      - name: Run trusted Testbox keepalive
+        if: always()
+        env:
+          JOB_STATUS: ${{ job.status }}
+        shell: bash
+        run: ./scripts/blacksmith-testbox-keepalive.sh
@@ -1,24 +1,99 @@
 name: cmux-tui
+run-name: cmux-tui ${{ inputs.mode }} ${{ inputs.request_id }} @ ${{ inputs.commit }}

 on:
-  # Temporarily manual-only beginning 2026-07-13 to pause automatic CI.
  workflow_dispatch:
+    inputs:
+      commit:
+        description: "Exact pushed 40-character commit SHA to verify"
+        required: true
+        type: string
+      mode:
+        description: "Focused Rust tests or the full cross-platform merge gate"
+        required: true
+        type: choice
+        options:
+          - focused
+          - full
+      test_filter:
+        description: "Rust test-name substring; required in focused mode"
+        required: false
+        default: ""
+        type: string
+      request_id:
+        description: "Unique caller token used to find this run"
+        required: true
+        type: string

 concurrency:
-  group: cmux-tui-${{ github.workflow }}-${{ github.ref }}
+  # Every caller waits for one exact commit. A newer request must not cancel it.
+  group: cmux-tui-${{ inputs.request_id }}
  cancel-in-progress: true

 permissions:
  contents: read

 jobs:
+  validate-inputs:
+    name: validate exact commit request
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 5
+    steps:
+      - name: Validate dispatch inputs
+        env:
+          EXACT_COMMIT: ${{ inputs.commit }}
+          WORKFLOW_COMMIT: ${{ github.sha }}
+          MODE: ${{ inputs.mode }}
+          TEST_FILTER: ${{ inputs.test_filter }}
+          REQUEST_ID: ${{ inputs.request_id }}
+        shell: bash
+        run: |
+          if [[ ! "$EXACT_COMMIT" =~ ^[0-9a-f]{40}$ ]]; then
+            echo "::error::commit must be a lowercase 40-character SHA" >&2
+            exit 1
+          fi
+          if [[ "$WORKFLOW_COMMIT" != "$EXACT_COMMIT" ]]; then
+            echo "::error::workflow revision $WORKFLOW_COMMIT does not match requested commit $EXACT_COMMIT" >&2
+            exit 1
+          fi
+          if [[ ! "$REQUEST_ID" =~ ^[A-Za-z0-9._-]{1,100}$ ]]; then
+            echo "::error::request_id contains unsupported characters" >&2
+            exit 1
+          fi
+          case "$MODE" in
+            focused)
+              if [[ ! "$TEST_FILTER" =~ ^[A-Za-z0-9_][A-Za-z0-9_:.-]{0,199}$ ]]; then
+                echo "::error::focused mode needs one safe Rust test-name substring" >&2
+                exit 1
+              fi
+              ;;
+            full)
+              if [[ -n "$TEST_FILTER" ]]; then
+                echo "::error::full mode does not accept test_filter" >&2
+                exit 1
+              fi
+              ;;
+            *)
+              echo "::error::unsupported mode: $MODE" >&2
+              exit 1
+              ;;
+          esac
+
  web-frontend:
-    runs-on: ${{ vars.LINUX_RUNNER || 'blacksmith-4vcpu-ubuntu-2404' }}
+    needs: validate-inputs
+    if: inputs.mode == 'full'
+    runs-on: blacksmith-4vcpu-ubuntu-2404
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false
+          ref: ${{ inputs.commit }}
+
+      - name: Require exact checkout
+        env:
+          EXACT_COMMIT: ${{ inputs.commit }}
+        run: test "$(git rev-parse HEAD)" = "$EXACT_COMMIT"

      - name: Set up Node.js
        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
@@ -44,19 +119,26 @@ jobs:

  valgrind-leak-check-shard:
    name: valgrind-leak-check (${{ matrix.shard }})
-    runs-on: ${{ vars.LINUX_RUNNER || 'blacksmith-4vcpu-ubuntu-2404' }}
-    # The core, remote, and application suites are intentionally serialized
-    # under instrumentation. Isolate them so none can consume another test
-    # binary group's runtime budget.
-    timeout-minutes: 60
+    needs: validate-inputs
+    if: inputs.mode == 'full'
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    # Full behavior stays in the normal macOS and Linux suites. Valgrind owns
+    # the bounded startup parsers and terminal replay state only.
+    timeout-minutes: 40
    strategy:
      fail-fast: false
      matrix:
-        shard: [core, remote, tui, remainder]
+        shard: [startup]
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false
+          ref: ${{ inputs.commit }}
+
+      - name: Require exact checkout
+        env:
+          EXACT_COMMIT: ${{ inputs.commit }}
+        run: test "$(git rev-parse HEAD)" = "$EXACT_COMMIT"

      - name: Init ghostty submodule
        run: git submodule update --init --depth 1 ghostty
@@ -69,13 +151,8 @@ jobs:
      - name: Install zig
        run: ./scripts/install-zig-ci.sh

-      - name: Rust version
-        run: |
-          rustc --version || true
-          if ! command -v cargo >/dev/null; then
-            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable
-            echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
-          fi
+      - name: Set up pinned Rust
+        uses: ./.github/actions/setup-cmux-tui-rust

      - name: Build test binaries
        working-directory: cmux-tui
@@ -95,19 +172,15 @@ jobs:
          import sys

          shard = os.environ["VALGRIND_SHARD"]
-          known_shards = {"core", "remote", "tui", "remainder"}
+          known_shards = {"startup"}
          if shard not in known_shards:
              raise SystemExit(f"unknown Valgrind shard: {shard}")

          def shard_for(executable):
              name = os.path.basename(executable)
-              if re.fullmatch(r"cmux_tui_core-[0-9a-f]+", name):
-                  return "core"
-              if re.fullmatch(r"cmux_remote-[0-9a-f]+", name):
-                  return "remote"
-              if re.fullmatch(r"cmux_tui-[0-9a-f]+", name):
-                  return "tui"
-              return "remainder"
+              if re.fullmatch(r"(?:cmux_tui|terminal)-[0-9a-f]+", name):
+                  return "startup"
+              return None

          seen = set()
          selected = []
@@ -141,19 +214,34 @@ jobs:
          )
          PY

+      - name: Verify baseline terminal replay behavior
+        if: matrix.shard == 'startup'
+        working-directory: cmux-tui
+        run: |
+          matches=0
+          while IFS= read -r bin; do
+            [ -n "$bin" ] || continue
+            case "$(basename "$bin")" in
+              terminal-*)
+                if ! "$bin" --list \
+                  | grep -Fqx 'pending_wrap_replay_preserves_cursor_with_origin_mode: test'; then
+                  echo "::error::terminal replay test binary does not contain the exact baseline test" >&2
+                  exit 1
+                fi
+                "$bin" pending_wrap_replay_preserves_cursor_with_origin_mode \
+                  --exact \
+                  --test-threads=1
+                matches=$((matches + 1))
+                ;;
+            esac
+          done < target/valgrind-test-binaries.txt
+          if [[ "$matches" -ne 1 ]]; then
+            echo "::error::expected one terminal integration test binary, found $matches" >&2
+            exit 1
+          fi
+
      - name: Run test binaries under valgrind
        working-directory: cmux-tui
-        env:
-          # Valgrind's ~30x slowdown breaks the 50ms ws-latency budget on an
-          # otherwise-correct build; the guarded regression (events serialized
-          # behind a 100ms read poll) inflates far past this bound anyway.
-          CMUX_TEST_WS_LATENCY_BUDGET_MS: "2000"
-          # Scale test-fixture deadlines and their observation windows together
-          # under instrumentation. Production defaults and normal CI remain strict.
-          CMUX_TEST_TIMEOUT_SCALE: "4"
-          # Retain the full 128 MiB fairness workload under Valgrind with
-          # explicit instrumentation-only bounds. Normal CI stays strict.
-          CMUX_TEST_PERF_INSTRUMENTED: "valgrind"
        run: |
          run_valgrind() {
            local bin="$1"
@@ -167,73 +255,57 @@ jobs:
              -- "$bin" "$@"
          }

-          while IFS= read -r bin; do
-            [ -n "$bin" ] || continue
-            echo "Running valgrind for $bin"
-            valgrind_args=(--track-origins=yes)
-            test_args=()
-            case "$(basename "$bin")" in
-              pty-*|cmux_tui_core-*|cmux_tui-[[:xdigit:]]*)
-                # These tests own bounded worker pools, PTYs, sockets, and
-                # deadline-sensitive readers. Valgrind serializes their CPU
-                # work internally, so test-harness parallelism only creates
-                # scheduler starvation and wall-clock timeout races.
-                test_args+=(--test-threads=1)
-                ;;
-              cmux_remote-[[:xdigit:]]*)
-                # Remote-runtime tests also own real schedulers, sockets, and
-                # deadline checks. Serial execution prevents the instrumented
-                # harness from starving its own observation deadlines.
-                test_args+=(--test-threads=1)
-                ;;
-              terminal_host_recovery-*)
-                # Valgrind instruments this client harness but not the hidden
-                # terminal-host child it launches. The normal-speed child can
-                # fill the socket while the instrumented reader is descheduled,
-                # correctly triggering the production stalled-client timeout
-                # mid-frame. Normal Linux and macOS CI retain this ordering test;
-                # every other recovery case remains under Valgrind.
-                test_args+=(--skip exit_follows_all_final_pty_bytes_on_the_live_stream)
-                ;;
-              direct_wss_e2e-*|relay_wss_diagnostic-*)
-                # ring's AES-GCM backend exposes initialized output through a
-                # partially initialized SIMD buffer. Valgrind reports its
-                # padding at Rustls writev. Keep leak and address checks for
-                # TLS integration binaries while scoping undefined-value
-                # suppression to those binaries.
-                valgrind_args=(--undef-value-errors=no)
-                ;;
-            esac
-
-            if [[ "$(basename "$bin")" == cmux_remote-[[:xdigit:]]* ]]; then
-              # Iroh's Rustls/ring and noq UDP paths expose initialized data
-              # through buffers with uninitialized SIMD or sockaddr padding.
-              # Run only those tests without undefined-value diagnostics while
-              # retaining address and leak checks. Every other remote test
-              # keeps the complete Valgrind diagnostic set.
-              if ! run_valgrind "$bin" --skip 'provider::iroh::' "${test_args[@]}"; then
-                echo "Valgrind failed for $bin outside the Iroh provider" >&2
-                exit 1
-              fi
-              valgrind_args=(--undef-value-errors=no)
-              if ! run_valgrind "$bin" 'provider::iroh::' "${test_args[@]}"; then
-                echo "Valgrind failed for $bin in the Iroh provider" >&2
-                exit 1
-              fi
-              continue
-            fi
-
-            if ! run_valgrind "$bin" "${test_args[@]}"; then
-              echo "Valgrind failed for $bin" >&2
+          require_exact_test() {
+            local bin="$1"
+            local test_name="$2"
+            if ! "$bin" --list | grep -Fqx "$test_name: test"; then
+              echo "::error::$(basename "$bin") does not contain exact test '$test_name'" >&2
              exit 1
            fi
+          }
+
+          cmux_tui_bin=""
+          terminal_bin=""
+          while IFS= read -r bin; do
+            case "$(basename "$bin")" in
+              cmux_tui-*) cmux_tui_bin="$bin" ;;
+              terminal-*) terminal_bin="$bin" ;;
+            esac
          done < target/valgrind-test-binaries.txt
+          if [[ -z "$cmux_tui_bin" || -z "$terminal_bin" ]]; then
+            echo "::error::startup memory check did not find both test binaries" >&2
+            exit 1
+          fi
+
+          valgrind_args=(--track-origins=yes)
+          require_exact_test \
+            "$terminal_bin" \
+            pending_wrap_replay_preserves_cursor_with_origin_mode
+          run_valgrind \
+            "$terminal_bin" \
+            pending_wrap_replay_preserves_cursor_with_origin_mode \
+            --exact \
+            --test-threads=1
+
+          startup_tests=(
+            config::tests::load_uses_file_ghostty_defaults_without_invoking_external_resolver
+            config::tests::ghostty_file_reader_enforces_byte_limit_during_read
+            config::tests::ghostty_config_helper_output_reader_enforces_byte_limit
+          )
+          for test_name in "${startup_tests[@]}"; do
+            require_exact_test "$cmux_tui_bin" "$test_name"
+            run_valgrind \
+              "$cmux_tui_bin" \
+              "$test_name" \
+              --exact \
+              --test-threads=1
+          done

  valgrind-leak-check:
    name: valgrind-leak-check
-    if: always()
+    if: always() && inputs.mode == 'full'
    needs: valgrind-leak-check-shard
-    runs-on: ${{ vars.LINUX_RUNNER || 'blacksmith-4vcpu-ubuntu-2404' }}
+    runs-on: blacksmith-4vcpu-ubuntu-2404
    timeout-minutes: 2
    steps:
      - name: Require every Valgrind shard
@@ -243,14 +315,27 @@ jobs:

  test:
    name: test (${{ matrix.os }})
-    runs-on: ${{ matrix.os == 'macos' && (vars.MACOS_RUNNER_15 || 'blacksmith-6vcpu-macos-15') || 'ubuntu-latest' }}
+    needs: validate-inputs
+    runs-on: ${{ matrix.runner }}
    timeout-minutes: 40
    strategy:
      fail-fast: false
      matrix:
-        os: [macos, linux]
+        include:
+          - os: macos
+            runner: blacksmith-6vcpu-macos-15
+          - os: linux
+            runner: blacksmith-4vcpu-ubuntu-2404
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+          ref: ${{ inputs.commit }}
+
+      - name: Require exact checkout
+        env:
+          EXACT_COMMIT: ${{ inputs.commit }}
+        run: test "$(git rev-parse HEAD)" = "$EXACT_COMMIT"

      - name: Init ghostty submodule
        run: git submodule update --init --depth 1 ghostty
@@ -264,47 +349,133 @@ jobs:
      - name: Install zig
        run: ./scripts/install-zig-ci.sh

-      - name: Rust version
+      - name: Ghostty VT cursor replay checks
+        if: inputs.mode == 'full'
+        working-directory: ghostty
        run: |
-          rustc --version || true
-          if ! command -v cargo >/dev/null; then
-            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable
-            echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
-          fi
+          "$CMUX_ZIG" build test-lib-vt -Dtest-filter="Terminal vt"
+
+      - name: Set up pinned Rust
+        uses: ./.github/actions/setup-cmux-tui-rust

      - name: cargo fmt
+        id: rustfmt-check
        working-directory: cmux-tui
        run: cargo fmt --check

+      - name: Prepare hosted rustfmt patch
+        if: ${{ failure() && steps.rustfmt-check.outcome == 'failure' }}
+        working-directory: cmux-tui
+        run: |
+          cargo fmt
+          git diff --binary -- . > "$RUNNER_TEMP/rustfmt.patch"
+          test -s "$RUNNER_TEMP/rustfmt.patch"
+
+      - name: Upload hosted rustfmt patch
+        if: ${{ failure() && steps.rustfmt-check.outcome == 'failure' }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: rustfmt-${{ runner.os }}-${{ github.sha }}
+          path: ${{ runner.temp }}/rustfmt.patch
+          if-no-files-found: error
+          retention-days: 1
+
      - name: cargo clippy
+        if: inputs.mode == 'full'
        working-directory: cmux-tui
        run: cargo clippy --workspace --all-targets --locked -- -D warnings

+      - name: focused Linux journal process-fence test
+        if: runner.os == 'Linux'
+        working-directory: cmux-tui
+        run: >-
+          cargo test -p cmux-tui-core --lib
+          journal_hooks::tests::unix_hook_tree_kills_a_descendant_that_created_a_new_session
+          -- --exact
+
+      - name: focused macOS journal process-fence tests
+        if: runner.os == 'macOS'
+        working-directory: cmux-tui
+        run: cargo test -p cmux-tui-core --lib unix_process_scope::tests::mac_process_scope_
+
+      - name: focused journal writer shutdown test
+        working-directory: cmux-tui
+        run: >-
+          cargo test -p cmux-tui-core --lib
+          journal_ingress::tests::shutdown_returns_when_an_admitted_commit_stays_blocked
+          -- --exact
+
+      - name: focused final journal ownership tests
+        working-directory: cmux-tui
+        run: |
+          cargo test -p cmux-tui-core --lib \
+            journal_ingress::tests::shutdown_closes_admission_while_a_terminal_producer_waits_for_space \
+            -- --exact
+          cargo test -p cmux-tui-core --lib \
+            journal_checkpoint::tests::replaying_an_old_producer_put_keeps_the_current_validator \
+            -- --exact
+          cargo test -p cmux-tui-core --test browser_runtime \
+            socket_browser_attach_streams_frames_input_and_cell_pixels \
+            -- --exact
+
      - name: cargo test
        working-directory: cmux-tui
-        run: cargo test --workspace --locked
+        env:
+          MODE: ${{ inputs.mode }}
+          TEST_FILTER: ${{ inputs.test_filter }}
+        shell: bash
+        run: |
+          if [[ "$MODE" == "full" ]]; then
+            cargo test --workspace --exclude cmux-tui-core --locked
+            mkdir -p target
+            cargo test -p cmux-tui-core --locked --no-run --message-format=json \
+              > target/cmux-tui-core-test-binaries.jsonl
+            python3 ../.github/scripts/run-cmux-tui-core-tests-isolated.py \
+              target/cmux-tui-core-test-binaries.jsonl \
+              crates/cmux-tui-core
+            cargo test -p cmux-tui-core --doc --locked
+            exit 0
+          fi
+          cargo test --workspace --locked "$TEST_FILTER" -- --list \
+            | tee "$RUNNER_TEMP/cmux-tui-focused-tests.txt"
+          if ! grep -Eq ': test$' "$RUNNER_TEMP/cmux-tui-focused-tests.txt"; then
+            echo "::error::test_filter '$TEST_FILTER' selected no Rust tests" >&2
+            exit 1
+          fi
+          cargo test --workspace --locked "$TEST_FILTER"

      - name: crossterm parser tests
+        if: inputs.mode == 'full'
        working-directory: cmux-tui
        run: cargo test --manifest-path vendor/crossterm/Cargo.toml --lib

      - name: TUI smoke test (scripted pty)
+        if: inputs.mode == 'full'
        working-directory: cmux-tui
        run: |
          cargo build -p cmux-tui
          python3 scripts/smoke-tui.py

      - name: Detach/reattach smoke test
+        if: inputs.mode == 'full'
        working-directory: cmux-tui
        run: python3 scripts/smoke-attach.py

  bindings-e2e:
-    runs-on: ${{ vars.LINUX_RUNNER || 'blacksmith-4vcpu-ubuntu-2404' }}
+    needs: validate-inputs
+    if: inputs.mode == 'full'
+    runs-on: blacksmith-4vcpu-ubuntu-2404
    timeout-minutes: 40
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false
+          ref: ${{ inputs.commit }}
+
+      - name: Require exact checkout
+        env:
+          EXACT_COMMIT: ${{ inputs.commit }}
+        run: test "$(git rev-parse HEAD)" = "$EXACT_COMMIT"

      - name: Set up Node.js
        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
@@ -328,13 +499,8 @@ jobs:
      - name: Install zig
        run: ./scripts/install-zig-ci.sh

-      - name: Rust version
-        run: |
-          rustc --version || true
-          if ! command -v cargo >/dev/null; then
-            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable
-            echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
-          fi
+      - name: Set up pinned Rust
+        uses: ./.github/actions/setup-cmux-tui-rust

      - name: Java version
        run: |
@@ -368,6 +534,10 @@ jobs:
          ZIG_FORCE_LOCAL_INSTALL: "1"
        run: ./scripts/install-zig-ci.sh

+      - name: Install TypeScript adapter build tools
+        working-directory: cmux-tui/bindings/typescript
+        run: npm ci --no-audit --no-fund
+
      - name: Python conformance fixtures
        run: |
          test "$("$CMUX_ZIG" version)" = "${{ steps.zig-sdk-version.outputs.version }}"
@@ -378,42 +548,64 @@ jobs:
          test "$("$CMUX_ZIG" version)" = "${{ steps.zig-sdk-version.outputs.version }}"
          bash cmux-tui/bindings/conformance/e2e.sh --require python,typescript,rust,go,java

-  windows-experimental:
-    name: windows experimental (x86_64-gnu)
-    runs-on: windows-latest
-    timeout-minutes: 40
-    continue-on-error: true
+  build-artifacts:
+    name: release-path dogfood artifacts
+    needs: validate-inputs
+    permissions:
+      contents: read
+    uses: ./.github/workflows/cmux-tui-build-package.yml
+    with:
+      version: 0.0.0-nightly.19700101.0
+      pypi_version: 0.0.0.dev197001010
+      package_npm: ${{ inputs.mode == 'full' }}
+      package_pypi: ${{ inputs.mode == 'full' }}
+      include_windows: ${{ inputs.mode == 'full' }}
+      target_set: ${{ inputs.mode == 'full' && 'all' || 'macos-arm64' }}
+      build_cloudflare_relay: false
+      verify_linux_arm64: ${{ inputs.mode == 'full' }}
+      macos_runner: blacksmith-6vcpu-macos-15
+      linux_runner: blacksmith-4vcpu-ubuntu-2404
+      windows_runner: windows-latest
+      checkout_ref: ${{ inputs.commit }}
+
+  hosted-verification:
+    name: ${{ inputs.mode == 'full' && 'hosted verification' || 'focused hosted verification' }}
+    if: always()
+    needs:
+      - validate-inputs
+      - web-frontend
+      - valgrind-leak-check
+      - test
+      - bindings-e2e
+      - build-artifacts
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 5
+    env:
+      MODE: ${{ inputs.mode }}
+      VALIDATE_RESULT: ${{ needs.validate-inputs.result }}
+      WEB_RESULT: ${{ needs.web-frontend.result }}
+      VALGRIND_RESULT: ${{ needs.valgrind-leak-check.result }}
+      TEST_RESULT: ${{ needs.test.result }}
+      BINDINGS_RESULT: ${{ needs.bindings-e2e.result }}
+      ARTIFACT_RESULT: ${{ needs.build-artifacts.result }}
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Init ghostty submodule
-        run: git submodule update --init --depth 1 ghostty
-
-      - name: Resolve Ghostty Zig version
-        id: ghostty-zig-version
+      - name: Require selected verification jobs
        shell: bash
        run: |
-          version="$(bash ./scripts/ghostty-zig-version.sh)"
-          echo "version=$version" >> "$GITHUB_OUTPUT"
+          require_success() {
+            local name="$1"
+            local result="$2"
+            if [[ "$result" != "success" ]]; then
+              echo "::error::$name finished with result '$result'" >&2
+              exit 1
+            fi
+          }

-      - name: Install zig
-        uses: mlugg/setup-zig@8d6198c65fb0feaa111df26e6b467fea8345e46f # v2.0.5
-        with:
-          version: ${{ steps.ghostty-zig-version.outputs.version }}
-
-      - name: Install Rust GNU target
-        shell: bash
-        run: |
-          rustup target add x86_64-pc-windows-gnu
-          printf '%s\n' 'C:\msys64\mingw64\bin' >> "$GITHUB_PATH"
-
-      - name: Build libghostty-vt for Windows GNU
-        shell: bash
-        working-directory: ghostty
-        run: |
-          zig build -Demit-lib-vt=true -Demit-xcframework=false -Doptimize=ReleaseFast -Dtarget=x86_64-windows-gnu --prefix "$RUNNER_TEMP/ghostty-vt-win-gnu"
-          zig ar t "$RUNNER_TEMP/ghostty-vt-win-gnu/lib/ghostty-vt-static.lib" | head
-
-      - name: cargo build cmux-tui for Windows GNU
-        working-directory: cmux-tui
-        run: cargo build -p cmux-tui --target x86_64-pc-windows-gnu --locked
+          require_success "input validation" "$VALIDATE_RESULT"
+          require_success "Rust tests" "$TEST_RESULT"
+          require_success "dogfood artifact build" "$ARTIFACT_RESULT"
+          if [[ "$MODE" == "full" ]]; then
+            require_success "web frontend" "$WEB_RESULT"
+            require_success "Valgrind" "$VALGRIND_RESULT"
+            require_success "binding end-to-end tests" "$BINDINGS_RESULT"
+          fi
@@ -55,9 +55,19 @@ jobs:
        run: ./scripts/ci/run-iroh-tailscale-compatibility-gate.sh

  simulator-e2e:
-    needs: tailscale-version-skew
+    env:
+      # The app gates compile optimized Swift for both endpoints. Xcode 26's
+      # AArch64 GlobalISel path is not reliable for that exact build shape, so
+      # use the same supported workaround as tagged cloud reloads and streamed
+      # validation instead of allowing a compiler failure to masquerade as a
+      # transport verdict.
+      CMUX_SWIFT_FRONTEND_WORKAROUND: "1"
    strategy:
      fail-fast: false
+      # The three app-backed modes share one staging account. Serial execution
+      # prevents one mode's zero-touch registration from replacing another
+      # mode's active Mac route while its authenticated RPC probe is running.
+      max-parallel: 1
      matrix:
        mode: ${{ fromJSON(inputs.mode == 'all' && '["automatic","relay-only","relay-expiry","direct-only","private-path"]' || format('["{0}"]', inputs.mode)) }}
    runs-on: ${{ vars.MACOS_RUNNER_STREAMED_VALIDATION || 'warp-macos-15-arm64-6x' }}
@@ -120,6 +130,8 @@ jobs:
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: iroh-release-gate-${{ matrix.mode }}
-          path: ${{ runner.temp }}/iroh-release-gate-${{ matrix.mode }}.json
+          path: |
+            ${{ runner.temp }}/iroh-release-gate-${{ matrix.mode }}.json
+            ${{ runner.temp }}/iroh-release-gate-${{ matrix.mode }}-mac.cmuxdiag
          if-no-files-found: warn
          retention-days: 7
@@ -63,6 +63,9 @@ jobs:
    env:
      # The ghostty CLI helper zig build is skipped; GhosttyKit comes prebuilt.
      CMUX_SKIP_ZIG_BUILD: "1"
+      # A degraded cache must lose to a cold build instead of stalling this
+      # latency-sensitive lane for actions/cache's ten-minute default.
+      SEGMENT_DOWNLOAD_TIMEOUT_MINS: "2"
      SWIFT_BACKTRACE: "interactive=no,timeout=0s,symbolicate=off,color=no"
    steps:
      - name: Checkout source ref
@@ -80,12 +83,333 @@ jobs:
          set -euo pipefail
          ./scripts/select-ci-xcode.sh

-      - name: Install zig
-        run: ./scripts/install-zig-ci.sh
-
-      - name: Provision GhosttyKit (macOS)
+      - name: Prepare macOS cache metadata
        if: ${{ inputs.platform == 'macos' }}
-        run: ./scripts/download-prebuilt-ghosttykit.sh || ./scripts/ensure-ghosttykit.sh
+        id: cache_meta
+        env:
+          SOURCE_REF: ${{ inputs.ref || github.ref_name }}
+        run: |
+          set -euo pipefail
+          xcode_version="$(xcodebuild -version | awk 'NR == 1 { print $2 }')"
+          xcode_build="$(xcodebuild -version | awk 'NR == 2 { print $3 }')"
+          xcode_key="$(printf 'xcode-%s-%s' "$xcode_version" "$xcode_build" | tr -c 'A-Za-z0-9._-' '-')"
+
+          branch_name="${SOURCE_REF#refs/heads/}"
+          branch_name="${branch_name#refs/tags/}"
+          if [ -z "$branch_name" ]; then
+            branch_name="$(git branch --show-current)"
+          fi
+          if [ -z "$branch_name" ]; then
+            branch_name="detached"
+          fi
+          branch_slug="$(printf '%s' "$branch_name" | tr -c 'A-Za-z0-9._-' '-' | sed 's/-\{2,\}/-/g; s/^-//; s/-$//')"
+          branch_digest="$(printf '%s' "$branch_name" | shasum -a 256 | awk '{ print substr($1, 1, 12) }')"
+          if [ "$branch_name" = "main" ]; then
+            branch_key="main"
+          else
+            branch_key="${branch_slug:0:48}-${branch_digest}"
+          fi
+          # Xcode's SourcePackages workspace state and DerivedData build
+          # database contain absolute checkout paths. Keep exact-state caches
+          # tied to the path contract; a different runner workspace must cold
+          # resolve/build instead of consuming stale absolute paths.
+          workspace_digest="$(printf '%s' "$GITHUB_WORKSPACE" | shasum -a 256 | awk '{ print substr($1, 1, 12) }')"
+          workspace_key="workspace-${workspace_digest}"
+          runner_os="$(printf '%s' "$(uname -s)" | tr -c 'A-Za-z0-9._-' '-')"
+          runner_os_version="$(sw_vers -productVersion 2>/dev/null || uname -r)"
+          runner_os_version="$(printf '%s' "$runner_os_version" | tr -c 'A-Za-z0-9._-' '-')"
+          runner_arch="$(printf '%s' "$(uname -m)" | tr -c 'A-Za-z0-9._-' '-')"
+          runner_key="${runner_os}-${runner_os_version}-${runner_arch}"
+
+          resolved_file="cmux.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved"
+          source_sha="$(git rev-parse HEAD)"
+          # Cache entries are immutable. A run-scoped save key plus a stable
+          # source prefix lets a cold retry publish a newer repaired entry.
+          cache_run_key="${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
+          spm_prefix="reload-build-macos-spm-v2-${xcode_key}-${workspace_key}-"
+          # DerivedData contains ONLY_ACTIVE_ARCH products and object files;
+          # never restore those across OS/architecture changes.
+          derived_prefix="reload-build-macos-deriveddata-v3-${xcode_key}-${runner_key}-${workspace_key}-"
+          if [ -f "$resolved_file" ]; then
+            resolved_hash="$(shasum -a 256 "$resolved_file" | awk '{ print $1 }')"
+            spm_cache_enabled=true
+            spm_key_base="${spm_prefix}${resolved_hash}"
+            spm_key="${spm_key_base}-run-${cache_run_key}"
+            spm_source_prefix="${spm_key_base}-run-"
+          else
+            echo "::warning::$resolved_file absent in source ref; disabling the SPM cache"
+            spm_cache_enabled=false
+            spm_key_base=""
+            spm_key=""
+            spm_source_prefix=""
+          fi
+          derived_data_key_base="${derived_prefix}${branch_key}-${source_sha}"
+
+          {
+            echo "xcode_key=$xcode_key"
+            echo "branch_key=$branch_key"
+            echo "workspace_key=$workspace_key"
+            echo "runner_key=$runner_key"
+            echo "source_sha=$source_sha"
+            echo "spm_cache_enabled=$spm_cache_enabled"
+            echo "spm_prefix=$spm_prefix"
+            echo "spm_key_base=$spm_key_base"
+            echo "spm_key=$spm_key"
+            echo "spm_source_prefix=$spm_source_prefix"
+            echo "derived_data_key_base=$derived_data_key_base"
+            echo "derived_data_key=${derived_data_key_base}-run-${cache_run_key}"
+            echo "derived_data_source_prefix=${derived_data_key_base}-run-"
+            echo "derived_data_branch_prefix=${derived_prefix}${branch_key}-"
+            echo "derived_data_main_prefix=${derived_prefix}main-"
+          } >> "$GITHUB_OUTPUT"
+
+      # The verified prebuilt is the happy path for both platforms. Zig is
+      # installed only after this attempt fails, immediately before the local
+      # ensure-ghosttykit.sh fallback that needs it.
+      - name: Download prebuilt GhosttyKit
+        id: ghosttykit_prebuilt
+        run: |
+          set -euo pipefail
+          start=$(date +%s)
+          # Keep a transient release outage from consuming the whole 60-minute
+          # job before the Zig-backed fallback gets a chance to run. The script
+          # still owns checksum/archive validation and preserves its normal
+          # defaults for local and fleet callers.
+          if GHOSTTYKIT_DOWNLOAD_RETRIES=2 \
+            GHOSTTYKIT_DOWNLOAD_RETRY_DELAY=5 \
+            GHOSTTYKIT_DOWNLOAD_MAX_TIME=60 \
+            ./scripts/download-prebuilt-ghosttykit.sh; then
+            available=true
+          else
+            available=false
+            echo "::warning::Prebuilt GhosttyKit download failed; enabling the Zig-backed fallback"
+          fi
+          end=$(date +%s)
+          echo "available=$available" >> "$GITHUB_OUTPUT"
+          echo "seconds=$(( end - start ))" >> "$GITHUB_OUTPUT"
+
+      - name: Install zig for GhosttyKit fallback
+        if: ${{ steps.ghosttykit_prebuilt.outputs.available != 'true' }}
+        id: zig_fallback
+        run: |
+          set -euo pipefail
+          start=$(date +%s)
+          ./scripts/install-zig-ci.sh
+          end=$(date +%s)
+          seconds="$(awk -v start="$start" -v end="$end" 'BEGIN { print end - start }')"
+          echo "seconds=$seconds" >> "$GITHUB_OUTPUT"
+
+      - name: Build fallback GhosttyKit
+        if: ${{ steps.ghosttykit_prebuilt.outputs.available != 'true' }}
+        id: ghosttykit_fallback
+        env:
+          # The bounded download step already proved the prebuilt path failed;
+          # do not let ensure-ghosttykit retry that URL with its long defaults.
+          CMUX_GHOSTTYKIT_NO_PREBUILT: "1"
+        run: |
+          set -euo pipefail
+          start=$(date +%s)
+          ./scripts/ensure-ghosttykit.sh
+          end=$(date +%s)
+          echo "seconds=$(( end - start ))" >> "$GITHUB_OUTPUT"
+
+      - name: Verify provisioned GhosttyKit
+        run: test -d GhosttyKit.xcframework
+
+      - name: Start SPM cache restore timer
+        if: ${{ inputs.platform == 'macos' && steps.cache_meta.outputs.spm_cache_enabled == 'true' }}
+        id: spm_restore_start
+        run: echo "epoch=$(date +%s)" >> "$GITHUB_OUTPUT"
+
+      - name: Restore SPM SourcePackages cache
+        if: ${{ inputs.platform == 'macos' && steps.cache_meta.outputs.spm_cache_enabled == 'true' }}
+        id: restore_spm
+        continue-on-error: true
+        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: .ci-source-packages
+          key: ${{ steps.cache_meta.outputs.spm_key }}
+          restore-keys: ${{ steps.cache_meta.outputs.spm_source_prefix }}
+
+      - name: Finish SPM cache restore
+        if: ${{ always() && inputs.platform == 'macos' }}
+        id: spm_restore
+        env:
+          CACHE_ENABLED: ${{ steps.cache_meta.outputs.spm_cache_enabled }}
+          CACHE_SOURCE_PREFIX: ${{ steps.cache_meta.outputs.spm_source_prefix }}
+          START_EPOCH: ${{ steps.spm_restore_start.outputs.epoch }}
+          CACHE_OUTCOME: ${{ steps.restore_spm.outcome }}
+          CACHE_HIT: ${{ steps.restore_spm.outputs.cache-hit }}
+          CACHE_MATCHED_KEY: ${{ steps.restore_spm.outputs.cache-matched-key }}
+        run: |
+          set -euo pipefail
+          now=$(date +%s)
+          start=${START_EPOCH:-0}
+          if ! [[ "$start" =~ ^[0-9]+$ ]] || [ "$start" -eq 0 ]; then
+            start=$now
+          fi
+          cache_hit=${CACHE_HIT:-false}
+          matched_key=${CACHE_MATCHED_KEY:-}
+          exact_hit=false
+          if [ "${CACHE_ENABLED:-false}" != "true" ]; then
+            status=disabled_missing_resolved
+            rm -rf "$GITHUB_WORKSPACE/.ci-source-packages"
+          elif [ "${CACHE_OUTCOME:-failure}" != "success" ]; then
+            status=restore_error
+            rm -rf "$GITHUB_WORKSPACE/.ci-source-packages"
+          elif [ "$cache_hit" = "true" ] || { [ -n "${CACHE_SOURCE_PREFIX:-}" ] && [[ "$matched_key" == "$CACHE_SOURCE_PREFIX"* ]]; }; then
+            status=exact_hit
+            exact_hit=true
+          elif [ -n "$matched_key" ]; then
+            status=fallback_hit
+          else
+            status=miss
+          fi
+          mkdir -p "$GITHUB_WORKSPACE/.ci-source-packages"
+          {
+            echo "seconds=$(( now - start ))"
+            echo "status=$status"
+            echo "exact_hit=$exact_hit"
+            echo "matched_key=$matched_key"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Sanitize restored SPM cache
+        if: ${{ inputs.platform == 'macos' }}
+        id: spm_sanitize
+        env:
+          CACHE_ENABLED: ${{ steps.cache_meta.outputs.spm_cache_enabled }}
+          CACHE_STATUS: ${{ steps.spm_restore.outputs.status }}
+        run: |
+          set -euo pipefail
+          status=${CACHE_STATUS:-restore_error}
+          discarded=false
+          sanitizer=scripts/ci/sanitize-xcode-source-packages-cache.py
+          if [ "${CACHE_ENABLED:-false}" != "true" ]; then
+            status=disabled_missing_resolved
+          elif [ "$status" = "exact_hit" ]; then
+            # The exact key is tied to Package.resolved, Xcode, source SHA, and
+            # the fixed Blacksmith checkout path. Preserve its workspace state
+            # so Xcode can reuse the resolved package graph; a bad state still
+            # trips the guarded cold retry below.
+            echo "preserving exact-hit SourcePackages workspace state"
+          elif [ ! -f "$sanitizer" ]; then
+            echo "::warning::$sanitizer absent in source ref; discarding the restored SPM cache"
+            status=sanitize_error
+            discarded=true
+          elif ! python3 "$sanitizer" .ci-source-packages; then
+            echo "::warning::SPM cache sanitize failed; discarding it and building cold"
+            status=sanitize_error
+            discarded=true
+          fi
+          if [ "$discarded" = "true" ]; then
+            rm -rf "$GITHUB_WORKSPACE/.ci-source-packages"
+            mkdir -p "$GITHUB_WORKSPACE/.ci-source-packages"
+          fi
+          echo "status=$status" >> "$GITHUB_OUTPUT"
+          echo "discarded=$discarded" >> "$GITHUB_OUTPUT"
+
+      - name: Start DerivedData cache restore timer
+        if: ${{ inputs.platform == 'macos' }}
+        id: derived_data_restore_start
+        run: echo "epoch=$(date +%s)" >> "$GITHUB_OUTPUT"
+
+      - name: Restore DerivedData cache
+        if: ${{ inputs.platform == 'macos' }}
+        id: restore_derived_data
+        continue-on-error: true
+        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          # Keep the build database, compiler outputs, and Debug products that
+          # Xcode needs for a true incremental build. Archives, indexes, logs,
+          # SourcePackages, and every non-Debug product remain excluded.
+          path: |
+            .ci-reload-derived-data/Build/Intermediates.noindex
+            .ci-reload-derived-data/Build/Products/Debug
+            .ci-reload-derived-data/ModuleCache.noindex
+            .ci-reload-derived-data/SDKStatCaches.noindex
+          key: ${{ steps.cache_meta.outputs.derived_data_key }}
+          restore-keys: |
+            ${{ steps.cache_meta.outputs.derived_data_source_prefix }}
+            ${{ steps.cache_meta.outputs.derived_data_branch_prefix }}
+            ${{ steps.cache_meta.outputs.derived_data_main_prefix }}
+
+      - name: Finish DerivedData cache restore
+        if: ${{ always() && inputs.platform == 'macos' }}
+        id: derived_data_restore
+        env:
+          CACHE_SOURCE_PREFIX: ${{ steps.cache_meta.outputs.derived_data_source_prefix }}
+          START_EPOCH: ${{ steps.derived_data_restore_start.outputs.epoch }}
+          CACHE_OUTCOME: ${{ steps.restore_derived_data.outcome }}
+          CACHE_HIT: ${{ steps.restore_derived_data.outputs.cache-hit }}
+          CACHE_MATCHED_KEY: ${{ steps.restore_derived_data.outputs.cache-matched-key }}
+        run: |
+          set -euo pipefail
+          now=$(date +%s)
+          start=${START_EPOCH:-0}
+          if ! [[ "$start" =~ ^[0-9]+$ ]] || [ "$start" -eq 0 ]; then
+            start=$now
+          fi
+          cache_hit=${CACHE_HIT:-false}
+          matched_key=${CACHE_MATCHED_KEY:-}
+          exact_hit=false
+          if [ "${CACHE_OUTCOME:-failure}" != "success" ]; then
+            status=restore_error
+            rm -rf "$GITHUB_WORKSPACE/.ci-reload-derived-data"
+          elif [ "$cache_hit" = "true" ] || { [ -n "${CACHE_SOURCE_PREFIX:-}" ] && [[ "$matched_key" == "$CACHE_SOURCE_PREFIX"* ]]; }; then
+            status=exact_hit
+            exact_hit=true
+          elif [ -n "$matched_key" ]; then
+            status=fallback_hit
+          else
+            status=miss
+          fi
+          mkdir -p "$GITHUB_WORKSPACE/.ci-reload-derived-data"
+          {
+            echo "seconds=$(( now - start ))"
+            echo "status=$status"
+            echo "exact_hit=$exact_hit"
+            echo "matched_key=$matched_key"
+          } >> "$GITHUB_OUTPUT"
+
+      # actions/checkout gives every tracked source a fresh mtime, newer than
+      # restored compiler outputs. Xcode then recompiles an exact cache hit as
+      # if it were cold. Derive a stable, pre-2020 mtime from each Git blob id:
+      # unchanged files stay unchanged across runs, while changed blobs receive
+      # a different file signature and are still invalidated correctly.
+      - name: Normalize tracked source mtimes for Xcode
+        if: ${{ inputs.platform == 'macos' }}
+        run: |
+          set -euo pipefail
+          python3 - <<'PY'
+          import os
+          import subprocess
+
+          # 2001-01-01 plus at most fifteen years keeps source mtimes safely
+          # behind newly generated outputs while preserving nanosecond entropy.
+          base_seconds = 978_307_200
+          span_seconds = 15 * 365 * 24 * 60 * 60
+          records = subprocess.check_output(
+              ["git", "ls-files", "--recurse-submodules", "--stage", "-z"]
+          ).split(b"\0")
+          normalized = 0
+          for record in records:
+              if not record:
+                  continue
+              metadata, raw_path = record.split(b"\t", 1)
+              mode, object_id, stage = metadata.split()
+              if mode == b"160000" or stage != b"0":
+                  continue
+              path = os.fsdecode(raw_path)
+              if not os.path.lexists(path):
+                  continue
+              digest = object_id.decode("ascii")
+              seconds = base_seconds + int(digest[:12], 16) % span_seconds
+              nanoseconds = int(digest[12:20], 16) % 1_000_000_000
+              mtime_ns = seconds * 1_000_000_000 + nanoseconds
+              os.utime(path, ns=(mtime_ns, mtime_ns), follow_symlinks=False)
+              normalized += 1
+          print(f"normalized {normalized} Git-tracked source mtimes")
+          PY

      - name: Mark deps-ready
        id: t1
@@ -95,12 +419,64 @@ jobs:
      - name: Build tagged macOS app
        if: ${{ inputs.platform == 'macos' }}
        id: build_macos
+        env:
+          BUILD_TAG: ${{ inputs.tag }}
+          CMUX_GHOSTTYKIT_PREPROVISIONED: "1"
+          CMUX_SOURCE_PACKAGES_DIR: ${{ github.workspace }}/.ci-source-packages
+          SPM_CACHE_STATUS: ${{ steps.spm_sanitize.outputs.status }}
+          DERIVED_DATA_CACHE_STATUS: ${{ steps.derived_data_restore.outputs.status }}
        run: |
          set -euo pipefail
          # Per-run log path: /tmp/reload.log collides across tenants on the
          # multi-tenant self-hosted fleet Macs (tee: Permission denied).
          log="$RUNNER_TEMP/reload.log"
-          ./scripts/reload.sh --tag "${{ inputs.tag }}" --swift-frontend-workaround 2>&1 | tee "$log"
+          derived_data="$GITHUB_WORKSPACE/.ci-reload-derived-data"
+          echo "cache_retry=false" >> "$GITHUB_OUTPUT"
+
+          run_reload() {
+            if [ "$SPM_CACHE_STATUS" = "exact_hit" ]; then
+              # The exact Package.resolved/state pair is safe to reuse. If it
+              # is stale or corrupt, the caller clears both caches and changes
+              # this marker before retrying from a normal cold resolve.
+              export CMUX_DISABLE_AUTOMATIC_PACKAGE_RESOLUTION=1
+            else
+              export CMUX_DISABLE_AUTOMATIC_PACKAGE_RESOLUTION=0
+            fi
+            ./scripts/reload.sh \
+              --tag "$BUILD_TAG" \
+              --derived-data "$derived_data" \
+              --swift-frontend-workaround
+          }
+
+          set +e
+          run_reload 2>&1 | tee "$log"
+          build_status=${PIPESTATUS[0]}
+          set -e
+
+          # A successfully restored but stale/corrupt cache must cost at most
+          # one failed attempt: clear both cache roots and retry once from cold.
+          if [ "$build_status" -ne 0 ] && {
+            [ "$SPM_CACHE_STATUS" = "exact_hit" ] ||
+            [ "$SPM_CACHE_STATUS" = "fallback_hit" ] ||
+            [ "$DERIVED_DATA_CACHE_STATUS" = "exact_hit" ] ||
+            [ "$DERIVED_DATA_CACHE_STATUS" = "fallback_hit" ];
+          }; then
+            echo "::warning::Cached macOS build failed; clearing SPM and DerivedData caches and retrying cold"
+            rm -rf "$CMUX_SOURCE_PACKAGES_DIR" "$derived_data"
+            mkdir -p "$CMUX_SOURCE_PACKAGES_DIR" "$derived_data"
+            SPM_CACHE_STATUS=miss
+            DERIVED_DATA_CACHE_STATUS=miss
+            : > "$log"
+            set +e
+            run_reload 2>&1 | tee "$log"
+            build_status=${PIPESTATUS[0]}
+            set -e
+            echo "cache_retry=true" >> "$GITHUB_OUTPUT"
+          fi
+          if [ "$build_status" -ne 0 ]; then
+            exit "$build_status"
+          fi
+
          app_path="$(awk '/^App path:/{getline; sub(/^  /,""); print; exit}' "$log")"
          [ -n "$app_path" ] && [ -d "$app_path" ] || { echo "could not locate built app" >&2; exit 1; }
          echo "app_path=$app_path" >> "$GITHUB_OUTPUT"
@@ -133,6 +509,7 @@ jobs:
        id: build_ios
        env:
          BUILD_TAG: ${{ inputs.tag }}
+          CMUX_XCODEBUILD_NONINTERACTIVE_HEARTBEAT_SECONDS: "60"
        run: |
          set -euo pipefail
          slug="$(printf '%s' "$BUILD_TAG" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9-' '-' | sed 's/-\{2,\}/-/g; s/^-//; s/-$//')"
@@ -144,6 +521,16 @@ jobs:
          api_base_url="${CMUX_IOS_API_BASE_URL:-${CMUX_DEV_API_BASE_URL:-https://cmux-staging.vercel.app}}"
          iroh_broker_base_url="${CMUX_IOS_IROH_BROKER_BASE_URL:-${CMUX_IROH_BROKER_BASE_URL:-https://cmux-staging.vercel.app}}"

+          # Match ios/scripts/reload.sh --swift-frontend-workaround. Optimized
+          # Debug builds need this Xcode 26 codegen path disabled on every lane.
+          # shellcheck disable=SC2016 # Xcode expands $(inherited), not this shell.
+          swift_workaround_args=(
+            SWIFT_ENABLE_BATCH_MODE=NO
+            DEBUG_INFORMATION_FORMAT=
+            GCC_GENERATE_DEBUGGING_SYMBOLS=NO
+            'OTHER_SWIFT_FLAGS=$(inherited) -Xllvm -aarch64-enable-global-isel-at-O=-1'
+          )
+
          # Register the iOS platform if the runner only has macOS provisioned.
          ios_ready() { xcrun simctl runtime list 2>/dev/null | grep -qiE "iOS [0-9].*\(Ready\)"; }
          if ! ios_ready; then
@@ -152,12 +539,12 @@ jobs:
            ios_ready || { echo "iOS platform still not registered; archive would fail" >&2; exit 1; }
          fi

-          ./scripts/ensure-ghosttykit.sh
+          test -d GhosttyKit.xcframework
          out="$GITHUB_WORKSPACE/build"
          mkdir -p "$out"
          archive="$out/cmux-ios-$slug.xcarchive"
          rm -rf "$archive"
-          xcodebuild archive \
+          scripts/ci/xcodebuild_noninteractive.py xcodebuild archive \
            -workspace ios/cmux.xcworkspace \
            -scheme cmux-ios \
            -configuration Debug \
@@ -176,18 +563,22 @@ jobs:
            CODE_SIGN_IDENTITY="" \
            SWIFT_OPTIMIZATION_LEVEL=-O \
            SWIFT_COMPILATION_MODE=wholemodule \
-            GCC_OPTIMIZATION_LEVEL=s
+            GCC_OPTIMIZATION_LEVEL=s \
+            "${swift_workaround_args[@]}"
          [ -d "$archive" ] || { echo "archive not produced: $archive" >&2; exit 1; }

          # Keep Blacksmith device reloads equivalent to the fleet path: one
          # build supplies both the unsigned phone archive and the exact same
          # source revision for an isolated Simulator verification.
-          xcodebuild build \
+          # The prebuilt GhosttyKit simulator slice is arm64-only.
+          scripts/ci/xcodebuild_noninteractive.py xcodebuild build \
            -workspace ios/cmux.xcworkspace \
            -scheme cmux-ios \
            -configuration Debug \
            -destination 'generic/platform=iOS Simulator' \
            -derivedDataPath "$RUNNER_TEMP/cmux-ios-dd" \
+            ARCHS=arm64 \
+            ONLY_ACTIVE_ARCH=YES \
            PRODUCT_BUNDLE_IDENTIFIER="$bundle_id" \
            PRODUCT_DISPLAY_NAME="$display_name" \
            CMUX_GIT_SHA="$(git rev-parse --short HEAD)" \
@@ -200,7 +591,8 @@ jobs:
            CODE_SIGN_IDENTITY="" \
            SWIFT_OPTIMIZATION_LEVEL=-O \
            SWIFT_COMPILATION_MODE=wholemodule \
-            GCC_OPTIMIZATION_LEVEL=s
+            GCC_OPTIMIZATION_LEVEL=s \
+            "${swift_workaround_args[@]}"
          sim_app="$RUNNER_TEMP/cmux-ios-dd/Build/Products/Debug-iphonesimulator/cmux.app"
          [ -d "$sim_app" ] || { echo "simulator app not produced: $sim_app" >&2; exit 1; }

@@ -212,36 +604,254 @@ jobs:
          ditto "$sim_app" "$pkg/simulator/cmux.app"
          ditto -c -k "$pkg" "$GITHUB_WORKSPACE/artifact/archive.zip"

+      - name: Mark build-ready
+        id: t2
+        run: echo "epoch=$(date +%s)" >> "$GITHUB_OUTPUT"
+
+      - name: Trim tag-specific products before DerivedData cache save
+        if: ${{ success() && inputs.platform == 'macos' }}
+        run: |
+          set -euo pipefail
+          products="$GITHUB_WORKSPACE/.ci-reload-derived-data/Build/Products/Debug"
+          [ -d "$products" ] || exit 0
+          # reload.sh stages the requested tagged app beside the stable base
+          # product. Keep only the base product in the cache; otherwise every
+          # tag accumulates another app bundle under the branch/SHA key.
+          for product in "$products"/cmux\ DEV\ *.app "$products"/.cmux\ DEV\ *.reload-*.app; do
+            [ -d "$product" ] || continue
+            [ "$(basename "$product")" = "cmux DEV.app" ] || rm -rf -- "$product"
+          done
+
+      - name: Start SPM cache save timer
+        if: ${{ success() && inputs.platform == 'macos' && steps.cache_meta.outputs.spm_cache_enabled == 'true' && (steps.spm_restore.outputs.exact_hit != 'true' || steps.spm_sanitize.outputs.discarded == 'true' || steps.build_macos.outputs.cache_retry == 'true') }}
+        id: spm_save_start
+        run: echo "epoch=$(date +%s)" >> "$GITHUB_OUTPUT"
+
+      - name: Save SPM SourcePackages cache
+        if: ${{ success() && inputs.platform == 'macos' && steps.cache_meta.outputs.spm_cache_enabled == 'true' && (steps.spm_restore.outputs.exact_hit != 'true' || steps.spm_sanitize.outputs.discarded == 'true' || steps.build_macos.outputs.cache_retry == 'true') }}
+        id: save_spm
+        continue-on-error: true
+        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: .ci-source-packages
+          key: ${{ steps.cache_meta.outputs.spm_key }}
+
+      - name: Finish SPM cache save
+        if: ${{ always() && inputs.platform == 'macos' }}
+        id: spm_save
+        env:
+          CACHE_ENABLED: ${{ steps.cache_meta.outputs.spm_cache_enabled }}
+          START_EPOCH: ${{ steps.spm_save_start.outputs.epoch }}
+          SAVE_OUTCOME: ${{ steps.save_spm.outcome }}
+          RESTORE_EXACT_HIT: ${{ steps.spm_restore.outputs.exact_hit }}
+        run: |
+          set -euo pipefail
+          now=$(date +%s)
+          start=${START_EPOCH:-0}
+          if [[ "$start" =~ ^[0-9]+$ ]] && [ "$start" -gt 0 ]; then
+            seconds=$(( now - start ))
+          else
+            seconds=0
+          fi
+          case "${SAVE_OUTCOME:-skipped}" in
+            success) status=saved ;;
+            failure) status=save_error ;;
+            *)
+              if [ "${CACHE_ENABLED:-false}" != "true" ]; then
+                status=skipped_disabled
+              elif [ "${RESTORE_EXACT_HIT:-false}" = "true" ]; then
+                status=skipped_exact_hit
+              else
+                status=skipped
+              fi
+              ;;
+          esac
+          echo "seconds=$seconds" >> "$GITHUB_OUTPUT"
+          echo "status=$status" >> "$GITHUB_OUTPUT"
+
+      - name: Start DerivedData cache save timer
+        if: ${{ success() && inputs.platform == 'macos' && (steps.derived_data_restore.outputs.exact_hit != 'true' || steps.build_macos.outputs.cache_retry == 'true') }}
+        id: derived_data_save_start
+        run: echo "epoch=$(date +%s)" >> "$GITHUB_OUTPUT"
+
+      - name: Save DerivedData cache
+        if: ${{ success() && inputs.platform == 'macos' && (steps.derived_data_restore.outputs.exact_hit != 'true' || steps.build_macos.outputs.cache_retry == 'true') }}
+        id: save_derived_data
+        continue-on-error: true
+        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          # Match the bounded restore set; only Debug products are included.
+          path: |
+            .ci-reload-derived-data/Build/Intermediates.noindex
+            .ci-reload-derived-data/Build/Products/Debug
+            .ci-reload-derived-data/ModuleCache.noindex
+            .ci-reload-derived-data/SDKStatCaches.noindex
+          key: ${{ steps.cache_meta.outputs.derived_data_key }}
+
+      - name: Finish DerivedData cache save
+        if: ${{ always() && inputs.platform == 'macos' }}
+        id: derived_data_save
+        env:
+          START_EPOCH: ${{ steps.derived_data_save_start.outputs.epoch }}
+          SAVE_OUTCOME: ${{ steps.save_derived_data.outcome }}
+          RESTORE_EXACT_HIT: ${{ steps.derived_data_restore.outputs.exact_hit }}
+        run: |
+          set -euo pipefail
+          now=$(date +%s)
+          start=${START_EPOCH:-0}
+          if [[ "$start" =~ ^[0-9]+$ ]] && [ "$start" -gt 0 ]; then
+            seconds=$(( now - start ))
+          else
+            seconds=0
+          fi
+          case "${SAVE_OUTCOME:-skipped}" in
+            success) status=saved ;;
+            failure) status=save_error ;;
+            *)
+              if [ "${RESTORE_EXACT_HIT:-false}" = "true" ]; then
+                status=skipped_exact_hit
+              else
+                status=skipped
+              fi
+              ;;
+          esac
+          echo "seconds=$seconds" >> "$GITHUB_OUTPUT"
+          echo "status=$status" >> "$GITHUB_OUTPUT"
+
      - name: Write timings.json
        if: ${{ always() }}
+        env:
+          TIMING_TAG: ${{ inputs.tag }}
+          TIMING_PLATFORM: ${{ inputs.platform }}
+          TIMING_RUNNER: ${{ inputs.runner }}
+          TIMING_REF: ${{ inputs.ref || github.ref }}
+          TIMING_T0: ${{ steps.t0.outputs.epoch || '0' }}
+          TIMING_T1: ${{ steps.t1.outputs.epoch || '0' }}
+          TIMING_T2: ${{ steps.t2.outputs.epoch || '0' }}
+          GHOSTTYKIT_PREBUILT: ${{ steps.ghosttykit_prebuilt.outputs.available || 'false' }}
+          GHOSTTYKIT_DOWNLOAD_SECONDS: ${{ steps.ghosttykit_prebuilt.outputs.seconds || '0' }}
+          ZIG_INSTALL_SECONDS: ${{ steps.zig_fallback.outputs.seconds || '0' }}
+          GHOSTTYKIT_FALLBACK_SECONDS: ${{ steps.ghosttykit_fallback.outputs.seconds || '0' }}
+          CACHE_XCODE_KEY: ${{ steps.cache_meta.outputs.xcode_key }}
+          CACHE_BRANCH_KEY: ${{ steps.cache_meta.outputs.branch_key }}
+          CACHE_WORKSPACE_KEY: ${{ steps.cache_meta.outputs.workspace_key }}
+          CACHE_RUNNER_KEY: ${{ steps.cache_meta.outputs.runner_key }}
+          SPM_CACHE_PRIMARY_KEY: ${{ steps.cache_meta.outputs.spm_key }}
+          SPM_CACHE_STATUS: ${{ steps.spm_sanitize.outputs.status || 'not_applicable' }}
+          SPM_CACHE_EXACT_HIT: ${{ steps.spm_sanitize.outputs.status == 'exact_hit' }}
+          SPM_CACHE_MATCHED_KEY: ${{ steps.spm_restore.outputs.matched_key }}
+          SPM_CACHE_RESTORE_OUTCOME: ${{ steps.restore_spm.outcome || 'not_applicable' }}
+          SPM_CACHE_RESTORE_SECONDS: ${{ steps.spm_restore.outputs.seconds || '0' }}
+          SPM_CACHE_SAVE_STATUS: ${{ steps.spm_save.outputs.status || 'not_applicable' }}
+          SPM_CACHE_SAVE_SECONDS: ${{ steps.spm_save.outputs.seconds || '0' }}
+          DERIVED_DATA_CACHE_PRIMARY_KEY: ${{ steps.cache_meta.outputs.derived_data_key }}
+          DERIVED_DATA_CACHE_STATUS: ${{ steps.derived_data_restore.outputs.status || 'not_applicable' }}
+          DERIVED_DATA_CACHE_EXACT_HIT: ${{ steps.derived_data_restore.outputs.exact_hit || 'false' }}
+          DERIVED_DATA_CACHE_MATCHED_KEY: ${{ steps.derived_data_restore.outputs.matched_key }}
+          DERIVED_DATA_CACHE_RESTORE_OUTCOME: ${{ steps.restore_derived_data.outcome || 'not_applicable' }}
+          DERIVED_DATA_CACHE_RESTORE_SECONDS: ${{ steps.derived_data_restore.outputs.seconds || '0' }}
+          DERIVED_DATA_CACHE_SAVE_STATUS: ${{ steps.derived_data_save.outputs.status || 'not_applicable' }}
+          DERIVED_DATA_CACHE_SAVE_SECONDS: ${{ steps.derived_data_save.outputs.seconds || '0' }}
+          CACHE_COLD_RETRY: ${{ steps.build_macos.outputs.cache_retry || 'false' }}
        run: |
          set -euo pipefail
          mkdir -p artifact
          now=$(date +%s)
-          t0=${{ steps.t0.outputs.epoch }}
-          t1=${{ steps.t1.outputs.epoch || 0 }}
-          cat > artifact/timings.json <<JSON
-          {
-            "tag": "${{ inputs.tag }}",
-            "platform": "${{ inputs.platform }}",
-            "runner": "${{ inputs.runner }}",
-            "ref": "${{ inputs.ref }}",
-            "deps_seconds": $(( t1 > t0 ? t1 - t0 : 0 )),
-            "build_seconds": $(( t1 > 0 ? now - t1 : 0 )),
-            "post_checkout_total_seconds": $(( now - t0 ))
+          export TIMING_NOW=$now
+          python3 - <<'PY' > artifact/timings.json
+          import json
+          import os
+          import sys
+
+          def integer(name: str) -> int:
+              try:
+                  return int(os.environ.get(name, "0"))
+              except ValueError:
+                  return 0
+
+          def boolean(name: str) -> bool:
+              return os.environ.get(name, "false").lower() == "true"
+
+          t0 = integer("TIMING_T0")
+          t1 = integer("TIMING_T1")
+          t2 = integer("TIMING_T2")
+          now = integer("TIMING_NOW")
+          timing_clock_valid = t0 > 0
+          spm_status = os.environ["SPM_CACHE_STATUS"]
+          derived_status = os.environ["DERIVED_DATA_CACHE_STATUS"]
+          payload = {
+              "tag": os.environ["TIMING_TAG"],
+              "platform": os.environ["TIMING_PLATFORM"],
+              "runner": os.environ["TIMING_RUNNER"],
+              "ref": os.environ["TIMING_REF"],
+              "deps_seconds": t1 - t0 if timing_clock_valid and t1 > t0 else 0,
+              "build_seconds": t2 - t1 if timing_clock_valid and t1 > t0 and t2 > t1 else 0,
+              "post_checkout_total_seconds": now - t0 if timing_clock_valid and now > t0 else 0,
+              "ghosttykit_prebuilt": boolean("GHOSTTYKIT_PREBUILT"),
+              "ghosttykit_download_seconds": integer("GHOSTTYKIT_DOWNLOAD_SECONDS"),
+              "zig_install_seconds": integer("ZIG_INSTALL_SECONDS"),
+              "ghosttykit_fallback_seconds": integer("GHOSTTYKIT_FALLBACK_SECONDS"),
+              "cache_xcode_key": os.environ.get("CACHE_XCODE_KEY", ""),
+              "cache_branch_key": os.environ.get("CACHE_BRANCH_KEY", ""),
+              "cache_workspace_key": os.environ.get("CACHE_WORKSPACE_KEY", ""),
+              "cache_runner_key": os.environ.get("CACHE_RUNNER_KEY", ""),
+              "spm_cache_primary_key": os.environ.get("SPM_CACHE_PRIMARY_KEY", ""),
+              "spm_cache_status": spm_status,
+              "spm_cache_hit": spm_status in {"exact_hit", "fallback_hit"},
+              "spm_cache_exact_hit": boolean("SPM_CACHE_EXACT_HIT"),
+              "spm_cache_matched_key": os.environ.get("SPM_CACHE_MATCHED_KEY", ""),
+              "spm_cache_restore_outcome": os.environ["SPM_CACHE_RESTORE_OUTCOME"],
+              "spm_cache_restore_seconds": integer("SPM_CACHE_RESTORE_SECONDS"),
+              "spm_cache_save_status": os.environ["SPM_CACHE_SAVE_STATUS"],
+              "spm_cache_save_seconds": integer("SPM_CACHE_SAVE_SECONDS"),
+              "derived_data_cache_primary_key": os.environ.get("DERIVED_DATA_CACHE_PRIMARY_KEY", ""),
+              "derived_data_cache_status": derived_status,
+              "derived_data_cache_hit": derived_status in {"exact_hit", "fallback_hit"},
+              "derived_data_cache_exact_hit": boolean("DERIVED_DATA_CACHE_EXACT_HIT"),
+              "derived_data_cache_matched_key": os.environ.get("DERIVED_DATA_CACHE_MATCHED_KEY", ""),
+              "derived_data_cache_restore_outcome": os.environ["DERIVED_DATA_CACHE_RESTORE_OUTCOME"],
+              "derived_data_cache_restore_seconds": integer("DERIVED_DATA_CACHE_RESTORE_SECONDS"),
+              "derived_data_cache_save_status": os.environ["DERIVED_DATA_CACHE_SAVE_STATUS"],
+              "derived_data_cache_save_seconds": integer("DERIVED_DATA_CACHE_SAVE_SECONDS"),
+              "cache_cold_retry": boolean("CACHE_COLD_RETRY"),
          }
-          JSON
+          json.dump(payload, fp=sys.stdout, indent=2, sort_keys=True)
+          print()
+          PY
+          t0=${TIMING_T0:-0}
+          t1=${TIMING_T1:-0}
+          t2=${TIMING_T2:-0}
+          if (( t0 > 0 && t1 > t0 )); then
+            deps_seconds=$(( t1 - t0 ))
+          else
+            deps_seconds=0
+          fi
+          if (( t0 > 0 && t1 > t0 && t2 > t1 )); then
+            build_seconds=$(( t2 - t1 ))
+          else
+            build_seconds=0
+          fi
+          if (( t0 > 0 && now > t0 )); then
+            total_seconds=$(( now - t0 ))
+          else
+            total_seconds=0
+          fi
          {
            echo "### reload-build timings"
            echo ""
-            echo "- runner: \`${{ inputs.runner }}\`"
-            echo "- platform: \`${{ inputs.platform }}\`"
-            echo "- deps: $(( t1 > t0 ? t1 - t0 : 0 ))s"
-            echo "- build: $(( t1 > 0 ? now - t1 : 0 ))s"
-            echo "- post-checkout total: $(( now - t0 ))s"
+            echo "- runner: \`$TIMING_RUNNER\`"
+            echo "- platform: \`$TIMING_PLATFORM\`"
+            echo "- deps: ${deps_seconds}s"
+            echo "- build: ${build_seconds}s"
+            echo "- SPM cache: ${SPM_CACHE_STATUS} (restore ${SPM_CACHE_RESTORE_SECONDS}s, save ${SPM_CACHE_SAVE_SECONDS}s / ${SPM_CACHE_SAVE_STATUS})"
+            echo "- DerivedData cache: ${DERIVED_DATA_CACHE_STATUS} (restore ${DERIVED_DATA_CACHE_RESTORE_SECONDS}s, save ${DERIVED_DATA_CACHE_SAVE_SECONDS}s / ${DERIVED_DATA_CACHE_SAVE_STATUS})"
+            echo "- cache-triggered cold retry: ${CACHE_COLD_RETRY}"
+            echo "- GhosttyKit prebuilt: ${GHOSTTYKIT_PREBUILT} (download ${GHOSTTYKIT_DOWNLOAD_SECONDS}s, Zig fallback ${ZIG_INSTALL_SECONDS}s)"
+            echo "- post-checkout total: ${total_seconds}s"
          } >> "$GITHUB_STEP_SUMMARY"

      - name: Upload artifact
+        if: ${{ always() }}
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: reload-${{ inputs.tag }}-${{ inputs.platform }}
@@ -502,11 +502,10 @@ jobs:
          # one xcodebuild invocation; a filter can select a suite living in either.
          xctest = [int(value) for value in re.findall(r"Executed\s+(\d+)\s+tests?\b", text)]
          swift_testing = [int(value) for value in re.findall(r"Test run with\s+(\d+)\s+tests?\b", text)]
-          counts = []
-          if xctest:
-              counts.append(xctest[-1])
-          if swift_testing:
-              counts.append(swift_testing[-1])
+          # App-hosted Swift Testing can emit a selected run followed by an
+          # auxiliary zero-test run. Count every summary so the later host
+          # teardown cannot erase a test that actually executed.
+          counts = xctest + swift_testing
          if counts:
              print(max(counts))
          PY
@@ -105,7 +105,9 @@ jobs:

  mobile-core-package:
    needs: detect-ios-changes
-    if: ${{ needs.detect-ios-changes.outputs.should_run == 'true' }}
+    if: >-
+      ${{ needs.detect-ios-changes.outputs.should_run == 'true'
+          && !(github.event_name == 'workflow_dispatch' && inputs.test_filter != '') }}
    runs-on: ${{ (!inputs.runner || inputs.runner == 'auto') && (vars.MACOS_RUNNER_IOS || 'blacksmith-6vcpu-macos-26') || inputs.runner }}
    timeout-minutes: 10
    steps:
@@ -377,6 +379,9 @@ jobs:
            -derivedDataPath "$IOS_DERIVED_DATA"
          )
          if [ -n "${TEST_FILTER:-}" ]; then
+            if [[ "$TEST_FILTER" == cmuxUITests/* ]]; then
+              XCODEBUILD_ARGS+=(-testPlan cmux-ui)
+            fi
            XCODEBUILD_ARGS+=(-only-testing:"$TEST_FILTER")
          else
            # Full UI tests currently exceed the pull-request simulator budget
@@ -393,9 +398,11 @@ jobs:
            # section is not always flushed into the tee'd log, and without the
            # ✘ patterns a real Swift Testing failure exiting 65 was
            # misclassified as a runner cleanup failure and turned the job green.
-            grep -Eq "Test Suite 'Selected tests' passed|Test Suite 'cmuxUITests' passed" "$log_path" &&
-              grep -Eq "Executed [1-9][0-9]* tests, with 0 failures \\(0 unexpected\\)" "$log_path" &&
-              ! grep -Eq "Test Suite '.*' failed|Test Case '.*' failed|Assertion Failure|Failing tests:|with [1-9][0-9]* failures|with [0-9]+ failures \\([1-9][0-9]* unexpected\\)|✘ Test|✘ Suite" "$log_path"
+            (
+              grep -Eq "Executed [1-9][0-9]* tests, with 0 failures \\(0 unexpected\\)" "$log_path" ||
+                grep -Eq "Test run with [1-9][0-9]* tests?( in [1-9][0-9]* suites?)? passed" "$log_path"
+            ) &&
+              ! grep -Eq "Test Suite '.*' failed|Test Case '.*' failed|Assertion Failure|Failing tests:|with [1-9][0-9]* failures|with [0-9]+ failures \\([1-9][0-9]* unexpected\\)|✘ Test|✘ Suite|Test run with [0-9]+ tests?.* failed" "$log_path"
          }
          for attempt in 1 2; do
            LOG_PATH="$IOS_DERIVED_DATA/logs/attempt-${attempt}.log"
@@ -412,7 +419,7 @@ jobs:
            fi
            status="${PIPESTATUS[0]}"
            if selected_tests_passed_despite_xcodebuild_status "$LOG_PATH"; then
-              echo "xcodebuild exited $status after XCTest reported the selected tests passed with zero failures; treating this as a runner cleanup failure."
+              echo "xcodebuild exited $status after the selected tests passed; treating this as a runner cleanup failure."
              exit 0
            fi
            if [ "$attempt" -lt 2 ] && grep -Eq "Timed out while launching application via Xcode|Failed to send signal 19|DTXMessage" "$LOG_PATH"; then
@@ -0,0 +1,62 @@
+name: Testbox broker guard
+
+# The main CI suite is dispatch-only right now, so the trust-boundary guard for
+# the Blacksmith Testbox lane gets its own always-on workflow. It must run on
+# every pull request, with no path filter: a path filter is exactly the thing a
+# change that moves the guard could slip past.
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions: {}
+
+concurrency:
+  group: testbox-broker-guard-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  guard:
+    name: Testbox broker trust boundary
+    runs-on: ${{ vars.LINUX_RUNNER || 'blacksmith-4vcpu-ubuntu-2404' }}
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.12"
+
+      - name: Install guard dependencies
+        run: python3 -m pip install --disable-pip-version-check --no-input PyYAML==6.0.3
+
+      - name: Validate Blacksmith Testbox broker trust boundary
+        run: python3 tests/test_ci_testbox_broker_guard.py
+
+      - name: Validate receipt-bound cleanup ownership check
+        run: ./tests/test_testbox_cleanup_receipt_ref.sh
+
+      - name: Lint the Testbox lane helpers
+        run: shellcheck scripts/blacksmith-bounded-command.sh scripts/blacksmith-cmux-tui-testbox-stage.sh scripts/blacksmith-testbox-cleanup.sh scripts/blacksmith-testbox-keepalive.sh
+
+      - name: Lint the Testbox warmup workflow
+        env:
+          ACTIONLINT_VERSION: "1.7.7"
+          ACTIONLINT_SHA256: "023070a287cd8cccd71515fedc843f1985bf96c436b7effaecce67290e7e0757"
+        run: |
+          set -euo pipefail
+          archive="$RUNNER_TEMP/actionlint.tar.gz"
+          curl -fsSL -o "$archive" \
+            "https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz"
+          echo "${ACTIONLINT_SHA256}  ${archive}" | sha256sum --check --strict
+          tar -xzf "$archive" -C "$RUNNER_TEMP" actionlint
+          "$RUNNER_TEMP/actionlint" \
+            .github/workflows/cmux-tui-testbox-warmup.yml \
+            .github/workflows/testbox-broker-guard.yml
@@ -18,6 +18,7 @@ ios/Config/AppStoreConnect.local.plist
 # Swift Package Manager
 .swiftpm/
 .ci-source-packages/
+.ci-reload-derived-data/

 # GhosttyKit binary (built from ghostty submodule via scripts/setup.sh)
 GhosttyKit.xcframework
@@ -73,3 +74,7 @@ artifacts/

 # tmux verbose debug logs (tmux -v) that land in the cwd
 tmux-*.log
+
+# Remote-only Blacksmith cmux-tui benchmark output
+/testbox-benchmark/
+/.cmux-scratch/
@@ -1,15 +1,13 @@
 {
  "images" : [
    {
-      "filename" : "HermesAgent.svg",
-      "idiom" : "universal"
+      "filename" : "HermesAgent.png",
+      "idiom" : "universal",
+      "scale" : "1x"
    }
  ],
  "info" : {
    "author" : "xcode",
    "version" : 1
-  },
-  "properties" : {
-    "preserves-vector-representation" : true
  }
 }
@@ -1,7 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64">
-  <rect width="64" height="64" rx="14" fill="#101820"/>
-  <path d="M20 47V17h7v12h10V17h7v30h-7V35H27v12h-7Z" fill="#F4F7FA"/>
-  <path d="M15 13h34v6H15z" fill="#4AD7D1"/>
-  <path d="M15 45h34v6H15z" fill="#CFA9FF"/>
-  <path d="M18 13l5-6 5 6M36 13l5-6 5 6M18 51l5 6 5-6M36 51l5 6 5-6" fill="none" stroke="#F4F7FA" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
-</svg>
@@ -17,6 +17,10 @@ A tag gives the app its own name, bundle ID, socket, and derived data path, so i

 Other variants: `reloadp.sh` (Release), `reloads.sh` (Release as isolated "cmux STAGING"), `reload2.sh --tag <tag>` (both).

+## Shared Mac fleet capacity
+
+Every healthy slot in the canonical Mac fleet is general-purpose. Builds, iOS archives, tests, profiling, simulator and UI verification, and any other resource-intensive workload may use any available slot. Do not wait for an AWS-only builder or infer capacity from a workload label. Use the shared lease state and slot-isolated paths supplied by the fleet tooling.
+
 Compile-only check, no launch:

 ```bash
@@ -44,15 +48,33 @@ The helper refuses to run without `CMUX_TAG`, targets `/tmp/cmux-debug-<tag>.soc

 ## iOS builds open on the iPhone by default

-Any work verified by opening the iOS app installs BOTH an isolated-simulator build AND the same build on the user's iPhone. Never stop at simulator-only. Use `ios/scripts/reload-cloud.sh --tag <tag>` (or `ios/scripts/reload.sh --tag <tag>`); with a default iPhone configured (`CMUX_IPHONE_DEVICE_ID` or `~/.config/cmux/iphone-device-id`) the device leg is automatic, and `--device-id <id>` still overrides (`xcrun devicectl list devices`). Auto sign-in and auto-pair apply as usual; launch the app so it is immediately open on the phone. The simulator leg uses the tag's own isolated device `cmux-dev-<slug>`, created on demand; do not target a shared or user-visible simulator.
+Any work verified by opening the iOS app installs BOTH an isolated-simulator build AND the same build on the user's iPhone. Never stop at simulator-only. Use `ios/scripts/reload-cloud.sh --tag <tag>` (or `ios/scripts/reload.sh --tag <tag>`); with a default iPhone configured (`CMUX_IPHONE_DEVICE_ID` or `~/.config/cmux/iphone-device-id`) the device leg is automatic, and `--device-id <id>` still overrides (`xcrun devicectl list devices`). Physical iPhone builds always select the `personal` auth profile. Agent-driven Simulator verification always selects `agent`. Both named profiles live in `~/.secrets/cmuxterm-dev.env`; neither may fall back to the other. The simulator leg uses the tag's own isolated device `cmux-dev-<slug>`, created on demand; do not target a shared or user-visible simulator.
+
+**Every phone install MUST be authenticated before handoff. Installed-but-signed-out is a failed install.** A tagged bundle id can retain an older account, so every authenticated launch clears that tagged session, signs both surfaces into the selected profile, verifies the exact tagged Mac account through `auth status`, then mints the pairing ticket. The iPhone auth gate passes only after the same-account host accepts the phone RPC and emits `mobile.rpc.ready`. `scripts/verify-iphone-auth.sh --tag <tag> [--device-id <id>]` repeats the Mac-account check, relaunches the phone without credentials, and passes only when persisted phone state reconnects. Never install with raw `devicectl device install app`, and never pass `--no-sign-in`/`--no-attach`/`--no-setup` for a dogfood build. The scripts refuse those device paths unless a human sets `CMUX_ALLOW_UNAUTHENTICATED_INSTALL=1`. If setup fails, report the gate reason and exact retry command.

 Every phone build requires the same-tag Mac dev build (the iOS app is unusable without its Mac). The reload scripts build the Mac tag first when it is missing and refuse to ship a phone-only build if that fails; do not bypass this with `CMUX_IOS_SKIP_MAC_BUILD_CHECK` in normal work.

-If the iPhone is unreachable at build time, the reload still completes: the signed build is parked in the offline install queue (`scripts/iphone-install-queue.sh`, persistent under `~/Library/Application Support/cmux-dev/iphone-install-queue`), and a LaunchAgent auto-installs and launches it within seconds of the phone being plugged back in or reappearing on the network, then sends a `cmux notify` with the installed tags. The LaunchAgent is a one-time per-Mac setup: `scripts/install-iphone-queue-agent.sh install`; it runs a stable copy of the queue script, so re-run the installer after changing that script. In the handoff, report the queued state (`scripts/iphone-install-queue.sh list`) instead of treating an unreachable phone as a failure; `drain` retries manually, `clear` abandons a queued build.
+If the iPhone is unreachable at build time, the signed build is parked in `scripts/iphone-install-queue.sh`. Each entry stores the chosen profile, normalized account, and credentials-file path. Drain revalidates that snapshot before device mutation and uses installed stable copies of the launcher and auth helpers, so an old or pruned feature worktree cannot change policy. Install or refresh that control plane with `scripts/install-iphone-queue-agent.sh install`. Report `scripts/iphone-install-queue.sh list` in the handoff; `drain` retries delivery and `clear` abandons a queued build.
+
+## All fleet slots are general-purpose
+
+Agent verification, macOS/iOS builds, archives, tests, profiling, and any other work too resource-intensive for the local Mac use the same Mac fleet. A slot is not a "build slot" or a "verify slot". From the cmuxterm-hq checkout that owns this worktree, every workload leases the canonical `~/.config/macfleet/hosts.json` inventory and shared `maclease` state.
+
+Before waiting for a builder, run `scripts/macfleet-doctor.sh report --probe` from that hq checkout. If it reports `needs-sync`, run `scripts/macfleet-doctor.sh sync --apply`; it backs up the canonical manifest and merges legacy `hosts-verify.json` entries by SSH endpoint. Refresh the hq checkout before diagnosing capacity. Do not infer capacity from a stale checkout, one pool tag, or a remembered host list.
+
+Agent verification runs on the fleet, not on the local Mac. `scripts/verify-remote.sh` leases a general-purpose slot, pushes the tagged build to the leased Mac, drives it there (per-lease uniquely named simulator for iOS; console launch with debug-socket and computer-use evidence for macOS), and fetches screenshots, recordings, and logs back into the hq `artifacts/verify-remote/` directory:
+
+```bash
+scripts/verify-remote.sh ios --tag <tag>
+scripts/verify-remote.sh mac --tag <tag>
+scripts/verify-remote.sh capacity             # all-purpose slots
+```
+
+Boot a local simulator only when all-purpose `capacity` reports no free slot, and keep at most 3 local sims booted. Scripted XCUITests go through the hosted `test-e2e.yml` lane when appropriate. The physical-iPhone signing/install leg stays local via the install queue; its archive build may use any healthy fleet slot. Verify leases carry a description and TTL, so a crashed agent frees its slot automatically; see `skills/infra/macfleet/references/verify-remote.md` in cmuxterm-hq for the shared-pool contract and host onboarding.

 ## iOS dev auth

-`ios/scripts/reload.sh` and `scripts/mobile-dev-launch.sh` auto-sign-in from `~/.secrets/cmuxterm-dev.env`. If the phone lands on the login screen or the helper reports missing credentials, do not ask the user to authenticate every build. Tell them to run `scripts/setup-team-dev.sh` once; it verifies their Stack login and writes the file chmod 600. Manual fallback: create it with `CMUX_DOGFOOD_STACK_EMAIL=...` and `CMUX_DOGFOOD_STACK_PASSWORD=...`.
+`~/.secrets/cmuxterm-dev.env` is the only mobile dev credential file. `CMUX_DOGFOOD_STACK_*` is the `personal` profile for physical iPhone dogfood. `CMUX_UITEST_STACK_*` is the `agent` profile for isolated Simulators. Run `scripts/setup-team-dev.sh` once to verify and merge the personal pair without deleting the agent pair. Use `scripts/mobile-dev-launch.sh --check-auth-contract --auth-profile personal` or `--auth-profile agent` for a mutation-free preflight. Never substitute one profile when the requested profile is incomplete.

 ## Regression test commits

@@ -109,3 +131,7 @@ Detailed contributor rules live in `skills/`. Use the task-specific skill before
 - `cmux-shared-behavior`: shared action paths for multi-entrypoint behavior and optimistic updates.
 - `cmux-ghostty`: Ghostty submodule and GhosttyKit workflow.
 - `cmux-release`: release, version bump, changelog, pretag guard, release assets.
+- Blacksmith Testbox (remote Linux builds for cmux-tui): warm your own box before any cmux-tui Rust or Zig
+  build, and never compile cmux-tui on the Mac. The skill lives in cmuxterm-hq at
+  `skills/infra/blacksmith-testbox/SKILL.md`; the workflows, `scripts/blacksmith-*.sh`, and the
+  `tests/test_testbox_*` guards stay here. Quickest path: `./scripts/blacksmith-testbox-demo.sh`.
@@ -187,7 +187,7 @@ enum AgentHookNotificationClassifier {
 }

 enum AgentHookNotificationPolicy {
-    static let dedupeEligibleAgents: Set<String> = ["grok", "antigravity"]
+    static let dedupeEligibleAgents: Set<String> = ["grok", "antigravity", "hermes-agent"]

    static func notificationTitle(
        agentName: String,
@@ -9,7 +9,8 @@ enum CLIExecutableLocator {
        if size > 0 {
            var buffer = Array<CChar>(repeating: 0, count: Int(size))
            if _NSGetExecutablePath(&buffer, &size) == 0 {
-                return URL(fileURLWithPath: String(cString: buffer))
+                let pathBytes = buffer.prefix { $0 != 0 }.map { UInt8(bitPattern: $0) }
+                return URL(fileURLWithPath: String(decoding: pathBytes, as: UTF8.self))
                    .resolvingSymlinksInPath()
                    .standardizedFileURL
            }
@@ -73,13 +74,55 @@ enum CLIExecutableLocator {
    }
 }

-enum CLISocketPathSource {
+enum CLISocketPathSource: Equatable, Sendable {
    case explicitFlag
    case environment
    case implicitDefault
 }

-enum CLISocketPathResolver {
+/// The observable result of resolving an implicit CLI socket path.
+struct CLISocketPathResolution: Sendable {
+    let source: CLISocketPathSource
+    let requestedPath: String
+    let candidatePaths: [String]
+    let selectedPath: String?
+
+    /// Whether resolution may proceed to the socket client.
+    ///
+    /// Explicit paths are intentionally not probed here: their identity is
+    /// pinned and the normal client error must report the requested path.
+    var hasLiveSocket: Bool {
+        source != .implicitDefault || selectedPath != nil
+    }
+
+    /// Whether discovery selected a different path than the one the caller expected.
+    var didReroute: Bool {
+        guard let selectedPath else { return false }
+        return !CLISocketPathResolver.pathsMatchForDiagnostics(requestedPath, selectedPath)
+    }
+
+    /// A user-facing diagnostic for an implicit discovery failure.
+    var failureMessage: String {
+        let header = String(
+            localized: "cli.socket.error.discoveryFailed",
+            defaultValue: "No live cmux socket found. Tried:"
+        )
+        let paths = candidatePaths.map { "  \($0)" }.joined(separator: "\n")
+        return paths.isEmpty ? header : "\(header)\n\(paths)"
+    }
+
+    /// A user-facing notice explaining a deterministic implicit reroute.
+    var rerouteNotice: String? {
+        guard let selectedPath, didReroute else { return nil }
+        let template = String(
+            localized: "cli.socket.notice.rerouted",
+            defaultValue: "cmux: default socket %@ is unavailable; using %@."
+        )
+        return String.localizedStringWithFormat(template, requestedPath, selectedPath)
+    }
+}
+
+struct CLISocketPathResolver {
    enum SocketPathEntry {
        case missing
        case socket(ownerUserID: uid_t)
@@ -93,6 +136,36 @@ enum CLISocketPathResolver {
    private static let nightlySocketPath = "/tmp/cmux-nightly.sock"
    private static let stagingSocketPath = "/tmp/cmux-staging.sock"

+    private let environment: [String: String]
+    private let bundleIdentifier: String?
+    private let currentUserID: uid_t
+    private let inspectSocketPathEntry: (String) -> SocketPathEntry
+    private let socketAcceptsConnections: (String) -> Bool
+    private let stateDirectory: URL
+
+    /// Creates a resolver with explicit discovery inputs and filesystem probes.
+    ///
+    /// The inputs are captured once so command dispatch uses one deterministic
+    /// resolution pass and tests can provide an isolated probe implementation.
+    init(
+        environment: [String: String] = ProcessInfo.processInfo.environment,
+        bundleIdentifier: String? = Self.currentAppBundleIdentifier(),
+        currentUserID: uid_t = getuid(),
+        inspectSocketPathEntry: @escaping (String) -> SocketPathEntry = Self.inspectSocketPathEntry,
+        socketAcceptsConnections: @escaping (String) -> Bool = Self.socketAcceptsConnections,
+        fileManager: FileManager = .default,
+        stateDirectory: URL? = nil
+    ) {
+        self.environment = environment
+        self.bundleIdentifier = bundleIdentifier
+        self.currentUserID = currentUserID
+        self.inspectSocketPathEntry = inspectSocketPathEntry
+        self.socketAcceptsConnections = socketAcceptsConnections
+        self.stateDirectory = stateDirectory ?? CmuxStateDirectory.url(
+            homeDirectory: fileManager.homeDirectoryForCurrentUser
+        )
+    }
+
    static func defaultSocketPath(
        bundleIdentifier: String?,
        environment: [String: String] = ProcessInfo.processInfo.environment
@@ -115,6 +188,22 @@ enum CLISocketPathResolver {
        return stablePath ?? legacyDefaultSocketPath
    }

+    private var resolvedStableDefaultSocketPath: String {
+        stateDirectory.appendingPathComponent(Self.stableSocketFileName, isDirectory: false).path
+    }
+
+    private func resolvedDefaultSocketPath() -> String {
+        SocketPathMarkerFiles.defaultSocketPath(
+            bundleIdentifier: bundleIdentifier,
+            environment: environment,
+            isDebugBuild: false,
+            stableSocketPath: resolvedStableDefaultSocketPath,
+            debugSocketPath: Self.fallbackSocketPath,
+            nightlySocketPath: Self.nightlySocketPath,
+            stagingSocketPath: Self.stagingSocketPath
+        )
+    }
+
    private static func userScopedStableSocketPath(currentUserID: uid_t = getuid()) -> String {
        stableSocketDirectoryURL()?
            .appendingPathComponent("cmux-\(currentUserID).sock", isDirectory: false)
@@ -136,83 +225,81 @@ enum CLISocketPathResolver {
        )
    }

-    static func resolve(
+    /// Resolves a socket using one ordered, liveness-aware discovery pass.
+    ///
+    /// Explicit flag and environment paths are deliberately returned verbatim and are
+    /// never probed or rerouted. Implicit discovery only selects a path after a real
+    /// non-blocking connect succeeds; a stale socket file is never handed to the client.
+    func resolve(
        requestedPath: String,
-        source: CLISocketPathSource,
-        environment: [String: String] = ProcessInfo.processInfo.environment,
-        bundleIdentifier: String? = currentAppBundleIdentifier(),
-        currentUserID: uid_t = getuid(),
-        inspectSocketPathEntry: (String) -> SocketPathEntry = inspectSocketPathEntry
-    ) -> String {
+        source: CLISocketPathSource
+    ) -> CLISocketPathResolution {
        guard source == .implicitDefault else {
-            return requestedPath
+            return CLISocketPathResolution(
+                source: source,
+                requestedPath: requestedPath,
+                candidatePaths: [requestedPath],
+                selectedPath: requestedPath
+            )
        }

-        let variant = SocketPathMarkerFiles.variant(bundleIdentifier: bundleIdentifier, environment: environment)
-        if case .stable = variant,
-           canConnect(to: requestedPath, currentUserID: currentUserID, inspectSocketPathEntry: inspectSocketPathEntry) {
-            return requestedPath
+        let candidates = Self.dedupe(candidatePaths(requestedPath: requestedPath))
+        let selectedPath = candidates.first { path in
+            canConnect(to: path)
        }
-
-        let candidates = dedupe(candidatePaths(
+        return CLISocketPathResolution(
+            source: source,
            requestedPath: requestedPath,
-            environment: environment,
-            bundleIdentifier: bundleIdentifier
-        ))
-
-        // Prefer sockets that are currently accepting connections.
-        for path in candidates where canConnect(
-            to: path,
-            currentUserID: currentUserID,
-            inspectSocketPathEntry: inspectSocketPathEntry
-        ) {
-            return path
-        }
-
-        // If the listener is still starting, prefer existing socket files.
-        for path in candidates where isOwnedSocketFile(
-            path,
-            currentUserID: currentUserID,
-            inspectSocketPathEntry: inspectSocketPathEntry
-        ) {
-            return path
-        }
-
-        return candidates.first ?? requestedPath
+            candidatePaths: candidates,
+            selectedPath: selectedPath
+        )
    }

-    private static func candidatePaths(
-        requestedPath: String,
-        environment: [String: String],
-        bundleIdentifier: String?
-    ) -> [String] {
+    private func candidatePaths(requestedPath: String) -> [String] {
        var candidates: [String] = []
        let variant = SocketPathMarkerFiles.variant(bundleIdentifier: bundleIdentifier, environment: environment)
-        let defaultPath = defaultSocketPath(bundleIdentifier: bundleIdentifier, environment: environment)
+        let ownDefaultPath = resolvedDefaultSocketPath()

-        candidates.append(defaultPath)
-        if let last = readLastSocketPath(bundleIdentifier: bundleIdentifier, environment: environment) {
-            candidates.append(last)
-        }
+        // Keep the current variant first. For a tagged debug CLI this is the
+        // tag-specific socket; for the stable CLI it is the primary stable socket.
+        candidates.append(ownDefaultPath)
+
+        // A dead dev socket must not strand ambient commands. The stable primary
+        // socket is the deterministic machine-wide fallback before any marker.
+        candidates.append(resolvedStableDefaultSocketPath)
+
+        // Markers are an ordered list, not a single pointer: the state-directory
+        // marker and its legacy /tmp mirror can disagree after a reload.
+        candidates.append(contentsOf: readLastSocketPaths(
+            bundleIdentifier: bundleIdentifier,
+            environment: environment
+        ))
+        // A dev process may be the last writer for its own marker while the
+        // stable app's marker still names a user-scoped stable listener. Walk
+        // those markers too, in deterministic order, rather than treating one
+        // variant's file as the entire discovery state.
+        candidates.append(contentsOf: readLastSocketPaths(
+            bundleIdentifier: SocketPathMarkerFiles.stableBundleIdentifier,
+            environment: [:]
+        ))
+
+        // Preserve legacy/user-scoped stable aliases after the primary and marker
+        // candidates. They remain useful on machines migrating from older releases.
+        candidates.append(contentsOf: implicitFallbackCandidatePaths(for: variant))
+
+        // A caller that supplies a non-default implicit path still gets that path
+        // tried, but it never displaces the current variant's own socket.
        if shouldIncludeImplicitRequestedPath(
            requestedPath,
-            defaultPath: defaultPath,
+            defaultPath: ownDefaultPath,
            variant: variant
        ) {
            candidates.append(requestedPath)
        }
-        candidates.append(contentsOf: implicitFallbackCandidatePaths(for: variant))
-        if shouldDiscoverTaggedSockets(
-            variant: variant,
-            bundleIdentifier: bundleIdentifier,
-            environment: environment
-        ) {
-            candidates.append(contentsOf: discoverTaggedSockets(limit: 12))
-        }
        return candidates
    }

-    private static func shouldIncludeImplicitRequestedPath(
+    private func shouldIncludeImplicitRequestedPath(
        _ requestedPath: String,
        defaultPath: String,
        variant: SocketPathVariant
@@ -221,91 +308,43 @@ enum CLISocketPathResolver {
        case .stable:
            return true
        case .nightly, .staging, .dev:
-            return pathsMatch(requestedPath, defaultPath)
-                || !containsPath(stableImplicitDefaultPaths(), requestedPath)
+            return Self.pathsMatch(requestedPath, defaultPath)
+                || !Self.containsPath(resolvedStableImplicitDefaultPaths(), requestedPath)
        }
    }

-    private static func implicitFallbackCandidatePaths(for variant: SocketPathVariant) -> [String] {
+    private func implicitFallbackCandidatePaths(for variant: SocketPathVariant) -> [String] {
        switch variant {
-        case .stable:
-            return stableImplicitDefaultPaths()
-        case .nightly, .staging, .dev:
-            return []
+        case .stable, .nightly, .staging, .dev:
+            return resolvedStableImplicitDefaultPaths()
        }
    }

-    private static func shouldDiscoverTaggedSockets(
-        variant: SocketPathVariant,
+    private func resolvedStableImplicitDefaultPaths() -> [String] {
+        Self.dedupe([
+            resolvedStableDefaultSocketPath,
+            Self.legacyDefaultSocketPath,
+            stateDirectory.appendingPathComponent("cmux-\(currentUserID).sock", isDirectory: false).path,
+            Self.legacyUserScopedStableSocketPath(currentUserID: currentUserID),
+        ])
+    }
+
+    private func readLastSocketPaths(
        bundleIdentifier: String?,
        environment: [String: String]
-    ) -> Bool {
-        switch variant {
-        case .dev(slug: nil):
-            return true
-        case .dev(slug: .some):
-            let bundleId = bundleIdentifier?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-            return bundleId == SocketPathMarkerFiles.defaultBaseDebugBundleIdentifier
-                && normalized(environment["CMUX_TAG"]) != nil
-        case .stable, .nightly, .staging:
-            return false
-        }
-    }
-
-    private static func readLastSocketPath(
-        bundleIdentifier: String?,
-        environment: [String: String]
-    ) -> String? {
+    ) -> [String] {
        let candidates = lastSocketPathFiles(bundleIdentifier: bundleIdentifier, environment: environment)
+        var values: [String] = []
        for candidate in candidates {
-            guard let data = try? String(contentsOfFile: candidate, encoding: .utf8) else {
-                continue
-            }
-            if let value = normalized(data) {
-                return value
+            guard let contents = boundedMarkerContents(at: candidate) else { continue }
+            if let value = Self.normalized(contents) {
+                values.append(value)
            }
        }
-        return nil
+        return values
    }

-    private static func discoverTaggedSockets(limit: Int) -> [String] {
-        var discovered: [(path: String, mtime: TimeInterval)] = []
-        for directory in socketDiscoveryDirectories() {
-            guard let entries = try? FileManager.default.contentsOfDirectory(atPath: directory) else {
-                continue
-            }
-            discovered.reserveCapacity(min(limit, discovered.count + entries.count))
-            for name in entries where name.hasPrefix("cmux-debug-") && name.hasSuffix(".sock") {
-                let path = URL(fileURLWithPath: directory)
-                    .appendingPathComponent(name, isDirectory: false)
-                    .path
-                var st = stat()
-                guard lstat(path, &st) == 0 else { continue }
-                guard (st.st_mode & mode_t(S_IFMT)) == mode_t(S_IFSOCK) else { continue }
-                if isKnownDefaultSocketPath(path) {
-                    continue
-                }
-                let modified = TimeInterval(st.st_mtimespec.tv_sec) + TimeInterval(st.st_mtimespec.tv_nsec) / 1_000_000_000
-                discovered.append((path: path, mtime: modified))
-            }
-        }
-
-        discovered.sort { $0.mtime > $1.mtime }
-        return dedupe(discovered.prefix(limit).map(\.path))
-    }
-
-    private static func isSocketFile(_ path: String) -> Bool {
-        if case .socket = inspectSocketPathEntry(path) {
-            return true
-        }
-        return false
-    }
-
-    private static func isOwnedSocketFile(
-        _ path: String,
-        currentUserID: uid_t,
-        inspectSocketPathEntry: (String) -> SocketPathEntry
-    ) -> Bool {
+    private func isOwnedSocketFile(_ path: String) -> Bool {
        if case .socket(let ownerUserID) = inspectSocketPathEntry(path) {
            return ownerUserID == currentUserID
        }
@@ -326,18 +365,14 @@ enum CLISocketPathResolver {
        return .other(ownerUserID: st.st_uid)
    }

-    private static func canConnect(
-        to path: String,
-        currentUserID: uid_t,
-        inspectSocketPathEntry: (String) -> SocketPathEntry
-    ) -> Bool {
-        guard isOwnedSocketFile(
-            path,
-            currentUserID: currentUserID,
-            inspectSocketPathEntry: inspectSocketPathEntry
-        ) else {
+    private func canConnect(to path: String) -> Bool {
+        guard isOwnedSocketFile(path) else {
            return false
        }
+        return socketAcceptsConnections(path)
+    }
+
+    private static func socketAcceptsConnections(_ path: String) -> Bool {
        let fd = socket(AF_UNIX, SOCK_STREAM, 0)
        guard fd >= 0 else { return false }
        defer { Darwin.close(fd) }
@@ -349,6 +384,9 @@ enum CLISocketPathResolver {
        var addr = sockaddr_un()
        addr.sun_family = sa_family_t(AF_UNIX)
        let maxLength = MemoryLayout.size(ofValue: addr.sun_path)
+        guard path.utf8.count < maxLength else {
+            return false
+        }
        path.withCString { ptr in
            withUnsafeMutablePointer(to: &addr.sun_path) { pathPtr in
                let buf = UnsafeMutableRawPointer(pathPtr).assumingMemoryBound(to: CChar.self)
@@ -387,6 +425,30 @@ enum CLISocketPathResolver {
        return optionResult == 0 && socketError == 0
    }

+    /// Reads at most one short socket marker without accepting unbounded input.
+    private func boundedMarkerContents(at path: String) -> String? {
+        var info = stat()
+        guard lstat(path, &info) == 0,
+              (info.st_mode & mode_t(S_IFMT)) == mode_t(S_IFREG),
+              info.st_uid == currentUserID,
+              info.st_nlink == 1,
+              info.st_size >= 0,
+              info.st_size <= off_t(SocketPathMarkerStore.maximumMarkerBytes)
+        else {
+            return nil
+        }
+
+        let url = URL(fileURLWithPath: path, isDirectory: false)
+        guard let handle = try? FileHandle(forReadingFrom: url) else { return nil }
+        defer { try? handle.close() }
+        guard let data = try? handle.read(upToCount: SocketPathMarkerStore.maximumMarkerBytes + 1),
+              data.count <= SocketPathMarkerStore.maximumMarkerBytes
+        else {
+            return nil
+        }
+        return String(data: data, encoding: .utf8)
+    }
+
    private static func knownImplicitDefaultPaths(
        bundleIdentifier: String?,
        environment: [String: String]
@@ -410,22 +472,6 @@ enum CLISocketPathResolver {
        ])
    }

-    private static func allKnownDefaultSocketPaths() -> Set<String> {
-        Set(dedupe([
-            stableDefaultSocketPath,
-            legacyDefaultSocketPath,
-            userScopedStableSocketPath(),
-            legacyUserScopedStableSocketPath(),
-            fallbackSocketPath,
-            nightlySocketPath,
-            stagingSocketPath,
-        ]))
-    }
-
-    private static func isKnownDefaultSocketPath(_ path: String) -> Bool {
-        containsPath(Array(allKnownDefaultSocketPaths()), path)
-    }
-
    private static func containsPath(_ paths: [String], _ path: String) -> Bool {
        paths.contains { pathsMatch($0, path) }
    }
@@ -441,6 +487,12 @@ enum CLISocketPathResolver {
        }
    }

+    /// Keeps diagnostic value semantics available to the result type without exposing
+    /// the resolver's path-normalization implementation as public API.
+    fileprivate static func pathsMatchForDiagnostics(_ lhs: String, _ rhs: String) -> Bool {
+        pathsMatch(lhs, rhs)
+    }
+
    private static func pathComparisonForms(_ path: String) -> [String] {
        let baseForms = [
            (path as NSString).standardizingPath,
@@ -457,14 +509,14 @@ enum CLISocketPathResolver {
        return dedupe(forms)
    }

-    private static func lastSocketPathFiles(
+    private func lastSocketPathFiles(
        bundleIdentifier: String?,
        environment: [String: String]
    ) -> [String] {
        SocketPathMarkerFiles.paths(
            bundleIdentifier: bundleIdentifier,
            environment: environment,
-            directory: stableSocketDirectoryURL()
+            directory: stateDirectory
        )
    }

@@ -482,9 +534,9 @@ enum CLISocketPathResolver {
        }

 #if DEBUG
-        return "com.cmuxterm.app.debug"
+        return SocketPathMarkerFiles.defaultBaseDebugBundleIdentifier
 #else
-        return "com.cmuxterm.app"
+        return SocketPathMarkerFiles.stableBundleIdentifier
 #endif
    }

@@ -505,14 +557,6 @@ enum CLISocketPathResolver {
        CmuxStateDirectory.url(homeDirectory: FileManager.default.homeDirectoryForCurrentUser)
    }

-    private static func socketDiscoveryDirectories() -> [String] {
-        let stateSocketDirectory: String = stableSocketDirectoryURL()?.path ?? ""
-        return dedupe([
-            "/tmp",
-            stateSocketDirectory,
-        ])
-    }
-
    private static func dedupe(_ paths: [String]) -> [String] {
        var seen: Set<String> = []
        var ordered: [String] = []
@@ -39,6 +39,7 @@ extension CMUXCLI {
                .init(agentEvent: "Notification", cmuxSubcommand: "notification"),
                .init(agentEvent: "SessionEnd", cmuxSubcommand: "session-end"),
            ],
+            dispatch: .pinned(marker: "cmux-grok-hook-v2"),
            publishesStopNotification: false,
            sessionEndIsTurnBoundary: true,
            feedHookEvents: ["PreToolUse"]
@@ -142,6 +143,7 @@ extension CMUXCLI {
                .init(agentEvent: "SessionEnd", cmuxSubcommand: "session-end"),
            ],
            aliases: ["agy"],
+            dispatch: .pinned(marker: "cmux-antigravity-hook-v2"),
            sessionEndIsTurnBoundary: true
        ),
        AgentHookDef(
@@ -159,6 +161,7 @@ extension CMUXCLI {
        AgentHookDef(
            name: "hermes-agent", displayName: "Hermes Agent", statusKey: "hermes-agent",
            configDir: ".hermes", configFile: "config.yaml", configDirEnvOverride: "HERMES_HOME",
+            createConfigDirIfMissing: true,
            binaryName: "hermes",
            sessionStoreSuffix: "hermes-agent", disableEnvVar: "CMUX_HERMES_AGENT_HOOKS_DISABLED",
            hookMarker: "cmux hooks hermes-agent", format: .hermesAgentYAML,
@@ -26,6 +26,12 @@ extension CMUXCLI {
        let format: HookFormat
        let events: [HookEvent]
        let aliases: Set<String>
+        /// How installed hooks find the cmux instance that owns them.
+        ///
+        /// `.ambient` is appropriate when an agent preserves the launch environment. `.pinned`
+        /// embeds the installing CLI and socket, which is required for agents that sanitize hook
+        /// subprocess environments and keeps callbacks attributed to the correct tagged app.
+        let dispatch: HookDispatch
        let publishesStopNotification: Bool
        /// Whether this agent's `SessionEnd`/`session-end` hook fires once per
        /// conversation turn rather than at a true session teardown.
@@ -62,6 +68,11 @@ extension CMUXCLI {
            case tomlArrayTable // ~/.kimi/config.toml [[hooks]] array-of-tables
        }

+        enum HookDispatch {
+            case ambient
+            case pinned(marker: String)
+        }
+
        struct HookEvent {
            let agentEvent: String
            let cmuxSubcommand: String
@@ -109,6 +120,7 @@ extension CMUXCLI {
             sessionStoreSuffix: String, disableEnvVar: String, hookMarker: String,
             format: HookFormat, events: [HookEvent],
             aliases: Set<String> = [],
+             dispatch: HookDispatch = .ambient,
             publishesStopNotification: Bool = true,
             sessionEndIsTurnBoundary: Bool = false,
             feedHookEvents: [String] = [],
@@ -123,6 +135,7 @@ extension CMUXCLI {
            self.binaryName = binaryName ?? name
            self.sessionStoreSuffix = sessionStoreSuffix; self.disableEnvVar = disableEnvVar
            self.hookMarker = hookMarker; self.format = format; self.events = events
+            self.dispatch = dispatch
            self.publishesStopNotification = publishesStopNotification
            self.sessionEndIsTurnBoundary = sessionEndIsTurnBoundary
            self.aliases = Set(aliases.compactMap { alias in
@@ -246,15 +259,12 @@ extension CMUXCLI {
        return "{ \(command); }"
    }

-    private static let grokPinnedHookMarker = "cmux-grok-hook-v2"
-    private static let antigravityPinnedHookMarker = "cmux-antigravity-hook-v2"
-
    private static func agentHookShellCommand(
        _ command: String,
        for def: AgentHookDef,
        noOpCommand: String = "echo '{}'"
    ) -> String {
-        if usesPinnedHookDispatch(def) {
+        if case .pinned = def.dispatch {
            return pinnedAgentHookShellCommand(command, for: def, noOpCommand: noOpCommand)
        }
        let routedArguments = command.hasPrefix("cmux ") ? String(command.dropFirst("cmux ".count)) : command
@@ -272,19 +282,14 @@ extension CMUXCLI {
        return "cmux_cli=\"${CMUX_BUNDLED_CLI_PATH:-}\"; if [ -z \"$cmux_cli\" ] || [ ! -x \"$cmux_cli\" ]; then cmux_cli=\"$(command -v cmux 2>/dev/null || true)\"; fi; if [ -n \"$CMUX_SURFACE_ID\" ] && [ \"$\(def.disableEnvVar)\" != \"1\" ] && [ -n \"$cmux_cli\" ]; then if [ -n \"${CMUX_SOCKET_PATH:-}\" ]; then \"$cmux_cli\" --socket \"$CMUX_SOCKET_PATH\" \(routedArguments); else \"$cmux_cli\" \(routedArguments); fi; status=$?; if [ \"$status\" -eq 2 ]; then exit 2; fi; if [ \"$status\" -ne 0 ]; then \(noOpSnippet); fi; else \(noOpSnippet); fi"
    }

-    private static func usesPinnedHookDispatch(_ def: AgentHookDef) -> Bool {
-        def.name == "grok" || def.name == "antigravity"
-    }
-
-    private static func pinnedHookMarker(for def: AgentHookDef) -> String {
-        def.name == "antigravity" ? antigravityPinnedHookMarker : grokPinnedHookMarker
-    }
-
    private static func pinnedAgentHookShellCommand(
        _ command: String,
        for def: AgentHookDef,
        noOpCommand: String = "echo '{}'"
    ) -> String {
+        guard case .pinned(let marker) = def.dispatch else {
+            return agentHookShellCommand(command, for: def, noOpCommand: noOpCommand)
+        }
        let routedArguments = command.hasPrefix("cmux ") ? String(command.dropFirst("cmux ".count)) : command
        let socketPath = pinnedAgentHookSocketPath()
        let noOpSnippet = shellNoOpSnippet(noOpCommand)
@@ -324,7 +329,7 @@ extension CMUXCLI {
        } else {
            dispatch = "command -v cmux >/dev/null 2>&1 && \(fallbackInvocation) || \(noOpSnippet)"
        }
-        return ": \(pinnedHookMarker(for: def)); \(shellTraceStart); printenv \(def.disableEnvVar) | grep -qx 1 && { \(shellTraceDisabled); \(noOpSnippet); } || { \(dispatch); cmux_hook_status=$?; \(shellTraceExit); exit $cmux_hook_status; }"
+        return ": \(marker); \(shellTraceStart); printenv \(def.disableEnvVar) | grep -qx 1 && { \(shellTraceDisabled); \(noOpSnippet); } || { \(dispatch); cmux_hook_status=$?; \(shellTraceExit); exit $cmux_hook_status; }"
    }

    private static func pinnedHookInvocation(
@@ -389,6 +394,17 @@ extension CMUXCLI {
        return "/tmp/cmux-debug-\(slug).sock"
    }

+    static func validateHookInstallDispatch(for def: AgentHookDef) throws {
+        guard case .pinned = def.dispatch,
+              pinnedAgentHookSocketPath() == nil else {
+            return
+        }
+        throw CLIError(message: String(
+            localized: "cli.hooks.error.pinnedTargetMissing",
+            defaultValue: "cmux could not connect this hook installation to a running app. Open a cmux workspace and run this command again."
+        ))
+    }
+
    private static func pinnedHookShellTraceCommand(
        agentName: String,
        phase: String,
@@ -434,7 +450,7 @@ extension CMUXCLI {
    }

    static func isCmuxOwnedHookCommand(_ command: String, for def: AgentHookDef, includeLegacy: Bool = true) -> Bool {
-        if usesPinnedHookDispatch(def), command.contains(pinnedHookMarker(for: def)) {
+        if case .pinned(let marker) = def.dispatch, command.contains(marker) {
            return true
        }
        if def.name == "codex", isCmuxOwnedCodexHookScriptCommand(command) {
@@ -0,0 +1,82 @@
+import Foundation
+import CMUXAgentLaunch
+import OSLog
+
+nonisolated private let codexResumeBindingLogger = Logger(
+    subsystem: "com.cmuxterm.cli",
+    category: "CodexResumeBinding"
+)
+
+extension CMUXCLI {
+    /// Verifies a hook checkpoint before the standalone CLI publishes it.
+    ///
+    /// Hook publication is intentionally decided in this short-lived CLI
+    /// process, not on cmux's MainActor or socket worker. The verifier starts
+    /// with one indexed SQLite lookup and applies hard byte, line, and fallback
+    /// candidate limits to the legacy rollout path, so the bounded inspection
+    /// cannot turn an app UI/socket lane into a history loader.
+    func codexResumeBindingVerification(
+        sessionId: String,
+        transcriptPath: String?,
+        launchCommand: AgentHookLaunchCommandRecord?
+    ) -> CodexSessionResumeVerification {
+        let environment = ProcessInfo.processInfo.environment
+        let codexHome = codexResumeBindingEffectiveHome(
+            launchEnvironment: launchCommand?.environment,
+            launchVerificationHome: launchCommand?.verificationHome,
+            ambientEnvironment: environment
+        )
+        return CodexSessionResumeVerifier().verify(
+            sessionId: sessionId,
+            transcriptPath: transcriptPath,
+            codexHome: codexHome
+        )
+    }
+
+    func codexResumeBindingEffectiveHome(
+        launchEnvironment: [String: String]?,
+        launchVerificationHome: String? = nil,
+        ambientEnvironment: [String: String] = ProcessInfo.processInfo.environment
+    ) -> String {
+        if let launchHome = normalizedHookValue(launchEnvironment?["CODEX_HOME"]) {
+            return (launchHome as NSString).expandingTildeInPath
+        }
+        if let launchHome = normalizedHookValue(launchVerificationHome)
+            ?? normalizedHookValue(launchEnvironment?["HOME"]) {
+            return URL(fileURLWithPath: (launchHome as NSString).expandingTildeInPath, isDirectory: true)
+                .appendingPathComponent(".codex", isDirectory: true)
+                .path
+        }
+        if let ambientHome = normalizedHookValue(ambientEnvironment["CODEX_HOME"]) {
+            return (ambientHome as NSString).expandingTildeInPath
+        }
+        let home = normalizedHookValue(ambientEnvironment["HOME"]) ?? NSHomeDirectory()
+        return URL(fileURLWithPath: home, isDirectory: true)
+            .appendingPathComponent(".codex", isDirectory: true)
+            .path
+    }
+
+    func logCodexResumeBindingRejection(
+        reason: String,
+        sessionId: String,
+        incoming: AgentResumeEvidenceProvenance?,
+        existing: AgentResumeEvidenceProvenance?,
+        telemetry: CLISocketSentryTelemetry?
+    ) {
+        let shortSessionID = String(sessionId.prefix(12))
+        let incomingValue = incoming?.logValue ?? "none"
+        let existingValue = existing?.logValue ?? "none"
+        codexResumeBindingLogger.notice(
+            "Codex resume binding publish rejected reason=\(reason, privacy: .public) session=\(shortSessionID, privacy: .private(mask: .hash)) incoming=\(incomingValue, privacy: .public) existing=\(existingValue, privacy: .public)"
+        )
+        telemetry?.breadcrumb(
+            "codex-resume-binding.publish-rejected",
+            data: [
+                "reason": reason,
+                "incoming_provenance": incomingValue,
+                "existing_provenance": existingValue,
+                "has_session_id": !sessionId.isEmpty,
+            ]
+        )
+    }
+}
@@ -369,10 +369,10 @@ extension CMUXCLI {
          docs                Print the same output as `cmux docs settings`.

        Targets:
-          account, app, terminal, sidebar-appearance, custom-sidebars,
-          automation, browser, browser-import, global-hotkey,
-          keyboard-shortcuts, shortcuts, workspace-colors, cmux-json,
-          json, reset
+          account, app, terminal, networking, sidebar-appearance,
+          custom-sidebars, automation, browser, browser-import,
+          global-hotkey, keyboard-shortcuts, shortcuts, workspace-colors,
+          cmux-json, json, reset

        Config file:
          \(Self.primarySettingsDisplayPath)
@@ -411,6 +411,8 @@ extension CMUXCLI {
            return "automation"
        case "browser":
            return "browser"
+        case "networking", "network", "iroh":
+            return "networking"
        case "browser-import", "browserimport", "import-browser-data":
            return "browserImport"
        case "global-hotkey", "globalhotkey", "hotkey":
@@ -37,16 +37,14 @@ extension CMUXCLI {
        return prefix.contains("cmux claude wrapper - injects hooks and session tracking")
    }

-    func isCmuxClaudeCommandShim(at path: String) -> Bool {
+    func isCmuxAgentCommandShim(at path: String) -> Bool {
        let candidate = URL(fileURLWithPath: path, isDirectory: false)
            .standardizedFileURL
            .path
        let environment = ProcessInfo.processInfo.environment
-        let shimPaths = [
-            environment["CMUX_CLAUDE_WRAPPER_SHIM"],
-        ]
-        for shimPath in shimPaths {
-            guard let shimPath else { continue }
+        for (key, rawPath) in environment where key.hasSuffix("_WRAPPER_SHIM") {
+            let shimPath = rawPath.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !shimPath.isEmpty else { continue }
            let standardizedShim = URL(fileURLWithPath: shimPath, isDirectory: false)
                .standardizedFileURL
                .path
@@ -55,16 +53,22 @@ extension CMUXCLI {
            }
        }

-        let shimRoots: [String?] = [
-            environment["CMUX_CLAUDE_WRAPPER_SHIM_ROOT"],
+        var shimRoots = environment.compactMap { key, rawPath -> String? in
+            guard key == "CMUX_AGENT_COMMAND_SHIM_ROOT" || key.hasSuffix("_WRAPPER_SHIM_ROOT") else {
+                return nil
+            }
+            return rawPath
+        }
+        shimRoots.append(contentsOf: [
            URL(fileURLWithPath: environment["TMPDIR"] ?? NSTemporaryDirectory(), isDirectory: true)
                .appendingPathComponent("cmux-cli-shims", isDirectory: true)
                .standardizedFileURL
                .path,
            "/tmp/cmux-cli-shims",
-        ]
+        ])
        for shimRoot in shimRoots {
-            guard let shimRoot else { continue }
+            let shimRoot = shimRoot.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !shimRoot.isEmpty else { continue }
            let standardizedRoot = URL(fileURLWithPath: shimRoot, isDirectory: true)
                .standardizedFileURL
                .path
@@ -94,6 +98,7 @@ extension CMUXCLI {
                  !isDirectory.boolValue,
                  FileManager.default.isExecutableFile(atPath: candidate) else { continue }
            guard !isBundledProviderExecutable(at: candidate) else { continue }
+            guard !isCmuxAgentCommandShim(at: candidate) else { continue }
            if let skip, skip(candidate) { continue }
            return candidate
        }
@@ -109,7 +114,7 @@ extension CMUXCLI {
                  !isDirectory.boolValue,
                  FileManager.default.isExecutableFile(atPath: trimmed),
                  !isBundledProviderExecutable(at: trimmed),
-                  !isCmuxClaudeCommandShim(at: trimmed),
+                  !isCmuxAgentCommandShim(at: trimmed),
                  !isCmuxClaudeWrapper(at: trimmed) else { continue }
            return URL(fileURLWithPath: trimmed, isDirectory: false).standardizedFileURL.path
        }
@@ -121,7 +126,7 @@ extension CMUXCLI {
        resolveExecutableInSearchPath(
            "claude",
            searchPath: searchPath,
-            skip: { self.isCmuxClaudeCommandShim(at: $0) || self.isCmuxClaudeWrapper(at: $0) }
+            skip: { self.isCmuxClaudeWrapper(at: $0) }
        )
    }

@@ -302,6 +307,8 @@ extension CMUXCLI {
        for key in ClaudeSessionEnvironmentPolicy().inheritedIndependentLaunchKeys {
            unsetenv(key)
        }
+        unsetenv(ClaudeTeamsRespawnEnvironmentTransport.environmentKey)
+        unsetenv("CMUX_CLAUDE_TEAMS_WRAPPER_LAUNCH")
    }

    private func providerExecutableSearchDirectories(searchPath: String?) -> [String] {
@@ -1,7 +1,191 @@
-import Foundation
 import CMUXAgentLaunch
+import Darwin
+import Foundation

 extension CMUXCLI {
+    private static let hermesTUIActiveSessionFilePrefix = "hermes-tui-active-session-"
+    private static let hermesTUIActiveSessionMaximumBytes: Int64 = 4_096
+
+    private func updateHermesAgentAllowlist(
+        atPath allowlistPath: String,
+        transform: (Data?) throws -> Data
+    ) throws -> Bool {
+        let lockPath = "\(allowlistPath).lock"
+        let descriptor = Darwin.open(
+            lockPath,
+            O_RDWR | O_CREAT | O_CLOEXEC,
+            S_IRUSR | S_IWUSR
+        )
+        guard descriptor >= 0 else {
+            throw NSError(domain: NSPOSIXErrorDomain, code: Int(errno))
+        }
+        defer { _ = Darwin.close(descriptor) }
+
+        var result: Int32
+        repeat {
+            result = flock(descriptor, LOCK_EX)
+        } while result != 0 && errno == EINTR
+        guard result == 0 else {
+            throw NSError(domain: NSPOSIXErrorDomain, code: Int(errno))
+        }
+        defer { _ = flock(descriptor, LOCK_UN) }
+
+        let oldAllowlist = FileManager.default.contents(atPath: allowlistPath)
+        let newAllowlist = try transform(oldAllowlist)
+        guard oldAllowlist != newAllowlist else { return false }
+        try newAllowlist.write(to: URL(fileURLWithPath: allowlistPath), options: .atomic)
+        return true
+    }
+
+    private func hermesAgentApprovalPayload(
+        def: AgentHookDef,
+        input: ClaudeHookParsedInput
+    ) -> (event: String, extra: [String: Any])? {
+        guard def.name == "hermes-agent",
+              let object = input.rawObject ?? input.object,
+              let event = firstString(
+                  in: object,
+                  keys: ["hook_event_name", "hookEventName", "event", "event_name"]
+              )?.lowercased(),
+              event == "pre_approval_request" || event == "post_approval_response" else {
+            return nil
+        }
+        return (event, (object["extra"] as? [String: Any]) ?? [:])
+    }
+
+    func hermesAgentApprovalSessionId(
+        def: AgentHookDef,
+        input: ClaudeHookParsedInput
+    ) -> String? {
+        guard let payload = hermesAgentApprovalPayload(def: def, input: input) else { return nil }
+        return normalizedHookValue(firstString(in: payload.extra, keys: ["session_key", "sessionKey"]))
+    }
+
+    /// Hermes 0.20's TUI approval gateway omits both the top-level session id
+    /// and `extra.session_key`. The cmux wrapper gives each TUI invocation a
+    /// private TMPDIR containing the same active-session file consumed by its
+    /// lifecycle watcher, so missing-id callbacks can still use Hermes's own
+    /// conversation identity instead of mistaking the cmux surface UUID for it.
+    func hermesAgentTUIActiveSessionId(
+        def: AgentHookDef,
+        env: [String: String]
+    ) -> String? {
+        guard def.name == "hermes-agent",
+              env["CMUX_HERMES_TUI_HOOK_BOOTSTRAP"] == "1",
+              let temporaryDirectory = normalizedHookValue(env["TMPDIR"]),
+              temporaryDirectory.hasPrefix("/") else {
+            return nil
+        }
+
+        let directoryURL = URL(
+            fileURLWithPath: temporaryDirectory,
+            isDirectory: true
+        ).standardizedFileURL
+        guard Self.isHermesTUIInvocationDirectoryName(directoryURL.lastPathComponent),
+              Self.isRegularFileWithoutFollowingSymbolicLinks(
+                  atPath: directoryURL.path,
+                  expectedType: S_IFDIR
+              ),
+              let names = try? FileManager.default.contentsOfDirectory(atPath: directoryURL.path) else {
+            return nil
+        }
+
+        let candidates = names.filter {
+            $0.hasPrefix(Self.hermesTUIActiveSessionFilePrefix) && $0.hasSuffix(".json")
+        }
+        guard candidates.count == 1 else { return nil }
+
+        let activeSessionURL = directoryURL.appendingPathComponent(
+            candidates[0],
+            isDirectory: false
+        )
+        guard let data = Self.readHermesTUIActiveSessionFile(atPath: activeSessionURL.path),
+              let object = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+              let sessionId = normalizedHookValue(object["session_id"] as? String),
+              Self.isValidHermesTUISessionId(sessionId) else {
+            return nil
+        }
+        return sessionId
+    }
+
+    private static func isHermesTUIInvocationDirectoryName(_ name: String) -> Bool {
+        let prefix = "cmux-hermes-tui."
+        guard name.hasPrefix(prefix) else { return false }
+        let suffix = name.dropFirst(prefix.count)
+        return suffix.utf8.count == 6 && suffix.utf8.allSatisfy(Self.isASCIIAlphaNumeric)
+    }
+
+    private static func isValidHermesTUISessionId(_ sessionId: String) -> Bool {
+        let bytes = Array(sessionId.utf8)
+        guard (1...128).contains(bytes.count),
+              let first = bytes.first,
+              isASCIIAlphaNumeric(first) else {
+            return false
+        }
+        return bytes.dropFirst().allSatisfy {
+            isASCIIAlphaNumeric($0) || $0 == 46 || $0 == 95 || $0 == 58 || $0 == 45
+        }
+    }
+
+    private static func isASCIIAlphaNumeric(_ byte: UInt8) -> Bool {
+        (48...57).contains(byte) || (65...90).contains(byte) || (97...122).contains(byte)
+    }
+
+    private static func isRegularFileWithoutFollowingSymbolicLinks(
+        atPath path: String,
+        expectedType: mode_t
+    ) -> Bool {
+        var metadata = stat()
+        return lstat(path, &metadata) == 0 && (metadata.st_mode & S_IFMT) == expectedType
+    }
+
+    private static func readHermesTUIActiveSessionFile(atPath path: String) -> Data? {
+        guard isRegularFileWithoutFollowingSymbolicLinks(atPath: path, expectedType: S_IFREG) else {
+            return nil
+        }
+        let descriptor = Darwin.open(path, O_RDONLY | O_CLOEXEC | O_NOFOLLOW)
+        guard descriptor >= 0 else { return nil }
+        defer { _ = Darwin.close(descriptor) }
+
+        var metadata = stat()
+        guard fstat(descriptor, &metadata) == 0,
+              (metadata.st_mode & S_IFMT) == S_IFREG,
+              metadata.st_size > 0,
+              metadata.st_size <= hermesTUIActiveSessionMaximumBytes else {
+            return nil
+        }
+
+        var bytes = [UInt8](repeating: 0, count: Int(metadata.st_size))
+        var offset = 0
+        while offset < bytes.count {
+            let remaining = bytes.count - offset
+            let count = bytes.withUnsafeMutableBytes { buffer -> Int in
+                guard let baseAddress = buffer.baseAddress else { return -1 }
+                return Darwin.read(
+                    descriptor,
+                    baseAddress.advanced(by: offset),
+                    remaining
+                )
+            }
+            if count < 0, errno == EINTR {
+                continue
+            }
+            guard count > 0 else { return nil }
+            offset += count
+        }
+        return Data(bytes)
+    }
+
+    func isHermesAgentAutomaticApprovalObservation(
+        def: AgentHookDef,
+        input: ClaudeHookParsedInput
+    ) -> Bool {
+        guard let payload = hermesAgentApprovalPayload(def: def, input: input) else { return false }
+        return firstString(in: payload.extra, keys: ["surface"])?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+            .lowercased() == "smart"
+    }
+
    func hermesAgentShellCommand(_ script: String) -> String {
        "sh -c \(shellQuote(script))"
    }
@@ -32,9 +216,31 @@ extension CMUXCLI {
        let skipConfirm = ProcessInfo.processInfo.arguments.contains("--yes")
            || ProcessInfo.processInfo.arguments.contains("-y")

-        guard fm.fileExists(atPath: configDir) else {
-            print("\(configDir) does not exist. Install \(def.displayName) first.")
-            return
+        let configDirectoryFileError = String.localizedStringWithFormat(
+            String(
+                localized: "cli.hooks.error.configDirectoryIsFile",
+                defaultValue: "cmux could not create the hooks directory: a file exists at %@. Remove or rename the conflicting file, then run `cmux hooks setup` again."
+            ),
+            configDir
+        )
+        let configDirectoryCreateError = String.localizedStringWithFormat(
+            String(
+                localized: "cli.hooks.error.configDirectoryCreateFailed",
+                defaultValue: "cmux could not create the hooks directory at %@. Check the parent directory permissions and try again."
+            ),
+            configDir
+        )
+        var isConfigDirectory: ObjCBool = false
+        if fm.fileExists(atPath: configDir, isDirectory: &isConfigDirectory) {
+            guard isConfigDirectory.boolValue else {
+                throw CLIError(message: configDirectoryFileError)
+            }
+        } else {
+            do {
+                try fm.createDirectory(atPath: configDir, withIntermediateDirectories: true)
+            } catch {
+                throw CLIError(message: configDirectoryCreateError)
+            }
        }

        let events = hermesAgentEvents(def: def)
@@ -61,10 +267,10 @@ extension CMUXCLI {
            print("\(def.displayName) hooks already up to date at \(filePath)")
        }

-        let oldAllowlist = fm.contents(atPath: allowlistPath)
-        let newAllowlist = try HermesAgentHookAllowlist.installing(events: events, in: oldAllowlist)
-        if oldAllowlist != newAllowlist {
-            try newAllowlist.write(to: URL(fileURLWithPath: allowlistPath), options: .atomic)
+        let updatedAllowlist = try updateHermesAgentAllowlist(atPath: allowlistPath) { oldAllowlist in
+            try HermesAgentHookAllowlist.installing(events: events, in: oldAllowlist)
+        }
+        if updatedAllowlist {
            print("Approved \(def.displayName) cmux shell hooks in \(allowlistPath)")
        }
    }
@@ -90,10 +296,10 @@ extension CMUXCLI {
        }

        guard fm.fileExists(atPath: allowlistPath) else { return }
-        let oldAllowlist = fm.contents(atPath: allowlistPath)
-        let newAllowlist = try HermesAgentHookAllowlist.uninstalling(events: events, from: oldAllowlist)
-        if oldAllowlist != newAllowlist {
-            try newAllowlist.write(to: URL(fileURLWithPath: allowlistPath), options: .atomic)
+        let updatedAllowlist = try updateHermesAgentAllowlist(atPath: allowlistPath) { oldAllowlist in
+            try HermesAgentHookAllowlist.uninstalling(events: events, from: oldAllowlist)
+        }
+        if updatedAllowlist {
            print("Removed Hermes Agent cmux shell hook approvals from \(allowlistPath)")
        }
    }
@@ -37,7 +37,7 @@ extension CMUXCLI {
        let configDirectoryFileError = String.localizedStringWithFormat(
            String(
                localized: "cli.hooks.error.configDirectoryIsFile",
-                defaultValue: "cmux could not create the hooks directory: a file exists at %@; remove or rename the conflicting file and re-run `cmux hooks setup`"
+                defaultValue: "cmux could not create the hooks directory: a file exists at %@. Remove or rename the conflicting file, then run `cmux hooks setup` again."
            ),
            configDir
        )
@@ -78,6 +78,14 @@ extension CMUXCLI {
            remoteMoshProbeFailedMessage: String(
                localized: "cli.ssh.mosh.probeFailed",
                defaultValue: "[cmux] Could not verify remote Mosh support; continuing over SSH."
+            ),
+            remoteBootstrapInstallFailedMessage: String(
+                localized: "cli.ssh.mosh.bootstrapInstallFailed",
+                defaultValue: "[cmux] Remote bootstrap install failed; continuing over SSH."
+            ),
+            remoteMoshAddressFallbackMessage: String(
+                localized: "cli.ssh.mosh.addressFallback",
+                defaultValue: "[cmux] Remote SSH advertised an unusable address; resolving the Mosh address through the SSH connection."
            )
        ).command()
    }
@@ -1,6 +1,7 @@
 extension CMUXCLI {
    static let piExtensionSource = [
        piExtensionSourcePart1,
+        piExtensionSourceDiagnostics,
        piExtensionSourceDispatch,
        piExtensionSourcePart2,
    ].joined(separator: "\n")
@@ -0,0 +1,221 @@
+extension CMUXCLI {
+    static let piExtensionSourceDiagnostics = #"""
+type CommandFailureReason = "timeout" | "nonzero-exit" | "spawn-error" | "cancelled";
+type CommandTerminationReason = "timeout" | "cancelled";
+
+// Loaded repositories have produced successful 9s+ lifecycle hooks. Leave
+// headroom above that observed tail without allowing a stuck child to block a
+// session's serialized control queue indefinitely.
+const defaultPiHookTimeoutMilliseconds = 15_000;
+const maximumPiHookTimeoutMilliseconds = 60_000;
+// Feed's CLI owns a four-second end-to-end deadline. Give the wrapper enough
+// headroom that the child reports that outcome itself instead of being killed
+// mid-deadline, while lifecycle tuning still cannot pin the shared Feed pool.
+const maximumPiFeedCommandTimeoutMilliseconds = 4_500;
+// Diagnostics are best effort and may hold a serialized hook queue only briefly.
+const piHookDiagnosticWriteDeadlineMilliseconds = 100;
+
+function piHookTimeoutMilliseconds(
+  rawValue: string | undefined = process.env.CMUX_PI_HOOK_TIMEOUT_MS,
+): number {
+  const normalized = rawValue?.trim();
+  if (!normalized || !/^\d+$/.test(normalized)) return defaultPiHookTimeoutMilliseconds;
+  const parsed = Number(normalized);
+  if (parsed >= maximumPiHookTimeoutMilliseconds) return maximumPiHookTimeoutMilliseconds;
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : defaultPiHookTimeoutMilliseconds;
+}
+
+function piCommandTimeoutMilliseconds(
+  args: string[],
+  rawValue: string | undefined = process.env.CMUX_PI_HOOK_TIMEOUT_MS,
+): number {
+  const configured = piHookTimeoutMilliseconds(rawValue);
+  return args[0] === "hooks" && args[1] === "feed"
+    ? Math.min(configured, maximumPiFeedCommandTimeoutMilliseconds)
+    : configured;
+}
+
+function commandFailureReason(
+  status: number | null,
+  error: unknown,
+  terminationReason?: CommandTerminationReason,
+): CommandFailureReason | undefined {
+  if (terminationReason) return terminationReason;
+  if (status === 0) return undefined;
+  if (status !== null && status !== 0) return "nonzero-exit";
+  return "spawn-error";
+}
+
+function boundedPiHookName(value: string): string {
+  return utf8Prefix(value, 128) || "unknown";
+}
+
+function piHookName(args: string[]): string {
+  if (args[0] === "hooks" && args[1] === "pi") {
+    return boundedPiHookName(firstString(args[2]) || "unknown");
+  }
+  if (args[0] === "hooks" && args[1] === "feed") {
+    const eventIndex = args.indexOf("--event");
+    const eventName = eventIndex >= 0 ? firstString(args[eventIndex + 1]) : null;
+    return boundedPiHookName(eventName ? `feed:${eventName}` : "feed");
+  }
+  if (args[0] === "--json" && args[1] === "surface" && args[2] === "resume") {
+    return boundedPiHookName(`surface-resume-${firstString(args[3]) || "unknown"}`);
+  }
+  return "cmux-command";
+}
+
+function expandedPiHookLogPath(value: string, home: string | undefined = process.env.HOME): string {
+  if (value === "~") return home || value;
+  if (value.startsWith("~/") && home) {
+    return path.join(home, value.slice(2));
+  }
+  return value;
+}
+
+function isOwnedRegularPiHookFile(metadata: fs.Stats): boolean {
+  return metadata.isFile()
+    && typeof process.getuid === "function"
+    && metadata.uid === process.getuid();
+}
+
+let activePiHookDiagnosticWrite: Promise<void> | undefined;
+
+async function runPiHookDiagnosticWrite(operation: () => Promise<void>): Promise<void> {
+  // Retain at most one file operation. If it stalls after the caller's deadline,
+  // later diagnostics are dropped instead of accumulating promises or handles.
+  if (activePiHookDiagnosticWrite) return;
+  let tracked: Promise<void>;
+  tracked = Promise.resolve()
+    .then(operation)
+    .catch(() => {})
+    .finally(() => {
+      if (activePiHookDiagnosticWrite === tracked) activePiHookDiagnosticWrite = undefined;
+    });
+  activePiHookDiagnosticWrite = tracked;
+
+  let deadline: ReturnType<typeof setTimeout> | undefined;
+  try {
+    await Promise.race([
+      tracked,
+      new Promise<void>((resolve) => {
+        deadline = setTimeout(resolve, piHookDiagnosticWriteDeadlineMilliseconds);
+      }),
+    ]);
+  } finally {
+    if (deadline !== undefined) clearTimeout(deadline);
+  }
+}
+
+function piHookDiagnosticPath(
+  environment: Record<string, string | undefined> = process.env,
+  lastDebugLogPathFile = "/tmp/cmux-last-debug-log-path",
+  fallbackLogPath = "/tmp/cmux-debug.log",
+): string {
+  const explicit = firstString(environment.CMUX_DEBUG_LOG);
+  if (explicit) return expandedPiHookLogPath(explicit, environment.HOME);
+
+  const socketPath = firstString(environment.CMUX_SOCKET_PATH, environment.CMUX_SOCKET);
+  if (socketPath) {
+    const socketName = path.basename(socketPath);
+    if (socketName.startsWith("cmux-debug-") && socketName.endsWith(".sock")) {
+      return path.join("/tmp", `${socketName.slice(0, -".sock".length)}.log`);
+    }
+  }
+
+  let pointerDescriptor: number | undefined;
+  try {
+    // The shared pointer is untrusted: inspect a nonblocking descriptor and
+    // bound the read so a special or oversized file cannot stall Pi.
+    pointerDescriptor = fs.openSync(
+      lastDebugLogPathFile,
+      fs.constants.O_RDONLY | fs.constants.O_NONBLOCK | fs.constants.O_NOFOLLOW,
+    );
+    if (isOwnedRegularPiHookFile(fs.fstatSync(pointerDescriptor))) {
+      const pointerContents = Buffer.alloc(4096);
+      const bytesRead = fs.readSync(
+        pointerDescriptor,
+        pointerContents,
+        0,
+        pointerContents.byteLength,
+        0,
+      );
+      const lastPath = firstString(pointerContents.subarray(0, bytesRead).toString("utf8"));
+      if (lastPath) return expandedPiHookLogPath(lastPath, environment.HOME);
+    }
+  } catch (_) {
+  } finally {
+    if (pointerDescriptor !== undefined) {
+      try { fs.closeSync(pointerDescriptor); } catch (_) {}
+    }
+  }
+  return fallbackLogPath;
+}
+
+async function appendPiHookDiagnostic(
+  payload: Record<string, unknown>,
+  environment: Record<string, string | undefined> = process.env,
+  lastDebugLogPathFile = "/tmp/cmux-last-debug-log-path",
+  fallbackLogPath = "/tmp/cmux-debug.log",
+): Promise<void> {
+  let line: string;
+  try {
+    line = JSON.stringify({ timestamp: new Date().toISOString(), ...payload });
+  } catch (_) {
+    line = JSON.stringify({
+      timestamp: new Date().toISOString(),
+      source: "cmux-pi-extension",
+      level: "warning",
+      message: "failed to serialize Pi hook diagnostic",
+      hook_name: "extension",
+      reason: "serialization-error",
+      timeout_ms: piHookTimeoutMilliseconds(),
+      elapsed_ms: 0,
+    });
+  }
+  try {
+    // Read/write permits checking the existing JSONL boundary, while O_NONBLOCK
+    // keeps special files such as a FIFO from stalling Pi's lifecycle queue.
+    const flags = fs.constants.O_RDWR
+      | fs.constants.O_APPEND
+      | fs.constants.O_CREAT
+      | fs.constants.O_NONBLOCK
+      | fs.constants.O_NOFOLLOW;
+    const handle = await fs.promises.open(
+      piHookDiagnosticPath(environment, lastDebugLogPathFile, fallbackLogPath),
+      flags,
+      0o600,
+    );
+    try {
+      const metadata = await handle.stat();
+      // cmux diagnostics are files; drop device, socket, and pipe destinations.
+      if (!isOwnedRegularPiHookFile(metadata)) return;
+      let prefix = "";
+      if (metadata.size > 0) {
+        const trailingByte = Buffer.alloc(1);
+        const { bytesRead } = await handle.read(trailingByte, 0, 1, metadata.size - 1);
+        if (bytesRead !== 1 || trailingByte[0] !== 0x0a) prefix = "\n";
+      }
+      await handle.writeFile(`${prefix}${line}\n`, "utf8");
+    } finally {
+      try { await handle.close(); } catch (_) {}
+    }
+  } catch (_) {}
+}
+
+function commandFailureDetails(
+  args: string[],
+  result: CommandResult,
+): Record<string, unknown> {
+  return {
+    hook_name: piHookName(args),
+    reason: result.reason || commandFailureReason(result.status, result.error) || "spawn-error",
+    timeout_ms: result.timeoutMs,
+    elapsed_ms: result.elapsedMs,
+    status: result.status,
+    stderr_available: result.stderr.trim().length > 0,
+    error_available: result.error !== undefined,
+  };
+}
+"""#
+}
@@ -335,7 +335,7 @@ class PiCmuxCommandDispatcher {
            this.failTerminalFeedForSession(sessionId);
            this.discardFeedForSession(sessionId);
          }
-        } else if (result.error instanceof Error && result.error.message.includes("timed out after")) {
+        } else if (result.reason === "timeout") {
          const sessionId = command.context.sessionId;
          if (sessionId) {
            this.failTerminalFeedForSession(sessionId);
@@ -367,18 +367,20 @@ class PiCmuxCommandDispatcher {
    }

    const result = await this.spawnCmux(args, cwd, input, cancellation);
-    if (this.isSurfaceResolutionFailure(result)) {
-      const shouldWarn = !sessionId || !this.unavailableSessions.has(sessionId);
-      if (sessionId) this.unavailableSessions.add(sessionId);
-      if (shouldWarn) {
-        warn(context, "cmux hook command failed", {
-          status: result.status,
-          stderr_available: result.stderr.trim().length > 0,
-          error_available: result.error !== undefined,
-          surface_unavailable: true,
-          dispatch_disabled: true,
-        });
-      }
+    const surfaceUnavailable = this.isSurfaceResolutionFailure(result);
+    let shouldLogFailure = true;
+    if (surfaceUnavailable && sessionId) {
+      // Claim synchronously so overlapping Feed/control failures emit one diagnostic.
+      shouldLogFailure = !this.unavailableSessions.has(sessionId);
+      this.unavailableSessions.add(sessionId);
+    }
+    if (!result.ok && result.reason !== "cancelled" && shouldLogFailure) {
+      await warn(context, "cmux hook command failed", {
+        ...commandFailureDetails(args, result),
+        ...(surfaceUnavailable ? { surface_unavailable: true, dispatch_disabled: true } : {}),
+      });
+    }
+    if (surfaceUnavailable) {
      return { ...result, surfaceUnavailable: true };
    }
    return result;
@@ -391,6 +393,8 @@ class PiCmuxCommandDispatcher {
    cancellation?: PiCommandCancellation,
  ): Promise<CommandResult> {
    return new Promise<CommandResult>((resolve) => {
+      const startedAt = performance.now();
+      const timeoutMs = piCommandTimeoutMilliseconds(args);
      let settled = false;
      let stdout = "";
      let stderr = "";
@@ -399,6 +403,7 @@ class PiCmuxCommandDispatcher {
      let terminateGrace: ReturnType<typeof setTimeout> | null = null;
      let forceSettleTimeout: ReturnType<typeof setTimeout> | null = null;
      let terminationError: Error | undefined;
+      let terminationReason: CommandTerminationReason | undefined;

      const appendOutput = (current: string, chunk: unknown): string => {
        const limit = 1024 * 1024;
@@ -414,12 +419,18 @@ class PiCmuxCommandDispatcher {
        if (cancellation) cancellation.cancel = undefined;
        resolve(result);
      };
+      const elapsedMilliseconds = (): number => (
+        Math.max(0, Math.round(performance.now() - startedAt))
+      );
      const terminatedResult = (): CommandResult => ({
        ok: false,
        status: null,
        stdout,
        stderr,
        error: terminationError,
+        reason: commandFailureReason(null, terminationError, terminationReason),
+        timeoutMs,
+        elapsedMs: elapsedMilliseconds(),
      });

      try {
@@ -438,9 +449,10 @@ class PiCmuxCommandDispatcher {
        child.stdin.on("error", (error) => {
          inputError = error;
        });
-        const beginTermination = (error: Error) => {
+        const beginTermination = (reason: CommandTerminationReason, error: Error) => {
          if (terminationError) return;
          terminationError = error;
+          terminationReason = reason;
          child.stdin.destroy();
          try {
            child.kill("SIGTERM");
@@ -458,7 +470,16 @@ class PiCmuxCommandDispatcher {
          }, 250);
        };
        child.on("error", (error) => {
-          settle(terminationError ? terminatedResult() : { ok: false, status: null, stdout, stderr, error });
+          settle(terminationError ? terminatedResult() : {
+            ok: false,
+            status: null,
+            stdout,
+            stderr,
+            error,
+            reason: commandFailureReason(null, error),
+            timeoutMs,
+            elapsedMs: elapsedMilliseconds(),
+          });
        });
        child.on("close", (code) => {
          if (terminationError) {
@@ -466,24 +487,38 @@ class PiCmuxCommandDispatcher {
            return;
          }
          const status = typeof code === "number" ? code : null;
+          const error = inputError;
+          const reason = commandFailureReason(status, error);
          settle({
-            ok: status === 0 && inputError === undefined,
+            ok: reason === undefined,
            status,
            stdout,
            stderr,
-            error: inputError,
+            error,
+            reason,
+            timeoutMs,
+            elapsedMs: elapsedMilliseconds(),
          });
        });
        if (cancellation) {
-          cancellation.cancel = () => beginTermination(new Error("cmux feed command cancelled"));
+          cancellation.cancel = () => beginTermination("cancelled", new Error("cmux feed command cancelled"));
          if (cancellation.cancelled) cancellation.cancel();
        }
        timeout = setTimeout(() => {
-          beginTermination(new Error("cmux command timed out after 5000ms"));
-        }, 5000);
+          beginTermination("timeout", new Error(`cmux command timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
        child.stdin.end(input);
      } catch (error) {
-        settle({ ok: false, status: null, stdout, stderr, error });
+        settle({
+          ok: false,
+          status: null,
+          stdout,
+          stderr,
+          error,
+          reason: commandFailureReason(null, error),
+          timeoutMs,
+          elapsedMs: elapsedMilliseconds(),
+        });
      }
    });
  }
@@ -498,6 +533,8 @@ class PiCmuxCommandDispatcher {
      status: null,
      stdout: "",
      stderr: "",
+      timeoutMs: piHookTimeoutMilliseconds(),
+      elapsedMs: 0,
      surfaceUnavailable: true,
    };
  }
@@ -1,6 +1,6 @@
 extension CMUXCLI {
    static let piExtensionSourcePart1 = #"""
-// cmux-pi-session-extension-marker v2
+// cmux-pi-session-extension-marker v3
 // Bridges Pi session lifecycle, tool telemetry, notifications, and resume bindings into cmux.
 // Installed by `cmux hooks pi install` or `cmux hooks setup`.
 // DO NOT EDIT MANUALLY. cmux upgrades this file in place.
@@ -34,13 +34,15 @@ interface CommandResult {
  stdout: string;
  stderr: string;
  error?: unknown;
+  reason?: CommandFailureReason;
+  timeoutMs: number;
+  elapsedMs: number;
  surfaceUnavailable?: boolean;
 }

 interface PiExtensionContextSnapshot {
  readonly sessionId: string | null;
  readonly cwd: string;
-  readonly notifyWarning?: () => void;
 }

 function firstString(...values: unknown[]): string | null {
@@ -348,6 +350,7 @@ function safeCmuxEnvKey(key: string): boolean {
  if (key.startsWith("CMUX_AGENT_LAUNCH_")) return !secretLikeEnvKey(key);
  if (key === "CMUX_AGENT_HOOK_STATE_DIR") return true;
  if (key === "CMUX_PI_CMUX_BIN" || key === "CMUX_PI_HOOKS_DISABLED") return true;
+  if (key === "CMUX_PI_HOOK_TIMEOUT_MS") return true;
  if (key === "CMUX_SURFACE_ID" || key === "CMUX_WORKSPACE_ID" || key === "CMUX_WINDOW_ID") return true;
  if (key === "CMUX_PANE_ID" || key === "CMUX_TAB_ID" || key === "CMUX_PANEL_ID") return true;
  if (key === "CMUX_SOCKET" || key === "CMUX_SOCKET_PATH") return true;
@@ -460,17 +463,9 @@ function cwdFrom(ctx: ExtensionContext): string {
 }

 function snapshotContext(ctx: ExtensionContext): PiExtensionContextSnapshot {
-  let notifyWarning: (() => void) | undefined;
-  try {
-    const ui = (ctx as unknown as { ui?: { notify?: (message: string, type?: string) => void } }).ui;
-    if (typeof ui?.notify === "function") {
-      notifyWarning = () => ui.notify?.("cmux Pi integration warning - check the terminal for details", "warning");
-    }
-  } catch (_) {}
  return {
    sessionId: sessionIdFrom(ctx),
    cwd: cwdFrom(ctx),
-    notifyWarning,
  };
 }

@@ -528,26 +523,20 @@ function settleTurn(sessionStates: Map<string, SessionState>, sessionId: string)
  return completion;
 }

-function warn(
-  ctx: PiExtensionContextSnapshot | null,
+async function warn(
+  _ctx: PiExtensionContextSnapshot | null,
  message: string,
  details: Record<string, unknown> = {},
-  notifyUser = false,
-): void {
-  const payload = { source: "cmux-pi-extension", level: "warning", message, ...details };
-  try {
-    console.warn(JSON.stringify(payload));
-  } catch (_) {
-    console.warn(`[cmux-pi-extension] ${message}`);
-  }
-  // Hook transport is best-effort telemetry. Keep routine command failures in
-  // the terminal instead of interrupting Pi with a generic toast; reserve the
-  // UI warning for an unexpected extension-task exception.
-  if (notifyUser) {
-    try {
-      ctx?.notifyWarning?.();
-    } catch (_) {}
-  }
+): Promise<void> {
+  const payload = {
+    source: "cmux-pi-extension",
+    level: "warning",
+    message,
+    hook_name: "extension",
+    reason: "extension-error",
+    ...details,
+  };
+  await runPiHookDiagnosticWrite(() => appendPiHookDiagnostic(payload));
 }

 function cmuxExecutable(): string {
@@ -27,14 +27,6 @@ async function sendHook(
    context,
  );
  if (result.ok) rememberSurfaceTarget(dispatcher, sessionId, result);
-  if (!result.ok && !result.surfaceUnavailable) {
-    warn(context, "cmux hook command failed", {
-      subcommand,
-      status: result.status,
-      stderr_available: result.stderr.trim().length > 0,
-      error_available: result.error !== undefined,
-    });
-  }
  return result.ok;
 }

@@ -206,14 +198,7 @@ async function ensureResumeBinding(
    "--",
    ...resumeArgv,
  ], cwd, undefined, context);
-  if (!set.ok && !set.surfaceUnavailable) {
-    warn(context, "failed to set Pi resume binding", {
-      status: set.status,
-      stderr_available: set.stderr.trim().length > 0,
-      error_available: set.error !== undefined,
-    });
-    return;
-  }
+  if (!set.ok && !set.surfaceUnavailable) return;
  if (set.surfaceUnavailable) return;

  const verification = await dispatcher.run(
@@ -225,7 +210,11 @@ async function ensureResumeBinding(
  if (verification.surfaceUnavailable) return;
  const verified = parseJSONOutput(verification);
  if (!resumeBindingMatches(verified, sessionId)) {
-    warn(context, "Pi resume binding did not verify after write", { session_id: sessionId });
+    await warn(context, "Pi resume binding did not verify after write", {
+      session_id: sessionId,
+      hook_name: "surface-resume-get",
+      reason: "verification-failure",
+    });
  }
 }

@@ -238,7 +227,7 @@ async function clearResumeBinding(
  const target = surfaceTargetArgs(dispatcher, sessionId);
  if (!target) return;
  const cwd = context.cwd;
-  const result = await dispatcher.run([
+  await dispatcher.run([
    "--json",
    "surface",
    "resume",
@@ -249,14 +238,6 @@ async function clearResumeBinding(
    "--source",
    "agent-hook",
  ], cwd, undefined, context);
-  if (result.surfaceUnavailable) return;
-  if (!result.ok) {
-    warn(context, "failed to clear Pi resume binding", {
-      status: result.status,
-      stderr_available: result.stderr.trim().length > 0,
-      error_available: result.error !== undefined,
-    });
-  }
 }

 type PiFeedEventName =
@@ -341,6 +322,17 @@ function prepareFeedDispatch(
  };
 }

+async function warnFeedDeliveryDropped(
+  context: PiExtensionContextSnapshot,
+  sessionId: string,
+): Promise<void> {
+  await warn(context, "cmux feed delivery dropped", {
+    session_id: sessionId,
+    hook_name: "feed",
+    reason: "dispatch-dropped",
+  });
+}
+
 async function publishPendingCompletion(
  dispatcher: PiCmuxCommandDispatcher,
  sessionStates: Map<string, SessionState>,
@@ -352,9 +344,7 @@ async function publishPendingCompletion(
  const state = stateFor(sessionStates, sessionId);
  const feedDelivered = !state.feedDeliveryFailed;
  state.feedDeliveryFailed = false;
-  if (!feedDelivered) {
-    warn(context, "cmux hook command failed", { session_id: sessionId });
-  }
+  if (!feedDelivered) await warnFeedDeliveryDropped(context, sessionId);
  const stopPayload: HookExtra = {
    last_assistant_message: completion.lastAssistantMessage,
    turn_id: completion.turnId,
@@ -374,34 +364,77 @@ async function publishPendingCompletion(
  await sendHook(dispatcher, "stop", context, stopPayload);
 }

-export default function cmuxPiSessionExtension(pi: ExtensionAPI) {
-  const dispatcher = new PiCmuxCommandDispatcher();
-  const sessionStates = new Map<string, SessionState>();
-  const lifecycleTails = new Map<string, Promise<void>>();
+// A stalled lifecycle hook may run for its full configured timeout while Pi
+// keeps emitting tool events. Bound the pending tasks a session can stack
+// behind it so bursts cannot pin unbounded event payloads: droppable Feed
+// preparation is shed first and surfaces as a dropped delivery at completion.
+const maximumPiLifecycleBacklogTasks = 32;

-  const enqueueLifecycleTask = (
+interface PiLifecycleQueue {
+  enqueue(
+    sessionId: string,
+    context: PiExtensionContextSnapshot,
+    operation: () => Promise<unknown> | unknown,
+  ): Promise<void>;
+  tryEnqueue(
+    sessionId: string,
+    context: PiExtensionContextSnapshot,
+    operation: () => Promise<unknown> | unknown,
+  ): boolean;
+}
+
+function createPiLifecycleQueue(): PiLifecycleQueue {
+  const tails = new Map<string, Promise<void>>();
+  const pendingCounts = new Map<string, number>();
+  const enqueue = (
    sessionId: string,
    context: PiExtensionContextSnapshot,
    operation: () => Promise<unknown> | unknown,
  ): Promise<void> => {
-    const previous = lifecycleTails.get(sessionId) || Promise.resolve();
+    pendingCounts.set(sessionId, (pendingCounts.get(sessionId) || 0) + 1);
+    const previous = tails.get(sessionId) || Promise.resolve();
    let tracked: Promise<void>;
    tracked = previous
      .then(operation)
      .then(() => undefined)
      .catch((error) => {
        const errorMessage = error instanceof Error ? error.message : undefined;
-        warn(context, "cmux lifecycle task failed", {
+        return warn(context, "cmux lifecycle task failed", {
+          hook_name: "lifecycle-task",
+          reason: "extension-error",
          error_available: error !== undefined,
          error_message: utf8Prefix(errorMessage, 512),
-        }, true);
+        });
      })
      .finally(() => {
-        if (lifecycleTails.get(sessionId) === tracked) lifecycleTails.delete(sessionId);
+        const remaining = (pendingCounts.get(sessionId) || 1) - 1;
+        if (remaining > 0) pendingCounts.set(sessionId, remaining);
+        else pendingCounts.delete(sessionId);
+        if (tails.get(sessionId) === tracked) tails.delete(sessionId);
      });
-    lifecycleTails.set(sessionId, tracked);
+    tails.set(sessionId, tracked);
    return tracked;
  };
+  return {
+    enqueue,
+    tryEnqueue(sessionId, context, operation) {
+      if ((pendingCounts.get(sessionId) || 0) >= maximumPiLifecycleBacklogTasks) return false;
+      void enqueue(sessionId, context, operation);
+      return true;
+    },
+  };
+}
+
+export default function cmuxPiSessionExtension(pi: ExtensionAPI) {
+  const dispatcher = new PiCmuxCommandDispatcher();
+  const sessionStates = new Map<string, SessionState>();
+  const lifecycleTasks = createPiLifecycleQueue();
+
+  const enqueueLifecycleTask = (
+    sessionId: string,
+    context: PiExtensionContextSnapshot,
+    operation: () => Promise<unknown> | unknown,
+  ): Promise<void> => lifecycleTasks.enqueue(sessionId, context, operation);

  pi.on("session_start", (_event, ctx) => {
    const context = snapshotContext(ctx);
@@ -439,7 +472,10 @@ export default function cmuxPiSessionExtension(pi: ExtensionAPI) {
    if (!sessionId) return;
    const dispatch = prepareFeedDispatch(dispatcher, sessionStates, eventName, context, event);
    if (!dispatch) return;
-    enqueueLifecycleTask(sessionId, context, dispatch);
+    if (!lifecycleTasks.tryEnqueue(sessionId, context, dispatch)) {
+      // A shed completion must fail visibly instead of reporting delivery.
+      if (isTerminalFeedEvent(eventName)) stateFor(sessionStates, sessionId).feedDeliveryFailed = true;
+    }
  };

  pi.on("tool_execution_start", (event, ctx) => {
@@ -513,7 +549,7 @@ export default function cmuxPiSessionExtension(pi: ExtensionAPI) {
      await dispatcher.finishFeedForSession(sessionId);
      const feedDelivered = !state.feedDeliveryFailed;
      state.feedDeliveryFailed = false;
-      if (!feedDelivered) warn(context, "cmux hook command failed", { session_id: sessionId });
+      if (!feedDelivered) await warnFeedDeliveryDropped(context, sessionId);
      if (stopPayload) await sendHook(dispatcher, "stop", context, stopPayload);
      try {
        await clearResumeBinding(dispatcher, context, sessionId);
@@ -26,6 +26,9 @@ extension CMUXCLI {
        if let environment = command.environment {
            payload["environment"] = environment
        }
+        if let verificationHome = command.verificationHome {
+            payload["verification_home"] = verificationHome
+        }
        if let capturedAt = command.capturedAt {
            payload["captured_at"] = capturedAt
        }
@@ -80,7 +83,7 @@ extension CMUXCLI {
                )
            )
        }
-        let record = try restoreRecord(from: rawRecord)
+        var record = try restoreRecord(from: rawRecord)
        if let expectedKind = selector.kind, expectedKind != record.kind {
            throw loggedRestoreError(
                stage: "record.kind-mismatch",
@@ -103,6 +106,14 @@ extension CMUXCLI {
            )
        }

+        if let surfaceID = params["surface_id"] as? String {
+            record = try recoveredHermesRestoreRecord(
+                record,
+                surfaceID: surfaceID,
+                processEnvironment: processEnvironment
+            )
+        }
+
        let environment = processEnvironment.merging(record.environment) { _, restored in
            restored
        }
@@ -188,6 +199,54 @@ extension CMUXCLI {
        )
    }

+    /// Repairs transient Hermes TUI identities using hook process-generation
+    /// evidence and the durable Hermes state database.
+    private func recoveredHermesRestoreRecord(
+        _ record: RestoreRecord,
+        surfaceID: String,
+        processEnvironment: [String: String]
+    ) throws -> RestoreRecord {
+        guard record.kind == "hermes-agent",
+              let checkpointID = record.checkpointID,
+              let surfaceUUID = UUID(uuidString: surfaceID) else {
+            return record
+        }
+        var recoveryEnvironment = processEnvironment
+        recoveryEnvironment.merge(record.environment) { _, restored in restored }
+        if let captured = record.launchCommand?.environment {
+            recoveryEnvironment.merge(captured) { _, restored in restored }
+        }
+        let hookStatePath = agentHookStatePath(
+            sessionStoreSuffix: "hermes-agent",
+            env: processEnvironment
+        )
+        switch HermesLegacySessionIdentityRecovery().resolve(
+            surfaceID: surfaceUUID,
+            corruptSessionID: checkpointID,
+            expectedWorkingDirectory: record.workingDirectory
+                ?? record.launchCommand?.workingDirectory,
+            hookStateFileURL: URL(fileURLWithPath: hookStatePath),
+            environment: recoveryEnvironment
+        ) {
+        case .valid, .legacyRestore, .unavailable:
+            return record
+        case .missing:
+            throw loggedRestoreError(
+                stage: "hermes.checkpoint.missing",
+                detail: checkpointID,
+                message: String(
+                    localized: "cli.restore.error.noRecord",
+                    defaultValue: "restore: this session has nothing to restore. Start the agent again in this terminal."
+                )
+            )
+        case .recovered(let candidate):
+            return record.repairingHermesCheckpoint(
+                candidate.sessionID,
+                fallbackLaunchCommand: candidate.launchCommand
+            )
+        }
+    }
+
    private func currentRestoreSurfaceID(
        client: SocketClient,
        processEnvironment: [String: String]
@@ -445,6 +504,7 @@ extension CMUXCLI {
            arguments: arguments,
            workingDirectory: object["working_directory"] as? String,
            environment: object["environment"] as? [String: String],
+            verificationHome: object["verification_home"] as? String,
            capturedAt: (object["captured_at"] as? NSNumber)?.doubleValue,
            source: object["source"] as? String
        )
@@ -14,5 +14,24 @@ extension CMUXCLI {
        let preparedArgumentsWorkingDirectory: String?
        let permissionMode: String?
        let legacyCommand: String?
+
+        func repairingHermesCheckpoint(
+            _ checkpointID: String,
+            fallbackLaunchCommand: AgentLaunchCommand?
+        ) -> RestoreRecord {
+            RestoreRecord(
+                mode: mode,
+                kind: kind,
+                checkpointID: checkpointID,
+                source: source,
+                workingDirectory: workingDirectory,
+                environment: environment,
+                launchCommand: launchCommand ?? fallbackLaunchCommand,
+                preparedArguments: nil,
+                preparedArgumentsWorkingDirectory: nil,
+                permissionMode: permissionMode,
+                legacyCommand: legacyCommand
+            )
+        }
    }
 }
@@ -130,72 +130,70 @@ extension CMUXCLI {
        surfaceID: String?,
        sessionID: String,
        lifecycleID: String,
+        reconciliationConfirmedSessionEnded: inout Bool,
        intentionalOnly: Bool,
-        sessionRunningExitCode: SSHPTYAttachExitCode = .bridgeClosedSessionRunning
+        sessionRunningExitCode: SSHPTYAttachExitCode = .bridgeClosedSessionRunning,
+        reconciliationUnavailableExitCode: SSHPTYAttachExitCode = .retryableTransient
    ) throws -> Bool {
-        let reconciliationFailure = "ssh-pty-attach: bridge closed before remote PTY exit could be confirmed"
-        let response: [String: Any]
-        do {
-            var params: [String: Any] = [
-                "workspace_id": workspaceId,
-                "session_id": sessionID,
-                "lifecycle_id": lifecycleID,
-                "acknowledge_lifecycle_if_session_absent": !intentionalOnly,
-            ]
-            if let surfaceID {
-                params["surface_id"] = surfaceID
-                params["allow_moved_surface"] = true
-            }
-            response = try client.sendV2(method: "workspace.remote.pty_sessions", params: params)
-        } catch {
-            throw CLIError(
-                message: "\(reconciliationFailure): \(userFacingRemotePTYErrorMessage(error))",
-                exitCode: SSHPTYAttachExitCode.retryableTransient
-            )
+        var params: [String: Any] = [
+            "workspace_id": workspaceId,
+            "session_id": sessionID,
+            "lifecycle_id": lifecycleID,
+            "acknowledge_lifecycle_if_session_absent": false,
+        ]
+        if let surfaceID {
+            params["surface_id"] = surfaceID
+            params["allow_moved_surface"] = true
        }

-        let requestedLifecycle = (response["requested_session_lifecycle"] as? String)?
-            .trimmingCharacters(in: .whitespacesAndNewlines)
-        let intentionalCleanup = requestedLifecycle == "intentional_cleanup_requested" ||
-            requestedLifecycle == "intentionally_closed"
-        guard let sessions = response["sessions"] as? [[String: Any]] else {
-            throw CLIError(message: reconciliationFailure, exitCode: SSHPTYAttachExitCode.retryableTransient)
-        }
-        let errors: [[String: Any]]
-        if let rawErrors = response["errors"] {
-            guard let parsedErrors = rawErrors as? [[String: Any]] else {
-                throw CLIError(message: reconciliationFailure, exitCode: SSHPTYAttachExitCode.retryableTransient)
-            }
-            errors = parsedErrors
-        } else {
-            errors = []
-        }
-        if !intentionalCleanup, !errors.isEmpty {
-            throw CLIError(
-                message: "\(reconciliationFailure)\n\(sshSessionListFailureMessage(errors))",
-                exitCode: SSHPTYAttachExitCode.retryableTransient
+        var reconciliation = try requestValidatedSSHPTYReconciliation(
+            client: client,
+            params: params,
+            unavailableExitCode: reconciliationUnavailableExitCode
+        )
+        if !intentionalOnly,
+           !reconciliation.intentionalCleanup,
+           !reconciliation.sessionIDs.contains(sessionID) {
+            // Keep the first liveness read side-effect free. Only after its
+            // response is validated may the server atomically recheck absence
+            // and acknowledge this exact lifecycle generation.
+            params["acknowledge_lifecycle_if_session_absent"] = true
+            reconciliation = try requestValidatedSSHPTYReconciliation(
+                client: client,
+                params: params,
+                unavailableExitCode: reconciliationUnavailableExitCode
            )
        }
-        if intentionalOnly, !intentionalCleanup { return false }
+        if intentionalOnly, !reconciliation.intentionalCleanup { return false }

-        let sessionStillRunning = sessions.contains {
-            (($0["session_id"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? "") == sessionID
-        }
-        if !intentionalCleanup, sessionStillRunning {
+        if !reconciliation.intentionalCleanup,
+           reconciliation.sessionIDs.contains(sessionID) {
            let message: String
            if sessionRunningExitCode == .bridgeClosedWithoutProgress {
                message = String(
                    localized: "cli.sshPtyAttach.bridgeClosedWithoutProgress",
-                    defaultValue: "ssh-pty-attach: bridge closed without receiving new output while the remote PTY session is still running"
+                    defaultValue: "ssh-pty-attach: bridge closed without receiving new output while the remote PTY session is still running",
+                    bundle: CLIExecutableLocator.enclosingAppBundle() ?? .main
+                )
+            } else if sshPTYAttachWrapperWillRetry(sessionRunningExitCode) {
+                message = String(
+                    localized: "cli.sshPtyAttach.bridgeClosedSessionRunningReconnecting",
+                    defaultValue: "The SSH terminal connection ended while the remote session is still running; cmux is reconnecting.",
+                    bundle: CLIExecutableLocator.enclosingAppBundle() ?? .main
                )
            } else {
-                message = "ssh-pty-attach: bridge closed while remote PTY session is still running"
+                message = String(
+                    localized: "cli.sshPtyAttach.bridgeClosedSessionRunning",
+                    defaultValue: "The SSH terminal connection ended; the remote session may still be running.",
+                    bundle: CLIExecutableLocator.enclosingAppBundle() ?? .main
+                )
            }
            throw CLIError(
                message: message,
                exitCode: sessionRunningExitCode
            )
        }
+        reconciliationConfirmedSessionEnded = true
        guard let surfaceID else { return true }
        do {
            _ = try client.sendV2(method: "workspace.remote.pty_attach_end", params: [
@@ -206,12 +204,117 @@ extension CMUXCLI {
        } catch {
            throw CLIError(
                message: "ssh-pty-attach: remote PTY exited but local session cleanup failed: \(userFacingRemotePTYErrorMessage(error))",
-                exitCode: SSHPTYAttachExitCode.retryableTransient
+                exitCode: SSHPTYAttachExitCode.fatal
            )
        }
        return true
    }

+    private func requestValidatedSSHPTYReconciliation(
+        client: SocketClient,
+        params: [String: Any],
+        unavailableExitCode: SSHPTYAttachExitCode
+    ) throws -> (intentionalCleanup: Bool, sessionIDs: [String]) {
+        let response: [String: Any]
+        do {
+            response = try client.sendV2(method: "workspace.remote.pty_sessions", params: params)
+        } catch {
+            throw CLIError(
+                message: sshPTYReconciliationUnavailableMessage(
+                    detail: userFacingRemotePTYErrorMessage(error)
+                ),
+                exitCode: unavailableExitCode
+            )
+        }
+        return try validatedSSHPTYReconciliation(
+            response,
+            unavailableExitCode: unavailableExitCode
+        )
+    }
+
+    private func validatedSSHPTYReconciliation(
+        _ response: [String: Any],
+        unavailableExitCode: SSHPTYAttachExitCode
+    ) throws -> (intentionalCleanup: Bool, sessionIDs: [String]) {
+        let requestedLifecycle: String?
+        if let rawRequestedLifecycle = response["requested_session_lifecycle"] {
+            guard let rawRequestedLifecycle = rawRequestedLifecycle as? String else {
+                throw CLIError(
+                    message: sshPTYReconciliationUnavailableMessage(detail: nil),
+                    exitCode: unavailableExitCode
+                )
+            }
+            let normalizedLifecycle = rawRequestedLifecycle
+                .trimmingCharacters(in: .whitespacesAndNewlines)
+            guard [
+                "active",
+                "intentional_cleanup_requested",
+                "intentionally_closed",
+            ].contains(normalizedLifecycle) else {
+                throw CLIError(
+                    message: sshPTYReconciliationUnavailableMessage(detail: nil),
+                    exitCode: unavailableExitCode
+                )
+            }
+            requestedLifecycle = normalizedLifecycle
+        } else {
+            requestedLifecycle = nil
+        }
+        let intentionalCleanup = requestedLifecycle == "intentional_cleanup_requested" ||
+            requestedLifecycle == "intentionally_closed"
+        guard let sessions = response["sessions"] as? [[String: Any]] else {
+            throw CLIError(
+                message: sshPTYReconciliationUnavailableMessage(detail: nil),
+                exitCode: unavailableExitCode
+            )
+        }
+        let sessionIDs = sessions.compactMap { session -> String? in
+            guard let rawSessionID = session["session_id"] as? String else { return nil }
+            let normalizedSessionID = rawSessionID.trimmingCharacters(in: .whitespacesAndNewlines)
+            return normalizedSessionID.isEmpty ? nil : normalizedSessionID
+        }
+        guard sessionIDs.count == sessions.count else {
+            throw CLIError(
+                message: sshPTYReconciliationUnavailableMessage(detail: nil),
+                exitCode: unavailableExitCode
+            )
+        }
+        let errors: [[String: Any]]
+        if let rawErrors = response["errors"] {
+            guard let parsedErrors = rawErrors as? [[String: Any]] else {
+                throw CLIError(
+                    message: sshPTYReconciliationUnavailableMessage(detail: nil),
+                    exitCode: unavailableExitCode
+                )
+            }
+            errors = parsedErrors
+        } else {
+            errors = []
+        }
+        if !intentionalCleanup, !errors.isEmpty {
+            throw CLIError(
+                message: sshPTYReconciliationUnavailableMessage(
+                    detail: sshSessionListFailureMessage()
+                ),
+                exitCode: unavailableExitCode
+            )
+        }
+        return (intentionalCleanup, sessionIDs)
+    }
+
+    private func sshPTYReconciliationUnavailableMessage(detail: String?) -> String {
+        let message = String(
+            localized: "cli.sshPtyAttach.reconciliationUnavailableReattach",
+            defaultValue: "The SSH terminal connection ended before the remote session state could be confirmed; preserving the remote session for reconnection.",
+            bundle: CLIExecutableLocator.enclosingAppBundle() ?? .main
+        )
+        guard let detail = detail?.trimmingCharacters(in: .whitespacesAndNewlines),
+              !detail.isEmpty else {
+            return message
+        }
+        return "\(message): \(detail)"
+    }
+
    func readSSHPTYBridgeReady(fd: Int32) throws -> (attachmentToken: String, replayBytes: Int) {
        let maxStatusBytes = 4096
        // Bound only the pre-ready status wait: a bridge that accepts the TCP
@@ -1,19 +1,71 @@
+import CmuxFoundation
+import Darwin
 import Foundation

 extension CMUXCLI {
    func sshAutoReconnectNoteFormat() -> String {
-        let status = String(localized: "cli.ssh.autoReconnect.status", defaultValue: "[cmux] ssh exited with status %s; reconnecting (attempt %s/%s).")
-        let stopHint = String(localized: "cli.ssh.autoReconnect.stopHint", defaultValue: "[cmux] close this pane or press Ctrl-C to stop reconnecting.")
+        let bundle = CLIExecutableLocator.enclosingAppBundle() ?? .main
+        let status = String(localized: "cli.ssh.autoReconnect.status", defaultValue: "[cmux] ssh exited with status %s; reconnecting (attempt %s/%s).", bundle: bundle)
+        let stopHint = String(localized: "cli.ssh.autoReconnect.stopHint", defaultValue: "[cmux] close this pane or press Ctrl-C to stop reconnecting.", bundle: bundle)
        return "\\n\\033[33m\(status)\\033[0m\\n\\033[2m\(stopHint)\\033[0m\\n"
    }

    func sshManualReconnectExitPromptFormat() -> String {
-        let status = String(localized: "cli.ssh.manualReconnectPrompt.status", defaultValue: "[cmux] ssh exited with status %s.")
-        let detail = String(localized: "cli.ssh.manualReconnectPrompt.detail", defaultValue: "[cmux] the remote VM may have been paused, destroyed, or lost network.")
-        let prompt = String(localized: "cli.ssh.manualReconnectPrompt.prompt", defaultValue: "[cmux] press Enter to close this pane. Press r then Enter to reconnect.")
+        let bundle = CLIExecutableLocator.enclosingAppBundle() ?? .main
+        let status = String(localized: "cli.ssh.manualReconnectPrompt.status", defaultValue: "[cmux] ssh exited with status %s.", bundle: bundle)
+        let detail = String(localized: "cli.ssh.manualReconnectPrompt.detail", defaultValue: "[cmux] the SSH connection ended; the remote session may still be running.", bundle: bundle)
+        let prompt = String(localized: "cli.ssh.manualReconnectPrompt.prompt", defaultValue: "[cmux] press Enter to close this pane. Press r then Enter to reconnect.", bundle: bundle)
        return "\\n\\033[31m\(status)\\033[0m\\n\\033[2m\(detail)\\033[0m\\n\\033[2m\(prompt)\\033[0m\\n"
    }

+    func sshTerminalExitPromptFormat() -> String {
+        let bundle = CLIExecutableLocator.enclosingAppBundle() ?? .main
+        let status = String(localized: "cli.ssh.manualReconnectPrompt.status", defaultValue: "[cmux] ssh exited with status %s.", bundle: bundle)
+        let detail = String(localized: "cli.ssh.manualReconnectPrompt.detail", defaultValue: "[cmux] the SSH connection ended; the remote session may still be running.", bundle: bundle)
+        let prompt = String(localized: "cli.ssh.terminalExitPrompt.prompt", defaultValue: "[cmux] press Enter to close this pane.", bundle: bundle)
+        return "\\n\\033[31m\(status)\\033[0m\\n\\033[2m\(detail)\\033[0m\\n\\033[2m\(prompt)\\033[0m\\n"
+    }
+
+    /// Waits for a post-failure Enter without accepting queued terminal reports.
+    func runSSHTerminalExitPrompt(commandArgs _: [String]) {
+        var original = termios()
+        guard tcgetattr(STDIN_FILENO, &original) == 0 else {
+            parkSSHTerminalExitPromptAfterEOF()
+        }
+
+        var promptMode = original
+        cfmakeraw(&promptMode)
+        promptMode.c_lflag |= tcflag_t(ISIG)
+        // Changing mode and flushing are one terminal operation: no byte queued
+        // before this prompt boundary can later be mistaken for a fresh Enter.
+        guard tcsetattr(STDIN_FILENO, TCSAFLUSH, &promptMode) == 0 else {
+            parkSSHTerminalExitPromptAfterEOF()
+        }
+        defer { _ = tcsetattr(STDIN_FILENO, TCSANOW, &original) }
+
+        var inputFilter = SSHTerminalExitPromptInputFilter()
+        var buffer = [UInt8](repeating: 0, count: 256)
+        while true {
+            let count = Darwin.read(STDIN_FILENO, &buffer, buffer.count)
+            if count > 0 {
+                if inputFilter.consume(Data(buffer.prefix(count))) {
+                    return
+                }
+            } else if count == 0 {
+                parkSSHTerminalExitPromptAfterEOF()
+            } else if errno != EINTR {
+                parkSSHTerminalExitPromptAfterEOF()
+            }
+        }
+    }
+
+    /// Keeps a dead input bridge from dismissing the pane while remaining signal-interruptible.
+    private func parkSSHTerminalExitPromptAfterEOF() -> Never {
+        while true {
+            _ = Darwin.pause()
+        }
+    }
+
    func sshRemoteReconnectShellFunction() -> String {
        [
            "cmux_ssh_remote_reconnect() {",
@@ -301,7 +301,17 @@ extension CMUXCLI {
        let trimmedOneTimeCommand = oneTimeCommand?.trimmingCharacters(in: .whitespacesAndNewlines)
        let hasOneTimeCommand = trimmedOneTimeCommand?.isEmpty == false
        let authRetryPolicy = SSHForegroundAuthenticationRetryPolicy()
+        let authenticationResult = authRetryPolicy.persistentAuthenticationResultShellLine(
+            variablePrefix: "cmux_ssh",
+            terminalFailureCommand: "break"
+        )
        let backoffBuilder = SSHRetryBackoffScriptBuilder(context: .startup)
+        let terminalModeReset = shellQuote(SSHTerminalModeResetSequence().shellPrintfFormat)
+        let terminalExitPrompt = shellQuote(sshTerminalExitPromptFormat())
+        let terminalExitPromptCommand = [
+            shellQuote(resolvedExecutableURL()?.path ?? (args.first ?? "cmux")),
+            "__ssh-terminal-exit-prompt",
+        ].joined(separator: " ")
        var scriptLines: [String] = []
        if !shellFeaturesBootstrap.isEmpty {
            scriptLines.append(shellFeaturesBootstrap)
@@ -363,11 +373,13 @@ extension CMUXCLI {
        ] + reconnectConfiguration + [
            "cmux_ssh_retry=0",
            "cmux_ssh_auth_retry_limit=\(authRetryPolicy.maximumConsecutiveTransientFailures); cmux_ssh_auth_retry=0",
+            "cmux_ssh_auth_succeeded=0",
            // Initial transient foreground-auth failures are a reconnect phase, so boot-time outages share this loop.
            "cmux_ssh_reauth_required=\(hasOneTimeCommand ? 1 : 0)",
            "CMUX_SSH_CHILD_PID=; CMUX_SSH_AUTH_PID=; CMUX_SSH_PENDING_SIGNAL=; CMUX_SSH_PENDING_SIGNAL_NAME=",
        ] + backoffBuilder.stateInitializationLines + [
            "cmux_ssh_note() { if [ -t 2 ]; then printf \"$@\" >&2 || true; fi; }",
+            "cmux_ssh_reset_terminal_modes() { if [ -t 2 ]; then printf \(terminalModeReset) >&2 || true; fi; }",
            "cmux_ssh_register_attempt() { \(lifecycleLaunching); }",
            "cmux_ssh_begin_attempt() { CMUX_SSH_ATTEMPT_ID=$(/usr/bin/uuidgen | /usr/bin/tr '[:upper:]' '[:lower:]') || return 1; export CMUX_SSH_ATTEMPT_ID; cmux_ssh_attempt_registration_retry=0; while ! cmux_ssh_register_attempt; do cmux_ssh_attempt_registration_retry=$((cmux_ssh_attempt_registration_retry + 1)); if [ \"$cmux_ssh_attempt_registration_retry\" -ge 3 ]; then return 1; fi; /bin/sleep 0.1; done; }",
            "cmux_ssh_session_end() { if [ \"${CMUX_SSH_SESSION_ENDED:-0}\" = 1 ]; then return; fi; CMUX_SSH_SESSION_ENDED=1; cmux_ssh_cleanup_password; \(lifecycleCleanup); }",
@@ -382,7 +394,7 @@ extension CMUXCLI {
        ]
        if hasOneTimeCommand {
            scriptLines.append("  if [ \"$cmux_ssh_reauth_required\" -eq 1 ]; then")
-            scriptLines += ["    ( cmux_ssh_foreground_auth ) <&0 &", "    CMUX_SSH_AUTH_PID=$!; if [ -n \"${CMUX_SSH_PENDING_SIGNAL:-}\" ]; then cmux_ssh_signal_exit \"$CMUX_SSH_PENDING_SIGNAL\" \"${CMUX_SSH_PENDING_SIGNAL_NAME:-TERM}\"; fi; wait \"$CMUX_SSH_AUTH_PID\"; cmux_ssh_status=$?; CMUX_SSH_AUTH_PID=; case \"$cmux_ssh_status\" in 129|130|143) cmux_ssh_retire_for_signal \"$cmux_ssh_status\" ;; esac; if [ -n \"${CMUX_SSH_PENDING_SIGNAL:-}\" ]; then cmux_ssh_session_end; trap - EXIT HUP INT TERM; exit \"$CMUX_SSH_PENDING_SIGNAL\"; fi", "    if [ \"$cmux_ssh_status\" -eq 0 ]; then cmux_ssh_reauth_required=0; cmux_ssh_auth_retry=0; else case \"$cmux_ssh_status\" in 254) cmux_ssh_auth_retry=$((cmux_ssh_auth_retry + 1)); if [ \"$cmux_ssh_auth_retry\" -ge \"$cmux_ssh_auth_retry_limit\" ]; then cmux_ssh_status=255; break; fi ;; \(authRetryPolicy.unclassifiedFailureExitStatus)) cmux_ssh_status=255; break ;; *) break ;; esac; fi", "  fi", "  if [ \"$cmux_ssh_reauth_required\" -eq 0 ]; then"]
+            scriptLines += ["    ( cmux_ssh_foreground_auth ) <&0 &", "    CMUX_SSH_AUTH_PID=$!; if [ -n \"${CMUX_SSH_PENDING_SIGNAL:-}\" ]; then cmux_ssh_signal_exit \"$CMUX_SSH_PENDING_SIGNAL\" \"${CMUX_SSH_PENDING_SIGNAL_NAME:-TERM}\"; fi; wait \"$CMUX_SSH_AUTH_PID\"; cmux_ssh_status=$?; CMUX_SSH_AUTH_PID=; case \"$cmux_ssh_status\" in 129|130|143) cmux_ssh_retire_for_signal \"$cmux_ssh_status\" ;; esac; if [ -n \"${CMUX_SSH_PENDING_SIGNAL:-}\" ]; then cmux_ssh_session_end; trap - EXIT HUP INT TERM; exit \"$CMUX_SSH_PENDING_SIGNAL\"; fi", "    \(authenticationResult)", "  fi", "  if [ \"$cmux_ssh_reauth_required\" -eq 0 ]; then"]
        }
        if let trimmedControlPathPreflight, !trimmedControlPathPreflight.isEmpty,
           !hasOneTimeCommand {
@@ -419,6 +431,7 @@ extension CMUXCLI {
            "  cmux_ssh_status=$?",
            "  CMUX_SSH_CHILD_PID=",
            "  if [ \"$cmux_ssh_status\" -eq 0 ]; then break; fi",
+            "  cmux_ssh_reset_terminal_modes",
            "  case \"$cmux_ssh_status\" in \(retryableStatusPattern)) ;; *) break ;; esac",
        ]
        if retryPTYAttachStatus {
@@ -436,6 +449,7 @@ extension CMUXCLI {
        scriptLines.append(retryLimitCondition)
        scriptLines += [
            "  cmux_ssh_retry=$((cmux_ssh_retry + 1))",
+            "  \(backoffBuilder.terminalInputModeResetLine)",
            "  cmux_ssh_note '\\n\\033[33m[cmux] ssh exited with status %s; reconnecting (attempt %s/%s).\\033[0m\\n\\033[2m[cmux] close this pane or press Ctrl-C to stop reconnecting.\\033[0m\\n' \"$cmux_ssh_status\" \"$cmux_ssh_retry\" \"$cmux_ssh_reconnect_limit\"",
        ]
        scriptLines += backoffBuilder.waitLines
@@ -448,8 +462,18 @@ extension CMUXCLI {
            "trap - EXIT HUP INT TERM",
            "cmux_ssh_session_end",
            "if [ \"$cmux_ssh_status\" -ne 0 ]; then",
-            "  printf '\\n\\033[31m[cmux] ssh exited with status %s.\\033[0m\\n\\033[2m[cmux] the remote VM may have been paused, destroyed, or lost network.\\033[0m\\n\\033[2m[cmux] press Enter to close this pane.\\033[0m\\n' \"$cmux_ssh_status\" >&2 || true",
-            "  IFS= read -r _cmux_dismiss_key 2>/dev/null || true",
+            "  \(backoffBuilder.terminalInputModeResetLine)",
+            "  cmux_ssh_prompt_tty_state=$(/bin/stty -g <&0 2>/dev/null || true)",
+            "  cmux_ssh_prompt_restore_tty() { if [ -n \"${cmux_ssh_prompt_tty_state:-}\" ]; then /bin/stty \"$cmux_ssh_prompt_tty_state\" <&0 2>/dev/null || true; cmux_ssh_prompt_tty_state=; fi; }",
+            "  cmux_ssh_prompt_signal_exit() { cmux_ssh_prompt_signal_status=\"$1\"; cmux_ssh_prompt_restore_tty; trap - EXIT HUP INT TERM; exit \"$cmux_ssh_prompt_signal_status\"; }",
+            "  trap 'cmux_ssh_prompt_restore_tty' EXIT",
+            "  trap 'cmux_ssh_prompt_signal_exit 129' HUP",
+            "  trap 'cmux_ssh_prompt_signal_exit 130' INT",
+            "  trap 'cmux_ssh_prompt_signal_exit 143' TERM",
+            "  printf \(terminalExitPrompt) \"$cmux_ssh_status\" >&2 || true",
+            "  if [ -t 0 ]; then \(terminalExitPromptCommand) <&0; else exec \(terminalExitPromptCommand) <&0; fi",
+            "  cmux_ssh_prompt_restore_tty",
+            "  trap - EXIT HUP INT TERM",
            "fi",
            "exit $cmux_ssh_status",
        ]
@@ -11,6 +11,11 @@ extension CMUXCLI {
        let surfaceId: String?
    }

+    struct ClaudeTeamsShimPlan {
+        let directory: URL
+        let managedClaudeWrapperURL: URL?
+    }
+
    func tmuxCompatResolvedSocketPath(processEnvironment: [String: String]) throws -> String {
        let envSocketPath = try CLISocketEnvironment.socketPath(in: processEnvironment)
        let bundleIdentifier = CLISocketPathResolver.currentAppBundleIdentifier()
@@ -19,21 +24,29 @@ extension CMUXCLI {
            environment: processEnvironment
        )
        let source: CLISocketPathSource
-        if let envSocketPath {
-            source = CLISocketPathResolver.isImplicitDefaultPath(
-                envSocketPath,
-                bundleIdentifier: bundleIdentifier,
-                environment: processEnvironment
-            ) ? .implicitDefault : .environment
+        if envSocketPath != nil {
+            // Environment overrides are explicit pins. Never reinterpret a
+            // stable-looking value as permission to select another instance.
+            source = .environment
        } else {
            source = .implicitDefault
        }
-        return CLISocketPathResolver.resolve(
-            requestedPath: requestedSocketPath,
-            source: source,
+        let resolver = CLISocketPathResolver(
            environment: processEnvironment,
            bundleIdentifier: bundleIdentifier
        )
+        let resolution = resolver.resolve(
+            requestedPath: requestedSocketPath,
+            source: source
+        )
+        guard resolution.hasLiveSocket else {
+            throw CLIError(message: resolution.failureMessage)
+        }
+        if source == .implicitDefault,
+           let rerouteNotice = resolution.rerouteNotice {
+            cliWriteStderr(rerouteNotice + "\n")
+        }
+        return resolution.selectedPath ?? requestedSocketPath
    }

    func tmuxCompatLaunchContext(
@@ -199,11 +212,11 @@ extension CMUXCLI {
        return environment
    }

-    func createClaudeTeamsShimDirectory(
+    func createClaudeTeamsShimPlan(
        processEnvironment: [String: String],
        commandArgs: [String],
        launchContext: TmuxCompatLaunchContext?
-    ) throws -> URL {
+    ) throws -> ClaudeTeamsShimPlan {
        let downstreamTmuxMissing = String(
            localized: "cli.tmux-compat.error.downstreamTmuxMissing",
            defaultValue: "cmux tmux shim: no downstream tmux executable found"
@@ -259,7 +272,11 @@ extension CMUXCLI {
                    script,
                    to: managedRoot.appendingPathComponent("tmux", isDirectory: false)
                )
-                return managedRoot
+                return ClaudeTeamsShimPlan(
+                    directory: managedRoot,
+                    managedClaudeWrapperURL: managedRoot
+                        .appendingPathComponent("claude", isDirectory: false)
+                )
            } catch {
                // Informational launches do not create teammates, so they may use the
                // launcher-only compatibility directory below. Real Teams sessions must
@@ -270,9 +287,12 @@ extension CMUXCLI {
        guard claudeTeamsIsNonLaunchInvocation(commandArgs: commandArgs) else {
            throw CLIError(message: managedTerminalRequiredMessage(displayName: "Claude Teams"))
        }
-        return try createTmuxCompatShimDirectory(
-            directoryName: "claude-teams-bin",
-            tmuxShimScript: script
+        return ClaudeTeamsShimPlan(
+            directory: try createTmuxCompatShimDirectory(
+                directoryName: "claude-teams-bin",
+                tmuxShimScript: script
+            ),
+            managedClaudeWrapperURL: nil
        )
    }

@@ -1,3 +1,4 @@
+import CMUXAgentLaunch
 import Foundation

 extension CMUXCLI {
@@ -76,26 +77,31 @@ extension CMUXCLI {
    /// the pane exits before the real command runs; that is why Claude Code
    /// 2.1.183 teammates never opened a split pane (issue #6447).
    ///
-    /// Every command is run through `/bin/sh -c '<command>'`, so Ghostty execs a
-    /// shell rather than a builtin/expression/assignment-prefix. The whole command
-    /// is single-quoted, so it round-trips verbatim regardless of operators or
-    /// quoting — there is no attempt to classify which commands "need" a shell,
-    /// which was unreliable (tmux shell-commands can hide operators with no
-    /// surrounding whitespace). Commands that are already a shell invocation (e.g.
-    /// OMO's `/bin/sh -c "…"`) are simply run through one more shell, which execs
-    /// straight into them.
+    /// Every command is run through `/bin/sh -lc '<command>'`, so Ghostty execs a
+    /// login shell rather than a builtin/expression/assignment-prefix. The `-l`
+    /// is important: Ghostty's `exec -l` only changes argv[0], and does not make
+    /// macOS `/bin/sh` read `/etc/profile` when it is given a non-interactive `-c`
+    /// command. The login shell therefore runs `path_helper` and restores the
+    /// user's full login PATH before the command starts (issue #10189). The whole
+    /// command is single-quoted, so it round-trips verbatim regardless of
+    /// operators or quoting — there is no attempt to classify which commands
+    /// "need" a shell, which was unreliable (tmux shell-commands can hide
+    /// operators with no surrounding whitespace). Commands that are already a
+    /// shell invocation (e.g. OMO's `/bin/sh -c "…"`) are simply run through one
+    /// more shell, which execs straight into them.
    ///
    /// A POSIX shell (`/bin/sh`) is used deliberately rather than the user's
    /// `$SHELL`: the commands being wrapped are POSIX `sh` syntax (Claude Code's
    /// `cd … && env …`, and the no-command fallback `exec ${SHELL:-/bin/sh} -l`),
-    /// and `csh`/`tcsh` login shells cannot parse `${VAR:-default}` parameter
-    /// expansion or `NAME=value` command prefixes. `/bin/sh` is always present and
-    /// runs the bodies correctly for every user. `-l` is not passed (`/bin/sh`
-    /// does not take it); on macOS Ghostty already supplies a login-style argv0.
+    /// and `csh`/`tcsh` cannot parse `${VAR:-default}` parameter expansion or
+    /// `NAME=value` command prefixes. `/bin/sh` is always present and runs the
+    /// bodies correctly for every user; its login mode is a shell-independent way to
+    /// invoke macOS `path_helper` without asking the user's shell to parse a
+    /// POSIX command body.
    func tmuxShellInvokedStartCommand(_ command: String) -> String {
        let trimmed = command.trimmingCharacters(in: .whitespacesAndNewlines)
        guard !trimmed.isEmpty else { return command }
-        return "/bin/sh -c \(tmuxShellQuote(trimmed))"
+        return "/bin/sh -lc \(tmuxShellQuote(trimmed))"
    }

    /// Like `tmuxShellInvokedStartCommand`, but first exports `prependEnv` inside
@@ -122,11 +128,14 @@ extension CMUXCLI {
    ///
    /// Teammate panes are respawned by cmux's surface layer, not by `cmux
    /// claude-teams`, so they do NOT inherit the launcher environment the lead
-    /// got from `configureClaudeTeamsEnvironment`. The one variable that matters
-    /// for startup is `CLAUDE_CODE_SANDBOXED`: Claude Code short-circuits its
-    /// interactive "Do you trust this folder?" gate on it, and a teammate that
-    /// hits that gate hangs forever (its pane opens but it never checks in —
-    /// issue #6447). Re-supply it so teammates start the same way the lead does.
+    /// got from `configureClaudeTeamsEnvironment`. The launcher records a
+    /// replay-safe snapshot in
+    /// ``ClaudeTeamsRespawnEnvironmentTransport/environmentKey``;
+    /// re-supply that snapshot so PATH-based tools and allowlisted Claude
+    /// configuration match the lead without copying secrets or surface identity.
+    /// `CLAUDE_CODE_SANDBOXED` is handled alongside it: Claude Code short-circuits
+    /// its interactive "Do you trust this folder?" gate on that variable, and a
+    /// teammate that hits the gate hangs forever (issue #6447).
    ///
    /// That trust gate is a real safety boundary, so it is only waived when the
    /// user already opted into skipping safety prompts. The opt-in is NOT inferred
@@ -146,10 +155,17 @@ extension CMUXCLI {
    /// it correctly falls back to Claude's trust prompt rather than silently bypassing
    /// the trust boundary outside an explicit opt-in.
    func tmuxClaudeTeamsRespawnEnvironment() -> [(key: String, value: String)] {
-        guard ProcessInfo.processInfo.environment["CMUX_CLAUDE_TEAMS_SANDBOXED"] == "1" else {
-            return []
+        let processEnvironment = ProcessInfo.processInfo.environment
+        let transport = ClaudeTeamsRespawnEnvironmentTransport()
+        var environment = transport.decodedEnvironment(
+            from: processEnvironment[ClaudeTeamsRespawnEnvironmentTransport.environmentKey]
+        )
+        if processEnvironment["CMUX_CLAUDE_TEAMS_SANDBOXED"] == "1" {
+            environment["CLAUDE_CODE_SANDBOXED"] = "1"
+        }
+        return environment.keys.sorted().compactMap { key in
+            environment[key].map { (key: key, value: $0) }
        }
-        return [(key: "CLAUDE_CODE_SANDBOXED", value: "1")]
    }

    func tmuxShellWords(_ commandText: String) -> [String] {
@@ -1,22 +1,13 @@
+import CmuxFoundation
 import Darwin
 import Foundation

 final class SSHPTYAttachReconnectInputFilter {
-    private static let escape: UInt8 = 0x1B
-    private static let bell: UInt8 = 0x07
-    private static let leftBracket: UInt8 = 0x5B
-    private static let rightBracket: UInt8 = 0x5D
-    private static let backslash: UInt8 = 0x5C
-    private static let semicolon: UInt8 = 0x3B
-    private static let questionMark: UInt8 = 0x3F
-    private static let dollar: UInt8 = 0x24
-    private static let maxPendingProbeBytes = 512
    // Terminal ESC disambiguation: bounded so a literal Escape key is not held indefinitely.
    private static let pendingProbeContinuationTimeoutMilliseconds: Int32 = 25
    private static let reconnectProbeDeadlineMilliseconds: Int64 = 2_000

-    private var isFiltering: Bool
-    private var pending = [UInt8]()
+    private var byteFilter: SSHPTYReconnectInputByteFilter
    private let deadlineReached: (@Sendable () -> Bool)?
    private let remainingDeadline: (@Sendable () -> Int64?)?

@@ -25,14 +16,13 @@ final class SSHPTYAttachReconnectInputFilter {
        deadlineReached: (@Sendable () -> Bool)? = nil,
        remainingDeadlineMilliseconds: (@Sendable () -> Int64?)? = nil
    ) {
-        isFiltering = enabled
+        byteFilter = SSHPTYReconnectInputByteFilter(enabled: enabled)
        self.deadlineReached = deadlineReached
        remainingDeadline = remainingDeadlineMilliseconds
    }

    private init(state: SSHPTYAttachReconnectInputFilterState) {
-        isFiltering = state.isFiltering
-        pending = state.pending
+        byteFilter = SSHPTYReconnectInputByteFilter(enabled: state.isFiltering)
        deadlineReached = state.deadlineReached
        remainingDeadline = state.remainingDeadlineMilliseconds
    }
@@ -52,7 +42,6 @@ final class SSHPTYAttachReconnectInputFilter {
        let filterState = filterEnabled
            ? SSHPTYAttachReconnectInputFilterState(
                isFiltering: true,
-                pending: [],
                deadlineReached: { deadline.map { now() >= $0 } ?? false },
                remainingDeadlineMilliseconds: {
                    guard let deadline else { return nil }
@@ -180,10 +169,10 @@ final class SSHPTYAttachReconnectInputFilter {
            return true
        }

-        func flushPendingThenShutdown() async {
-            if let filter = reconnectInputFilter, filter.hasPendingInput {
-                _ = await writeOrShutdown(filter.flushPendingInput())
-            }
+        func finishStdin() {
+            // Reconnect input can disappear with the old bridge during wake.
+            // It is not an intentional EOF for the newly attached remote PTY.
+            guard reconnectInputFilter == nil else { return }
            _ = shutdown(fd, SHUT_WR)
        }

@@ -210,7 +199,7 @@ final class SSHPTYAttachReconnectInputFilter {
                stopSignalFD: stopSignalFD,
                timeoutMilliseconds: timeoutMilliseconds
            ) else {
-                await flushPendingThenShutdown()
+                finishStdin()
                return
            }

@@ -222,13 +211,13 @@ final class SSHPTYAttachReconnectInputFilter {
                    stopSignalFD: nil,
                    timeoutMilliseconds: pendingProbeContinuationTimeoutMilliseconds
                ) else {
-                    await flushPendingThenShutdown()
+                    finishStdin()
                    return
                }
                if pendingReadiness.inputReady {
                    readiness = (inputReady: true, stopRequested: true)
                } else if let filter = reconnectInputFilter {
-                    guard await writeOrShutdown(filter.flushPendingInput()) else { return }
+                    guard await writeOrShutdown(filter.stopFiltering()) else { return }
                    guard stopReconnectFiltering() else { return }
                    continue
                }
@@ -244,7 +233,7 @@ final class SSHPTYAttachReconnectInputFilter {
            if !readiness.inputReady {
                if let filter = reconnectInputFilter,
                   filter.hasPendingInput {
-                    guard await writeOrShutdown(filter.flushPendingInput()) else { return }
+                    guard await writeOrShutdown(filter.stopFiltering()) else { return }
                }
                continue
            }
@@ -273,227 +262,51 @@ final class SSHPTYAttachReconnectInputFilter {
                    }
                }
            } else if count == 0 {
-                await flushPendingThenShutdown()
+                finishStdin()
                return
            } else if errno != EINTR {
-                await flushPendingThenShutdown()
+                finishStdin()
                return
            }
        }
    }

    func filter(_ data: Data) -> Data {
-        guard isFiltering, !data.isEmpty else {
-            return data
-        }
        if isDeadlineReached {
            var output = stopFiltering()
            output.append(data)
            return output
        }
-
-        var bytes = pending
-        pending.removeAll(keepingCapacity: true)
-        bytes.append(contentsOf: data)
-
-        var output = Data()
-        var index = 0
-        while index < bytes.count {
-            guard bytes[index] == Self.escape else {
-                isFiltering = false
-                output.append(contentsOf: bytes[index...])
-                return output
-            }
-
-            switch Self.reconnectProbeReplySequence(in: bytes, at: index) {
-            case .strip(let length):
-                index += length
-            case .incomplete:
-                let suffix = bytes[index...]
-                guard suffix.count <= Self.maxPendingProbeBytes else {
-                    isFiltering = false
-                    output.append(contentsOf: suffix)
-                    return output
-                }
-                pending.append(contentsOf: suffix)
-                return output
-            case .passThrough:
-                isFiltering = false
-                output.append(contentsOf: bytes[index...])
-                return output
-            }
-        }
-
-        return output
+        return byteFilter.filter(data)
    }

    func finish() -> Data {
-        guard !pending.isEmpty else {
-            return Data()
-        }
-        let data = Data(pending)
-        pending.removeAll(keepingCapacity: false)
-        return data
+        byteFilter.finish()
    }

    func stopFiltering() -> Data {
-        let input = finish()
-        isFiltering = false
-        return input
+        byteFilter.stopFiltering()
    }

    var hasPendingInput: Bool {
-        isFiltering && !pending.isEmpty
+        byteFilter.hasPendingInput
    }

    var isFilteringAtProbeBoundary: Bool {
-        isFiltering && pending.isEmpty
+        byteFilter.isFilteringAtProbeBoundary
    }

    var isFilteringActive: Bool {
-        isFiltering
+        byteFilter.isFilteringActive
    }

    var isDeadlineReached: Bool {
-        isFiltering && (deadlineReached?() == true)
+        byteFilter.isFilteringActive && (deadlineReached?() == true)
    }

    var remainingDeadlineMilliseconds: Int64? {
-        guard isFiltering else { return nil }
+        guard byteFilter.isFilteringActive else { return nil }
        return remainingDeadline?()
    }

-    func flushPendingInput() -> Data {
-        guard hasPendingInput else {
-            return Data()
-        }
-        let data = Data(pending)
-        pending.removeAll(keepingCapacity: true)
-        isFiltering = false
-        return data
-    }
-
-    private static func reconnectProbeReplySequence(
-        in bytes: [UInt8],
-        at start: Int
-    ) -> SSHPTYAttachReconnectInputFilterSequenceMatch {
-        guard start < bytes.count, bytes[start] == escape else {
-            return .passThrough
-        }
-        guard start + 1 < bytes.count else {
-            // read() can split immediately after ESC; wait for one more byte before deciding.
-            return .incomplete
-        }
-
-        switch bytes[start + 1] {
-        case rightBracket:
-            return oscColorReplySequence(in: bytes, at: start)
-        case leftBracket:
-            return csiProbeReplySequence(in: bytes, at: start)
-        default:
-            return .passThrough
-        }
-    }
-
-    private static func oscColorReplySequence(
-        in bytes: [UInt8],
-        at start: Int
-    ) -> SSHPTYAttachReconnectInputFilterSequenceMatch {
-        var cursor = start + 2
-        var command = [UInt8]()
-
-        while cursor < bytes.count {
-            let byte = bytes[cursor]
-            if byte == semicolon {
-                break
-            }
-            if byte < 0x30 || byte > 0x39 || command.count >= 2 {
-                return .passThrough
-            }
-            command.append(byte)
-            cursor += 1
-        }
-
-        guard cursor < bytes.count else {
-            return isOSCColorReplyCommandPrefix(command) ? .incomplete : .passThrough
-        }
-        guard bytes[cursor] == semicolon else {
-            return .passThrough
-        }
-        guard command == [0x31, 0x30] || command == [0x31, 0x31] || command == [0x31, 0x32] else {
-            return .passThrough
-        }
-
-        cursor += 1
-        while cursor < bytes.count {
-            let byte = bytes[cursor]
-            if byte == bell {
-                return .strip(length: cursor - start + 1)
-            }
-            if byte == escape {
-                guard cursor + 1 < bytes.count else {
-                    return .incomplete
-                }
-                if bytes[cursor + 1] == backslash {
-                    return .strip(length: cursor - start + 2)
-                }
-            }
-            cursor += 1
-        }
-        return .incomplete
-    }
-
-    private static func csiProbeReplySequence(
-        in bytes: [UInt8],
-        at start: Int
-    ) -> SSHPTYAttachReconnectInputFilterSequenceMatch {
-        var cursor = start + 2
-        while cursor < bytes.count {
-            let byte = bytes[cursor]
-            if byte >= 0x40, byte <= 0x7E {
-                return shouldStripCSIReply(bytes: bytes, bodyStart: start + 2, finalIndex: cursor)
-                    ? .strip(length: cursor - start + 1)
-                    : .passThrough
-            }
-            guard byte >= 0x20, byte <= 0x3F else {
-                return .passThrough
-            }
-            cursor += 1
-        }
-        return .incomplete
-    }
-
-    private static func isOSCColorReplyCommandPrefix(_ command: [UInt8]) -> Bool {
-        command.isEmpty ||
-            command == [0x31] ||
-            command == [0x31, 0x30] ||
-            command == [0x31, 0x31] ||
-            command == [0x31, 0x32]
-    }
-
-    private static func shouldStripCSIReply(bytes: [UInt8], bodyStart: Int, finalIndex: Int) -> Bool {
-        var parameterEnd = bodyStart
-        while parameterEnd < finalIndex, bytes[parameterEnd] >= 0x30, bytes[parameterEnd] <= 0x3F {
-            parameterEnd += 1
-        }
-        guard bytes[parameterEnd..<finalIndex].allSatisfy({ $0 >= 0x20 && $0 <= 0x2F }) else {
-            return false
-        }
-
-        let parameters = bytes[bodyStart..<parameterEnd]
-        let intermediates = bytes[parameterEnd..<finalIndex]
-        let final = bytes[finalIndex]
-
-        switch final {
-        case 0x52, 0x63, 0x6E:
-            return intermediates.isEmpty
-        case 0x75:
-            return intermediates.isEmpty && parameters.first == questionMark
-        case 0x79:
-            return intermediates.elementsEqual([dollar])
-        default:
-            return false
-        }
-    }
-
 }
@@ -1,6 +1,5 @@
 struct SSHPTYAttachReconnectInputFilterState: Sendable {
    let isFiltering: Bool
-    let pending: [UInt8]
    let deadlineReached: @Sendable () -> Bool
    let remainingDeadlineMilliseconds: @Sendable () -> Int64?
 }
@@ -0,0 +1,65 @@
+import CmuxControlSocket
+import Foundation
+
+extension SocketClient {
+    static func waitForConnectableSocket(path: String, timeout: TimeInterval) throws -> SocketClient {
+        try waitForConnectableSocket(resolvePath: { path }, timeout: timeout)
+    }
+
+    /// Waits for a socket selected by `resolvePath` to become connectable.
+    ///
+    /// ``SocketStartupWaiter`` owns the shared deadline, path re-resolution,
+    /// vnode wakeups, and backoff. This adapter owns CLI connection creation and
+    /// classifies transport failures so permanent path conflicts surface
+    /// immediately while startup races remain retryable.
+    static func waitForConnectableSocket(
+        resolvePath: () -> String,
+        timeout: TimeInterval
+    ) throws -> SocketClient {
+        do {
+            return try SocketStartupWaiter().wait(
+                timeout: timeout,
+                resolvePath: resolvePath
+            ) { path, remainingTime in
+                let client = SocketClient(path: path)
+                do {
+                    // Use the remaining total budget as the connect deadline so
+                    // a full listen backlog cannot extend the bounded startup wait.
+                    try client.connectWithoutRetry(
+                        responseTimeout: max(remainingTime, 0.001)
+                    )
+                    if client.isRelayBacked {
+                        client.close()
+                    }
+                    return client
+                } catch {
+                    client.close()
+                    guard shouldRetrySocketStartup(error) else {
+                        throw error
+                    }
+                    return nil
+                }
+            }
+        } catch let startupTimeout as SocketStartupWaitTimeout {
+            throw startupSocketTimeout(path: startupTimeout.path)
+        }
+    }
+
+    static func isSocketStartupTimeout(_ error: Error) -> Bool {
+        (error as? CLIError)?.socketFailureKind == .startupTimeout
+    }
+
+    private static func shouldRetrySocketStartup(_ error: Error) -> Bool {
+        if shouldRetryConnect(error) {
+            return true
+        }
+        return (error as? CLIError)?.socketFailureKind == .pathMissing
+    }
+
+    private static func startupSocketTimeout(path: String) -> CLIError {
+        CLIError(
+            message: "cmux app did not start in time (socket not found at \(path))",
+            socketFailureKind: .startupTimeout
+        )
+    }
+}
@@ -9,10 +9,14 @@ This is a standalone macOS app that embeds a CMUX sidebar ExtensionKit app exten
 3. Replace the Manaflow signing team with your own team.
 4. Replace the app and extension bundle identifiers with your own reverse-DNS identifiers.
 5. Keep the extension point identifier as `com.cmuxterm.app.cmux.sidebar`.
-6. Build and launch the containing app once.
-7. In CMUX, click the puzzle button next to the sidebar help button, open Sidebar Extensions, and enable the sample.
-8. In the same puzzle menu, choose the extension sidebar provider.
-9. In the extension sidebar header, choose `CMUX ExtKit Sample Sidebar` if more than one sidebar extension is enabled.
+6. Keep App Sandbox enabled for the extension target. An unsandboxed appex can
+   build, embed, and sign without registering with ExtensionKit.
+7. Build and launch the containing app once.
+8. In CMUX, click the puzzle button next to the sidebar help button, open Sidebar
+   Extensions, and enable the sample.
+9. In the same puzzle menu, choose the extension sidebar provider.
+10. In the extension sidebar header, choose `CMUX ExtKit Sample Sidebar` if more
+    than one sidebar extension is enabled.

 The sample targets macOS 14+, matching CMUX.

@@ -90,9 +94,29 @@ authors do not define `configuration`, bind an extension point in Swift, or touc
 The manifest is the permission request CMUX shows to users. Request only the scopes
 your sidebar actually needs.

+## Running External Tools
+
+CMUX read scopes can supply a workspace path, but they do not grant filesystem
+access to that path. A compiled extension that launches `git` or another
+external process must also satisfy the macOS App Sandbox, executable resolution,
+working-directory, and file-privacy rules. Follow the SDK's
+[Running external tools](../../Packages/macOS/CmuxExtensionKit/README.md#running-external-tools)
+guide before adding `Process` code.
+
 ## Troubleshooting

-If the extension does not appear in CMUX, launch the containing app once, then reopen CMUX's Sidebar Extensions browser.
+If the extension does not appear in CMUX, confirm that App Sandbox is enabled for
+the extension target, launch the containing app once, then reopen CMUX's Sidebar
+Extensions browser. You can also check system discovery directly:
+
+```sh
+pluginkit -mAvvv
+```
+
+The normal CMUX release uses `com.cmuxterm.app.cmux.sidebar`. Tagged development
+builds use the point stored in the host's `CMUXSidebarExtensionPointIdentifier`
+Info.plist key (currently `<host-bundle-id>.cmux.sidebar`), so do not filter on
+the production point when diagnosing a tagged or custom host.

 If it appears but cannot be enabled, check signing on both the containing app and the embedded appex.

@@ -0,0 +1,17 @@
+import UIKit
+
+@main
+final class AppDelegate: UIResponder, UIApplicationDelegate {
+    func application(
+        _ application: UIApplication,
+        configurationForConnecting connectingSceneSession: UISceneSession,
+        options: UIScene.ConnectionOptions
+    ) -> UISceneConfiguration {
+        let configuration = UISceneConfiguration(
+            name: "Default Configuration",
+            sessionRole: connectingSceneSession.role
+        )
+        configuration.delegateClass = SceneDelegate.self
+        return configuration
+    }
+}
@@ -0,0 +1,19 @@
+import UIKit
+
+final class SceneDelegate: UIResponder, UIWindowSceneDelegate {
+    var window: UIWindow?
+
+    func scene(
+        _ scene: UIScene,
+        willConnectTo session: UISceneSession,
+        options connectionOptions: UIScene.ConnectionOptions
+    ) {
+        guard let windowScene = scene as? UIWindowScene else { return }
+
+        let window = UIWindow(windowScene: windowScene)
+        window.rootViewController = WorkspaceDetailViewController()
+        window.overrideUserInterfaceStyle = .dark
+        window.makeKeyAndVisible()
+        self.window = window
+    }
+}
@@ -0,0 +1,354 @@
+import OSLog
+import UIKit
+
+@MainActor
+final class WorkspaceDetailViewController: UIViewController {
+    private let logger = Logger(subsystem: "ai.manaflow.KeyboardPinningLab", category: "Keyboard")
+    private let terminalView = TerminalCanvasView()
+    private let dockView = ComposerDockView()
+    private let headerView = WorkspaceHeaderView()
+    private var stressTask: Task<Void, Never>?
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        configureHierarchy()
+        configureKeyboardPinning()
+        configureActions()
+        observeKeyboardFrames()
+    }
+
+    override func viewDidAppear(_ animated: Bool) {
+        super.viewDidAppear(animated)
+        dockView.focusComposer()
+
+        if UserDefaults.standard.bool(forKey: "stressKeyboard") {
+            runStressSequence()
+        }
+    }
+
+    override func viewDidDisappear(_ animated: Bool) {
+        super.viewDidDisappear(animated)
+        stressTask?.cancel()
+    }
+
+    override func viewDidLayoutSubviews() {
+        super.viewDidLayoutSubviews()
+        let guideTop = view.keyboardLayoutGuide.layoutFrame.minY
+        let dockBottom = dockView.frame.maxY
+        let gap = guideTop - dockBottom
+        headerView.updatePinGap(gap)
+    }
+
+    private func configureHierarchy() {
+        view.backgroundColor = UIColor(red: 0.075, green: 0.078, blue: 0.082, alpha: 1)
+        [headerView, terminalView, dockView].forEach {
+            $0.translatesAutoresizingMaskIntoConstraints = false
+            view.addSubview($0)
+        }
+
+        NSLayoutConstraint.activate([
+            headerView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
+            headerView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
+            headerView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
+            headerView.heightAnchor.constraint(equalToConstant: 60),
+
+            terminalView.topAnchor.constraint(equalTo: headerView.bottomAnchor),
+            terminalView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
+            terminalView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
+            terminalView.bottomAnchor.constraint(equalTo: dockView.topAnchor),
+
+            dockView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
+            dockView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
+        ])
+    }
+
+    private func configureKeyboardPinning() {
+        let keyboardGuide = view.keyboardLayoutGuide
+        keyboardGuide.followsUndockedKeyboard = true
+
+        // The dock and keyboard share one UIKit constraint graph. UIKit owns the
+        // keyboard's presentation frame and interruptible animation, so no copied
+        // keyboard height or separately-timed animation can diverge.
+        dockView.bottomAnchor.constraint(equalTo: keyboardGuide.topAnchor).isActive = true
+    }
+
+    private func configureActions() {
+        terminalView.onTap = { [weak self] in
+            self?.dockView.focusComposer()
+        }
+        dockView.onKeyboardToggle = { [weak self] in
+            self?.toggleKeyboard()
+        }
+        headerView.onStress = { [weak self] in
+            self?.runStressSequence()
+        }
+    }
+
+    private func observeKeyboardFrames() {
+        NotificationCenter.default.addObserver(
+            forName: UIResponder.keyboardWillChangeFrameNotification,
+            object: nil,
+            queue: .main
+        ) { [weak self] notification in
+            guard let self,
+                  let frame = notification.userInfo?[UIResponder.keyboardFrameEndUserInfoKey] as? CGRect
+            else { return }
+            self.logger.debug("Keyboard target minY: \(frame.minY, format: .fixed(precision: 1))")
+        }
+    }
+
+    private func toggleKeyboard() {
+        if dockView.isComposerFocused {
+            dockView.dismissComposer()
+        } else {
+            dockView.focusComposer()
+        }
+    }
+
+    private func runStressSequence() {
+        stressTask?.cancel()
+        stressTask = Task { [weak self] in
+            guard let self else { return }
+            for _ in 0..<20 {
+                guard !Task.isCancelled else { return }
+                self.toggleKeyboard()
+                try? await Task.sleep(for: .milliseconds(135))
+            }
+            guard !Task.isCancelled else { return }
+            self.dockView.focusComposer()
+        }
+    }
+}
+
+private final class WorkspaceHeaderView: UIView {
+    var onStress: (() -> Void)?
+
+    private let statusLabel = UILabel()
+
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        backgroundColor = UIColor(red: 0.075, green: 0.078, blue: 0.082, alpha: 0.98)
+
+        let backButton = Self.symbolButton("chevron.left")
+        let titleLabel = UILabel()
+        titleLabel.text = String(localized: "workspace.title", defaultValue: "cmux DEV lab")
+        titleLabel.font = .preferredFont(forTextStyle: .headline)
+        titleLabel.textColor = .white
+
+        let terminalButton = Self.symbolButton("rectangle.on.rectangle")
+        let stressButton = Self.symbolButton("arrow.trianglehead.2.clockwise.rotate.90")
+        stressButton.accessibilityIdentifier = "stressKeyboard"
+        stressButton.accessibilityLabel = String(localized: "stress.accessibility", defaultValue: "Rapidly toggle keyboard 20 times")
+        stressButton.addAction(UIAction { [weak self] _ in self?.onStress?() }, for: .touchUpInside)
+        statusLabel.font = .monospacedDigitSystemFont(ofSize: 11, weight: .semibold)
+        statusLabel.textColor = UIColor(red: 0.31, green: 0.84, blue: 0.53, alpha: 1)
+        statusLabel.textAlignment = .center
+        statusLabel.accessibilityIdentifier = "pinGapStatus"
+
+        let row = UIStackView(arrangedSubviews: [backButton, titleLabel, UIView(), statusLabel, stressButton, terminalButton])
+        row.axis = .horizontal
+        row.alignment = .center
+        row.spacing = 10
+        row.translatesAutoresizingMaskIntoConstraints = false
+        addSubview(row)
+
+        NSLayoutConstraint.activate([
+            row.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 12),
+            row.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -12),
+            row.centerYAnchor.constraint(equalTo: centerYAnchor),
+            statusLabel.widthAnchor.constraint(equalToConstant: 105),
+        ])
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) { nil }
+
+    func updatePinGap(_ gap: CGFloat) {
+        let clamped = abs(gap) < 0.05 ? 0 : gap
+        let formattedGap = Double(clamped).formatted(.number.precision(.fractionLength(1)))
+        statusLabel.text = String(localized: "PIN GAP \(formattedGap) pt")
+        statusLabel.textColor = abs(clamped) < 0.1 ? UIColor(red: 0.31, green: 0.84, blue: 0.53, alpha: 1) : .systemRed
+    }
+
+    private static func symbolButton(_ symbol: String) -> UIButton {
+        var configuration = UIButton.Configuration.plain()
+        configuration.image = UIImage(systemName: symbol)
+        configuration.baseForegroundColor = .white
+        return UIButton(configuration: configuration)
+    }
+}
+
+private final class TerminalCanvasView: UIView {
+    var onTap: (() -> Void)?
+
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        backgroundColor = UIColor(red: 0.105, green: 0.108, blue: 0.112, alpha: 1)
+        isAccessibilityElement = true
+        accessibilityIdentifier = "terminalCanvas"
+        accessibilityLabel = String(localized: "terminal.accessibility", defaultValue: "Terminal. Tap to show keyboard.")
+
+        let tapGesture = UITapGestureRecognizer(target: self, action: #selector(handleTap))
+        addGestureRecognizer(tapGesture)
+
+        let terminalText = UILabel()
+        terminalText.translatesAutoresizingMaskIntoConstraints = false
+        terminalText.numberOfLines = 0
+        terminalText.font = .monospacedSystemFont(ofSize: 11, weight: .regular)
+        terminalText.textColor = UIColor(white: 0.79, alpha: 1)
+        terminalText.text = String(localized: "terminal.sample", defaultValue: "Last login: Fri Aug 7 19:45:12 on ttys006\n\n~/cmux  git:(feat/keyboard-pinning-lab)\n❯")
+        addSubview(terminalText)
+
+        NSLayoutConstraint.activate([
+            terminalText.topAnchor.constraint(equalTo: topAnchor, constant: 14),
+            terminalText.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 12),
+            terminalText.trailingAnchor.constraint(lessThanOrEqualTo: trailingAnchor, constant: -12),
+        ])
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) { nil }
+
+    @objc private func handleTap() {
+        onTap?()
+    }
+}
+
+private final class ComposerDockView: UIView, UITextFieldDelegate {
+    var onKeyboardToggle: (() -> Void)?
+
+    private let textField = UITextField()
+
+    var isComposerFocused: Bool { textField.isFirstResponder }
+
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        backgroundColor = UIColor(red: 0.075, green: 0.078, blue: 0.082, alpha: 0.99)
+
+        let shortcuts = makeShortcutBar()
+        let composer = makeComposerBar()
+        let stack = UIStackView(arrangedSubviews: [shortcuts, composer])
+        stack.axis = .vertical
+        stack.spacing = 4
+        stack.translatesAutoresizingMaskIntoConstraints = false
+        addSubview(stack)
+
+        NSLayoutConstraint.activate([
+            stack.topAnchor.constraint(equalTo: topAnchor, constant: 6),
+            stack.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 8),
+            stack.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -8),
+            stack.bottomAnchor.constraint(equalTo: bottomAnchor, constant: -6),
+            shortcuts.heightAnchor.constraint(equalToConstant: 36),
+            composer.heightAnchor.constraint(equalToConstant: 42),
+        ])
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) { nil }
+
+    func focusComposer() {
+        textField.becomeFirstResponder()
+    }
+
+    func dismissComposer() {
+        textField.resignFirstResponder()
+    }
+
+    private func makeShortcutBar() -> UIView {
+        let specs: [(String, String)] = [
+            ("keyboard", "keyboard.toggle"),
+            ("circle.fill", "shortcut.control"),
+            ("square.and.pencil", "shortcut.command"),
+            ("chevron.up", "shortcut.up"),
+            ("option", "shortcut.option"),
+            ("command", "shortcut.command"),
+            ("doc.on.clipboard", "shortcut.paste"),
+        ]
+
+        let buttons = specs.map { symbol, identifier in
+            var configuration = UIButton.Configuration.plain()
+            configuration.image = UIImage(systemName: symbol)
+            configuration.baseForegroundColor = .white
+            configuration.contentInsets = .zero
+            let button = UIButton(configuration: configuration)
+            button.accessibilityIdentifier = identifier
+            if identifier == "keyboard.toggle" {
+                button.addAction(UIAction { [weak self] _ in self?.onKeyboardToggle?() }, for: .touchUpInside)
+            }
+            return button
+        }
+
+        var tabConfiguration = UIButton.Configuration.filled()
+        tabConfiguration.title = String(localized: "shortcut.tab", defaultValue: "Tab")
+        tabConfiguration.baseBackgroundColor = UIColor(white: 0.18, alpha: 1)
+        tabConfiguration.baseForegroundColor = .white
+        tabConfiguration.cornerStyle = .capsule
+        tabConfiguration.contentInsets = .init(top: 0, leading: 2, bottom: 0, trailing: 2)
+        tabConfiguration.titleLineBreakMode = .byClipping
+        tabConfiguration.titleTextAttributesTransformer = UIConfigurationTextAttributesTransformer { attributes in
+            var attributes = attributes
+            attributes.font = .systemFont(ofSize: 11, weight: .medium)
+            return attributes
+        }
+        let tabButton = UIButton(configuration: tabConfiguration)
+
+        var escapeConfiguration = tabConfiguration
+        escapeConfiguration.title = String(localized: "shortcut.escape", defaultValue: "Esc")
+        let escapeButton = UIButton(configuration: escapeConfiguration)
+
+        let stack = UIStackView(arrangedSubviews: buttons + [tabButton, escapeButton])
+        stack.axis = .horizontal
+        stack.alignment = .fill
+        stack.distribution = .fillEqually
+        stack.spacing = 4
+        return stack
+    }
+
+    private func makeComposerBar() -> UIView {
+        let attachment = Self.circleButton(symbol: "paperclip")
+        let microphone = Self.circleButton(symbol: "mic")
+        let send = Self.circleButton(symbol: "arrow.up", filled: true)
+
+        textField.delegate = self
+        textField.placeholder = String(localized: "composer.placeholder", defaultValue: "Message")
+        textField.textColor = .white
+        textField.tintColor = .white
+        textField.font = .preferredFont(forTextStyle: .body)
+        textField.returnKeyType = .send
+        textField.autocorrectionType = .no
+        textField.accessibilityIdentifier = "composerTextField"
+
+        let fieldContainer = UIView()
+        fieldContainer.backgroundColor = UIColor(white: 0.12, alpha: 1)
+        fieldContainer.layer.cornerRadius = 17
+        textField.translatesAutoresizingMaskIntoConstraints = false
+        fieldContainer.addSubview(textField)
+        NSLayoutConstraint.activate([
+            textField.leadingAnchor.constraint(equalTo: fieldContainer.leadingAnchor, constant: 12),
+            textField.trailingAnchor.constraint(equalTo: fieldContainer.trailingAnchor, constant: -8),
+            textField.topAnchor.constraint(equalTo: fieldContainer.topAnchor),
+            textField.bottomAnchor.constraint(equalTo: fieldContainer.bottomAnchor),
+        ])
+
+        let row = UIStackView(arrangedSubviews: [attachment, microphone, fieldContainer, send])
+        row.axis = .horizontal
+        row.alignment = .fill
+        row.spacing = 6
+        return row
+    }
+
+    private static func circleButton(symbol: String, filled: Bool = false) -> UIButton {
+        var configuration = filled ? UIButton.Configuration.filled() : UIButton.Configuration.plain()
+        configuration.image = UIImage(systemName: symbol)
+        configuration.baseForegroundColor = filled ? .black : .white
+        configuration.baseBackgroundColor = filled ? UIColor(white: 0.85, alpha: 1) : .clear
+        configuration.cornerStyle = .capsule
+        configuration.contentInsets = .zero
+        return UIButton(configuration: configuration)
+    }
+
+    func textFieldShouldReturn(_ textField: UITextField) -> Bool {
+        textField.text = nil
+        return false
+    }
+}
@@ -0,0 +1,11 @@
+# Verification
+
+Source reference: `ScreenRecording_08-07-2026 19-50-56_1.MP4`, 1320×2868, 60 fps, 51.62 seconds.
+
+Invariant: during interrupted rapid keyboard show and hide cycles, the Shortcut bar and Composer bar remain one rigid dock. The dock bottom stays coincident with the keyboard top, with no transient gap, overlap, lag, or snap-back.
+
+Scenario: iPhone 17 Pro Max simulator on iOS 26.5, dark appearance, keyboard initially shown, 20 first-responder reversals at 135 ms intervals, then a final focused state. This interval is shorter than a normal keyboard transition and forces animation interruption.
+
+Result: the live layout diagnostic remained `PIN GAP 0.0 pt`. The final run was sampled at 15 fps, including steady, partial-hide, hidden, partial-show, reversed, and final frames. The invariant held in every sampled frame.
+
+Durable evidence is stored at `cmux-assets/feat-keyboard-pinning-lab/rapid-toggle-final/` in the cmuxterm-hq checkout. The directory contains the raw recording, annotated frames, contact sheet, and manifest with the success criterion.
@@ -0,0 +1,351 @@
+// !$*UTF8*$!
+{
+	archiveVersion = 1;
+	classes = {
+	};
+	objectVersion = 77;
+	objects = {
+
+/* Begin PBXBuildFile section */
+		1E81F0EEF337DE057CCEC892 /* InfoPlist.strings in Resources */ = {isa = PBXBuildFile; fileRef = CE0E17A1008C3577E9CD4995 /* InfoPlist.strings */; };
+		7BCC8A0872603104E124D03E /* WorkspaceDetailViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = 12AF82959FE7DAAA5C3ADBEE /* WorkspaceDetailViewController.swift */; };
+		8F1F331AA4DD22756ED437F4 /* Localizable.xcstrings in Resources */ = {isa = PBXBuildFile; fileRef = 949EB7D848CCC51B60D11989 /* Localizable.xcstrings */; };
+		DE8D30BAEC473E45B80219A5 /* SceneDelegate.swift in Sources */ = {isa = PBXBuildFile; fileRef = 2728F872D5FB8D33A41A6E91 /* SceneDelegate.swift */; };
+		EFCF59C7ED8878A5FAA7DDF5 /* AppDelegate.swift in Sources */ = {isa = PBXBuildFile; fileRef = 4444F6FE9025CD71B41223BE /* AppDelegate.swift */; };
+/* End PBXBuildFile section */
+
+/* Begin PBXFileReference section */
+		12AF82959FE7DAAA5C3ADBEE /* WorkspaceDetailViewController.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = WorkspaceDetailViewController.swift; sourceTree = "<group>"; };
+		2728F872D5FB8D33A41A6E91 /* SceneDelegate.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SceneDelegate.swift; sourceTree = "<group>"; };
+		2C03363774959A68994988EB /* ja */ = {isa = PBXFileReference; lastKnownFileType = text.plist.strings; name = ja; path = ja.lproj/InfoPlist.strings; sourceTree = "<group>"; };
+		4444F6FE9025CD71B41223BE /* AppDelegate.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AppDelegate.swift; sourceTree = "<group>"; };
+		5405DD1047FED983298B8CD3 /* en */ = {isa = PBXFileReference; lastKnownFileType = text.plist.strings; name = en; path = en.lproj/InfoPlist.strings; sourceTree = "<group>"; };
+		949EB7D848CCC51B60D11989 /* Localizable.xcstrings */ = {isa = PBXFileReference; lastKnownFileType = text.json.xcstrings; path = Localizable.xcstrings; sourceTree = "<group>"; };
+		D4959730D56E1DB02C931108 /* KeyboardPinningLab.app */ = {isa = PBXFileReference; includeInIndex = 0; lastKnownFileType = wrapper.application; path = KeyboardPinningLab.app; sourceTree = BUILT_PRODUCTS_DIR; };
+/* End PBXFileReference section */
+
+/* Begin PBXGroup section */
+		0CA61C38419BE31AC5D5455E /* App */ = {
+			isa = PBXGroup;
+			children = (
+				4444F6FE9025CD71B41223BE /* AppDelegate.swift */,
+				2728F872D5FB8D33A41A6E91 /* SceneDelegate.swift */,
+				12AF82959FE7DAAA5C3ADBEE /* WorkspaceDetailViewController.swift */,
+			);
+			path = App;
+			sourceTree = "<group>";
+		};
+		CD6A0D068D8B8C2D583490C8 = {
+			isa = PBXGroup;
+			children = (
+				0CA61C38419BE31AC5D5455E /* App */,
+				E0F87851FC78526801069DE5 /* Resources */,
+				E6422832B55FB3758A111DC2 /* Products */,
+			);
+			sourceTree = "<group>";
+		};
+		E0F87851FC78526801069DE5 /* Resources */ = {
+			isa = PBXGroup;
+			children = (
+				949EB7D848CCC51B60D11989 /* Localizable.xcstrings */,
+				CE0E17A1008C3577E9CD4995 /* InfoPlist.strings */,
+			);
+			path = Resources;
+			sourceTree = "<group>";
+		};
+		E6422832B55FB3758A111DC2 /* Products */ = {
+			isa = PBXGroup;
+			children = (
+				D4959730D56E1DB02C931108 /* KeyboardPinningLab.app */,
+			);
+			name = Products;
+			sourceTree = "<group>";
+		};
+/* End PBXGroup section */
+
+/* Begin PBXNativeTarget section */
+		27AE499E18794152BA4672C0 /* KeyboardPinningLab */ = {
+			isa = PBXNativeTarget;
+			buildConfigurationList = 76AA4EB0FA9193B6C03BEA00 /* Build configuration list for PBXNativeTarget "KeyboardPinningLab" */;
+			buildPhases = (
+				668F9A8ACF9F66A71F3435F3 /* Sources */,
+				AF47256CFA451165B9D69F33 /* Resources */,
+			);
+			buildRules = (
+			);
+			dependencies = (
+			);
+			name = KeyboardPinningLab;
+			packageProductDependencies = (
+			);
+			productName = KeyboardPinningLab;
+			productReference = D4959730D56E1DB02C931108 /* KeyboardPinningLab.app */;
+			productType = "com.apple.product-type.application";
+		};
+/* End PBXNativeTarget section */
+
+/* Begin PBXProject section */
+		58E3B7797EDEB766152AADC7 /* Project object */ = {
+			isa = PBXProject;
+			attributes = {
+				BuildIndependentTargetsInParallel = YES;
+				LastUpgradeCheck = 1430;
+				TargetAttributes = {
+					27AE499E18794152BA4672C0 = {
+						DevelopmentTeam = 7WLXT3NR37;
+						ProvisioningStyle = Automatic;
+					};
+				};
+			};
+			buildConfigurationList = 6AE1CD5DF1B492DCA42ECF57 /* Build configuration list for PBXProject "KeyboardPinningLab" */;
+			developmentRegion = en;
+			hasScannedForEncodings = 0;
+			knownRegions = (
+				Base,
+				en,
+				ja,
+			);
+			mainGroup = CD6A0D068D8B8C2D583490C8;
+			minimizedProjectReferenceProxies = 1;
+			preferredProjectObjectVersion = 77;
+			productRefGroup = E6422832B55FB3758A111DC2 /* Products */;
+			projectDirPath = "";
+			projectRoot = "";
+			targets = (
+				27AE499E18794152BA4672C0 /* KeyboardPinningLab */,
+			);
+		};
+/* End PBXProject section */
+
+/* Begin PBXResourcesBuildPhase section */
+		AF47256CFA451165B9D69F33 /* Resources */ = {
+			isa = PBXResourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+				1E81F0EEF337DE057CCEC892 /* InfoPlist.strings in Resources */,
+				8F1F331AA4DD22756ED437F4 /* Localizable.xcstrings in Resources */,
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
+/* End PBXResourcesBuildPhase section */
+
+/* Begin PBXSourcesBuildPhase section */
+		668F9A8ACF9F66A71F3435F3 /* Sources */ = {
+			isa = PBXSourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+				EFCF59C7ED8878A5FAA7DDF5 /* AppDelegate.swift in Sources */,
+				DE8D30BAEC473E45B80219A5 /* SceneDelegate.swift in Sources */,
+				7BCC8A0872603104E124D03E /* WorkspaceDetailViewController.swift in Sources */,
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
+/* End PBXSourcesBuildPhase section */
+
+/* Begin PBXVariantGroup section */
+		CE0E17A1008C3577E9CD4995 /* InfoPlist.strings */ = {
+			isa = PBXVariantGroup;
+			children = (
+				5405DD1047FED983298B8CD3 /* en */,
+				2C03363774959A68994988EB /* ja */,
+			);
+			name = InfoPlist.strings;
+			sourceTree = "<group>";
+		};
+/* End PBXVariantGroup section */
+
+/* Begin XCBuildConfiguration section */
+		0E30ABD0849A82BD34D9BF72 /* Release */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				ALWAYS_SEARCH_USER_PATHS = NO;
+				CLANG_ANALYZER_NONNULL = YES;
+				CLANG_ANALYZER_NUMBER_OBJECT_CONVERSION = YES_AGGRESSIVE;
+				CLANG_CXX_LANGUAGE_STANDARD = "gnu++14";
+				CLANG_CXX_LIBRARY = "libc++";
+				CLANG_ENABLE_MODULES = YES;
+				CLANG_ENABLE_OBJC_ARC = YES;
+				CLANG_ENABLE_OBJC_WEAK = YES;
+				CLANG_WARN_BLOCK_CAPTURE_AUTORELEASING = YES;
+				CLANG_WARN_BOOL_CONVERSION = YES;
+				CLANG_WARN_COMMA = YES;
+				CLANG_WARN_CONSTANT_CONVERSION = YES;
+				CLANG_WARN_DEPRECATED_OBJC_IMPLEMENTATIONS = YES;
+				CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR;
+				CLANG_WARN_DOCUMENTATION_COMMENTS = YES;
+				CLANG_WARN_EMPTY_BODY = YES;
+				CLANG_WARN_ENUM_CONVERSION = YES;
+				CLANG_WARN_INFINITE_RECURSION = YES;
+				CLANG_WARN_INT_CONVERSION = YES;
+				CLANG_WARN_NON_LITERAL_NULL_CONVERSION = YES;
+				CLANG_WARN_OBJC_IMPLICIT_RETAIN_SELF = YES;
+				CLANG_WARN_OBJC_LITERAL_CONVERSION = YES;
+				CLANG_WARN_OBJC_ROOT_CLASS = YES_ERROR;
+				CLANG_WARN_QUOTED_INCLUDE_IN_FRAMEWORK_HEADER = YES;
+				CLANG_WARN_RANGE_LOOP_ANALYSIS = YES;
+				CLANG_WARN_STRICT_PROTOTYPES = YES;
+				CLANG_WARN_SUSPICIOUS_MOVE = YES;
+				CLANG_WARN_UNGUARDED_AVAILABILITY = YES_AGGRESSIVE;
+				CLANG_WARN_UNREACHABLE_CODE = YES;
+				CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
+				COPY_PHASE_STRIP = NO;
+				DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";
+				DEVELOPMENT_TEAM = 7WLXT3NR37;
+				ENABLE_NS_ASSERTIONS = NO;
+				ENABLE_STRICT_OBJC_MSGSEND = YES;
+				GCC_C_LANGUAGE_STANDARD = gnu11;
+				GCC_NO_COMMON_BLOCKS = YES;
+				GCC_WARN_64_TO_32_BIT_CONVERSION = YES;
+				GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR;
+				GCC_WARN_UNDECLARED_SELECTOR = YES;
+				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
+				GCC_WARN_UNUSED_FUNCTION = YES;
+				GCC_WARN_UNUSED_VARIABLE = YES;
+				IPHONEOS_DEPLOYMENT_TARGET = 17.0;
+				MTL_ENABLE_DEBUG_INFO = NO;
+				MTL_FAST_MATH = YES;
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				SDKROOT = iphoneos;
+				SWIFT_COMPILATION_MODE = wholemodule;
+				SWIFT_OPTIMIZATION_LEVEL = "-O";
+				SWIFT_STRICT_CONCURRENCY = complete;
+				SWIFT_VERSION = 6.0;
+			};
+			name = Release;
+		};
+		C0E137783EBF25A0C576D57F /* Release */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
+				CODE_SIGN_IDENTITY = "iPhone Developer";
+				CODE_SIGN_STYLE = Automatic;
+				GENERATE_INFOPLIST_FILE = YES;
+				INFOPLIST_KEY_CFBundleDisplayName = "Pinning Lab";
+				INFOPLIST_KEY_UIApplicationSceneManifest_Generation = YES;
+				INFOPLIST_KEY_UIApplicationSupportsIndirectInputEvents = YES;
+				INFOPLIST_KEY_UILaunchScreen_Generation = YES;
+				INFOPLIST_KEY_UISupportedInterfaceOrientations_iPhone = UIInterfaceOrientationPortrait;
+				LD_RUNPATH_SEARCH_PATHS = (
+					"$(inherited)",
+					"@executable_path/Frameworks",
+				);
+				PRODUCT_BUNDLE_IDENTIFIER = ai.manaflow.KeyboardPinningLab;
+				PRODUCT_NAME = "Keyboard Pinning Lab";
+				SDKROOT = iphoneos;
+				TARGETED_DEVICE_FAMILY = 1;
+			};
+			name = Release;
+		};
+		DF22FCDD84F72C666DC4079C /* Debug */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
+				CODE_SIGN_IDENTITY = "iPhone Developer";
+				CODE_SIGN_STYLE = Automatic;
+				GENERATE_INFOPLIST_FILE = YES;
+				INFOPLIST_KEY_CFBundleDisplayName = "Pinning Lab";
+				INFOPLIST_KEY_UIApplicationSceneManifest_Generation = YES;
+				INFOPLIST_KEY_UIApplicationSupportsIndirectInputEvents = YES;
+				INFOPLIST_KEY_UILaunchScreen_Generation = YES;
+				INFOPLIST_KEY_UISupportedInterfaceOrientations_iPhone = UIInterfaceOrientationPortrait;
+				LD_RUNPATH_SEARCH_PATHS = (
+					"$(inherited)",
+					"@executable_path/Frameworks",
+				);
+				PRODUCT_BUNDLE_IDENTIFIER = ai.manaflow.KeyboardPinningLab;
+				PRODUCT_NAME = "Keyboard Pinning Lab";
+				SDKROOT = iphoneos;
+				TARGETED_DEVICE_FAMILY = 1;
+			};
+			name = Debug;
+		};
+		EE990F81439C9DDADF595351 /* Debug */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				ALWAYS_SEARCH_USER_PATHS = NO;
+				CLANG_ANALYZER_NONNULL = YES;
+				CLANG_ANALYZER_NUMBER_OBJECT_CONVERSION = YES_AGGRESSIVE;
+				CLANG_CXX_LANGUAGE_STANDARD = "gnu++14";
+				CLANG_CXX_LIBRARY = "libc++";
+				CLANG_ENABLE_MODULES = YES;
+				CLANG_ENABLE_OBJC_ARC = YES;
+				CLANG_ENABLE_OBJC_WEAK = YES;
+				CLANG_WARN_BLOCK_CAPTURE_AUTORELEASING = YES;
+				CLANG_WARN_BOOL_CONVERSION = YES;
+				CLANG_WARN_COMMA = YES;
+				CLANG_WARN_CONSTANT_CONVERSION = YES;
+				CLANG_WARN_DEPRECATED_OBJC_IMPLEMENTATIONS = YES;
+				CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR;
+				CLANG_WARN_DOCUMENTATION_COMMENTS = YES;
+				CLANG_WARN_EMPTY_BODY = YES;
+				CLANG_WARN_ENUM_CONVERSION = YES;
+				CLANG_WARN_INFINITE_RECURSION = YES;
+				CLANG_WARN_INT_CONVERSION = YES;
+				CLANG_WARN_NON_LITERAL_NULL_CONVERSION = YES;
+				CLANG_WARN_OBJC_IMPLICIT_RETAIN_SELF = YES;
+				CLANG_WARN_OBJC_LITERAL_CONVERSION = YES;
+				CLANG_WARN_OBJC_ROOT_CLASS = YES_ERROR;
+				CLANG_WARN_QUOTED_INCLUDE_IN_FRAMEWORK_HEADER = YES;
+				CLANG_WARN_RANGE_LOOP_ANALYSIS = YES;
+				CLANG_WARN_STRICT_PROTOTYPES = YES;
+				CLANG_WARN_SUSPICIOUS_MOVE = YES;
+				CLANG_WARN_UNGUARDED_AVAILABILITY = YES_AGGRESSIVE;
+				CLANG_WARN_UNREACHABLE_CODE = YES;
+				CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
+				COPY_PHASE_STRIP = NO;
+				DEBUG_INFORMATION_FORMAT = dwarf;
+				DEVELOPMENT_TEAM = 7WLXT3NR37;
+				ENABLE_STRICT_OBJC_MSGSEND = YES;
+				ENABLE_TESTABILITY = YES;
+				GCC_C_LANGUAGE_STANDARD = gnu11;
+				GCC_DYNAMIC_NO_PIC = NO;
+				GCC_NO_COMMON_BLOCKS = YES;
+				GCC_OPTIMIZATION_LEVEL = 0;
+				GCC_PREPROCESSOR_DEFINITIONS = (
+					"$(inherited)",
+					"DEBUG=1",
+				);
+				GCC_WARN_64_TO_32_BIT_CONVERSION = YES;
+				GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR;
+				GCC_WARN_UNDECLARED_SELECTOR = YES;
+				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
+				GCC_WARN_UNUSED_FUNCTION = YES;
+				GCC_WARN_UNUSED_VARIABLE = YES;
+				IPHONEOS_DEPLOYMENT_TARGET = 17.0;
+				MTL_ENABLE_DEBUG_INFO = INCLUDE_SOURCE;
+				MTL_FAST_MATH = YES;
+				ONLY_ACTIVE_ARCH = YES;
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				SDKROOT = iphoneos;
+				SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG;
+				SWIFT_OPTIMIZATION_LEVEL = "-Onone";
+				SWIFT_STRICT_CONCURRENCY = complete;
+				SWIFT_VERSION = 6.0;
+			};
+			name = Debug;
+		};
+/* End XCBuildConfiguration section */
+
+/* Begin XCConfigurationList section */
+		6AE1CD5DF1B492DCA42ECF57 /* Build configuration list for PBXProject "KeyboardPinningLab" */ = {
+			isa = XCConfigurationList;
+			buildConfigurations = (
+				EE990F81439C9DDADF595351 /* Debug */,
+				0E30ABD0849A82BD34D9BF72 /* Release */,
+			);
+			defaultConfigurationIsVisible = 0;
+			defaultConfigurationName = Debug;
+		};
+		76AA4EB0FA9193B6C03BEA00 /* Build configuration list for PBXNativeTarget "KeyboardPinningLab" */ = {
+			isa = XCConfigurationList;
+			buildConfigurations = (
+				DF22FCDD84F72C666DC4079C /* Debug */,
+				C0E137783EBF25A0C576D57F /* Release */,
+			);
+			defaultConfigurationIsVisible = 0;
+			defaultConfigurationName = Debug;
+		};
+/* End XCConfigurationList section */
+	};
+	rootObject = 58E3B7797EDEB766152AADC7 /* Project object */;
+}
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Workspace
+   version = "1.0">
+   <FileRef
+      location = "self:">
+   </FileRef>
+</Workspace>
@@ -0,0 +1,95 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "1430"
+   version = "1.7">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES"
+      runPostActionsOnFailure = "NO">
+      <BuildActionEntries>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "27AE499E18794152BA4672C0"
+               BuildableName = "KeyboardPinningLab.app"
+               BlueprintName = "KeyboardPinningLab"
+               ReferencedContainer = "container:KeyboardPinningLab.xcodeproj">
+            </BuildableReference>
+         </BuildActionEntry>
+      </BuildActionEntries>
+   </BuildAction>
+   <TestAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      onlyGenerateCoverageForSpecifiedTargets = "NO">
+      <MacroExpansion>
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "27AE499E18794152BA4672C0"
+            BuildableName = "KeyboardPinningLab.app"
+            BlueprintName = "KeyboardPinningLab"
+            ReferencedContainer = "container:KeyboardPinningLab.xcodeproj">
+         </BuildableReference>
+      </MacroExpansion>
+      <Testables>
+      </Testables>
+      <CommandLineArguments>
+      </CommandLineArguments>
+   </TestAction>
+   <LaunchAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"
+      allowLocationSimulation = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "27AE499E18794152BA4672C0"
+            BuildableName = "KeyboardPinningLab.app"
+            BlueprintName = "KeyboardPinningLab"
+            ReferencedContainer = "container:KeyboardPinningLab.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+      <CommandLineArguments>
+      </CommandLineArguments>
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Release"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      savedToolIdentifier = ""
+      useCustomWorkingDirectory = "NO"
+      debugDocumentVersioning = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "27AE499E18794152BA4672C0"
+            BuildableName = "KeyboardPinningLab.app"
+            BlueprintName = "KeyboardPinningLab"
+            ReferencedContainer = "container:KeyboardPinningLab.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+      <CommandLineArguments>
+      </CommandLineArguments>
+   </ProfileAction>
+   <AnalyzeAction
+      buildConfiguration = "Debug">
+   </AnalyzeAction>
+   <ArchiveAction
+      buildConfiguration = "Release"
+      revealArchiveInOrganizer = "YES">
+   </ArchiveAction>
+</Scheme>
@@ -0,0 +1,11 @@
+# Keyboard Pinning Lab
+
+This standalone iOS app isolates the Workspace Detail keyboard geometry from cmux state and networking.
+
+The Composer and Shortcut bars live in one `ComposerDockView`. Its bottom edge is constrained directly to `UIKeyboardLayoutGuide.topAnchor`. UIKit therefore owns the keyboard frame, the dock frame, and interrupted animation timing in one constraint graph.
+
+The circular-arrow header button reverses first-responder state every 135 ms to stress interrupted keyboard transitions. The header reports the live constraint gap. Green `PIN GAP 0.0 pt` means the dock and keyboard guide are coincident in the current layout pass.
+
+Tapping the terminal canvas focuses the same Composer text field, so terminal tap, direct Composer tap, the keyboard button, and the stress control all exercise one keyboard ownership path.
+
+Generate the Xcode project with `xcodegen generate`, then build the `KeyboardPinningLab` scheme.
@@ -0,0 +1,54 @@
+{
+  "sourceLanguage" : "en",
+  "strings" : {
+    "composer.placeholder" : {
+      "localizations" : {
+        "en" : { "stringUnit" : { "state" : "translated", "value" : "Message" } },
+        "ja" : { "stringUnit" : { "state" : "translated", "value" : "メッセージ" } }
+      }
+    },
+    "PIN GAP %@ pt" : {
+      "localizations" : {
+        "en" : { "stringUnit" : { "state" : "translated", "value" : "PIN GAP %1$@ pt" } },
+        "ja" : { "stringUnit" : { "state" : "translated", "value" : "固定間隔 %1$@ pt" } }
+      }
+    },
+    "shortcut.escape" : {
+      "localizations" : {
+        "en" : { "stringUnit" : { "state" : "translated", "value" : "Esc" } },
+        "ja" : { "stringUnit" : { "state" : "translated", "value" : "Esc" } }
+      }
+    },
+    "stress.accessibility" : {
+      "localizations" : {
+        "en" : { "stringUnit" : { "state" : "translated", "value" : "Rapidly toggle keyboard 20 times" } },
+        "ja" : { "stringUnit" : { "state" : "translated", "value" : "キーボードを20回すばやく切り替える" } }
+      }
+    },
+    "shortcut.tab" : {
+      "localizations" : {
+        "en" : { "stringUnit" : { "state" : "translated", "value" : "Tab" } },
+        "ja" : { "stringUnit" : { "state" : "translated", "value" : "Tab" } }
+      }
+    },
+    "terminal.sample" : {
+      "localizations" : {
+        "en" : { "stringUnit" : { "state" : "translated", "value" : "Last login: Fri Aug 7 19:45:12 on ttys006\n\n~/cmux  git:(feat/keyboard-pinning-lab)\n❯" } },
+        "ja" : { "stringUnit" : { "state" : "translated", "value" : "最終ログイン: 8月7日 金 19:45:12 ttys006\n\n~/cmux  git:(feat/keyboard-pinning-lab)\n❯" } }
+      }
+    },
+    "terminal.accessibility" : {
+      "localizations" : {
+        "en" : { "stringUnit" : { "state" : "translated", "value" : "Terminal. Tap to show keyboard." } },
+        "ja" : { "stringUnit" : { "state" : "translated", "value" : "ターミナル。タップしてキーボードを表示します。" } }
+      }
+    },
+    "workspace.title" : {
+      "localizations" : {
+        "en" : { "stringUnit" : { "state" : "translated", "value" : "cmux DEV lab" } },
+        "ja" : { "stringUnit" : { "state" : "translated", "value" : "cmux DEV ラボ" } }
+      }
+    }
+  },
+  "version" : "1.0"
+}
@@ -0,0 +1 @@
+"CFBundleDisplayName" = "Pinning Lab";
@@ -0,0 +1 @@
+"CFBundleDisplayName" = "ピン留めラボ";
@@ -0,0 +1,32 @@
+name: KeyboardPinningLab
+options:
+  bundleIdPrefix: ai.manaflow
+  deploymentTarget:
+    iOS: "17.0"
+  generateEmptyDirectories: true
+settings:
+  base:
+    DEVELOPMENT_TEAM: 7WLXT3NR37
+    SWIFT_VERSION: 6.0
+    SWIFT_STRICT_CONCURRENCY: complete
+targets:
+  KeyboardPinningLab:
+    type: application
+    platform: iOS
+    sources:
+      - path: App
+      - path: Resources
+    settings:
+      base:
+        PRODUCT_BUNDLE_IDENTIFIER: ai.manaflow.KeyboardPinningLab
+        PRODUCT_NAME: Keyboard Pinning Lab
+        INFOPLIST_KEY_CFBundleDisplayName: Pinning Lab
+        INFOPLIST_KEY_UIApplicationSceneManifest_Generation: true
+        INFOPLIST_KEY_UIApplicationSupportsIndirectInputEvents: true
+        INFOPLIST_KEY_UILaunchScreen_Generation: true
+        INFOPLIST_KEY_UISupportedInterfaceOrientations_iPhone: UIInterfaceOrientationPortrait
+        TARGETED_DEVICE_FAMILY: 1
+        GENERATE_INFOPLIST_FILE: true
+        CODE_SIGN_STYLE: Automatic
+    scheme:
+      testTargets: []
@@ -0,0 +1,591 @@
+public import Foundation
+
+/// The consolidated on-disk application log: one active file with bounded
+/// archives for app-wide events and one equivalent set for network diagnostics.
+///
+/// ``AppLog`` is the durable half of the diagnostics stack. The in-memory
+/// ``DiagnosticLog`` ring stays the single structured spine every subsystem
+/// records into; the composition root taps that ring into an ``AppLog``, which
+/// renders each event through ``DiagnosticEventPresentation`` and appends it to
+/// one of two files:
+///
+/// - the **app log** (``appLogFileName``): every event that is not
+///   network-plane — simulator streaming/control, browser streaming, composer,
+///   render — plus mirrored string debug-log lines, so one file tells the whole
+///   in-app story in wall-clock order;
+/// - the **network log** (``networkLogFileName``): transport dials, discovery,
+///   relay policy, path changes, session lifecycle and close attribution.
+///
+/// Cross-cutting context (app lifecycle, reachability) is written to both so
+/// each file is self-sufficient. Diagnostic events are integer-encoded and
+/// privacy-safe by construction, so persistence is always on, including
+/// Release; the free-text mirror keeps the string log's own gating (DEBUG
+/// always, Release behind the verbose opt-in) because those lines are not
+/// structurally scrubbed.
+///
+/// Ordering: both entry points are non-blocking and feed one buffered stream
+/// drained by a single internal task, so lines land on disk in admission
+/// order. Consecutive frame-pipeline events for the same panel and stage are
+/// coalesced into a `repeated ×N` summary when the run breaks, so a healthy
+/// 20 fps stream costs one line plus one summary instead of megabytes.
+///
+/// The active generation is reopened for appending on the next launch. When
+/// the byte budget is reached it is moved to a timestamped archive, then a
+/// fresh active generation is opened. Archives are bounded by both count and
+/// total bytes, so retention never requires clearing the app container.
+///
+/// Inject one instance from the app composition root; do not add a `.shared`
+/// singleton.
+public actor AppLog {
+    /// Which on-disk file an event belongs to.
+    public enum Domain: Sendable, Equatable {
+        case app
+        case network
+        case both
+    }
+
+    public static let appLogFileName = "cmux-app.log"
+    public static let networkLogFileName = "cmux-network.log"
+    /// The approximate size of one active generation in production.
+    public static let defaultMaxFileBytes = 5_000_000
+    /// Number of timestamped generations retained in addition to the active
+    /// file. A legacy `.1` file is migrated before this limit is applied.
+    public static let defaultMaxArchiveCount = 3
+    /// Per-file retention ceiling, including the active generation.
+    public static let defaultMaxRetainedBytes = 12_000_000
+
+    /// Default location of the app-wide log inside Application Support, or
+    /// `nil` when the directory cannot be resolved. Exists so settings UI can
+    /// offer the file for sharing without holding the ``AppLog`` instance.
+    public static var defaultAppLogFileURL: URL? {
+        defaultFileURL(named: appLogFileName)
+    }
+
+    /// Default location of the network diagnostics log. See
+    /// ``defaultAppLogFileURL``.
+    public static var defaultNetworkLogFileURL: URL? {
+        defaultFileURL(named: networkLogFileName)
+    }
+
+    /// All available generations for the app log, newest first after the
+    /// active file. Settings passes this collection to the share UI so a
+    /// diagnostic export includes the bounded history, not only the active
+    /// generation.
+    public static var appLogFileURLs: [URL] {
+        guard let url = defaultAppLogFileURL else { return [] }
+        return logFileURLs(for: url)
+    }
+
+    /// All available generations for the network log, with the active file
+    /// first. See ``appLogFileURLs``.
+    public static var networkLogFileURLs: [URL] {
+        guard let url = defaultNetworkLogFileURL else { return [] }
+        return logFileURLs(for: url)
+    }
+
+    /// Returns the active file and any retained archive generations for a
+    /// caller-supplied location. The legacy `<name>.1` generation is included
+    /// when a prior build could not migrate it.
+    public static func logFileURLs(for fileURL: URL) -> [URL] {
+        let fileManager = FileManager.default
+        var urls: [URL] = []
+        if fileManager.fileExists(atPath: fileURL.path) {
+            urls.append(fileURL)
+        }
+        urls.append(contentsOf: archiveURLs(for: fileURL))
+        let legacyURL = legacyRotationURL(for: fileURL)
+        if fileManager.fileExists(atPath: legacyURL.path) {
+            urls.append(legacyURL)
+        }
+        return urls
+    }
+
+    private static let archiveMarker = ".archive-"
+
+    private static func legacyRotationURL(for fileURL: URL) -> URL {
+        URL(fileURLWithPath: fileURL.path + ".1")
+    }
+
+    private static func archivePrefix(for fileURL: URL) -> String {
+        let stem = fileURL.pathExtension.isEmpty
+            ? fileURL.lastPathComponent
+            : fileURL.deletingPathExtension().lastPathComponent
+        return "\(stem)\(archiveMarker)"
+    }
+
+    private static func archiveStamp(for url: URL, prefix: String) -> Int64? {
+        let remainder = url.lastPathComponent.dropFirst(prefix.count)
+        let stamp = remainder.prefix(13)
+        guard stamp.count == 13,
+              stamp.allSatisfy({ $0.isNumber }),
+              remainder.dropFirst(stamp.count).first == "-"
+        else {
+            return nil
+        }
+        return Int64(stamp)
+    }
+
+    private static func archiveURLs(for fileURL: URL) -> [URL] {
+        let fileManager = FileManager.default
+        let directory = fileURL.deletingLastPathComponent()
+        let prefix = archivePrefix(for: fileURL)
+        guard let names = try? fileManager.contentsOfDirectory(
+            at: directory,
+            includingPropertiesForKeys: [.contentModificationDateKey, .fileSizeKey],
+            options: [.skipsHiddenFiles]
+        ) else {
+            return []
+        }
+        return names
+            .filter { candidate in
+                candidate.lastPathComponent.hasPrefix(prefix)
+                    && candidate.pathExtension == fileURL.pathExtension
+                    && fileManager.fileExists(atPath: candidate.path)
+            }
+            .sorted { lhs, rhs in
+                let leftStamp = archiveStamp(for: lhs, prefix: prefix)
+                let rightStamp = archiveStamp(for: rhs, prefix: prefix)
+                switch (leftStamp, rightStamp) {
+                case let (left?, right?):
+                    if left != right { return left > right }
+                case (_?, nil):
+                    return true
+                case (nil, _?):
+                    return false
+                case (nil, nil):
+                    break
+                }
+                let leftDate = (try? lhs.resourceValues(
+                    forKeys: [.contentModificationDateKey]
+                ).contentModificationDate) ?? .distantPast
+                let rightDate = (try? rhs.resourceValues(
+                    forKeys: [.contentModificationDateKey]
+                ).contentModificationDate) ?? .distantPast
+                if leftDate != rightDate { return leftDate > rightDate }
+                return lhs.lastPathComponent > rhs.lastPathComponent
+            }
+    }
+
+    private static func makeArchiveURL(for fileURL: URL, date: Date) -> URL {
+        let stem = fileURL.pathExtension.isEmpty
+            ? fileURL.lastPathComponent
+            : fileURL.deletingPathExtension().lastPathComponent
+        let extensionSuffix = fileURL.pathExtension.isEmpty
+            ? ""
+            : ".\(fileURL.pathExtension)"
+        let milliseconds = Int64(date.timeIntervalSince1970 * 1_000)
+        let stamp = String(format: "%013lld", milliseconds)
+        let unique = String(UUID().uuidString.prefix(8))
+        return fileURL.deletingLastPathComponent()
+            .appendingPathComponent(
+                "\(stem)\(archiveMarker)\(stamp)-\(unique)\(extensionSuffix)"
+            )
+    }
+
+    private static func defaultFileURL(named name: String) -> URL? {
+        let fileManager = FileManager.default
+        guard let base = fileManager.urls(
+            for: .applicationSupportDirectory,
+            in: .userDomainMask
+        ).first else { return nil }
+        do {
+            try fileManager.createDirectory(at: base, withIntermediateDirectories: true)
+        } catch {
+            return nil
+        }
+        return base.appendingPathComponent(name)
+    }
+
+    private enum Entry: Sendable {
+        case event(DiagnosticEvent, wall: Date)
+        case appLine(String, wall: Date)
+    }
+
+    private struct LogFile {
+        let url: URL
+        let maxBytes: Int
+        let maxArchiveCount: Int
+        let maxRetainedBytes: Int
+        let header: String
+        let now: @Sendable () -> Date
+        var handle: FileHandle?
+        var bytesWritten = 0
+        /// Byte level at which the next rotation is attempted. Normally
+        /// `maxBytes`; raised after a failed rotate so a sustained failure
+        /// (busy file, read-only directory) retries once per additional
+        /// budget of growth instead of once per appended line.
+        var rotationThreshold: Int
+
+        init(
+            url: URL,
+            maxBytes: Int,
+            maxArchiveCount: Int,
+            maxRetainedBytes: Int,
+            header: String,
+            now: @escaping @Sendable () -> Date
+        ) {
+            self.url = url
+            self.maxBytes = max(1, maxBytes)
+            self.maxArchiveCount = max(1, maxArchiveCount)
+            self.maxRetainedBytes = max(maxRetainedBytes, self.maxBytes)
+            self.header = header
+            self.now = now
+            self.rotationThreshold = max(1, maxBytes)
+            migrateLegacyRotation()
+            if FileManager.default.fileExists(atPath: url.path) {
+                openExistingForAppending()
+                if handle != nil, bytesWritten >= self.maxBytes {
+                    _ = rotate()
+                }
+            } else {
+                _ = openFreshGeneration()
+            }
+            if handle != nil {
+                pruneArchives()
+            }
+        }
+
+        /// Moves a legacy `<name>.1` generation into the timestamped archive
+        /// namespace. If the move cannot be completed, the legacy file stays
+        /// untouched and remains shareable.
+        private mutating func migrateLegacyRotation() {
+            let fileManager = FileManager.default
+            let legacyURL = AppLog.legacyRotationURL(for: url)
+            guard fileManager.fileExists(atPath: legacyURL.path) else { return }
+            let archiveURL = AppLog.makeArchiveURL(for: url, date: now())
+            try? fileManager.moveItem(at: legacyURL, to: archiveURL)
+        }
+
+        /// Opens a new active generation. This method never removes or
+        /// overwrites an existing file. The caller must move an old active
+        /// generation away first.
+        @discardableResult
+        private mutating func openFreshGeneration() -> Bool {
+            let fileManager = FileManager.default
+            guard !fileManager.fileExists(atPath: url.path),
+                  fileManager.createFile(atPath: url.path, contents: nil),
+                  let opened = try? FileHandle(forWritingTo: url) else {
+                handle = nil
+                return false
+            }
+            handle = opened
+            bytesWritten = 0
+            rotationThreshold = maxBytes
+            write(header)
+            return handle != nil
+        }
+
+        /// Rotates the active generation into a unique archive. A failed move
+        /// reopens the original file for appending and leaves every existing
+        /// byte in place. If creating the replacement fails after the move,
+        /// the archive is restored when possible; otherwise it remains on disk
+        /// and is still returned by ``AppLog.logFileURLs(for:)``.
+        @discardableResult
+        private mutating func rotate() -> Bool {
+            let fileManager = FileManager.default
+            guard fileManager.fileExists(atPath: url.path) else {
+                return openFreshGeneration()
+            }
+            close()
+            let archiveURL = AppLog.makeArchiveURL(for: url, date: now())
+            do {
+                try fileManager.moveItem(at: url, to: archiveURL)
+            } catch {
+                openExistingForAppending()
+                rotationThreshold = bytesWritten + maxBytes
+                return false
+            }
+            guard openFreshGeneration() else {
+                if !fileManager.fileExists(atPath: url.path) {
+                    try? fileManager.moveItem(at: archiveURL, to: url)
+                }
+                openExistingForAppending()
+                rotationThreshold = bytesWritten + maxBytes
+                return false
+            }
+            pruneArchives()
+            return true
+        }
+
+        /// Keeps writing to the current generation. Existing files are opened
+        /// at their end, never truncated. An empty pre-existing file receives
+        /// the generation header once.
+        private mutating func openExistingForAppending() {
+            guard let opened = try? FileHandle(forWritingTo: url),
+                  let size = try? opened.seekToEnd() else {
+                // A generation that cannot be opened or positioned at its end
+                // is not safely appendable: writing from offset 0 would
+                // overwrite the content this fallback exists to preserve.
+                handle = nil
+                return
+            }
+            handle = opened
+            bytesWritten = Int(clamping: size)
+            rotationThreshold = maxBytes
+            if bytesWritten == 0 {
+                write(header)
+            }
+        }
+
+        mutating func append(_ line: String) {
+            guard handle != nil else { return }
+            let data = Data((line + "\n").utf8)
+            if bytesWritten + data.count > rotationThreshold {
+                _ = rotate()
+            }
+            write(line)
+        }
+
+        /// Removes only timestamped archives, and only after a new active
+        /// generation has been opened. The newest archive is always kept even
+        /// if one unusually large line temporarily exceeds the byte ceiling.
+        private mutating func pruneArchives() {
+            let fileManager = FileManager.default
+            var archives = AppLog.archiveURLs(for: url)
+            guard !archives.isEmpty else { return }
+            var totalBytes = fileSize(of: url)
+            var archiveSizes = archives.map { fileSize(of: $0) }
+            totalBytes += archiveSizes.reduce(0, +)
+            while archives.count > maxArchiveCount || totalBytes > maxRetainedBytes {
+                guard archives.count > 1 else { break }
+                let oldestIndex = archives.count - 1
+                let oldest = archives.remove(at: oldestIndex)
+                let oldestSize = archiveSizes.remove(at: oldestIndex)
+                do {
+                    try fileManager.removeItem(at: oldest)
+                    totalBytes -= oldestSize
+                } catch {
+                    // A protection or sharing failure should never cause us
+                    // to remove a different, newer generation.
+                    break
+                }
+            }
+        }
+
+        private func fileSize(of fileURL: URL) -> Int {
+            guard let values = try? fileURL.resourceValues(forKeys: [.fileSizeKey]),
+                  let size = values.fileSize else {
+                return 0
+            }
+            return size
+        }
+
+        private mutating func write(_ line: String) {
+            guard let handle else { return }
+            let data = Data((line + "\n").utf8)
+            do {
+                try handle.write(contentsOf: data)
+                bytesWritten += data.count
+            } catch {
+                try? handle.close()
+                self.handle = nil
+            }
+        }
+
+        mutating func close() {
+            try? handle?.close()
+            handle = nil
+        }
+    }
+
+    /// One in-progress run of coalescible frame events.
+    private struct FrameRun {
+        let key: FrameRunKey
+        var lastEvent: DiagnosticEvent
+        var count: Int
+    }
+
+    private struct FrameRunKey: Equatable {
+        let code: DiagnosticEventCode
+        let surface: UInt32?
+        let stage: Int?
+    }
+
+    private var appFile: LogFile?
+    private var networkFile: LogFile?
+    private var pendingFrameRun: FrameRun?
+    private var processed = 0
+    private let presentation = DiagnosticEventPresentation()
+    private let timestampFormatter: ISO8601DateFormatter
+    private let ingress: AsyncStream<Entry>.Continuation
+
+    /// Create a log writing to the given locations. Passing `nil` for a URL
+    /// disables that file (used by tests exercising one file at a time).
+    public init(
+        appFileURL: URL?,
+        networkFileURL: URL?,
+        maxFileBytes: Int = AppLog.defaultMaxFileBytes,
+        buildStamp: String = "",
+        maxArchiveCount: Int = AppLog.defaultMaxArchiveCount,
+        maxRetainedBytes: Int = AppLog.defaultMaxRetainedBytes,
+        now: @escaping @Sendable () -> Date = { Date() }
+    ) {
+        let formatter = ISO8601DateFormatter()
+        formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+        timestampFormatter = formatter
+        let started = formatter.string(from: now())
+        if let appFileURL {
+            appFile = LogFile(
+                url: appFileURL,
+                maxBytes: maxFileBytes,
+                maxArchiveCount: maxArchiveCount,
+                maxRetainedBytes: maxRetainedBytes,
+                header: "cmux app log · \(buildStamp) · started \(started)",
+                now: now
+            )
+        }
+        if let networkFileURL {
+            networkFile = LogFile(
+                url: networkFileURL,
+                maxBytes: maxFileBytes,
+                maxArchiveCount: maxArchiveCount,
+                maxRetainedBytes: maxRetainedBytes,
+                header: "cmux network diagnostics log · \(buildStamp) · started \(started)",
+                now: now
+            )
+        }
+        let (stream, continuation) = AsyncStream<Entry>.makeStream(
+            bufferingPolicy: .bufferingNewest(2048)
+        )
+        ingress = continuation
+        // The drain holds self only across one write; when the log deallocs,
+        // `deinit` finishes the stream and the loop ends on its own.
+        Task { [weak self] in
+            for await entry in stream {
+                guard let self else { return }
+                await self.write(entry)
+            }
+        }
+    }
+
+    deinit {
+        ingress.finish()
+    }
+
+    /// Record one structured diagnostic event. Non-blocking and safe to call
+    /// from the ``DiagnosticLog`` event tap (which runs on the ring's drain
+    /// task and must not block).
+    public nonisolated func ingest(_ event: DiagnosticEvent) {
+        ingress.yield(.event(event, wall: Date()))
+    }
+
+    /// Mirror one free-text debug-log line into the app file. The caller owns
+    /// the privacy gating (the string debug log only produces lines in DEBUG
+    /// or behind the user's verbose opt-in).
+    public nonisolated func mirrorAppLine(_ line: String) {
+        ingress.yield(.appLine(line, wall: Date()))
+    }
+
+    /// The total number of entries the drain task has written. Never
+    /// decreases, so after admitting `n` entries a test can poll this to `n`
+    /// to know everything reached the files, without sleeping.
+    public func processedCount() -> Int {
+        processed
+    }
+
+    /// Flushes a pending coalesced frame run to disk. Test-only
+    /// synchronization; in production runs flush when they break.
+    public func flushForTesting() {
+        flushPendingFrameRun()
+    }
+
+    private func write(_ entry: Entry) {
+        processed += 1
+        switch entry {
+        case .event(let event, let wall):
+            writeEvent(event, wall: wall)
+        case .appLine(let line, let wall):
+            flushPendingFrameRun()
+            appFile?.append("\(timestampFormatter.string(from: wall)) \(line)")
+        }
+    }
+
+    private func writeEvent(_ event: DiagnosticEvent, wall: Date) {
+        if let key = Self.frameRunKey(for: event) {
+            if var run = pendingFrameRun, run.key == key {
+                run.lastEvent = event
+                run.count += 1
+                pendingFrameRun = run
+                return
+            }
+            flushPendingFrameRun()
+            appendRendered(event, wall: wall)
+            pendingFrameRun = FrameRun(key: key, lastEvent: event, count: 1)
+            return
+        }
+        flushPendingFrameRun()
+        appendRendered(event, wall: wall)
+    }
+
+    /// Frame-pipeline events repeat at frame cadence with only the sequence
+    /// and byte count varying; they coalesce per (code, panel, stage).
+    private static func frameRunKey(for event: DiagnosticEvent) -> FrameRunKey? {
+        guard event.code == .simulatorFrameLifecycle else { return nil }
+        return FrameRunKey(code: event.code, surface: event.surface, stage: event.a)
+    }
+
+    private func flushPendingFrameRun() {
+        guard let run = pendingFrameRun else { return }
+        pendingFrameRun = nil
+        guard run.count > 1 else { return }
+        let summary = presentation.summary(run.lastEvent)
+        append(
+            line: "\(timestampFormatter.string(from: Date())) \(summary) (repeated ×\(run.count))",
+            domain: run.key.code.appLogDomain
+        )
+    }
+
+    private func appendRendered(_ event: DiagnosticEvent, wall: Date) {
+        append(
+            line: "\(timestampFormatter.string(from: wall)) \(presentation.summary(event))",
+            domain: event.code.appLogDomain
+        )
+    }
+
+    private func append(line: String, domain: Domain) {
+        switch domain {
+        case .app:
+            appFile?.append(line)
+        case .network:
+            networkFile?.append(line)
+        case .both:
+            appFile?.append(line)
+            networkFile?.append(line)
+        }
+    }
+}
+
+public extension DiagnosticEventCode {
+    /// Which on-disk log this event belongs to: the app-wide log, the network
+    /// diagnostics log, or both (cross-cutting context that keeps each file
+    /// self-sufficient). New codes default to the app log.
+    var appLogDomain: AppLog.Domain {
+        switch self {
+        case .connect, .pairOk, .pairFail, .pairUnreachable,
+             .livenessResubscribe, .streamEnded, .inputSeqBehind, .byteGap,
+             .transportDialStarted, .transportDialConnected, .transportDialFailed,
+             .hostAuthenticated, .hostAuthenticationFailed,
+             .rpcReady, .rpcFailed,
+             .recoveryStarted, .recoverySucceeded, .recoveryFailed,
+             .endpointStarting, .endpointActive, .endpointStopped, .endpointFailed,
+             .relayPolicyRefreshStarted, .relayPolicyRefreshSucceeded,
+             .relayPolicyRefreshFailed,
+             .selectedPathChanged, .sessionClosed, .routeUnavailable,
+             .retryScheduled,
+             .discoveryStarted, .discoverySucceeded, .discoveryFailed,
+             .admissionSucceeded, .admissionFailed,
+             .transportSessionLifecycle,
+             .transportCloseAttribution, .transportPathEvent,
+             .transportDialPlanBuilt, .transportPrivateAddressJoin,
+             .transportLANDiscovery, .transportDialLegSucceeded,
+             .transportDialLegFailed, .lanPublicationState,
+             .transportDialSessionLinked, .transportDialCancelled,
+             .transportCloseReason:
+            return .network
+        case .appLifecycleChanged, .reachabilityChanged:
+            return .both
+        default:
+            return .app
+        }
+    }
+}
@@ -0,0 +1,161 @@
+/// A privacy-safe, staged explanation of Iroh connection readiness.
+public struct CmxIrohConnectionCheckReport: Equatable, Sendable {
+    public enum Role: Equatable, Sendable {
+        case mobileClient
+        case macHost
+    }
+
+    public enum StageKind: CaseIterable, Hashable, Sendable {
+        case encryptedTransport
+        case relayPolicy
+        case relayReachability
+        case macDiscovery
+        case secureSession
+    }
+
+    public enum StageStatus: Equatable, Sendable {
+        case passed
+        case warning
+        case failed
+        case notApplicable
+    }
+
+    public enum RelayReachability: Equatable, Sendable {
+        case notConfigured
+        case reachable
+        case unreachable
+        case unavailable
+    }
+
+    public enum MacDiscovery: Equatable, Sendable {
+        case found
+        case missing
+        case unavailable
+    }
+
+    public enum Recommendation: Equatable, Sendable {
+        case none
+        case retry
+        case checkInternet
+        case openMacApp
+        case allowRelayTraffic
+        case refreshAccount
+        case reviewRelaySettings
+        case updateOrRepair
+    }
+
+    public struct Stage: Identifiable, Equatable, Sendable {
+        public var id: StageKind { kind }
+        public let kind: StageKind
+        public let status: StageStatus
+
+        public init(kind: StageKind, status: StageStatus) {
+            self.kind = kind
+            self.status = status
+        }
+    }
+
+    public let role: Role
+    public let stages: [Stage]
+    public let recommendation: Recommendation
+    public let failureKind: DiagnosticFailureKind?
+    public let selectedPath: CmxIrohSelectedTransportPath
+
+    public var isReady: Bool {
+        !stages.contains { $0.status == .failed }
+    }
+
+    public init(
+        role: Role,
+        snapshot: CmxIrohSettingsSnapshot,
+        diagnostics: DiagnosticReport,
+        relayReachability: RelayReachability,
+        macDiscovery: MacDiscovery = .unavailable
+    ) {
+        self.role = role
+        failureKind = diagnostics.lastFailureKind
+        selectedPath = snapshot.selectedTransportPath
+
+        let transportStatus: StageStatus = switch snapshot.runtimeStatus {
+        case .inactive, .degraded: .failed
+        case .starting: .warning
+        case .active, .direct, .relayed, .privateNetwork: .passed
+        }
+        let policyStatus: StageStatus = switch snapshot.policySource {
+        case .server: .passed
+        case .cached: .warning
+        case .unavailable: .failed
+        }
+        let relayStatus: StageStatus = switch relayReachability {
+        case .notConfigured: .notApplicable
+        case .reachable: .passed
+        case .unreachable: .failed
+        case .unavailable: .failed
+        }
+        let discoveryStatus: StageStatus
+        let sessionStatus: StageStatus
+        switch role {
+        case .macHost:
+            discoveryStatus = .notApplicable
+            sessionStatus = .notApplicable
+        case .mobileClient:
+            discoveryStatus = switch macDiscovery {
+            case .found: .passed
+            case .missing, .unavailable: .failed
+            }
+            sessionStatus = snapshot.selectedTransportPath == .unavailable ? .failed : .passed
+        }
+
+        stages = [
+            Stage(kind: .encryptedTransport, status: transportStatus),
+            Stage(kind: .relayPolicy, status: policyStatus),
+            Stage(kind: .relayReachability, status: relayStatus),
+            Stage(kind: .macDiscovery, status: discoveryStatus),
+            Stage(kind: .secureSession, status: sessionStatus),
+        ]
+        recommendation = Self.recommendation(
+            role: role,
+            transportStatus: transportStatus,
+            policyStatus: policyStatus,
+            relayReachability: relayReachability,
+            discoveryStatus: discoveryStatus,
+            sessionStatus: sessionStatus,
+            failureKind: diagnostics.lastFailureKind,
+            hasRelayConfigurationProblem: !snapshot.staleRelayIDs.isEmpty
+                || snapshot.failureDescription != nil
+        )
+    }
+
+    private static func recommendation(
+        role: Role,
+        transportStatus: StageStatus,
+        policyStatus: StageStatus,
+        relayReachability: RelayReachability,
+        discoveryStatus: StageStatus,
+        sessionStatus: StageStatus,
+        failureKind: DiagnosticFailureKind?,
+        hasRelayConfigurationProblem: Bool
+    ) -> Recommendation {
+        if transportStatus == .failed, failureKind == .offline { return .checkInternet }
+        if policyStatus == .failed || hasRelayConfigurationProblem {
+            return .reviewRelaySettings
+        }
+        // Corporate-allowlist advice requires a relay that was actually probed
+        // and blocked. An unavailable probe is indeterminate (inactive runtime,
+        // unreadable path hints), so it must never send users to IT.
+        if relayReachability == .unreachable { return .allowRelayTraffic }
+        if transportStatus == .failed { return .refreshAccount }
+        if role == .mobileClient, discoveryStatus == .failed { return .openMacApp }
+        if role == .mobileClient, sessionStatus == .failed {
+            switch failureKind {
+            case .identityMismatch, .accountMismatch, .authorizationFailed,
+                 .admissionDenied, .secureChannelFailed:
+                return .updateOrRepair
+            default:
+                return .retry
+            }
+        }
+        if relayReachability == .unavailable { return .retry }
+        return .none
+    }
+}
@@ -1,6 +1,6 @@
 public import Foundation

-/// Release-safe, device-local Iroh path constraint chosen in Settings.
+/// Legacy device-local Iroh path preference retained for version compatibility.
 public enum CmxIrohPathPreference: String, CaseIterable, Equatable, Sendable {
    /// Allows Iroh to select automatic, direct, private-network, or relay paths.
    case automatic = "auto"
@@ -8,14 +8,21 @@ public enum CmxIrohPathPreference: String, CaseIterable, Equatable, Sendable {
    /// Keeps Iroh connections on relay paths.
    case relayOnly

+    /// Prevents this device from listening or dialing through Iroh relays.
+    case neverUseRelays
+
    /// Shared defaults key used independently by the macOS and iOS apps.
    public static let defaultsKey = "cmux.iroh.pathPreference"

-    /// The transport constraint this preference imposes on the runtime.
+    /// The release transport mode after normalizing retired preferences.
+    ///
+    /// Relay-only is a DEBUG verification mode. A value persisted by an older
+    /// release must not constrain a current production connection.
    public var transportVerificationMode: CmxIrohTransportVerificationMode {
        switch self {
        case .automatic: .automatic
-        case .relayOnly: .relayOnly
+        case .relayOnly: .automatic
+        case .neverUseRelays: .directOnly
        }
    }

@@ -0,0 +1,26 @@
+import Foundation
+
+public extension Sequence where Element == String {
+    /// Returns unique, sorted, credential-free HTTPS origins suitable for an IT allowlist.
+    func cmxIrohCanonicalRelayOrigins() -> [String] {
+        Array(Set(compactMap { rawValue in
+            guard let components = URLComponents(string: rawValue),
+                  components.scheme?.lowercased() == "https",
+                  let host = components.host,
+                  !host.isEmpty,
+                  components.user == nil,
+                  components.password == nil,
+                  components.query == nil,
+                  components.fragment == nil,
+                  components.path.isEmpty || components.path == "/" else {
+                return nil
+            }
+
+            var origin = URLComponents()
+            origin.scheme = "https"
+            origin.host = host
+            origin.port = components.port
+            return origin.string
+        })).sorted()
+    }
+}
@@ -27,12 +27,19 @@ public protocol CmxIrohSettingsControlling: AnyObject {
    /// Probes one custom relay without changing the active preference.
    func testIrohCustomRelay(id: String) async -> CmxIrohRelayTestResult

+    /// Runs a bounded, privacy-safe check of the active encrypted connection path.
+    func runIrohConnectionCheck() async -> CmxIrohConnectionCheckReport
+
    /// Persists one device-local custom private-path configuration.
    func upsertIrohCustomPrivatePath(_ path: CmxIrohCustomPrivatePathDraft) async throws

    /// Removes this device's custom private paths for one Mac.
    func removeIrohCustomPrivatePath(macDeviceID: String) async throws

+    /// Restores the active networking choices to their safe defaults without
+    /// deleting saved relay definitions or private addresses.
+    func resetIrohSettingsToDefaults() async throws
+
    /// Fetches the latest signed fleet and account preference.
    func refreshIrohSettings() async

@@ -51,6 +58,16 @@ public protocol CmxIrohSettingsControlling: AnyObject {
 }

 public extension CmxIrohSettingsControlling {
+    func runIrohConnectionCheck() async -> CmxIrohConnectionCheckReport {
+        CmxIrohConnectionCheckReport(
+            role: .mobileClient,
+            snapshot: await irohSettingsSnapshot(),
+            diagnostics: await irohDiagnosticReport(),
+            relayReachability: .unavailable,
+            macDiscovery: .unavailable
+        )
+    }
+
    func setIrohPathPreference(_ preference: CmxIrohPathPreference) async throws {
        throw CmxIrohSettingsControlError.unsupported
    }
@@ -63,6 +80,35 @@ public extension CmxIrohSettingsControlling {
        throw CmxIrohSettingsControlError.unsupported
    }

+    func resetIrohSettingsToDefaults() async throws {
+        let snapshot = await irohSettingsSnapshot()
+        var firstError: (any Error)?
+
+        do {
+            try await setIrohRelayPreference(.automatic)
+        } catch {
+            firstError = error
+        }
+        do {
+            try await setIrohPathPreference(.automatic)
+        } catch {
+            firstError = firstError ?? error
+        }
+        for privateNetwork in snapshot.customPrivateNetworks where privateNetwork.isEnabled {
+            do {
+                try await upsertIrohCustomPrivatePath(.init(
+                    macDeviceID: privateNetwork.macDeviceID,
+                    macDisplayName: privateNetwork.macDisplayName,
+                    addresses: privateNetwork.addresses,
+                    isEnabled: false
+                ))
+            } catch {
+                firstError = firstError ?? error
+            }
+        }
+        if let firstError { throw firstError }
+    }
+
    func irohDiagnosticReport() async -> DiagnosticReport {
        .empty
    }
@@ -92,10 +92,16 @@ public struct CmxIrohSettingsSnapshot: Equatable, Sendable {
    public struct PrivateNetworkMac: Identifiable, Equatable, Sendable {
        public let id: String
        public let displayName: String
+        public let supportsPrivatePaths: Bool

-        public init(id: String, displayName: String) {
+        public init(
+            id: String,
+            displayName: String,
+            supportsPrivatePaths: Bool = false
+        ) {
            self.id = id
            self.displayName = displayName
+            self.supportsPrivatePaths = supportsPrivatePaths
        }
    }

@@ -12,9 +12,16 @@ public struct CmxLegacyPrivateNetworkPairingCode: Sendable {

    /// Returns a tokenless Tailscale-only v1 pairing URL, or `nil` when the
    /// ticket has no Tailscale route to disclose.
-    public func encode(_ ticket: CmxAttachTicket) throws -> URL? {
+    public func encode(
+        _ ticket: CmxAttachTicket,
+        pairingURLScheme: CmxPairingURLScheme? =
+            CmxPairingURLSchemeResolver().resolved
+    ) throws -> URL? {
        let tailscaleRoutes = ticket.routes.filter { $0.kind == .tailscale }
-        guard !tailscaleRoutes.isEmpty else { return nil }
+        guard !tailscaleRoutes.isEmpty,
+              let scheme = pairingURLScheme?.rawValue else {
+            return nil
+        }

        let legacyTicket = try CmxAttachTicket(
            version: ticket.version,
@@ -35,7 +42,7 @@ public struct CmxLegacyPrivateNetworkPairingCode: Sendable {
        encoder.dateEncodingStrategy = .iso8601
        let payload = base64URLEncode(try encoder.encode(legacyTicket))
        return URL(
-            string: "\(CmxPairingURLScheme.current)://attach?v=\(legacyTicket.version)&payload=\(payload)"
+            string: "\(scheme)://attach?v=\(legacyTicket.version)&payload=\(payload)"
        )
    }

@@ -77,8 +77,13 @@ public struct CmxPairingQRCode: Sendable {
    /// route is dropped, never written into a scannable code.
    public func encode(
        _ ticket: CmxAttachTicket,
-        routeDisclosureMode: CmxPairingRouteDisclosureMode
+        routeDisclosureMode: CmxPairingRouteDisclosureMode,
+        pairingURLScheme: CmxPairingURLScheme? =
+            CmxPairingURLSchemeResolver().resolved
    ) -> String? {
+        guard let scheme = pairingURLScheme?.rawValue else {
+            return nil
+        }
        let items: [String]
        switch routeDisclosureMode {
        case .irohIdentityOnly:
@@ -119,7 +124,7 @@ public struct CmxPairingQRCode: Sendable {
        // Mac's QR opens the dev iOS build, a release Mac's QR opens the
        // release build, and the system camera can no longer hand a beta/prod
        // code to a dev build that also claimed the scheme.
-        return "\(CmxPairingURLScheme.current)://attach?" + items.joined(separator: "&")
+        return "\(scheme)://attach?" + items.joined(separator: "&")
    }

    /// Whether `ticket` is expressible in the selected minimal grammar.
@@ -224,7 +229,7 @@ public struct CmxPairingQRCode: Sendable {
    /// the minimal grammar).
    public func isPairingCodeURLString(_ rawValue: String) -> Bool {
        guard let url = URL(string: rawValue),
-              CmxPairingURLScheme.isPairingScheme(url.scheme),
+              CmxPairingURLScheme(rawValue: url.scheme) != nil,
              url.host == "attach",
              let components = URLComponents(url: url, resolvingAgainstBaseURL: false) else {
            return false
@@ -316,7 +321,10 @@ private extension CmxPairingQRCode {
            terminalID: nil,
            macDeviceID: "",
            macDisplayName: nil,
-            macPairingCompatibilityVersion: 0,
+            // v3 is intentionally endpoint-only. `nil` means the QR did not
+            // make a compatibility claim, unlike v2's explicit unknown value
+            // (0), which must continue to trigger its legacy warning.
+            macPairingCompatibilityVersion: nil,
            routes: [route],
            expiresAt: nil,
            authToken: nil
@@ -1,75 +1,95 @@
 import Foundation

-/// The channel-specific URL scheme carried by cmux pairing/attach deep links.
+/// One validated URL scheme carried by a cmux pairing or attach deep link.
 ///
-/// All builds used to register and emit one scheme (`cmux-ios`), so scanning a
-/// beta/prod pairing QR with the iOS Camera app could open a *dev* build that
-/// happened to be installed (the OS picks an arbitrary app when several claim
-/// a scheme). The scheme is therefore channel-specific, mirroring how
-/// `MobileBuildType` splits channels:
-///
-/// - **Development (DEBUG)** builds — local Xcode and `reload.sh` tagged
-///   builds on both Mac and iPhone — register and emit ``development``.
-/// - **Release** builds (TestFlight beta and App Store prod) register and
-///   emit ``release``. Beta and prod share a scheme because they are the same
-///   compile configuration and a phone realistically has only one of them.
-///
-/// Emitters (the Mac building a pairing QR or attach URL) use ``current`` so a
-/// dev Mac pairs a dev phone and a release Mac pairs a release phone via the
-/// system camera. Parsers (the in-app scanner, manual paste, the root scene's
-/// deep-link gate) accept *any* pairing scheme via ``isPairingScheme(_:)`` /
-/// ``hasPairingScheme(_:)``, so cross-channel pairing still works when the
-/// user scans from inside the app.
-///
-/// The iOS app's registered scheme comes from `CMUX_IOS_URL_SCHEME` in
-/// `ios/Config/Shared.xcconfig` (dev) and `ios/Config/Release.xcconfig`
-/// (release); keep those values in sync with these constants.
-///
-/// lint:allow namespace-type — the build channel's URL scheme is a pure
-/// compile-time constant set with no per-instance state to inject; these
-/// scheme strings and the stateless pairing-scheme predicates are a genuine
-/// namespace, like the sanctioned FFI/seam holders.
+/// Every installed iOS bundle registers exactly one scheme derived from its
+/// complete bundle identifier. Parsers also accept the two historical shared
+/// schemes so an old QR remains scannable inside an already-open app, but new
+/// apps never register those shared schemes with iOS.
 public struct CmxPairingURLScheme {
-    private init() {}
+    /// The validated, lowercase URL scheme.
+    public let rawValue: String

-    /// The scheme Release (TestFlight beta + App Store) builds register and emit.
+    /// Creates the exact scheme registered by one installed iOS bundle.
+    public init?(iOSBundleIdentifier: String?) {
+        guard let namespace = MobileIOSAppNamespace(
+            bundleIdentifier: iOSBundleIdentifier
+        ) else {
+            return nil
+        }
+        let scheme = namespace.pairingURLScheme.lowercased()
+        guard Self.releaseSchemes.contains(scheme)
+                || scheme == Self.untaggedDevelopmentScheme
+                || scheme.hasPrefix(Self.developmentPrefix) else {
+            return nil
+        }
+        rawValue = scheme
+    }
+
+    /// Parses a classifiable bundle-specific or historical shared pairing
+    /// scheme. Unknown release-like namespaces fail closed so account preflight
+    /// cannot be bypassed by a syntactically valid but unclassified scheme.
+    public init?(rawValue: String?) {
+        guard let rawValue else { return nil }
+        let normalized = rawValue.lowercased()
+        if Self.all.contains(normalized) {
+            self.rawValue = normalized
+            return
+        }
+        let prefix = "cmux-ios-"
+        guard normalized.hasPrefix(prefix),
+              MobileIOSAppNamespace(
+                bundleIdentifier: String(normalized.dropFirst(prefix.count))
+              ) != nil,
+              Self.releaseSchemes.contains(normalized)
+                || normalized == Self.untaggedDevelopmentScheme
+                || normalized.hasPrefix(Self.developmentPrefix) else {
+            return nil
+        }
+        self.rawValue = normalized
+    }
+
+    /// Parses the scheme from a complete pairing URL.
+    public init?(urlString: String) {
+        guard urlString.contains("://"),
+              let components = URLComponents(string: urlString),
+              let scheme = CmxPairingURLScheme(rawValue: components.scheme) else {
+            return nil
+        }
+        self = scheme
+    }
+
+    /// Whether this scheme identifies a tagged iOS development build.
+    public var isDevelopment: Bool {
+        rawValue == Self.development
+            || rawValue == Self.untaggedDevelopmentScheme
+            || rawValue.hasPrefix(Self.developmentPrefix)
+    }
+
+    /// Whether this scheme identifies an App Store or TestFlight build.
+    public var isRelease: Bool {
+        Self.releaseSchemes.contains(rawValue)
+    }
+
+    /// Historical shared Release scheme. Parse-only in new iOS builds.
    public static let release = "cmux-ios"

-    /// The scheme development (DEBUG/tagged) builds register and emit.
+    /// Historical shared development scheme. Parse-only in new iOS builds.
    public static let development = "cmux-ios-dev"

-    /// Every scheme any cmux build may emit; parsers accept all of them.
+    /// Historical schemes retained for source compatibility and old QR tests.
    public static let all: [String] = [release, development]

-    /// The scheme this build emits in pairing QRs and attach URLs.
-    public static var current: String {
-        scheme(isDevelopmentBuild: isDevelopmentBuild)
-    }
+    private static let untaggedDevelopmentScheme = "cmux-ios-dev.cmux.ios"
+    private static let developmentPrefix = "cmux-ios-dev.cmux.ios."

-    /// Pure channel-to-scheme mapping, injected with the compile flag so the
-    /// derivation is testable from a single build configuration.
-    public static func scheme(isDevelopmentBuild: Bool) -> String {
-        isDevelopmentBuild ? development : release
-    }
-
-    /// Whether `scheme` is a pairing scheme from any cmux channel.
-    public static func isPairingScheme(_ scheme: String?) -> Bool {
-        guard let scheme else { return false }
-        return all.contains { $0.caseInsensitiveCompare(scheme) == .orderedSame }
-    }
-
-    /// Whether `rawValue` starts with any channel's pairing scheme (the
-    /// scanner/paste-side prefix check, before URL parsing).
-    public static func hasPairingScheme(_ rawValue: String) -> Bool {
-        let lowercased = rawValue.lowercased()
-        return all.contains { lowercased.hasPrefix($0 + "://") }
-    }
-
-    private static var isDevelopmentBuild: Bool {
-        #if DEBUG
-        true
-        #else
-        false
-        #endif
-    }
+    private static let releaseSchemes: Set<String> = [
+        release,
+        "cmux-ios-com.cmux.app",
+        "cmux-ios-dev.cmux.app.beta",
+        "cmux-ios-dev.cmux.app.internal",
+        "cmux-ios-dev.cmux.app.demo",
+    ]
 }
+
+extension CmxPairingURLScheme: Equatable, Sendable {}
@@ -0,0 +1,71 @@
+import Foundation
+
+/// Resolves the pairing target for the current process without global state.
+public struct CmxPairingURLSchemeResolver: Sendable {
+    private let currentIOSBundleIdentifier: String?
+    private let targetIOSBundleIdentifier: String?
+    private let macInstanceTag: String?
+    private let isDevelopmentBuild: Bool
+
+    /// Captures the current app identity and any explicit Mac pairing target.
+    ///
+    /// A Mac may set `CMUX_IOS_PAIRING_BUNDLE_IDENTIFIER` to any authoritative
+    /// release-lane bundle id. Tagged Mac builds otherwise target their exact
+    /// same-tag iOS bundle.
+    public init(
+        bundle: Bundle = .main,
+        environment: [String: String] = ProcessInfo.processInfo.environment
+    ) {
+        currentIOSBundleIdentifier = bundle.bundleIdentifier
+        targetIOSBundleIdentifier =
+            environment["CMUX_IOS_PAIRING_BUNDLE_IDENTIFIER"]
+        macInstanceTag = environment["CMUX_TAG"]
+        #if DEBUG
+        isDevelopmentBuild = true
+        #else
+        isDevelopmentBuild = false
+        #endif
+    }
+
+    init(
+        currentIOSBundleIdentifier: String?,
+        targetIOSBundleIdentifier: String?,
+        macInstanceTag: String?,
+        isDevelopmentBuild: Bool
+    ) {
+        self.currentIOSBundleIdentifier = currentIOSBundleIdentifier
+        self.targetIOSBundleIdentifier = targetIOSBundleIdentifier
+        self.macInstanceTag = macInstanceTag
+        self.isDevelopmentBuild = isDevelopmentBuild
+    }
+
+    /// The exact scheme this process should emit, or `nil` on invalid identity.
+    public var resolved: CmxPairingURLScheme? {
+        #if os(iOS)
+        return CmxPairingURLScheme(
+            iOSBundleIdentifier: currentIOSBundleIdentifier
+        )
+        #else
+        if let targetIOSBundleIdentifier {
+            return CmxPairingURLScheme(
+                iOSBundleIdentifier: targetIOSBundleIdentifier
+            )
+        }
+        if macInstanceTag == nil || macInstanceTag?.isEmpty == true {
+            return CmxPairingURLScheme(
+                iOSBundleIdentifier: isDevelopmentBuild
+                    ? "dev.cmux.ios"
+                    : "com.cmux.app"
+            )
+        }
+        guard let namespace = MobileIOSAppNamespace(
+            pairedMacInstanceTag: macInstanceTag
+        ) else {
+            return nil
+        }
+        return CmxPairingURLScheme(
+            iOSBundleIdentifier: namespace.bundleIdentifier
+        )
+        #endif
+    }
+}
@@ -422,6 +422,15 @@ public protocol CmxByteTransportContinuityIdentifying: CmxByteTransport {
    func transportContinuityID() async -> UInt64?
 }

+/// Optional privacy-safe link from a byte dial to the admitted transport
+/// session that backs it. The value is process-local and never leaves the
+/// diagnostic ring.
+public protocol CmxByteTransportDiagnosticSessionIdentifying: CmxByteTransport {
+    /// Returns the current admitted session ID, or `nil` before connection or
+    /// after the session has been released.
+    func transportDiagnosticSessionID() async -> Int?
+}
+
 /// A privacy-safe handle that waits for one exact native transport to close.
 ///
 /// The handle captures the transport generation at creation time, so callers
@@ -0,0 +1,164 @@
+import Foundation
+
+/// Fixed terminal-toolbar actions stored in the value payload of
+/// ``DiagnosticAppEventKind/terminalToolbarActionUsed``.
+///
+/// Values 0...31 mirror the persisted `TerminalInputAccessoryAction` raw
+/// values. Values starting at 100 are fixed controls outside that configurable
+/// action list. Append only, because these values ship in diagnostic reports.
+public enum DiagnosticTerminalToolbarAction: Int, Sendable, Codable, CaseIterable {
+    case control = 0
+    case alternate = 1
+    case command = 2
+    case shift = 3
+    case zoomOut = 4
+    case zoomIn = 5
+    case escape = 6
+    case tab = 7
+    case upArrow = 8
+    case downArrow = 9
+    case leftArrow = 10
+    case rightArrow = 11
+    case claude = 12
+    case codex = 13
+    case tilde = 14
+    case pipe = 15
+    case dollar = 16
+    case slash = 17
+    case atSign = 18
+    case ctrlC = 19
+    case ctrlD = 20
+    case ctrlZ = 21
+    case ctrlL = 22
+    case home = 23
+    case end = 24
+    case pageUp = 25
+    case pageDown = 26
+    case paste = 27
+    case composer = 28
+    case returnKey = 29
+    case ollama = 30
+    case files = 31
+    case keyboardToggle = 100
+    case hideChrome = 101
+    case customize = 102
+    case zoomResetToDefault = 103
+    case zoomSaveAsDefault = 104
+    case zoomRestoreBuiltIn = 105
+}
+
+/// Fixed reason stored in the value payload of
+/// ``DiagnosticAppEventKind/terminalZoomChanged``.
+public enum DiagnosticTerminalZoomAction: Int, Sendable, Codable, CaseIterable {
+    case stepDecrease = 1
+    case stepIncrease = 2
+    case resetToDefault = 3
+    case restoreBuiltIn = 4
+    case hostSet = 5
+}
+
+/// Fixed primary navigation destination stored in the value payload of
+/// ``DiagnosticAppEventKind/primaryTabSelected``.
+public enum DiagnosticPrimaryTab: Int, Sendable, Codable, CaseIterable {
+    case workspaces = 1
+    case notifications = 2
+    case search = 3
+}
+
+/// Fixed search owner stored in the value payload of search lifecycle events.
+public enum DiagnosticSearchScope: Int, Sendable, Codable, CaseIterable {
+    case workspaces = 1
+    case notifications = 2
+}
+
+/// Fixed mutations stored in the value payload of terminal toolbar settings
+/// events. The custom-action cases report only the operation, never the action's
+/// user-authored label or inserted text.
+public enum DiagnosticToolbarConfigurationAction: Int, Sendable, Codable, CaseIterable {
+    case shortcutShown = 1
+    case shortcutHidden = 2
+    case shortcutReordered = 3
+    case shortcutsReset = 4
+    case customActionAdded = 10
+    case customActionUpdated = 11
+    case customActionRemoved = 12
+}
+
+/// Privacy-safe delivery route stored in feedback outcome events.
+public enum DiagnosticFeedbackRoute: Int, Sendable, Codable, CaseIterable {
+    case privilegedAgent = 1
+    case email = 2
+    case privilegedAgentFallbackToEmail = 3
+}
+
+/// Privacy-safe visual style stored for toast admission events. Toast title,
+/// message, action label, and coalescing key are never retained.
+public enum DiagnosticToastStyle: Int, Sendable, Codable, CaseIterable {
+    case info = 1
+    case success = 2
+    case warning = 3
+    case failure = 4
+}
+
+/// Fixed reason stored in ``DiagnosticAppEventKind/toastDismissed``.
+public enum DiagnosticToastDismissReason: Int, Sendable, Codable, CaseIterable {
+    case caller = 1
+    case automatic = 2
+    case featureDisabled = 3
+    case dismissAll = 4
+    case removedFromQueue = 5
+}
+
+/// A typed, privacy-safe value carried by an app diagnostic event.
+///
+/// The durable event schema stores this discriminator in `DiagnosticEvent.c`,
+/// but producers use this enum instead of the generic `count` parameter. That
+/// keeps item counts, byte counts, and categorical values distinct at the API
+/// boundary and lets report presentation assign a stable semantic field name.
+public enum DiagnosticAppEventDetail: Sendable, Equatable {
+    case terminalToolbarAction(DiagnosticTerminalToolbarAction)
+    case terminalZoomAction(DiagnosticTerminalZoomAction)
+    case primaryTab(DiagnosticPrimaryTab)
+    case searchScope(DiagnosticSearchScope)
+    case toolbarConfigurationAction(DiagnosticToolbarConfigurationAction)
+    case feedbackRoute(DiagnosticFeedbackRoute)
+    case toastStyle(DiagnosticToastStyle)
+    case toastDismissReason(DiagnosticToastDismissReason)
+
+    var rawValue: Int {
+        switch self {
+        case .terminalToolbarAction(let value): value.rawValue
+        case .terminalZoomAction(let value): value.rawValue
+        case .primaryTab(let value): value.rawValue
+        case .searchScope(let value): value.rawValue
+        case .toolbarConfigurationAction(let value): value.rawValue
+        case .feedbackRoute(let value): value.rawValue
+        case .toastStyle(let value): value.rawValue
+        case .toastDismissReason(let value): value.rawValue
+        }
+    }
+
+    func supports(_ kind: DiagnosticAppEventKind) -> Bool {
+        switch (self, kind) {
+        case (.terminalToolbarAction(_), .terminalToolbarActionUsed),
+             (.terminalZoomAction(_), .terminalZoomChanged),
+             (.primaryTab(_), .primaryTabSelected),
+             (.searchScope(_), .searchPresented),
+             (.searchScope(_), .searchDismissed),
+             (.searchScope(_), .searchResultSelected),
+             (.toolbarConfigurationAction(_), .customToolbarChanged),
+             (.toolbarConfigurationAction(_), .terminalShortcutChanged),
+             (.feedbackRoute(_), .feedbackSubmitStarted),
+             (.feedbackRoute(_), .feedbackSubmitSucceeded),
+             (.feedbackRoute(_), .feedbackSubmitFailed),
+             (.toastStyle(_), .toastPresented),
+             (.toastStyle(_), .toastCoalesced),
+             (.toastStyle(_), .toastQueued),
+             (.toastStyle(_), .toastDropped),
+             (.toastDismissReason(_), .toastDismissed):
+            true
+        default:
+            false
+        }
+    }
+}
@@ -0,0 +1,38 @@
+import Foundation
+
+/// Builds the short identity printed in every exported network report.
+///
+/// The git SHA and dev tag are signed bundle metadata, not runtime input. The
+/// helper keeps iOS and macOS reports comparable and applies the same bounded
+/// sanitization at their shared boundary.
+public enum DiagnosticBuildStamp {
+    /// Returns a bounded `name version (build) tag sha` stamp from bundle data.
+    public static func make(
+        infoDictionary: [String: Any]?,
+        fallbackName: String = "cmux"
+    ) -> String {
+        let info = infoDictionary ?? [:]
+        let name = nonEmptyString(info["CFBundleName"]) ?? fallbackName
+        let version = nonEmptyString(info["CFBundleShortVersionString"]) ?? "?"
+        let build = nonEmptyString(info["CFBundleVersion"]) ?? "?"
+        let tag = nonEmptyString(info["CMUXDevTag"])
+        let sha = nonEmptyString(info["CMUXGitSHA"]).map {
+            String($0.prefix(12))
+        }
+
+        var result = "\(name) \(version) (\(build))"
+        if let tag {
+            result += " tag \(tag)"
+        }
+        if let sha {
+            result += " sha \(sha)"
+        }
+        return DiagnosticReport.sanitizeBuildStamp(result)
+    }
+
+    private static func nonEmptyString(_ value: Any?) -> String? {
+        guard let value = value as? String else { return nil }
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+    }
+}
@@ -0,0 +1,20 @@
+import Foundation
+
+/// Produces privacy-safe handles that correlate related events within one app run.
+///
+/// Swift's `Hasher` is randomly seeded for each process. The same opaque model
+/// identifier therefore maps to the same integer inside one exported report,
+/// while a later launch produces a different value. This keeps workspace,
+/// surface, panel, and computer operations debuggable without persisting their
+/// raw identifiers or creating a cross-launch tracking key.
+public struct DiagnosticCorrelation: Sendable {
+    public init() {}
+
+    /// Returns a process-local handle for a non-empty opaque identifier.
+    public func handle(for rawValue: String?) -> UInt32? {
+        guard let rawValue, !rawValue.isEmpty else { return nil }
+        var hasher = Hasher()
+        hasher.combine(rawValue)
+        return UInt32(truncatingIfNeeded: hasher.finalize())
+    }
+}
@@ -151,12 +151,16 @@ public enum DiagnosticEventCode: UInt16, Sendable, Codable, CaseIterable {
    case routeUnavailable = 42
    /// A bounded retry was scheduled. `ms` is the delay before retry.
    case retryScheduled = 43
-    /// Same-account or local-route discovery started.
+    /// Same-account or local-route discovery started. `a` is
+    /// ``DiagnosticTransportKind``.
    case discoveryStarted = 44
-    /// Discovery produced at least one authenticated candidate.
+    /// Discovery produced an authoritative snapshot. `a` is
+    /// ``DiagnosticTransportKind``, `b` is its binding count, `c` is its
+    /// managed relay-fleet count, and `ms` is the fetch duration.
    case discoverySucceeded = 45
-    /// Discovery failed to produce an authenticated candidate. `b`, when
-    /// present, is ``DiagnosticFailureKind``.
+    /// Discovery failed to produce an authoritative snapshot. `a` is
+    /// ``DiagnosticTransportKind``, `b`, when present, is
+    /// ``DiagnosticFailureKind``, and `ms` is the fetch duration.
    case discoveryFailed = 46
    /// The host admitted the authenticated client to an RPC session.
    case admissionSucceeded = 47
@@ -193,6 +197,8 @@ public enum DiagnosticEventCode: UInt16, Sendable, Codable, CaseIterable {
    /// `b` is ``DiagnosticPathKind`` for the affected path, and `c` is the
    /// matching positive, process-local session correlation ID.
    case transportPathEvent = 55
+    // MARK: Browser streaming and control
+
    /// A phone-driven browser stream session changed lifecycle state on the
    /// Mac. `a` is the stage (1 started, 2 replaced an existing session,
    /// 3 stopped, 4 first frame emitted), and `c` is the positive browser
@@ -213,6 +219,91 @@ public enum DiagnosticEventCode: UInt16, Sendable, Codable, CaseIterable {
    /// `a` is 1 on success else 0, and `c` is the panel correlation ID of the
    /// created panel (absent on failure).
    case browserPanelCreateResolved = 59
+
+    // MARK: Simulator streaming and control
+
+    /// A phone-controlled Simulator stream lifecycle edge. `surface` is a
+    /// process-local panel handle, `a` is
+    /// ``DiagnosticSimulatorStreamLifecycle``, `b` is
+    /// ``DiagnosticSimulatorOwnershipState``, and `c`, when present, is a
+    /// bounded count such as the active session count.
+    case simulatorStreamLifecycle = 60
+    /// One frame-pipeline edge. `surface` is a process-local panel handle,
+    /// `a` is ``DiagnosticSimulatorFrameLifecycle``, `b`, when present, is a
+    /// clamped frame sequence number, and `c`, when present, is a byte count.
+    case simulatorFrameLifecycle = 61
+    /// One phone-originated Simulator input edge. `surface` is a process-local
+    /// panel handle, `a` is ``DiagnosticSimulatorInputLifecycle``, `b` is
+    /// ``DiagnosticSimulatorInputKind``, and `c`, when present, is a
+    /// phase/button/text-size detail.
+    case simulatorInputLifecycle = 62
+    /// A phone touch point was mapped before dispatch. `surface` is a
+    /// process-local panel handle, `a` and `b` are normalized x/y in
+    /// ten-thousandths, and `c` is ``DiagnosticSimulatorCoordinateState``.
+    case simulatorCoordinateMapped = 63
+    /// A Simulator stream ownership descriptor changed. `surface` is a
+    /// process-local panel handle, `a` is the new
+    /// ``DiagnosticSimulatorOwnershipState``, and `b` is the previous state
+    /// when known.
+    case simulatorOwnershipChanged = 64
+
+    // MARK: App-wide feature observability
+
+    /// One privacy-safe iOS feature boundary event. `a` is
+    /// ``DiagnosticAppEventKind``; `b`, when present, is a
+    /// ``DiagnosticFailureKind``; `c`, when present, is a bounded count or
+    /// magnitude documented by that event kind; `ms`, when present, is elapsed
+    /// time; and `surface`, when present, is a process-local correlation handle.
+    ///
+    /// This is the app-wide vocabulary for user actions and feature outcomes
+    /// that do not belong to the transport, browser-frame, or Simulator hot
+    /// paths. Event kinds are fixed enums, never caller-provided strings, so the
+    /// durable Release log cannot capture terminal contents, credentials,
+    /// account identifiers, file paths, URLs, workspace titles, or error text.
+    case appFeatureAction = 65
+
+    // Raw values 66-70 are reserved for app-wide diagnostic expansion.
+
+    // MARK: Iroh bootstrap diagnostics
+
+    /// One direct dial plan was assembled before any connect attempt. `a` is
+    /// the public path hint count, `b` is the private fallback path hint
+    /// count, and `c` is the public relay-URL hint count. A plan with both
+    /// counts zero proves no dial packet was sent.
+    case transportDialPlanBuilt = 71
+    /// Configured private addresses were joined with the target Mac's
+    /// broker-registered UDP port for one dial. `a` is the join state
+    /// (``DiagnosticPrivateAddressJoinState``), `b` is the configured
+    /// address count, and `c` is the resulting dialable hint count.
+    case transportPrivateAddressJoin = 72
+    /// Account-private LAN discovery resolved for one dial. `a` is the
+    /// outcome (``DiagnosticLANDiscoveryOutcome``) and `b` is the resolved
+    /// hint count.
+    case transportLANDiscovery = 73
+    /// One direct dial leg connected. `a` is the leg
+    /// (``DiagnosticDirectDialLeg``).
+    case transportDialLegSucceeded = 74
+    /// One direct dial leg failed before a connection existed. `a` is the
+    /// leg (``DiagnosticDirectDialLeg``) and `b` is the classified
+    /// ``DiagnosticFailureKind``.
+    case transportDialLegFailed = 75
+    /// The Mac's account-private LAN advertisement changed publication
+    /// state. `a` is the state (``DiagnosticLANPublicationState``) and `b`
+    /// is the synchronization reason (0 applied, 1 listener setting
+    /// disabled, 2 runtime context unavailable).
+    case lanPublicationState = 76
+
+    /// The transport dial was associated with the admitted session it opened.
+    /// `surface` is the process-local peer alias, `a` is the dial attempt ID,
+    /// and `c` is the matching session ID.
+    case transportDialSessionLinked = 77
+    /// A pending dial was cancelled by a lifecycle owner. `surface` is the
+    /// peer alias, `a` is ``DiagnosticCancellationReason``, `ms` is elapsed
+    /// dial time, and `c` is the dial attempt ID.
+    case transportDialCancelled = 78
+    /// A close carried a bounded remote reason token. `surface` is the peer
+    /// alias, `a` is ``DiagnosticRemoteCloseReason``, and `c` is the session ID.
+    case transportCloseReason = 79
 }

 /// Scene phase carried by ``DiagnosticEventCode/appLifecycleChanged``.
@@ -221,3 +312,25 @@ public enum DiagnosticAppLifecyclePhase: Int, Sendable, Codable, CaseIterable {
    case active = 1
    case inactive = 2
 }
+
+public extension DiagnosticEventCode {
+    /// Whether this event belongs to the Simulator streaming/control feature.
+    var isSimulatorDiagnosticEvent: Bool {
+        switch self {
+        case .simulatorStreamLifecycle,
+             .simulatorFrameLifecycle,
+             .simulatorInputLifecycle,
+             .simulatorCoordinateMapped,
+             .simulatorOwnershipChanged:
+            true
+        default:
+            false
+        }
+    }
+
+    /// Whether this event belongs to app-wide iOS feature observability rather
+    /// than the network or frame-stream planes.
+    var isAppFeatureDiagnosticEvent: Bool {
+        self == .appFeatureAction
+    }
+}
@@ -74,11 +74,96 @@ public struct DiagnosticEventPresentation: Sendable {
        String(describing: phase)
    }

+    /// The stable machine name of an app-wide iOS feature event.
+    public func name(_ kind: DiagnosticAppEventKind) -> String {
+        String(describing: kind)
+    }
+
+    /// The stable machine name of a terminal toolbar action.
+    public func name(_ action: DiagnosticTerminalToolbarAction) -> String {
+        String(describing: action)
+    }
+
+    /// The stable machine name of a terminal zoom action.
+    public func name(_ action: DiagnosticTerminalZoomAction) -> String {
+        String(describing: action)
+    }
+
+    /// The stable machine name of a primary navigation destination.
+    public func name(_ tab: DiagnosticPrimaryTab) -> String {
+        String(describing: tab)
+    }
+
+    /// The stable machine name of a primary search owner.
+    public func name(_ scope: DiagnosticSearchScope) -> String {
+        String(describing: scope)
+    }
+
+    /// The stable machine name of a terminal toolbar configuration mutation.
+    public func name(_ action: DiagnosticToolbarConfigurationAction) -> String {
+        String(describing: action)
+    }
+
+    /// The stable machine name of a feedback delivery route.
+    public func name(_ route: DiagnosticFeedbackRoute) -> String {
+        String(describing: route)
+    }
+
+    /// The stable machine name of a toast style.
+    public func name(_ style: DiagnosticToastStyle) -> String {
+        String(describing: style)
+    }
+
+    /// The stable machine name of a toast dismissal reason.
+    public func name(_ reason: DiagnosticToastDismissReason) -> String {
+        String(describing: reason)
+    }
+
    /// The stable machine name of a runtime role.
    public func name(_ role: DiagnosticRuntimeRole) -> String {
        String(describing: role)
    }

+    /// The stable machine name of a Simulator stream lifecycle edge.
+    public func name(_ kind: DiagnosticSimulatorStreamLifecycle) -> String {
+        String(describing: kind)
+    }
+
+    /// The stable machine name of a Simulator frame lifecycle edge.
+    public func name(_ kind: DiagnosticSimulatorFrameLifecycle) -> String {
+        String(describing: kind)
+    }
+
+    /// The stable machine name of a Simulator input lifecycle edge.
+    public func name(_ kind: DiagnosticSimulatorInputLifecycle) -> String {
+        String(describing: kind)
+    }
+
+    /// The stable machine name of a Simulator input kind.
+    public func name(_ kind: DiagnosticSimulatorInputKind) -> String {
+        String(describing: kind)
+    }
+
+    /// The stable machine name of a Simulator hardware button kind.
+    public func name(_ kind: DiagnosticSimulatorHardwareButtonKind) -> String {
+        String(describing: kind)
+    }
+
+    /// The stable machine name of a Simulator pointer phase.
+    public func name(_ phase: DiagnosticSimulatorPointerPhase) -> String {
+        String(describing: phase)
+    }
+
+    /// The stable machine name of a Simulator ownership state.
+    public func name(_ state: DiagnosticSimulatorOwnershipState) -> String {
+        String(describing: state)
+    }
+
+    /// The stable machine name of a Simulator coordinate mapping state.
+    public func name(_ state: DiagnosticSimulatorCoordinateState) -> String {
+        String(describing: state)
+    }
+
    /// Human-readable name of a diagnostic failure category.
    public func displayName(_ kind: DiagnosticFailureKind) -> String {
        switch kind {
@@ -108,6 +193,11 @@ public struct DiagnosticEventPresentation: Sendable {
        case .admissionRevalidationFailed: localized("diagnostics.failure.admissionRevalidationFailed", defaultValue: "Admission revalidation failed")
        case .sendQueueOverflow: localized("diagnostics.failure.sendQueueOverflow", defaultValue: "Send queue overflow")
        case .routeGated: localized("diagnostics.failure.routeGated", defaultValue: "Route already connecting")
+        case .payloadTooLarge: localized("diagnostics.failure.payloadTooLarge", defaultValue: "Payload too large")
+        case .resourceLimitReached: localized("diagnostics.failure.resourceLimitReached", defaultValue: "Resource limit reached")
+        case .attachmentCountLimitReached: localized("diagnostics.failure.attachmentCountLimitReached", defaultValue: "Attachment count limit reached")
+        case .attachmentAggregateSizeLimitReached: localized("diagnostics.failure.attachmentAggregateSizeLimitReached", defaultValue: "Attachment size limit reached")
+        case .localStateUnavailable: localized("diagnostics.failure.localStateUnavailable", defaultValue: "Local state unavailable")
        case .unknown: localized("diagnostics.failure.unknown", defaultValue: "Unknown failure")
        }
    }
@@ -123,6 +213,14 @@ public struct DiagnosticEventPresentation: Sendable {
        }
    }

+    /// Human-readable name of a configured connection method.
+    public func displayName(_ method: DiagnosticConnectionMethod) -> String {
+        switch method {
+        case .automatic: localized("diagnostics.connectionMethod.automatic", defaultValue: "Auto-Connect (Iroh)")
+        case .tailscale: localized("diagnostics.connectionMethod.tailscale", defaultValue: "Tailscale Only")
+        }
+    }
+
    /// Human-readable name of a selected network path.
    public func displayName(_ kind: DiagnosticPathKind) -> String {
        switch kind {
@@ -177,7 +275,24 @@ public struct DiagnosticEventPresentation: Sendable {
    public func describe(_ event: DiagnosticEvent) -> DescribedEvent {
        var fields: [Field] = []
        if let surface = event.surface {
-            fields.append(Field(key: "surface", value: String(surface)))
+            let key: String
+            switch event.code {
+            case .recoveryStarted, .recoverySucceeded, .recoveryFailed:
+                key = "recovery"
+            case .transportDialStarted, .transportDialConnected,
+                 .transportDialFailed, .transportDialSessionLinked,
+                 .transportDialCancelled, .transportSessionLifecycle,
+                 .sessionClosed, .transportCloseAttribution,
+                 .transportCloseReason, .transportPathEvent,
+                 .transportDialPlanBuilt, .transportPrivateAddressJoin,
+                 .transportLANDiscovery, .transportDialLegSucceeded,
+                 .transportDialLegFailed, .discoveryStarted,
+                 .discoverySucceeded, .discoveryFailed:
+                key = "peer"
+            default:
+                key = "surface"
+            }
+            fields.append(Field(key: key, value: String(surface)))
        }
        if let a = event.a {
            fields.append(decodeA(a, code: event.code))
@@ -189,7 +304,7 @@ public struct DiagnosticEventPresentation: Sendable {
            fields.append(decodeMilliseconds(ms, code: event.code))
        }
        if let c = event.c {
-            fields.append(decodeC(c, code: event.code))
+            fields.append(decodeC(c, event: event))
        }
        return DescribedEvent(name: title(for: event.code), fields: fields)
    }
@@ -233,10 +348,10 @@ public struct DiagnosticEventPresentation: Sendable {

    /// Event codes whose `b` slot carries a ``DiagnosticFailureKind``.
    private static let codesWithFailureB: Set<DiagnosticEventCode> = [
-        .pairFail, .transportDialFailed, .recoveryFailed, .endpointFailed,
+        .pairFail, .transportDialFailed, .transportDialLegFailed, .recoveryFailed, .endpointFailed,
        .relayPolicyRefreshFailed, .sessionClosed, .routeUnavailable,
        .discoveryFailed, .admissionFailed, .hostAuthenticationFailed,
-        .rpcFailed, .transportCloseAttribution,
+        .rpcFailed, .transportCloseAttribution, .appFeatureAction,
    ]

    /// Event codes whose `a` slot carries a ``DiagnosticTransportKind``.
@@ -297,6 +412,10 @@ public struct DiagnosticEventPresentation: Sendable {
            localized("diagnostics.event.transportDialConnected", defaultValue: "Transport connected")
        case .transportDialFailed:
            localized("diagnostics.event.transportDialFailed", defaultValue: "Transport dial failed")
+        case .transportDialSessionLinked:
+            localized("diagnostics.event.transportDialSessionLinked", defaultValue: "Transport dial linked to session")
+        case .transportDialCancelled:
+            localized("diagnostics.event.transportDialCancelled", defaultValue: "Transport dial cancelled")
        case .hostAuthenticated:
            localized("diagnostics.event.hostAuthenticated", defaultValue: "Host authenticated")
        case .rpcReady:
@@ -351,6 +470,8 @@ public struct DiagnosticEventPresentation: Sendable {
            localized("diagnostics.event.reachabilityChanged", defaultValue: "Network reachability changed")
        case .transportCloseAttribution:
            localized("diagnostics.event.transportCloseAttribution", defaultValue: "Transport close attributed")
+        case .transportCloseReason:
+            localized("diagnostics.event.transportCloseReason", defaultValue: "Remote close reason")
        case .transportPathEvent:
            localized("diagnostics.event.transportPathEvent", defaultValue: "Transport path changed")
        case .browserStreamLifecycle:
@@ -361,6 +482,30 @@ public struct DiagnosticEventPresentation: Sendable {
            localized("diagnostics.event.browserEditableFocus", defaultValue: "Browser editable focus")
        case .browserPanelCreateResolved:
            localized("diagnostics.event.browserPanelCreateResolved", defaultValue: "Browser panel create resolved")
+        case .simulatorStreamLifecycle:
+            localized("diagnostics.event.simulatorStreamLifecycle", defaultValue: "Simulator stream state changed")
+        case .simulatorFrameLifecycle:
+            localized("diagnostics.event.simulatorFrameLifecycle", defaultValue: "Simulator frame pipeline changed")
+        case .simulatorInputLifecycle:
+            localized("diagnostics.event.simulatorInputLifecycle", defaultValue: "Simulator input state changed")
+        case .simulatorCoordinateMapped:
+            localized("diagnostics.event.simulatorCoordinateMapped", defaultValue: "Simulator touch coordinate mapped")
+        case .simulatorOwnershipChanged:
+            localized("diagnostics.event.simulatorOwnershipChanged", defaultValue: "Simulator control ownership changed")
+        case .appFeatureAction:
+            localized("diagnostics.event.appFeatureAction", defaultValue: "App feature event")
+        case .transportDialPlanBuilt:
+            localized("diagnostics.event.transportDialPlanBuilt", defaultValue: "Direct dial plan assembled")
+        case .transportPrivateAddressJoin:
+            localized("diagnostics.event.transportPrivateAddressJoin", defaultValue: "Private addresses joined broker port")
+        case .transportLANDiscovery:
+            localized("diagnostics.event.transportLANDiscovery", defaultValue: "LAN discovery resolved")
+        case .transportDialLegSucceeded:
+            localized("diagnostics.event.transportDialLegSucceeded", defaultValue: "Direct dial leg connected")
+        case .transportDialLegFailed:
+            localized("diagnostics.event.transportDialLegFailed", defaultValue: "Direct dial leg failed")
+        case .lanPublicationState:
+            localized("diagnostics.event.lanPublicationState", defaultValue: "LAN advertisement state changed")
        }
    }

@@ -403,6 +548,28 @@ public struct DiagnosticEventPresentation: Sendable {
            return Field(key: "editable_focused", value: booleanName(raw))
        case .browserPanelCreateResolved:
            return Field(key: "created", value: booleanName(raw))
+        case .simulatorStreamLifecycle:
+            return Field(key: "state", value: simulatorStreamLifecycleName(raw))
+        case .simulatorFrameLifecycle:
+            return Field(key: "state", value: simulatorFrameLifecycleName(raw))
+        case .simulatorInputLifecycle:
+            return Field(key: "state", value: simulatorInputLifecycleName(raw))
+        case .simulatorCoordinateMapped:
+            return Field(key: "x", value: normalizedCoordinate(raw))
+        case .simulatorOwnershipChanged:
+            return Field(key: "owner", value: simulatorOwnershipName(raw))
+        case .appFeatureAction:
+            return Field(key: "operation", value: appEventName(raw))
+        case .transportDialPlanBuilt:
+            return Field(key: "public_paths", value: String(raw))
+        case .transportPrivateAddressJoin:
+            return Field(key: "join", value: privateAddressJoinName(raw))
+        case .transportLANDiscovery:
+            return Field(key: "outcome", value: lanDiscoveryOutcomeName(raw))
+        case .transportDialLegSucceeded, .transportDialLegFailed:
+            return Field(key: "leg", value: dialLegName(raw))
+        case .lanPublicationState:
+            return Field(key: "state", value: lanPublicationStateName(raw))
        default:
            return Field(key: "detail_1", value: String(raw))
        }
@@ -431,6 +598,26 @@ public struct DiagnosticEventPresentation: Sendable {
            return Field(key: "count", value: String(raw))
        case .browserEditableFocus:
            return Field(key: "outcome", value: browserFocusOutcomeName(raw))
+        case .transportDialPlanBuilt:
+            return Field(key: "private_fallback_paths", value: String(raw))
+        case .discoverySucceeded:
+            return Field(key: "bindings", value: String(raw))
+        case .transportPrivateAddressJoin:
+            return Field(key: "configured_addresses", value: String(raw))
+        case .transportLANDiscovery:
+            return Field(key: "hints", value: String(raw))
+        case .lanPublicationState:
+            return Field(key: "reason", value: lanPublicationReasonName(raw))
+        case .simulatorStreamLifecycle:
+            return Field(key: "owner", value: simulatorOwnershipName(raw))
+        case .simulatorFrameLifecycle:
+            return Field(key: "frame_sequence", value: String(raw))
+        case .simulatorInputLifecycle:
+            return Field(key: "input", value: simulatorInputKindName(raw))
+        case .simulatorCoordinateMapped:
+            return Field(key: "y", value: normalizedCoordinate(raw))
+        case .simulatorOwnershipChanged:
+            return Field(key: "previous_owner", value: simulatorOwnershipName(raw))
        default:
            return Field(key: "detail_2", value: String(raw))
        }
@@ -456,8 +643,12 @@ public struct DiagnosticEventPresentation: Sendable {
        }
    }

-    private func decodeC(_ raw: Int, code: DiagnosticEventCode) -> Field {
-        switch code {
+    private func decodeC(_ raw: Int, event: DiagnosticEvent) -> Field {
+        switch event.code {
+        case .transportDialPlanBuilt:
+            return Field(key: "public_relay_urls", value: String(raw))
+        case .discoverySucceeded:
+            return Field(key: "relay_fleet", value: String(raw))
        case .transportDialStarted, .transportDialConnected, .transportDialFailed:
            return Field(key: "attempt", value: String(raw))
        case .sessionClosed, .transportSessionLifecycle,
@@ -468,11 +659,130 @@ public struct DiagnosticEventPresentation: Sendable {
        case .browserStreamLifecycle, .browserInputReplayed,
             .browserEditableFocus, .browserPanelCreateResolved:
            return Field(key: "panel", value: String(raw))
+        case .simulatorStreamLifecycle:
+            return Field(key: "active_sessions", value: String(raw))
+        case .simulatorFrameLifecycle:
+            return Field(key: "payload_size", value: byteCount(raw))
+        case .simulatorInputLifecycle:
+            return Field(
+                key: "input_detail",
+                value: simulatorInputDetailName(raw, inputKindRaw: event.b)
+            )
+        case .simulatorCoordinateMapped:
+            return Field(key: "mapping", value: simulatorCoordinateStateName(raw))
+        case .appFeatureAction:
+            if let kind = event.a.flatMap(DiagnosticAppEventKind.init(rawValue:)) {
+                switch kind {
+                case .terminalToolbarActionUsed:
+                    return Field(key: "action", value: terminalToolbarActionName(raw))
+                case .terminalZoomChanged:
+                    return Field(key: "action", value: terminalZoomActionName(raw))
+                case .primaryTabSelected:
+                    return Field(key: "tab", value: primaryTabName(raw))
+                case .searchPresented, .searchDismissed, .searchResultSelected:
+                    return Field(key: "scope", value: searchScopeName(raw))
+                case .customToolbarChanged, .terminalShortcutChanged:
+                    return Field(key: "change", value: toolbarConfigurationActionName(raw))
+                case .feedbackSubmitStarted, .feedbackSubmitSucceeded, .feedbackSubmitFailed:
+                    return Field(key: "route", value: feedbackRouteName(raw))
+                case .toastPresented, .toastCoalesced, .toastQueued, .toastDropped:
+                    return Field(key: "style", value: toastStyleName(raw))
+                case .toastDismissed:
+                    return Field(key: "reason", value: toastDismissReasonName(raw))
+                case .connectionMethodPreferenceChanged, .connectionMethodConfigured:
+                    return Field(key: "method", value: connectionMethodName(raw))
+                case .foregroundTransportSelected:
+                    return Field(key: "transport", value: transportName(raw))
+                default:
+                    if Self.appEventKindsWithValuePayload.contains(kind) {
+                        return Field(key: "value", value: String(raw))
+                    }
+                }
+            }
+            return Field(key: "count", value: String(raw))
        default:
            return Field(key: "detail_3", value: String(raw))
        }
    }

+    private func appEventName(_ raw: Int) -> String {
+        guard let kind = DiagnosticAppEventKind(rawValue: raw) else {
+            return localized(
+                "diagnostics.unknown.appEvent",
+                defaultValue: "Unknown app event (\(raw))"
+            )
+        }
+        return name(kind)
+    }
+
+    private func terminalToolbarActionName(_ raw: Int) -> String {
+        DiagnosticTerminalToolbarAction(rawValue: raw).map(name)
+            ?? unknownPayloadName(raw)
+    }
+
+    private func terminalZoomActionName(_ raw: Int) -> String {
+        DiagnosticTerminalZoomAction(rawValue: raw).map(name)
+            ?? unknownPayloadName(raw)
+    }
+
+    private func primaryTabName(_ raw: Int) -> String {
+        DiagnosticPrimaryTab(rawValue: raw).map(name)
+            ?? unknownPayloadName(raw)
+    }
+
+    private func searchScopeName(_ raw: Int) -> String {
+        DiagnosticSearchScope(rawValue: raw).map(name)
+            ?? unknownPayloadName(raw)
+    }
+
+    private func toolbarConfigurationActionName(_ raw: Int) -> String {
+        DiagnosticToolbarConfigurationAction(rawValue: raw).map(name)
+            ?? unknownPayloadName(raw)
+    }
+
+    private func feedbackRouteName(_ raw: Int) -> String {
+        DiagnosticFeedbackRoute(rawValue: raw).map(name)
+            ?? unknownPayloadName(raw)
+    }
+
+    private func toastStyleName(_ raw: Int) -> String {
+        DiagnosticToastStyle(rawValue: raw).map(name)
+            ?? unknownPayloadName(raw)
+    }
+
+    private func toastDismissReasonName(_ raw: Int) -> String {
+        DiagnosticToastDismissReason(rawValue: raw).map(name)
+            ?? unknownPayloadName(raw)
+    }
+
+    private func connectionMethodName(_ raw: Int) -> String {
+        DiagnosticConnectionMethod(rawValue: raw).map(displayName)
+            ?? unknownPayloadName(raw)
+    }
+
+    private func unknownPayloadName(_ raw: Int) -> String {
+        localized(
+            "diagnostics.unknown.payload",
+            defaultValue: "Unknown value (\(raw))"
+        )
+    }
+
+    private static let appEventKindsWithValuePayload: Set<DiagnosticAppEventKind> = [
+        .displayAltScreenNoticeChanged,
+        .displayFolderTapChanged,
+        .displayHapticsChanged,
+        .taskComposerFeatureChanged,
+        .terminalFilesFeatureChanged,
+        .toastFeatureChanged,
+        .displayMissingFilesChanged,
+        .displayWorkspaceTitleWrappingChanged,
+        .displayWorkspacePreviewLinesChanged,
+        .terminalScrollbackRowsChanged,
+        .telemetrySharingChanged,
+        .notificationPreferenceChanged,
+        .terminalDraftStateChanged,
+    ]
+
    private func failureName(_ raw: Int) -> String {
        guard let value = DiagnosticFailureKind(rawValue: raw) else {
            return localized(
@@ -523,6 +833,100 @@ public struct DiagnosticEventPresentation: Sendable {
        return displayName(value)
    }

+    private func dialLegName(_ raw: Int) -> String {
+        switch raw {
+        case DiagnosticDirectDialLeg.publicPaths.rawValue:
+            localized("diagnostics.dialLeg.public", defaultValue: "Public paths")
+        case DiagnosticDirectDialLeg.privateFallback.rawValue:
+            localized("diagnostics.dialLeg.privateFallback", defaultValue: "Private fallback")
+        default:
+            localized("diagnostics.unknown.dialLeg", defaultValue: "Unknown leg (\(raw))")
+        }
+    }
+
+    private func privateAddressJoinName(_ raw: Int) -> String {
+        switch raw {
+        case DiagnosticPrivateAddressJoinState.notConfigured.rawValue:
+            localized("diagnostics.privateJoin.notConfigured", defaultValue: "None configured")
+        case DiagnosticPrivateAddressJoinState.joined.rawValue:
+            localized("diagnostics.privateJoin.joined", defaultValue: "Joined broker port")
+        case DiagnosticPrivateAddressJoinState.brokerPortsStale.rawValue:
+            localized(
+                "diagnostics.privateJoin.stalePorts",
+                defaultValue: "Broker ports missing or stale"
+            )
+        default:
+            localized(
+                "diagnostics.unknown.privateJoin",
+                defaultValue: "Unknown join state (\(raw))"
+            )
+        }
+    }
+
+    private func lanDiscoveryOutcomeName(_ raw: Int) -> String {
+        switch raw {
+        case DiagnosticLANDiscoveryOutcome.noAuthority.rawValue:
+            localized("diagnostics.lanDiscovery.noAuthority", defaultValue: "No broker LAN authority")
+        case DiagnosticLANDiscoveryOutcome.found.rawValue:
+            localized("diagnostics.lanDiscovery.found", defaultValue: "Advertisement found")
+        case DiagnosticLANDiscoveryOutcome.notFound.rawValue:
+            localized("diagnostics.lanDiscovery.notFound", defaultValue: "Advertisement not found")
+        case DiagnosticLANDiscoveryOutcome.policyDenied.rawValue:
+            localized(
+                "diagnostics.lanDiscovery.policyDenied",
+                defaultValue: "Local Network permission denied"
+            )
+        default:
+            localized(
+                "diagnostics.unknown.lanDiscovery",
+                defaultValue: "Unknown discovery outcome (\(raw))"
+            )
+        }
+    }
+
+    private func lanPublicationStateName(_ raw: Int) -> String {
+        switch raw {
+        case DiagnosticLANPublicationState.inactive.rawValue:
+            localized("diagnostics.lanPublication.inactive", defaultValue: "Stopped")
+        case DiagnosticLANPublicationState.active.rawValue:
+            localized("diagnostics.lanPublication.active", defaultValue: "Advertising")
+        case DiagnosticLANPublicationState.unavailable.rawValue:
+            localized("diagnostics.lanPublication.unavailable", defaultValue: "Registration failing")
+        case DiagnosticLANPublicationState.policyDenied.rawValue:
+            localized(
+                "diagnostics.lanPublication.policyDenied",
+                defaultValue: "Local Network permission denied"
+            )
+        default:
+            localized(
+                "diagnostics.unknown.lanPublication",
+                defaultValue: "Unknown publication state (\(raw))"
+            )
+        }
+    }
+
+    private func lanPublicationReasonName(_ raw: Int) -> String {
+        switch raw {
+        case 0:
+            localized("diagnostics.lanPublicationReason.applied", defaultValue: "Settings applied")
+        case 1:
+            localized(
+                "diagnostics.lanPublicationReason.listenerDisabled",
+                defaultValue: "Listener setting disabled"
+            )
+        case 2:
+            localized(
+                "diagnostics.lanPublicationReason.noContext",
+                defaultValue: "Runtime context unavailable"
+            )
+        default:
+            localized(
+                "diagnostics.unknown.lanPublicationReason",
+                defaultValue: "Unknown reason (\(raw))"
+            )
+        }
+    }
+
    private func sessionPurposeName(_ raw: Int) -> String {
        guard let byte = UInt8(exactly: raw),
              let purpose = CmxTransportSessionPurpose(rawValue: byte)
@@ -677,6 +1081,241 @@ public struct DiagnosticEventPresentation: Sendable {
        }
    }

+    private func simulatorStreamLifecycleName(_ raw: Int) -> String {
+        guard let value = DiagnosticSimulatorStreamLifecycle(rawValue: raw) else {
+            return localized(
+                "diagnostics.unknown.simulatorStreamState",
+                defaultValue: "Unknown stream state (\(raw))"
+            )
+        }
+        switch value {
+        case .startRequested:
+            return localized("diagnostics.simulator.stream.startRequested", defaultValue: "Start requested")
+        case .started:
+            return localized("diagnostics.simulator.stream.started", defaultValue: "Started")
+        case .locked:
+            return localized("diagnostics.simulator.stream.locked", defaultValue: "Locked by another controller")
+        case .startFailed:
+            return localized("diagnostics.simulator.stream.startFailed", defaultValue: "Start failed")
+        case .stopRequested:
+            return localized("diagnostics.simulator.stream.stopRequested", defaultValue: "Stop requested")
+        case .stopped:
+            return localized("diagnostics.simulator.stream.stopped", defaultValue: "Stopped")
+        case .closed:
+            return localized("diagnostics.simulator.stream.closed", defaultValue: "Closed")
+        case .restartRequested:
+            return localized("diagnostics.simulator.stream.restartRequested", defaultValue: "Restart requested")
+        case .pausedForBackground:
+            return localized("diagnostics.simulator.stream.pausedForBackground", defaultValue: "Paused for background")
+        case .descriptorApplied:
+            return localized("diagnostics.simulator.stream.descriptorApplied", defaultValue: "Descriptor applied")
+        case .stalled:
+            return localized("diagnostics.simulator.stream.stalled", defaultValue: "Stalled (no frames or keepalives)")
+        case .stopFailed:
+            return localized("diagnostics.simulator.stream.stopFailed", defaultValue: "Stop failed")
+        }
+    }
+
+    private func simulatorFrameLifecycleName(_ raw: Int) -> String {
+        guard let value = DiagnosticSimulatorFrameLifecycle(rawValue: raw) else {
+            return localized(
+                "diagnostics.unknown.simulatorFrameState",
+                defaultValue: "Unknown frame state (\(raw))"
+            )
+        }
+        switch value {
+        case .readerAttached:
+            return localized("diagnostics.simulator.frame.readerAttached", defaultValue: "Reader attached")
+        case .readerMissing:
+            return localized("diagnostics.simulator.frame.readerMissing", defaultValue: "Reader missing")
+        case .copied:
+            return localized("diagnostics.simulator.frame.copied", defaultValue: "Frame copied")
+        case .encodeFailed:
+            return localized("diagnostics.simulator.frame.encodeFailed", defaultValue: "Frame encode failed")
+        case .sent:
+            return localized("diagnostics.simulator.frame.sent", defaultValue: "Frame sent")
+        case .refused:
+            return localized("diagnostics.simulator.frame.refused", defaultValue: "Frame refused by queue")
+        case .cachedSent:
+            return localized("diagnostics.simulator.frame.cachedSent", defaultValue: "Cached frame sent")
+        case .subscriptionReasserted:
+            return localized("diagnostics.simulator.frame.subscriptionReasserted", defaultValue: "Subscription reasserted")
+        case .received:
+            return localized("diagnostics.simulator.frame.received", defaultValue: "Frame received")
+        case .staleIgnored:
+            return localized("diagnostics.simulator.frame.staleIgnored", defaultValue: "Stale frame ignored")
+        case .decodeFailed:
+            return localized("diagnostics.simulator.frame.decodeFailed", defaultValue: "Frame decode failed")
+        case .imageDecoded:
+            return localized("diagnostics.simulator.frame.imageDecoded", defaultValue: "Image decoded")
+        case .imageDecodeFailed:
+            return localized("diagnostics.simulator.frame.imageDecodeFailed", defaultValue: "Image decode failed")
+        case .unknownPanel:
+            return localized("diagnostics.simulator.frame.unknownPanel", defaultValue: "Unknown panel")
+        }
+    }
+
+    private func simulatorInputLifecycleName(_ raw: Int) -> String {
+        guard let value = DiagnosticSimulatorInputLifecycle(rawValue: raw) else {
+            return localized(
+                "diagnostics.unknown.simulatorInputState",
+                defaultValue: "Unknown input state (\(raw))"
+            )
+        }
+        switch value {
+        case .queued:
+            return localized("diagnostics.simulator.input.queued", defaultValue: "Queued")
+        case .sent:
+            return localized("diagnostics.simulator.input.sent", defaultValue: "Sent")
+        case .accepted:
+            return localized("diagnostics.simulator.input.accepted", defaultValue: "Accepted")
+        case .failed:
+            return localized("diagnostics.simulator.input.failed", defaultValue: "Failed")
+        case .rejectedLocked:
+            return localized("diagnostics.simulator.input.rejectedLocked", defaultValue: "Rejected because locked")
+        case .unavailable:
+            return localized("diagnostics.simulator.input.unavailable", defaultValue: "Unavailable")
+        case .invalidParameters:
+            return localized("diagnostics.simulator.input.invalidParameters", defaultValue: "Invalid parameters")
+        case .panelMissing:
+            return localized("diagnostics.simulator.input.panelMissing", defaultValue: "Panel missing")
+        case .featureDisabled:
+            return localized("diagnostics.simulator.input.featureDisabled", defaultValue: "Feature disabled")
+        case .blockedViewOnly:
+            return localized("diagnostics.simulator.input.blockedViewOnly", defaultValue: "Blocked in view-only mode")
+        }
+    }
+
+    private func simulatorInputKindName(_ raw: Int) -> String {
+        guard let value = DiagnosticSimulatorInputKind(rawValue: raw) else {
+            return localized(
+                "diagnostics.unknown.simulatorInputKind",
+                defaultValue: "Unknown input kind (\(raw))"
+            )
+        }
+        switch value {
+        case .pointer:
+            return localized("diagnostics.simulator.inputKind.pointer", defaultValue: "Pointer")
+        case .text:
+            return localized("diagnostics.simulator.inputKind.text", defaultValue: "Text")
+        case .hardwareButton:
+            return localized("diagnostics.simulator.inputKind.hardwareButton", defaultValue: "Hardware button")
+        }
+    }
+
+    private func simulatorInputDetailName(_ raw: Int, inputKindRaw: Int?) -> String {
+        guard let inputKindRaw,
+              let inputKind = DiagnosticSimulatorInputKind(rawValue: inputKindRaw) else {
+            return String(raw)
+        }
+        switch inputKind {
+        case .pointer:
+            return simulatorPointerPhaseName(raw)
+        case .text:
+            return byteCount(raw)
+        case .hardwareButton:
+            return simulatorHardwareButtonName(raw)
+        }
+    }
+
+    private func simulatorPointerPhaseName(_ raw: Int) -> String {
+        guard let value = DiagnosticSimulatorPointerPhase(rawValue: raw) else {
+            return localized(
+                "diagnostics.unknown.simulatorPointerPhase",
+                defaultValue: "Unknown pointer phase (\(raw))"
+            )
+        }
+        switch value {
+        case .began:
+            return localized("diagnostics.simulator.pointer.began", defaultValue: "Began")
+        case .moved:
+            return localized("diagnostics.simulator.pointer.moved", defaultValue: "Moved")
+        case .ended:
+            return localized("diagnostics.simulator.pointer.ended", defaultValue: "Ended")
+        case .tap:
+            return localized("diagnostics.simulator.pointer.tap", defaultValue: "Tap")
+        }
+    }
+
+    private func simulatorHardwareButtonName(_ raw: Int) -> String {
+        guard let value = DiagnosticSimulatorHardwareButtonKind(rawValue: raw) else {
+            return localized(
+                "diagnostics.unknown.simulatorHardwareButton",
+                defaultValue: "Unknown hardware button (\(raw))"
+            )
+        }
+        switch value {
+        case .unknown:
+            return localized("diagnostics.simulator.button.unknown", defaultValue: "Unknown button")
+        case .home:
+            return localized("diagnostics.simulator.button.home", defaultValue: "Home")
+        case .swipeHome:
+            return localized("diagnostics.simulator.button.swipeHome", defaultValue: "Swipe Home")
+        case .appSwitcher:
+            return localized("diagnostics.simulator.button.appSwitcher", defaultValue: "App Switcher")
+        case .lock:
+            return localized("diagnostics.simulator.button.lock", defaultValue: "Lock")
+        case .siri:
+            return localized("diagnostics.simulator.button.siri", defaultValue: "Siri")
+        case .sideButton:
+            return localized("diagnostics.simulator.button.sideButton", defaultValue: "Side button")
+        case .power:
+            return localized("diagnostics.simulator.button.power", defaultValue: "Power")
+        case .volumeUp:
+            return localized("diagnostics.simulator.button.volumeUp", defaultValue: "Volume up")
+        case .volumeDown:
+            return localized("diagnostics.simulator.button.volumeDown", defaultValue: "Volume down")
+        case .action:
+            return localized("diagnostics.simulator.button.action", defaultValue: "Action")
+        case .watchSideButton:
+            return localized("diagnostics.simulator.button.watchSideButton", defaultValue: "Watch side button")
+        }
+    }
+
+    private func simulatorOwnershipName(_ raw: Int) -> String {
+        guard let value = DiagnosticSimulatorOwnershipState(rawValue: raw) else {
+            return localized(
+                "diagnostics.unknown.simulatorOwner",
+                defaultValue: "Unknown owner state (\(raw))"
+            )
+        }
+        switch value {
+        case .unowned:
+            return localized("diagnostics.simulator.owner.unowned", defaultValue: "Unowned")
+        case .currentConnection:
+            return localized("diagnostics.simulator.owner.currentConnection", defaultValue: "Current connection")
+        case .otherConnection:
+            return localized("diagnostics.simulator.owner.otherConnection", defaultValue: "Other connection")
+        case .pendingHandshake:
+            return localized("diagnostics.simulator.owner.pendingHandshake", defaultValue: "Pending handshake")
+        case .unknown:
+            return localized("diagnostics.simulator.owner.unknown", defaultValue: "Unknown")
+        }
+    }
+
+    private func simulatorCoordinateStateName(_ raw: Int) -> String {
+        guard let value = DiagnosticSimulatorCoordinateState(rawValue: raw) else {
+            return localized(
+                "diagnostics.unknown.simulatorCoordinateState",
+                defaultValue: "Unknown coordinate state (\(raw))"
+            )
+        }
+        switch value {
+        case .mapped:
+            return localized("diagnostics.simulator.coordinate.mapped", defaultValue: "Mapped")
+        case .outsideImage:
+            return localized("diagnostics.simulator.coordinate.outsideImage", defaultValue: "Outside image")
+        case .viewOnlyBlocked:
+            return localized("diagnostics.simulator.coordinate.viewOnlyBlocked", defaultValue: "View-only blocked")
+        case .zeroImage:
+            return localized("diagnostics.simulator.coordinate.zeroImage", defaultValue: "Missing image geometry")
+        }
+    }
+
+    private func normalizedCoordinate(_ raw: Int) -> String {
+        String(format: "%.4f", Double(raw) / 10_000.0)
+    }
+
    private func duration(_ milliseconds: UInt32) -> String {
        guard milliseconds >= 1_000 else {
            return localized(
@@ -756,12 +1395,44 @@ public struct DiagnosticEventPresentation: Sendable {
        case "delivered_sequence": localized("diagnostics.field.deliveredSequence", defaultValue: "Delivered sequence")
        case "next_sequence": localized("diagnostics.field.nextSequence", defaultValue: "Next sequence")
        case "stage": localized("diagnostics.field.stage", defaultValue: "Stage")
+        case "owner": localized("diagnostics.field.owner", defaultValue: "Owner")
+        case "previous_owner": localized("diagnostics.field.previousOwner", defaultValue: "Previous owner")
+        case "frame_sequence": localized("diagnostics.field.frameSequence", defaultValue: "Frame sequence")
+        case "payload_size": localized("diagnostics.field.payloadSize", defaultValue: "Payload size")
        case "input": localized("diagnostics.field.input", defaultValue: "Input")
+        case "input_detail": localized("diagnostics.field.inputDetail", defaultValue: "Input detail")
+        case "active_sessions": localized("diagnostics.field.activeSessions", defaultValue: "Active sessions")
        case "count": localized("diagnostics.field.count", defaultValue: "Count")
+        case "value": localized("diagnostics.field.value", defaultValue: "Value")
+        case "method": localized("diagnostics.field.method", defaultValue: "Method")
+        case "action": localized("diagnostics.field.action", defaultValue: "Action")
+        case "tab": localized("diagnostics.field.tab", defaultValue: "Tab")
+        case "scope": localized("diagnostics.field.scope", defaultValue: "Scope")
+        case "change": localized("diagnostics.field.change", defaultValue: "Change")
+        case "route": localized("diagnostics.field.route", defaultValue: "Route")
+        case "style": localized("diagnostics.field.style", defaultValue: "Style")
+        case "reason": localized("diagnostics.field.reason", defaultValue: "Reason")
        case "outcome": localized("diagnostics.field.outcome", defaultValue: "Outcome")
        case "editable_focused": localized("diagnostics.field.editableFocused", defaultValue: "Editable focused")
        case "created": localized("diagnostics.field.created", defaultValue: "Created")
+        case "public_paths": localized("diagnostics.field.publicPaths", defaultValue: "Public paths")
+        case "private_fallback_paths":
+            localized(
+                "diagnostics.field.privateFallbackPaths",
+                defaultValue: "Private fallback paths"
+            )
+        case "join": localized("diagnostics.field.join", defaultValue: "Join")
+        case "configured_addresses":
+            localized(
+                "diagnostics.field.configuredAddresses",
+                defaultValue: "Configured addresses"
+            )
+        case "hints": localized("diagnostics.field.hints", defaultValue: "Hints")
+        case "leg": localized("diagnostics.field.leg", defaultValue: "Leg")
        case "panel": localized("diagnostics.field.panel", defaultValue: "Panel")
+        case "x": localized("diagnostics.field.x", defaultValue: "X")
+        case "y": localized("diagnostics.field.y", defaultValue: "Y")
+        case "mapping": localized("diagnostics.field.mapping", defaultValue: "Mapping")
        case "detail_1": localized("diagnostics.field.detail1", defaultValue: "Detail 1")
        case "detail_2": localized("diagnostics.field.detail2", defaultValue: "Detail 2")
        case "detail_3": localized("diagnostics.field.detail3", defaultValue: "Detail 3")
@@ -47,6 +47,10 @@ public final class DiagnosticLog: Sendable {
    /// The optional live observer, delivered retained events on the drain task.
    private let tap: TapBox

+    /// Stateless hashing seam used to reduce opaque model identifiers before
+    /// they enter the event ring. Swift supplies its process-randomized seed.
+    private let correlation = DiagnosticCorrelation()
+
    /// The drain task. Its closure captures only local stream/store values, so
    /// deinitialization can finish ingress and let accepted clear commands drain
    /// to their acknowledgements without retaining this log.
@@ -167,6 +171,96 @@ public final class DiagnosticLog: Sendable {
        ingress.record(event)
    }

+    /// Records one privacy-safe iOS product event into the same ordered ring
+    /// and durable app-log tap as transport diagnostics.
+    ///
+    /// Callers select only fixed enum values and bounded integers. Never add a
+    /// free-text overload: the absence of strings is what makes this API safe
+    /// to leave enabled in Release builds for every user.
+    ///
+    /// - Parameters:
+    ///   - kind: Stable feature action or outcome.
+    ///   - surface: Optional process-local correlation handle.
+    ///   - elapsedMilliseconds: Optional elapsed time for the operation.
+    ///   - failure: Optional privacy-safe failure category.
+    ///   - count: Optional bounded item/byte/attempt count documented by `kind`.
+    public nonisolated func recordAppEvent(
+        _ kind: DiagnosticAppEventKind,
+        surface: UInt32? = nil,
+        elapsedMilliseconds: UInt32? = nil,
+        failure: DiagnosticFailureKind? = nil,
+        count: Int? = nil
+    ) {
+        let boundedCount = count.map { min(max(0, $0), Int(UInt32.max)) }
+        record(DiagnosticEvent(
+            .appFeatureAction,
+            surface: surface,
+            ms: elapsedMilliseconds,
+            a: kind.rawValue,
+            b: failure?.rawValue,
+            c: boundedCount
+        ))
+    }
+
+    /// Records one app event correlated to an opaque model identifier.
+    ///
+    /// The identifier is immediately reduced to a process-local handle by
+    /// ``DiagnosticCorrelation`` and is never retained or written to disk.
+    public nonisolated func recordAppEvent(
+        _ kind: DiagnosticAppEventKind,
+        correlationID: String?,
+        elapsedMilliseconds: UInt32? = nil,
+        failure: DiagnosticFailureKind? = nil,
+        count: Int? = nil
+    ) {
+        recordAppEvent(
+            kind,
+            surface: correlation.handle(for: correlationID),
+            elapsedMilliseconds: elapsedMilliseconds,
+            failure: failure,
+            count: count
+        )
+    }
+
+    /// Records a categorical app-event value through a typed payload instead
+    /// of conflating its raw discriminator with an item or byte count.
+    public nonisolated func recordAppEvent(
+        _ kind: DiagnosticAppEventKind,
+        surface: UInt32? = nil,
+        elapsedMilliseconds: UInt32? = nil,
+        failure: DiagnosticFailureKind? = nil,
+        detail: DiagnosticAppEventDetail
+    ) {
+        guard detail.supports(kind) else {
+            assertionFailure("Unsupported diagnostic detail for \(kind)")
+            return
+        }
+        recordAppEvent(
+            kind,
+            surface: surface,
+            elapsedMilliseconds: elapsedMilliseconds,
+            failure: failure,
+            count: detail.rawValue
+        )
+    }
+
+    /// Records a typed categorical value correlated to an opaque model ID.
+    public nonisolated func recordAppEvent(
+        _ kind: DiagnosticAppEventKind,
+        correlationID: String?,
+        elapsedMilliseconds: UInt32? = nil,
+        failure: DiagnosticFailureKind? = nil,
+        detail: DiagnosticAppEventDetail
+    ) {
+        recordAppEvent(
+            kind,
+            surface: correlation.handle(for: correlationID),
+            elapsedMilliseconds: elapsedMilliseconds,
+            failure: failure,
+            detail: detail
+        )
+    }
+
    /// Snapshot the currently-drained ring and format a plain-language report.
    ///
    /// Reads whatever the drain task has already moved into the ring; it does not
@@ -354,7 +354,19 @@ public extension DiagnosticEvent {
    /// Positive process-local correlation ID shared by a dial attempt and its
    /// outcome. It is intentionally not stable across launches or devices.
    var diagnosticAttemptID: Int? {
-        guard code.isTransportDialEvent, let c, c > 0 else { return nil }
+        guard code.isTransportDialEvent || code == .transportDialSessionLinked
+                || code == .transportDialCancelled,
+              let c,
+              c > 0 else { return nil }
+        return c
+    }
+
+    /// Positive process-local session correlation ID carried by a dial/session
+    /// link or close-reason event.
+    var diagnosticLinkedSessionID: Int? {
+        guard code == .transportDialSessionLinked || code == .transportCloseReason,
+              let c,
+              c > 0 else { return nil }
        return c
    }

@@ -388,6 +400,7 @@ public extension DiagnosticEvent {
        guard code == .transportSessionLifecycle
                || code == .sessionClosed
                || code == .transportCloseAttribution
+                || code == .transportCloseReason
                || code == .transportPathEvent,
              let c,
              c > 0 else { return nil }
@@ -429,6 +442,7 @@ public extension DiagnosticEventCode {
             .streamEnded,
             .error,
             .transportDialFailed,
+             .transportDialLegFailed,
             .recoveryFailed,
             .endpointFailed,
             .relayPolicyRefreshFailed,
@@ -446,6 +460,7 @@ public extension DiagnosticEventCode {
    var carriesDiagnosticFailureKind: Bool {
        switch self {
        case .transportDialFailed,
+             .transportDialLegFailed,
             .recoveryFailed,
             .endpointFailed,
             .relayPolicyRefreshFailed,
@@ -473,6 +488,7 @@ public extension DiagnosticEventCode {
        case .pairFail,
             .error,
             .transportDialFailed,
+             .transportDialLegFailed,
             .recoveryFailed,
             .endpointFailed,
             .relayPolicyRefreshFailed,
@@ -76,6 +76,18 @@ public enum DiagnosticFailureKind: Int, Sendable, Codable, CaseIterable {
    /// genuine dial timeouts in exports; a gated attempt never reached the
    /// network.
    case routeGated = 25
+    /// A bounded operation rejected one input because its payload exceeded the
+    /// supported per-item size. The payload itself is never retained.
+    case payloadTooLarge = 26
+    /// A bounded operation could not admit more work because its item-count or
+    /// aggregate byte budget was already exhausted.
+    case resourceLimitReached = 27
+    /// An attachment picker or composer reached its fixed item-count cap.
+    case attachmentCountLimitReached = 28
+    /// An attachment picker or composer reached its aggregate byte budget.
+    case attachmentAggregateSizeLimitReached = 29
+    /// Required device-local persisted state was absent or unavailable.
+    case localStateUnavailable = 30
    case unknown = 255

    /// Reduces a typed or system error to the bounded diagnostic vocabulary.
@@ -151,6 +163,36 @@ public enum DiagnosticFailureKind: Int, Sendable, Codable, CaseIterable {
    }
 }

+/// Why a pending transport dial was cancelled by its owner.
+///
+/// This is deliberately separate from ``DiagnosticFailureKind/cancelled``:
+/// the failure says what the transport observed, while this value says which
+/// lifecycle boundary asked it to stop.
+public enum DiagnosticCancellationReason: Int, Sendable, Codable, CaseIterable {
+    case unknown = 0
+    case requestCancelled = 1
+    case requestTimedOut = 2
+    case sessionTeardown = 3
+    case sessionDeinitialized = 4
+}
+
+/// The bounded reason token sent by an admitted Iroh peer when it closes.
+///
+/// Raw Iroh close text is never exported. The server and client agree on these
+/// tokens so a report can distinguish an expected replacement from a network
+/// failure without retaining a peer-chosen string.
+public enum DiagnosticRemoteCloseReason: Int, Sendable, Codable, CaseIterable {
+    case unknown = 0
+    case clientClosed = 1
+    case serverClosed = 2
+    case superseded = 3
+    case admissionLeaseExpired = 4
+    case admissionRevalidationFailed = 5
+    case sendQueueOverflow = 6
+    case serverFailure = 7
+    case serverCancelled = 8
+}
+
 /// Adopted by transport and policy errors that can provide a safe failure
 /// category without exporting their raw associated values or description.
 public protocol DiagnosticFailureProviding: Error, Sendable {
@@ -181,6 +223,60 @@ public enum DiagnosticPathKind: Int, Sendable, Codable, CaseIterable {
    }
 }

+/// The dial leg attempted while establishing a direct Iroh connection.
+///
+/// Raw values are stable export vocabulary; never renumber.
+public enum DiagnosticDirectDialLeg: Int, Sendable, Codable, CaseIterable {
+    /// Broker-published public path hints.
+    case publicPaths = 0
+    /// Profile-gated private fallback hints (manual, LAN, or VPN sourced).
+    case privateFallback = 1
+}
+
+/// Whether configured private addresses became dialable hints for one dial.
+///
+/// Raw values are stable export vocabulary. The cases carry only the join
+/// outcome, never an address, port, or identity.
+public enum DiagnosticPrivateAddressJoinState: Int, Sendable, Codable, CaseIterable {
+    /// No enabled private address is configured for the target Mac.
+    case notConfigured = 0
+    /// At least one configured address joined a fresh broker UDP port.
+    case joined = 1
+    /// Addresses are configured but the target's broker-registered ports
+    /// were missing or older than the private-hint TTL, so none joined.
+    case brokerPortsStale = 2
+}
+
+/// The outcome of account-private LAN discovery for one dial.
+///
+/// Raw values are stable export vocabulary; the cases carry no peer,
+/// address, or service identity.
+public enum DiagnosticLANDiscoveryOutcome: Int, Sendable, Codable, CaseIterable {
+    /// No broker-issued LAN authority exists for the target, so no browse ran.
+    case noAuthority = 0
+    /// The target Mac's advertisement resolved to dialable hints.
+    case found = 1
+    /// The browse completed without resolving the target's advertisement.
+    case notFound = 2
+    /// The system denied Bonjour browsing (Local Network permission).
+    case policyDenied = 3
+}
+
+/// The Mac-side account-private Bonjour publication state.
+///
+/// Raw values are stable export vocabulary mirroring the publisher's
+/// lifecycle without exposing any advertised name, address, or port.
+public enum DiagnosticLANPublicationState: Int, Sendable, Codable, CaseIterable {
+    /// Publication is stopped.
+    case inactive = 0
+    /// Advertisements are registered on at least one interface.
+    case active = 1
+    /// Registration is wanted but currently failing.
+    case unavailable = 2
+    /// The system denied Bonjour publication (Local Network policy).
+    case policyDenied = 3
+}
+
 /// Why an admitted transport session entered or left its local pool.
 ///
 /// Raw values are stable export vocabulary. The cases identify only local
@@ -221,3 +317,642 @@ public enum DiagnosticRuntimeRole: Int, Sendable, Codable, CaseIterable {
    /// Source-level spelling used by the current Apple mobile composition.
    public static let iosClient = DiagnosticRuntimeRole.mobileClient
 }
+
+/// Stable, privacy-safe iOS product events written to the durable app log.
+///
+/// Each case names a feature boundary and outcome without carrying the user's
+/// content or identity. Raw values are shipped diagnostic vocabulary: append
+/// new cases physically at the end and never renumber existing ones. Stable
+/// declaration order also prevents stale incremental clients from constructing
+/// a case with a different enum discriminator. Gaps reserve room for each
+/// product area so future events remain easy to audit in exported logs.
+///
+/// `DiagnosticEvent.c` has one stable contract per event. Categorical values
+/// use ``DiagnosticAppEventDetail``. Numeric producers use `count` only for a
+/// documented item count, byte count, ordinal, boolean, or bounded setting.
+public enum DiagnosticAppEventKind: Int, Sendable, Codable, CaseIterable {
+    // MARK: App runtime (1-19)
+    case appLaunched = 1
+    case appForegrounded = 2
+    case appBecameInactive = 3
+    case appBackgrounded = 4
+    case appOpenURLReceived = 5
+    case appOpenURLDeferredForAuthentication = 6
+    case appOpenURLHandled = 7
+    case appOpenURLRejected = 8
+    case appMemoryWarningReceived = 9
+    case appProtectedDataUnavailable = 10
+    case appProtectedDataAvailable = 11
+    case appScreenshotCaptured = 12
+
+    // MARK: Authentication and account (20-39)
+    case authRestoreStarted = 20
+    case authRestoreSucceeded = 21
+    case authRestoreFailed = 22
+    case authSignInStarted = 23
+    case authCodeRequested = 24
+    case authCodeRequestFailed = 25
+    case authVerificationStarted = 26
+    case authSignInSucceeded = 27
+    case authSignInFailed = 28
+    case authSignInCancelled = 29
+    case authSignOutStarted = 30
+    case authSignOutSucceeded = 31
+    case authSignOutFailed = 32
+    case authTeamChanged = 33
+    case authAccountDeletionStarted = 34
+    case authAccountDeletionSucceeded = 35
+    case authAccountDeletionFailed = 36
+    case authRevalidationStarted = 37
+    case authRevalidationSucceeded = 38
+    case authRevalidationFailed = 39
+
+    // MARK: Onboarding and migration (40-59)
+    case onboardingStarted = 40
+    case onboardingStageViewed = 41
+    case onboardingConnectionMethodChanged = 42
+    case onboardingPairingStarted = 43
+    case onboardingConnectionRetried = 44
+    case onboardingSkipped = 45
+    case onboardingCompleted = 46
+    case autoConnectMigrationPresented = 47
+    case autoConnectMigrationAccepted = 48
+    case autoConnectMigrationDismissed = 49
+
+    // MARK: Push notifications (60-99)
+    case pushConfigured = 60
+    case pushAuthorizationPrompted = 61
+    case pushAuthorizationGranted = 62
+    case pushAuthorizationDenied = 63
+    case pushRemoteRegistrationRequested = 64
+    case pushDeviceTokenReceived = 65
+    case pushDeviceTokenRegistrationFailed = 66
+    case pushBackendSyncStarted = 67
+    case pushBackendSyncSucceeded = 68
+    case pushBackendSyncFailed = 69
+    case pushReceivedInForeground = 70
+    case pushPresentedInForeground = 71
+    case pushSuppressedInForeground = 72
+    case pushTapped = 73
+    case pushReplyStarted = 74
+    case pushReplySucceeded = 75
+    case pushReplyFailed = 76
+    case pushDismissStarted = 77
+    case pushDismissSucceeded = 78
+    case pushDismissFailed = 79
+    case pushRemoteDismissReceived = 80
+    case pushRemoteDismissApplied = 81
+    case pushDeeplinkParked = 82
+    case pushDeeplinkResolved = 83
+    case pushDeeplinkExpired = 84
+    case pushDeeplinkFailed = 85
+    case pushDisabled = 86
+
+    // MARK: Computers and pairing (100-129)
+    case pairingStarted = 100
+    case pairingSucceeded = 101
+    case pairingFailed = 102
+    case pairingCancelled = 103
+    case computerListRefreshStarted = 104
+    case computerListRefreshSucceeded = 105
+    case computerListRefreshFailed = 106
+    case computerSelected = 107
+    case computerHidden = 108
+    case computerUnhidden = 109
+    case computerForgetStarted = 110
+    case computerForgetSucceeded = 111
+    case computerForgetFailed = 112
+    case computerAliasChanged = 113
+    case computerRoutesUpdated = 114
+    case tailscaleStatusChanged = 116
+    case computerSwitchStarted = 117
+    case computerSwitchSucceeded = 118
+    case computerSwitchFailed = 119
+    case reconnectStarted = 120
+    case reconnectSucceeded = 121
+    case reconnectFailed = 122
+    case presenceStreamStarted = 123
+    case presenceStreamUpdated = 124
+    case presenceStreamFailed = 125
+    case deviceRegistryLoadStarted = 126
+    case deviceRegistryLoadSucceeded = 127
+    case deviceRegistryLoadFailed = 128
+    case connectionStateChanged = 129
+
+    // MARK: Workspaces and groups (130-179)
+    case workspaceListRefreshStarted = 130
+    case workspaceListRefreshSucceeded = 131
+    case workspaceListRefreshFailed = 132
+    case workspaceStateSyncStarted = 133
+    case workspaceStateSyncSucceeded = 134
+    case workspaceStateSyncFailed = 135
+    case workspaceStateSyncFellBack = 136
+    case workspaceOpenStarted = 137
+    case workspaceOpenSucceeded = 138
+    case workspaceOpenFailed = 139
+    case workspaceCreateStarted = 140
+    case workspaceCreateSucceeded = 141
+    case workspaceCreateFailed = 142
+    case workspaceRenameStarted = 143
+    case workspaceRenameSucceeded = 144
+    case workspaceRenameFailed = 145
+    case workspaceCloseStarted = 146
+    case workspaceCloseSucceeded = 147
+    case workspaceCloseFailed = 148
+    case workspaceMoveStarted = 149
+    case workspaceMoveSucceeded = 150
+    case workspaceMoveFailed = 151
+    case workspaceReorderStarted = 152
+    case workspaceReorderSucceeded = 153
+    case workspaceReorderFailed = 154
+    case workspaceReadStateChanged = 155
+    case workspaceReadStateChangeFailed = 156
+    case workspaceGroupCreateStarted = 157
+    case workspaceGroupCreateSucceeded = 158
+    case workspaceGroupCreateFailed = 159
+    case workspaceGroupRenameStarted = 160
+    case workspaceGroupRenameSucceeded = 161
+    case workspaceGroupRenameFailed = 162
+    case workspaceGroupDeleteStarted = 163
+    case workspaceGroupDeleteSucceeded = 164
+    case workspaceGroupDeleteFailed = 165
+    case workspaceCustomizationChanged = 166
+    case workspaceCustomizationChangeFailed = 167
+    case workspaceSortChanged = 168
+    case workspaceComputerOrderChanged = 169
+    case workspaceDragDropStarted = 170
+    case workspaceDragDropSucceeded = 171
+    case workspaceDragDropFailed = 172
+    case workspaceListRecoveryStarted = 173
+    case workspaceListRecoverySucceeded = 174
+    case workspaceListRecoveryFailed = 175
+    case workspaceMutationUnavailable = 176
+    case workspaceMutationCancelled = 177
+    case workspaceGroupCollapsedChanged = 178
+    case workspaceListFilterChanged = 179
+
+    // MARK: Surfaces and navigation (180-199)
+    case surfaceSelected = 180
+    case surfaceListUpdated = 181
+    case surfaceFocused = 182
+    case surfaceCloseStarted = 183
+    case surfaceCloseSucceeded = 184
+    case surfaceCloseFailed = 185
+    case surfaceTitleChanged = 186
+    case primaryTabSelected = 187
+    case searchPresented = 188
+    case searchDismissed = 189
+    case searchResultSelected = 190
+
+    // MARK: Terminal (200-239)
+    case terminalMounted = 200
+    case terminalUnmounted = 201
+    case terminalStreamSubscribed = 202
+    case terminalStreamResubscribed = 203
+    case terminalStreamEnded = 204
+    case terminalReplayStarted = 205
+    case terminalReplaySucceeded = 206
+    case terminalReplayFailed = 207
+    case terminalReplayRetried = 208
+    case terminalInputSubmitted = 209
+    case terminalInputSent = 210
+    case terminalInputAcknowledged = 211
+    case terminalInputDropped = 212
+    case terminalOutputReceived = 213
+    case terminalOutputGapDetected = 214
+    case terminalRenderLagDetected = 215
+    case terminalViewportChanged = 216
+    case terminalViewportReportSucceeded = 217
+    case terminalViewportReportFailed = 218
+    case terminalScrollSent = 219
+    case terminalScrollFailed = 220
+    case terminalThemeChanged = 221
+    /// Detail: ``DiagnosticAppEventDetail/terminalZoomAction(_:)``.
+    case terminalZoomChanged = 222
+    /// Detail: ``DiagnosticAppEventDetail/terminalToolbarAction(_:)``.
+    case terminalToolbarActionUsed = 223
+    case terminalCreateStarted = 224
+    case terminalCreateSucceeded = 225
+    case terminalCreateFailed = 226
+    case terminalClosed = 227
+    case terminalAlternateScreenChanged = 228
+    case terminalTextViewOpened = 229
+    case terminalArtifactGalleryOpened = 230
+    case terminalArtifactListLoaded = 231
+    case terminalArtifactLoadFailed = 232
+
+    // MARK: Task composer and agent launch (240-279)
+    case taskComposerOpened = 240
+    case taskComposerClosed = 241
+    case taskDraftChanged = 242
+    case taskProviderSelected = 243
+    case taskModelListLoadStarted = 244
+    case taskModelListLoadSucceeded = 245
+    case taskModelListLoadFailed = 246
+    case taskModelSelected = 247
+    case taskDirectorySearchStarted = 248
+    case taskDirectorySearchSucceeded = 249
+    case taskDirectorySearchFailed = 250
+    case taskAttachmentPickerOpened = 251
+    case taskAttachmentPrepared = 252
+    case taskAttachmentPreparationFailed = 253
+    case taskAttachmentRemoved = 254
+    case taskSubmitStarted = 255
+    case taskSubmitSucceeded = 256
+    case taskSubmitFailed = 257
+    case taskSubmitCancelled = 258
+    case taskWorkspaceCreated = 259
+    case taskAgentLaunched = 260
+    case taskTemplateListLoaded = 261
+    case taskTemplateCreated = 262
+    case taskTemplateUpdated = 263
+    case taskTemplateDeleted = 264
+    case taskMachineSelected = 265
+    case taskRouteSelected = 266
+    case taskComposerRecoveryStarted = 267
+    case taskComposerRecovered = 268
+    case taskComposerRecoveryFailed = 269
+    /// Count is the admitted attachment count for
+    /// ``DiagnosticFailureKind/attachmentCountLimitReached`` and aggregate
+    /// bytes for ``DiagnosticFailureKind/attachmentAggregateSizeLimitReached``.
+    case taskAttachmentLimitReached = 270
+
+    // MARK: Agent chat (280-309)
+    case chatOpened = 280
+    case chatClosed = 281
+    case chatSessionListLoadStarted = 282
+    case chatSessionListLoadSucceeded = 283
+    case chatSessionListLoadFailed = 284
+    case chatSessionSelected = 285
+    case chatEventStreamStarted = 286
+    case chatEventStreamEnded = 287
+    case chatMessageSubmitStarted = 289
+    case chatMessageSubmitSucceeded = 290
+    case chatMessageSubmitFailed = 291
+    case chatPermissionAnswered = 292
+    case chatQuestionAnswered = 293
+    case chatArtifactDiscovered = 294
+    case chatArtifactOpened = 295
+    case chatMessageRetried = 296
+    case chatComposerAttachmentAdded = 297
+    case chatComposerAttachmentRemoved = 298
+    case chatBlockDetailOpened = 299
+    case chatPermissionAnswerFailed = 300
+    case chatQuestionAnswerFailed = 301
+    case chatMessageQueued = 560
+    case chatInterruptSucceeded = 561
+    case chatInterruptFailed = 562
+    case chatHistoryLoadStarted = 563
+    case chatHistoryLoadSucceeded = 564
+    case chatHistoryLoadFailed = 565
+    case chatOlderHistoryLoadStarted = 566
+    case chatOlderHistoryLoadSucceeded = 567
+    case chatOlderHistoryLoadFailed = 568
+
+    // MARK: Notification feed (310-339)
+    case notificationFeedOpened = 310
+    case notificationFeedClosed = 311
+    case notificationFeedLoadStarted = 312
+    case notificationFeedLoadSucceeded = 313
+    case notificationFeedLoadFailed = 314
+    case notificationFeedLoadMoreStarted = 315
+    case notificationFeedLoadMoreSucceeded = 316
+    case notificationFeedItemOpened = 318
+    case notificationFeedItemMarkedRead = 319
+    case notificationFeedItemDismissed = 320
+    case notificationBadgeReconciled = 324
+    case notificationBadgeReconcileFailed = 325
+    case phonePushTestStarted = 327
+    case phonePushTestSucceeded = 328
+    case phonePushTestFailed = 329
+    case notificationFeedFilterChanged = 330
+
+    // MARK: Changes and diffs (340-369)
+    case changesOpened = 340
+    case changesClosed = 341
+    case changesSummaryLoadStarted = 342
+    case changesSummaryLoadSucceeded = 343
+    case changesSummaryLoadFailed = 344
+    case changedFilesLoadStarted = 345
+    case changedFilesLoadSucceeded = 346
+    case changedFilesLoadFailed = 347
+    case fileDiffLoadStarted = 348
+    case fileDiffLoadSucceeded = 349
+    case fileDiffLoadFailed = 350
+    /// Count is the zero-based file ordinal in the already-redacted list.
+    case fileDiffExpanded = 351
+    case fileDiffCacheHit = 352
+    case changedFileSelected = 353
+    case diffCopied = 354
+
+    // MARK: Artifacts and files (370-399)
+    case artifactListLoadStarted = 370
+    case artifactListLoadSucceeded = 371
+    case artifactListLoadFailed = 372
+    case artifactOpened = 373
+    case artifactDownloadStarted = 374
+    case artifactDownloadSucceeded = 375
+    case artifactDownloadFailed = 376
+    case artifactShareStarted = 377
+    case artifactShareSucceeded = 378
+    case artifactShareFailed = 379
+    case artifactPreviewFailed = 380
+    case artifactSearchChanged = 381
+    case artifactFolderOpened = 382
+    case artifactCopied = 383
+    case artifactQuickLookOpened = 385
+    case artifactCacheHit = 386
+    case artifactStreamInterrupted = 387
+    case artifactSaveStarted = 388
+    case artifactSaveSucceeded = 389
+    case artifactSaveFailed = 390
+
+    // MARK: Browser (400-429)
+    case browserListRefreshStarted = 400
+    case browserListRefreshSucceeded = 401
+    case browserListRefreshFailed = 402
+    case browserCreateStarted = 403
+    case browserCreateSucceeded = 404
+    case browserCreateFailed = 405
+    case browserStreamStartRequested = 406
+    case browserStreamStarted = 407
+    case browserStreamStartFailed = 408
+    case browserStreamStopped = 409
+    case browserStreamRestarted = 410
+    case browserNavigateStarted = 411
+    case browserNavigateSucceeded = 412
+    case browserNavigateFailed = 413
+    case browserBackRequested = 414
+    case browserForwardRequested = 415
+    case browserReloadRequested = 416
+    case browserDialogPresented = 417
+    case browserDialogResponded = 418
+    case browserFrameReceived = 419
+    case browserFrameDecodeFailed = 420
+    case browserStateReceived = 421
+    case browserViewportChanged = 422
+    case browserInputFailed = 423
+    case browserClosed = 424
+    case browserDialogResponseFailed = 425
+    case browserStopRequested = 426
+    case browserStateDecodeFailed = 427
+    case browserDialogDecodeFailed = 428
+    case browserClosedDecodeFailed = 429
+
+    // MARK: Settings, feedback, and diagnostics (430-449)
+    case settingsOpened = 430
+    case settingsClosed = 431
+    case feedbackSubmitStarted = 435
+    case feedbackSubmitSucceeded = 436
+    case feedbackSubmitFailed = 437
+    case crashReportingConsentChanged = 438
+    case analyticsUploadStarted = 441
+    case analyticsUploadSucceeded = 442
+    case analyticsUploadFailed = 443
+    case analyticsUploadDropped = 444
+    case analyticsConsentChanged = 445
+    case crashReportingStarted = 446
+    case crashReportingDisabled = 447
+
+    // MARK: Camera and media attachments (450-479)
+    case cameraAuthorizationRequested = 450
+    case cameraAuthorizationGranted = 451
+    case cameraAuthorizationDenied = 452
+    case qrScanStarted = 453
+    case qrScanSucceeded = 454
+    case qrScanFailed = 455
+    case qrScanCancelled = 456
+    case photoPickerOpened = 457
+    /// Count is the number of picker results returned.
+    case photoPickerSelected = 458
+    case photoPickerDismissed = 459
+    case attachmentPreparationStarted = 460
+    /// Count is the prepared attachment's byte size.
+    case attachmentPreparationSucceeded = 461
+    case attachmentPreparationFailed = 462
+
+    // MARK: Persistence and capability negotiation (480-519)
+    case pairedMacStoreOpened = 480
+    case pairedMacStoreOpenFailed = 481
+    case pairedMacStoreReadFailed = 482
+    case pairedMacStoreWriteFailed = 483
+    case draftRestored = 484
+    case draftSaved = 485
+    case draftPersistenceFailed = 486
+    case pairedMacStoreReadSucceeded = 487
+    case pairedMacStoreWriteSucceeded = 488
+    case pairedMacBackupRefreshStarted = 489
+    case pairedMacBackupRefreshSucceeded = 490
+    case pairedMacBackupRefreshFailed = 491
+    case pairedMacRestoreStarted = 492
+    case pairedMacRestoreSucceeded = 493
+    case pairedMacRestoreFailed = 494
+    case settingPersistenceFailed = 495
+    case draftDeleted = 496
+    case templatePersistenceFailed = 497
+    case pairedMacBackupWriteStarted = 498
+    case pairedMacBackupWriteSucceeded = 499
+    case capabilitySnapshotReceived = 500
+    case pairedMacBackupWriteFailed = 502
+
+    // MARK: Detailed setting mutations (520-559)
+    case displayAltScreenNoticeChanged = 520
+    case displayFolderTapChanged = 521
+    case displayHapticsChanged = 522
+    case taskComposerFeatureChanged = 523
+    case terminalFilesFeatureChanged = 524
+    case toastFeatureChanged = 525
+    case displayMissingFilesChanged = 526
+    case displayWorkspaceTitleWrappingChanged = 527
+    case displayWorkspacePreviewLinesChanged = 528
+    case terminalScrollbackRowsChanged = 529
+    case telemetrySharingChanged = 530
+    /// `c`: ``DiagnosticConnectionMethod`` the user switched to.
+    case connectionMethodPreferenceChanged = 531
+    /// Detail: ``DiagnosticAppEventDetail/toolbarConfigurationAction(_:)``.
+    case customToolbarChanged = 532
+    /// Detail: ``DiagnosticAppEventDetail/toolbarConfigurationAction(_:)``.
+    case terminalShortcutChanged = 533
+    case notificationPreferenceChanged = 534
+    case appDiagnosticsShared = 535
+    case networkDiagnosticsShared = 536
+    case toastPresented = 537
+    case toastCoalesced = 538
+    case toastQueued = 539
+    case toastDropped = 540
+    case toastDismissed = 541
+    case toastInteractionStarted = 542
+    case toastInteractionEnded = 543
+
+    // MARK: Iroh settings (610-639)
+    case irohSettingsOpened = 610
+    case irohSettingsClosed = 611
+    case irohRelayPreferenceChangeStarted = 612
+    case irohRelayPreferenceChangeSucceeded = 613
+    case irohRelayPreferenceChangeFailed = 614
+    case irohPathPreferenceChangeStarted = 615
+    case irohPathPreferenceChangeSucceeded = 616
+    case irohPathPreferenceChangeFailed = 617
+    case irohCustomRelayUpsertStarted = 618
+    case irohCustomRelayUpsertSucceeded = 619
+    case irohCustomRelayUpsertFailed = 620
+    case irohCustomRelayRemoveStarted = 621
+    case irohCustomRelayRemoveSucceeded = 622
+    case irohCustomRelayRemoveFailed = 623
+    case irohCustomRelayTestStarted = 624
+    case irohCustomRelayTestSucceeded = 625
+    case irohCustomRelayTestFailed = 626
+    case irohPrivatePathUpsertStarted = 627
+    case irohPrivatePathUpsertSucceeded = 628
+    case irohPrivatePathUpsertFailed = 629
+    case irohPrivatePathRemoveStarted = 630
+    case irohPrivatePathRemoveSucceeded = 631
+    case irohPrivatePathRemoveFailed = 632
+    case irohDiagnosticsCleared = 633
+    case verboseDiagnosticLoggingChanged = 634
+    case irohDiagnosticsShared = 635
+    case verboseDiagnosticsShared = 636
+
+    // MARK: Terminal composer, media, and feature delivery (640-669)
+    case terminalDraftStateChanged = 640
+    case terminalAttachmentStaged = 641
+    case terminalAttachmentRemoved = 642
+    case terminalAttachmentRejected = 643
+    case terminalImagePasteStarted = 644
+    case terminalImagePasteSucceeded = 645
+    case terminalImagePasteFailed = 646
+    case terminalViewportClearStarted = 647
+    case terminalViewportClearSucceeded = 648
+    case terminalViewportClearFailed = 649
+    case browserFrameAcknowledgementFailed = 650
+    case dictationStartRequested = 651
+    case dictationStarted = 652
+    case dictationStopRequested = 653
+    case dictationStopped = 654
+    case dictationCancelled = 655
+    case dictationUnavailable = 656
+    case dictationFirstResultReceived = 657
+    case dictationRecognitionFailed = 658
+    case dictationStopTimedOut = 659
+
+    // MARK: Appended persistence events
+    case pairedMacStoreWriteStarted = 660
+
+    // MARK: Appended connection reporting events
+    /// The configured connection method, recorded at composition and on every
+    /// foreground so any shared report window states it even after the ring
+    /// rolls past app launch. `c`: ``DiagnosticConnectionMethod``.
+    case connectionMethodConfigured = 661
+    /// The transport that actually carries the foreground connection, recorded
+    /// on connect and on every active-route change. `c`: ``DiagnosticTransportKind``.
+    case foregroundTransportSelected = 662
+}
+
+/// The user's configured connection method, mirrored from the settings picker
+/// without account, address, or grant details.
+public enum DiagnosticConnectionMethod: Int, Sendable, Codable, CaseIterable {
+    case automatic = 0
+    case tailscale = 1
+}
+
+/// High-level lifecycle state for one phone-controlled Simulator stream.
+///
+/// Values intentionally omit panel UUIDs, device names, workspace titles, and
+/// frame contents. The associated ``DiagnosticEvent`` carries only a
+/// process-local surface handle and bounded counters.
+public enum DiagnosticSimulatorStreamLifecycle: Int, Sendable, Codable, CaseIterable {
+    case startRequested = 1
+    case started = 2
+    case locked = 3
+    case startFailed = 4
+    case stopRequested = 5
+    case stopped = 6
+    case closed = 7
+    case restartRequested = 8
+    case pausedForBackground = 9
+    case descriptorApplied = 10
+    /// The client's staleness watchdog saw a full silent interval (no frame
+    /// or keepalive) for an active stream and is re-requesting it.
+    case stalled = 11
+    case stopFailed = 12
+}
+
+/// Frame-pipeline state for the Simulator video stream.
+public enum DiagnosticSimulatorFrameLifecycle: Int, Sendable, Codable, CaseIterable {
+    case readerAttached = 1
+    case readerMissing = 2
+    case copied = 3
+    case encodeFailed = 4
+    case sent = 5
+    case refused = 6
+    case cachedSent = 7
+    case subscriptionReasserted = 8
+    case received = 9
+    case staleIgnored = 10
+    case decodeFailed = 11
+    case imageDecoded = 12
+    case imageDecodeFailed = 13
+    case unknownPanel = 14
+}
+
+/// Input delivery state for phone-originated Simulator actions.
+public enum DiagnosticSimulatorInputLifecycle: Int, Sendable, Codable, CaseIterable {
+    case queued = 1
+    case sent = 2
+    case accepted = 3
+    case failed = 4
+    case rejectedLocked = 5
+    case unavailable = 6
+    case invalidParameters = 7
+    case panelMissing = 8
+    case featureDisabled = 9
+    case blockedViewOnly = 10
+}
+
+/// Phone-originated Simulator input category.
+public enum DiagnosticSimulatorInputKind: Int, Sendable, Codable, CaseIterable {
+    case pointer = 1
+    case text = 2
+    case hardwareButton = 3
+}
+
+/// Hardware button category for phone-originated Simulator actions.
+public enum DiagnosticSimulatorHardwareButtonKind: Int, Sendable, Codable, CaseIterable {
+    case unknown = 0
+    case home = 1
+    case swipeHome = 2
+    case appSwitcher = 3
+    case lock = 4
+    case siri = 5
+    case sideButton = 6
+    case power = 7
+    case volumeUp = 8
+    case volumeDown = 9
+    case action = 10
+    case watchSideButton = 11
+}
+
+/// Pointer phase for phone-originated Simulator touch events.
+public enum DiagnosticSimulatorPointerPhase: Int, Sendable, Codable, CaseIterable {
+    case began = 1
+    case moved = 2
+    case ended = 3
+    case tap = 4
+}
+
+/// Privacy-safe ownership state for a Simulator pane's active controller.
+public enum DiagnosticSimulatorOwnershipState: Int, Sendable, Codable, CaseIterable {
+    case unowned = 0
+    case currentConnection = 1
+    case otherConnection = 2
+    case pendingHandshake = 3
+    case unknown = 4
+}
+
+/// Coordinate mapping state for a phone gesture before it leaves the device.
+public enum DiagnosticSimulatorCoordinateState: Int, Sendable, Codable, CaseIterable {
+    case mapped = 1
+    case outsideImage = 2
+    case viewOnlyBlocked = 3
+    case zeroImage = 4
+}
@@ -0,0 +1,93 @@
+import Foundation
+
+/// Immutable isolation boundary for one installed cmux iOS application.
+///
+/// The complete bundle identifier is the namespace. Distribution labels and
+/// short development tags are deliberately not accepted here because either
+/// can alias another installed app.
+public struct MobileIOSAppNamespace: Equatable, Hashable, Sendable {
+    /// Exact bundle identifier that owns this namespace.
+    public let bundleIdentifier: String
+
+    /// Creates a namespace from one complete, validated iOS bundle identifier.
+    public init?(bundleIdentifier: String?) {
+        guard let bundleIdentifier else { return nil }
+        let trimmed = bundleIdentifier.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty,
+              trimmed == bundleIdentifier,
+              trimmed == trimmed.lowercased(),
+              trimmed.count <= 255,
+              trimmed.contains("."),
+              trimmed.range(
+                of: #"^[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?$"#,
+                options: .regularExpression
+              ) != nil
+        else {
+            return nil
+        }
+        self.bundleIdentifier = trimmed
+    }
+
+    /// Resolves the exact iOS bundle paired with one Mac app instance.
+    ///
+    /// Tagged Mac builds pair with the same tagged iOS development bundle.
+    /// The stable Mac instance pairs with the public App Store bundle. Invalid
+    /// tags fail closed instead of aliasing another installed iOS app.
+    public init?(pairedMacInstanceTag instanceTag: String?) {
+        let tag = instanceTag?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if let instanceTag, instanceTag != tag {
+            return nil
+        }
+        let bundleIdentifier = if tag.isEmpty || tag == "default" {
+            "com.cmux.app"
+        } else {
+            "dev.cmux.ios.\(tag)"
+        }
+        self.init(bundleIdentifier: bundleIdentifier)
+    }
+
+    /// The exact Keychain access group this app must claim after signing.
+    public func keychainAccessGroup(teamIdentifier: String) -> String {
+        "\(teamIdentifier).\(bundleIdentifier)"
+    }
+
+    /// A Keychain service that cannot collide with another installed bundle.
+    public func keychainService(base: String) -> String {
+        "\(base).\(bundleIdentifier)"
+    }
+
+    /// The only pairing URL scheme this bundle registers with iOS.
+    public var pairingURLScheme: String {
+        "cmux-ios-\(bundleIdentifier)"
+    }
+
+    /// Opaque server partition for data restored to this exact app bundle.
+    public var serverScope: String {
+        let encoded = Data(bundleIdentifier.utf8)
+            .base64EncodedString()
+            .replacingOccurrences(of: "+", with: "-")
+            .replacingOccurrences(of: "/", with: "_")
+            .replacingOccurrences(of: "=", with: "")
+        return "ios:v3:\(encoded)"
+    }
+
+    /// The only legacy backup collection that can be attributed to this bundle.
+    ///
+    /// The App Store app owns the former unscoped release collection. Tagged
+    /// development bundles own their same-tag v2 collection. Beta, Internal,
+    /// and Demo intentionally adopt nothing because their old unscoped records
+    /// cannot be attributed without risking cross-build restore.
+    public var legacyBackupScope: MobileIOSLegacyBackupScope? {
+        if bundleIdentifier == "com.cmux.app" {
+            return .unscoped
+        }
+        let prefix = "dev.cmux.ios."
+        guard bundleIdentifier.hasPrefix(prefix),
+              let buildScope = MobileIOSBuildScope(
+                String(bundleIdentifier.dropFirst(prefix.count))
+              ) else {
+            return nil
+        }
+        return .scoped(buildScope.serializedScope)
+    }
+}
@@ -0,0 +1,16 @@
+/// One unambiguous pre-v3 backup collection eligible for one-time adoption.
+public enum MobileIOSLegacyBackupScope: Equatable, Sendable {
+    /// The former App Store collection that did not carry a scope header.
+    case unscoped
+
+    /// A former development collection identified by its exact v2 scope.
+    case scoped(String)
+
+    /// The legacy request header value, or `nil` for the unscoped collection.
+    public var headerValue: String? {
+        switch self {
+        case .unscoped: nil
+        case .scoped(let value): value
+        }
+    }
+}
@@ -0,0 +1,42 @@
+public enum MobileSimulatorFrameFormat: String, Codable, Equatable, Sendable {
+    case jpeg
+    case png
+}
+
+public struct MobileSimulatorFrameEvent: Codable, Equatable, Sendable {
+    public let panelID: String
+    public let sequence: UInt64
+    public let format: MobileSimulatorFrameFormat
+    public let pixelWidth: Int
+    public let pixelHeight: Int
+    public let displayScale: Double
+    public let dataBase64: String
+
+    public init(
+        panelID: String,
+        sequence: UInt64,
+        format: MobileSimulatorFrameFormat,
+        pixelWidth: Int,
+        pixelHeight: Int,
+        displayScale: Double,
+        dataBase64: String
+    ) {
+        self.panelID = panelID
+        self.sequence = sequence
+        self.format = format
+        self.pixelWidth = pixelWidth
+        self.pixelHeight = pixelHeight
+        self.displayScale = displayScale
+        self.dataBase64 = dataBase64
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case panelID = "panel_id"
+        case sequence = "seq"
+        case format
+        case pixelWidth = "pixel_width"
+        case pixelHeight = "pixel_height"
+        case displayScale = "display_scale"
+        case dataBase64 = "data_base64"
+    }
+}
@@ -0,0 +1,69 @@
+public struct MobileSimulatorPanelDescriptor: Codable, Equatable, Identifiable, Sendable {
+    public var id: String { panelID }
+
+    public let panelID: String
+    public let workspaceID: String
+    public let title: String
+    public let selectedDeviceName: String?
+    public let selectedDeviceState: String?
+    public let status: String
+    public let isReady: Bool
+    public let supportsTouch: Bool
+    public let supportsKeyboard: Bool
+    public let supportsHardwareButtons: Bool
+    public let supportsRotation: Bool
+    public let ownerConnectionID: String?
+    /// Whether the receiving connection owns the pane's control lock.
+    /// `nil` means "not personalized": the descriptor was built for a shared
+    /// payload (state-sync rows, workspace lists) that fans out to every
+    /// phone, so it cannot say anything about *this* connection. Receivers
+    /// keep their last per-connection answer (stream start response,
+    /// `simulator.state` events, `mobile.simulator.list`) when this is `nil`.
+    public let isOwnedByCurrentConnection: Bool?
+
+    public init(
+        panelID: String,
+        workspaceID: String,
+        title: String,
+        selectedDeviceName: String?,
+        selectedDeviceState: String?,
+        status: String,
+        isReady: Bool,
+        supportsTouch: Bool,
+        supportsKeyboard: Bool,
+        supportsHardwareButtons: Bool,
+        supportsRotation: Bool,
+        ownerConnectionID: String? = nil,
+        isOwnedByCurrentConnection: Bool? = nil
+    ) {
+        self.panelID = panelID
+        self.workspaceID = workspaceID
+        self.title = title
+        self.selectedDeviceName = selectedDeviceName
+        self.selectedDeviceState = selectedDeviceState
+        self.status = status
+        self.isReady = isReady
+        self.supportsTouch = supportsTouch
+        self.supportsKeyboard = supportsKeyboard
+        self.supportsHardwareButtons = supportsHardwareButtons
+        self.supportsRotation = supportsRotation
+        self.ownerConnectionID = ownerConnectionID
+        self.isOwnedByCurrentConnection = isOwnedByCurrentConnection
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case panelID = "panel_id"
+        case workspaceID = "workspace_id"
+        case title
+        case selectedDeviceName = "selected_device_name"
+        case selectedDeviceState = "selected_device_state"
+        case status
+        case isReady = "is_ready"
+        case supportsTouch = "supports_touch"
+        case supportsKeyboard = "supports_keyboard"
+        case supportsHardwareButtons = "supports_hardware_buttons"
+        case supportsRotation = "supports_rotation"
+        case ownerConnectionID = "owner_connection_id"
+        case isOwnedByCurrentConnection = "is_owned_by_current_connection"
+    }
+}
@@ -0,0 +1,140 @@
+public struct MobileSimulatorListParameters: Codable, Equatable, Sendable {
+    public let workspaceID: String?
+
+    public init(workspaceID: String? = nil) {
+        self.workspaceID = workspaceID
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case workspaceID = "workspace_id"
+    }
+}
+
+public struct MobileSimulatorStreamStartParameters: Codable, Equatable, Sendable {
+    public let panelID: String
+    public let workspaceID: String
+
+    public init(panelID: String, workspaceID: String) {
+        self.panelID = panelID
+        self.workspaceID = workspaceID
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case panelID = "panel_id"
+        case workspaceID = "workspace_id"
+    }
+}
+
+public struct MobileSimulatorPanelParameters: Codable, Equatable, Sendable {
+    public let panelID: String
+    public let workspaceID: String
+
+    public init(panelID: String, workspaceID: String) {
+        self.panelID = panelID
+        self.workspaceID = workspaceID
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case panelID = "panel_id"
+        case workspaceID = "workspace_id"
+    }
+}
+
+public enum MobileSimulatorPointerPhase: String, Codable, Equatable, Sendable {
+    case began
+    case moved
+    case ended
+    case tap
+}
+
+public struct MobileSimulatorPointerInput: Codable, Equatable, Sendable {
+    public let panelID: String
+    public let workspaceID: String
+    public let phase: MobileSimulatorPointerPhase
+    public let x: Double
+    public let y: Double
+
+    public init(
+        panelID: String,
+        workspaceID: String,
+        phase: MobileSimulatorPointerPhase,
+        x: Double,
+        y: Double
+    ) {
+        self.panelID = panelID
+        self.workspaceID = workspaceID
+        self.phase = phase
+        self.x = x
+        self.y = y
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case panelID = "panel_id"
+        case workspaceID = "workspace_id"
+        case phase
+        case x
+        case y
+    }
+}
+
+public struct MobileSimulatorTextInput: Codable, Equatable, Sendable {
+    public let panelID: String
+    public let workspaceID: String
+    public let text: String
+
+    public init(panelID: String, workspaceID: String, text: String) {
+        self.panelID = panelID
+        self.workspaceID = workspaceID
+        self.text = text
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case panelID = "panel_id"
+        case workspaceID = "workspace_id"
+        case text
+    }
+}
+
+public enum MobileSimulatorHardwareButton: String, Codable, CaseIterable, Equatable, Sendable {
+    case home
+    case swipeHome
+    case appSwitcher
+    case lock
+    case siri
+    case sideButton
+    case power
+    case volumeUp
+    case volumeDown
+    case action
+    case watchSideButton
+}
+
+public struct MobileSimulatorButtonInput: Codable, Equatable, Sendable {
+    public let panelID: String
+    public let workspaceID: String
+    public let button: MobileSimulatorHardwareButton
+
+    public init(panelID: String, workspaceID: String, button: MobileSimulatorHardwareButton) {
+        self.panelID = panelID
+        self.workspaceID = workspaceID
+        self.button = button
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case panelID = "panel_id"
+        case workspaceID = "workspace_id"
+        case button
+    }
+}
+
+public struct MobileSimulatorClosedEvent: Codable, Equatable, Sendable {
+    public let panelID: String
+
+    public init(panelID: String) {
+        self.panelID = panelID
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case panelID = "panel_id"
+    }
+}
@@ -0,0 +1,23 @@
+public struct MobileSimulatorStreamCapability: Sendable {
+    public static let current = MobileSimulatorStreamCapability()
+
+    public let identifier: String
+    public let inputIdentifier: String
+    public let ownershipIdentifier: String
+    /// The Mac re-emits `simulator.state` on a fixed cadence while a stream
+    /// session is active, so clients can treat event silence as staleness
+    /// without misreading a static Simulator screen as a dead stream.
+    public let keepaliveIdentifier: String
+
+    public init(
+        identifier: String = "simulator.stream.v1",
+        inputIdentifier: String = "simulator.input.v1",
+        ownershipIdentifier: String = "simulator.ownership.v1",
+        keepaliveIdentifier: String = "simulator.keepalive.v1"
+    ) {
+        self.identifier = identifier
+        self.inputIdentifier = inputIdentifier
+        self.ownershipIdentifier = ownershipIdentifier
+        self.keepaliveIdentifier = keepaliveIdentifier
+    }
+}
@@ -35,6 +35,43 @@ public struct MobileSyncCollectionID: RawRepresentable, Codable, Hashable, Senda
 /// `mobile.workspace.list` payload (same snake_case wire names) plus an
 /// explicit `sort_index` so list order syncs without positional inference.
 public struct WorkspaceSyncRecord: MobileSyncRecord {
+    /// One surface row within a workspace.
+    public struct Surface: Codable, Equatable, Sendable {
+        /// Stable surface identifier.
+        public let surfaceID: String
+        /// Open surface-kind wire string.
+        public let kind: String
+        /// User-facing surface title.
+        public let title: String
+        /// Backing file path for file-based surfaces, when reported.
+        public let filePath: String?
+        /// Bounded checklist/status payload for todo surfaces.
+        public let todo: MobileTodoSnapshot?
+
+        /// Creates a surface row from its wire fields.
+        public init(
+            surfaceID: String,
+            kind: String,
+            title: String,
+            filePath: String?,
+            todo: MobileTodoSnapshot? = nil
+        ) {
+            self.surfaceID = surfaceID
+            self.kind = kind
+            self.title = title
+            self.filePath = filePath
+            self.todo = todo
+        }
+
+        private enum CodingKeys: String, CodingKey {
+            case surfaceID = "surface_id"
+            case kind
+            case title
+            case filePath = "file_path"
+            case todo
+        }
+    }
+
    /// One terminal row within a workspace.
    public struct Terminal: Codable, Equatable, Sendable {
        /// Stable terminal identifier.
@@ -104,6 +141,11 @@ public struct WorkspaceSyncRecord: MobileSyncRecord {
    public let sortIndex: Int
    /// Terminal rows belonging to this workspace, in spatial order.
    public let terminals: [Terminal]
+    /// All surface rows belonging to this workspace, in spatial order.
+    /// `nil` when decoded from a Mac that predates surface inventory support.
+    public let surfaces: [Surface]?
+    /// Simulator panes belonging to this workspace, in spatial order.
+    public let simulators: [MobileSimulatorPanelDescriptor]

    /// ``MobileSyncRecord`` identity: the workspace id.
    public var syncID: String { id }
@@ -127,7 +169,9 @@ public struct WorkspaceSyncRecord: MobileSyncRecord {
        lastActivityAt: Double,
        hasUnread: Bool,
        sortIndex: Int,
-        terminals: [Terminal]
+        terminals: [Terminal],
+        surfaces: [Surface]? = nil,
+        simulators: [MobileSimulatorPanelDescriptor] = []
    ) {
        self.id = id
        self.windowID = windowID
@@ -145,6 +189,8 @@ public struct WorkspaceSyncRecord: MobileSyncRecord {
        self.hasUnread = hasUnread
        self.sortIndex = sortIndex
        self.terminals = terminals
+        self.surfaces = surfaces
+        self.simulators = simulators
    }

    public init(from decoder: any Decoder) throws {
@@ -168,6 +214,11 @@ public struct WorkspaceSyncRecord: MobileSyncRecord {
        hasUnread = try container.decode(Bool.self, forKey: .hasUnread)
        sortIndex = try container.decode(Int.self, forKey: .sortIndex)
        terminals = try container.decode([Terminal].self, forKey: .terminals)
+        surfaces = try container.decodeIfPresent([Surface].self, forKey: .surfaces)
+        simulators = try container.decodeIfPresent(
+            [MobileSimulatorPanelDescriptor].self,
+            forKey: .simulators
+        ) ?? []
    }

    private enum CodingKeys: String, CodingKey {
@@ -187,6 +238,8 @@ public struct WorkspaceSyncRecord: MobileSyncRecord {
        case hasUnread = "has_unread"
        case sortIndex = "sort_index"
        case terminals
+        case surfaces
+        case simulators
    }
 }

@@ -0,0 +1,48 @@
+/// A mobile surface kind identified by its open wire string.
+///
+/// Known kinds have static constants, while unknown raw values remain valid so
+/// older clients can preserve and route surface kinds introduced by newer Macs.
+public struct MobileSurfaceKind: RawRepresentable, Codable, Hashable, Sendable {
+    /// The surface kind's wire identifier.
+    public let rawValue: String
+
+    /// Creates a surface kind from its wire identifier.
+    /// - Parameter rawValue: The open surface-kind string.
+    public init(rawValue: String) {
+        self.rawValue = rawValue
+    }
+
+    /// Decodes the kind directly from its open wire string.
+    public init(from decoder: any Decoder) throws {
+        rawValue = try decoder.singleValueContainer().decode(String.self)
+    }
+
+    /// Encodes the kind directly as its open wire string.
+    public func encode(to encoder: any Encoder) throws {
+        var container = encoder.singleValueContainer()
+        try container.encode(rawValue)
+    }
+
+    /// A Ghostty terminal surface.
+    public static let terminal = MobileSurfaceKind(rawValue: "terminal")
+    /// A browser surface.
+    public static let browser = MobileSurfaceKind(rawValue: "browser")
+    /// A markdown preview surface.
+    public static let markdown = MobileSurfaceKind(rawValue: "markdown")
+    /// A file preview surface.
+    public static let filePreview = MobileSurfaceKind(rawValue: "filePreview")
+    /// A right-sidebar tool hosted as a surface.
+    public static let rightSidebarTool = MobileSurfaceKind(rawValue: "rightSidebarTool")
+    /// A custom sidebar hosted as a surface.
+    public static let customSidebar = MobileSurfaceKind(rawValue: "customSidebar")
+    /// An agent-session surface.
+    public static let agentSession = MobileSurfaceKind(rawValue: "agentSession")
+    /// A project surface.
+    public static let project = MobileSurfaceKind(rawValue: "project")
+    /// A browser surface owned by an extension.
+    public static let extensionBrowser = MobileSurfaceKind(rawValue: "extensionBrowser")
+    /// A workspace todo surface.
+    public static let todo = MobileSurfaceKind(rawValue: "todo")
+    /// A transient Cloud VM loading surface.
+    public static let cloudVMLoading = MobileSurfaceKind(rawValue: "cloudVMLoading")
+}
@@ -116,14 +116,15 @@ public struct MobileSyncPairingPayload: Equatable, Sendable, Codable {
        encoder.dateEncodingStrategy = .iso8601
        let data = try encoder.encode(self)
        let payload = Self.base64URLEncode(data)
-        guard let url = URL(string: "\(CmxPairingURLScheme.current)://pair?v=\(version)&payload=\(payload)") else {
+        guard let scheme = CmxPairingURLSchemeResolver().resolved?.rawValue,
+              let url = URL(string: "\(scheme)://pair?v=\(version)&payload=\(payload)") else {
            throw MobileSyncPairingPayloadError.invalidURL
        }
        return url
    }

    public static func decodeURL(_ url: URL, now: Date = Date()) throws -> MobileSyncPairingPayload {
-        guard CmxPairingURLScheme.isPairingScheme(url.scheme),
+        guard CmxPairingURLScheme(rawValue: url.scheme) != nil,
              url.host == "pair",
              let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
              let encodedPayload = components.queryItems?.first(where: { $0.name == "payload" })?.value,
@@ -0,0 +1,32 @@
+/// One bounded checklist item synced with a workspace todo surface.
+public struct MobileTodoItem: Codable, Equatable, Identifiable, Sendable {
+    /// The maximum number of characters accepted for one item's normalized text.
+    public static let maxTextLength = 500
+
+    /// The Mac-owned stable item identifier.
+    public let id: String
+    /// The normalized item text.
+    public let text: String
+    /// The item's progress state.
+    public let state: MobileTodoItemState
+    /// Who created the item.
+    public let origin: MobileTodoItemOrigin
+
+    /// Creates a mobile checklist item.
+    /// - Parameters:
+    ///   - id: The Mac-owned stable item identifier.
+    ///   - text: The normalized item text.
+    ///   - state: The item's progress state.
+    ///   - origin: Who created the item.
+    public init(
+        id: String,
+        text: String,
+        state: MobileTodoItemState,
+        origin: MobileTodoItemOrigin
+    ) {
+        self.id = id
+        self.text = text
+        self.state = state
+        self.origin = origin
+    }
+}
@@ -0,0 +1,7 @@
+/// The creator of a mobile checklist item.
+public enum MobileTodoItemOrigin: String, Codable, CaseIterable, Sendable {
+    /// A person created the item.
+    case user
+    /// An agent created the item.
+    case agent
+}
@@ -0,0 +1,18 @@
+/// A mobile checklist item's progress state.
+public enum MobileTodoItemState: String, Codable, CaseIterable, Sendable {
+    /// Work has not started.
+    case pending
+    /// Work is actively progressing.
+    case inProgress = "in_progress"
+    /// Work is complete.
+    case completed
+
+    /// The next state in the mobile tap cycle.
+    public var next: MobileTodoItemState {
+        switch self {
+        case .pending: .inProgress
+        case .inProgress: .completed
+        case .completed: .pending
+        }
+    }
+}
@@ -0,0 +1,29 @@
+/// The bounded todo payload attached to a synced todo surface.
+public struct MobileTodoSnapshot: Codable, Equatable, Sendable {
+    /// The maximum number of checklist items carried by one mobile snapshot.
+    public static let maxItems = 50
+
+    /// The effective status after applying any valid manual override.
+    public let status: MobileTodoStatus
+    /// Whether the workspace opted out of showing its status lane.
+    public let statusHidden: Bool
+    /// Checklist items in the Mac's storage order.
+    public let items: [MobileTodoItem]
+
+    /// Creates a todo snapshot.
+    /// - Parameters:
+    ///   - status: The effective workspace status.
+    ///   - statusHidden: Whether status presentation is hidden.
+    ///   - items: Checklist items in storage order.
+    public init(status: MobileTodoStatus, statusHidden: Bool, items: [MobileTodoItem]) {
+        self.status = status
+        self.statusHidden = statusHidden
+        self.items = items
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case status
+        case statusHidden = "status_hidden"
+        case items
+    }
+}
@@ -0,0 +1,20 @@
+/// A workspace's effective todo status on the mobile wire.
+public enum MobileTodoStatus: String, Codable, CaseIterable, Sendable {
+    /// Work has not started.
+    case todo
+    /// Work is actively progressing.
+    case working
+    /// Work is waiting for attention or input.
+    case needsAttention = "needs-attention"
+    /// Work is ready for review.
+    case review
+    /// Work is complete.
+    case done
+
+    /// The next status in the same cycle used by the Mac todo controls.
+    public var next: MobileTodoStatus {
+        let statuses = Self.allCases
+        guard let index = statuses.firstIndex(of: self) else { return .todo }
+        return statuses[(index + 1) % statuses.count]
+    }
+}
@@ -151,6 +151,7 @@ public struct TransportIncidentPolicy: Sendable {
    /// Event codes that are failure candidates (subject to suppression rules).
    public static let failureCodes: Set<DiagnosticEventCode> = [
        .pairFail, .pairUnreachable, .error, .transportDialFailed,
+        .transportDialLegFailed,
        .recoveryFailed, .endpointFailed, .relayPolicyRefreshFailed,
        .sessionClosed, .routeUnavailable, .discoveryFailed, .admissionFailed,
        .hostAuthenticationFailed, .rpcFailed,
@@ -0,0 +1,316 @@
+import Foundation
+import Testing
+@testable import CMUXMobileCore
+
+@Suite struct AppLogTests {
+    private func makeTempDirectory() throws -> URL {
+        let url = FileManager.default.temporaryDirectory
+            .appendingPathComponent("app-log-tests-\(UUID().uuidString)")
+        try FileManager.default.createDirectory(at: url, withIntermediateDirectories: true)
+        return url
+    }
+
+    /// Poll the drain barrier until `expected` entries have been written.
+    private func waitForProcessed(_ log: AppLog, _ expected: Int) async throws {
+        for _ in 0..<300 {
+            if await log.processedCount() >= expected { return }
+            try await Task.sleep(nanoseconds: 10_000_000)
+        }
+        #expect(await log.processedCount() >= expected)
+    }
+
+    private func contents(of url: URL) throws -> String {
+        try String(contentsOf: url, encoding: .utf8)
+    }
+
+    @Test func routesEventsByDomain() async throws {
+        let dir = try makeTempDirectory()
+        defer { try? FileManager.default.removeItem(at: dir) }
+        let appURL = dir.appendingPathComponent("app.log")
+        let networkURL = dir.appendingPathComponent("network.log")
+        let log = AppLog(appFileURL: appURL, networkFileURL: networkURL, buildStamp: "test")
+
+        log.ingest(DiagnosticEvent(
+            .simulatorStreamLifecycle,
+            surface: 7,
+            a: DiagnosticSimulatorStreamLifecycle.started.rawValue
+        ))
+        log.ingest(DiagnosticEvent(.transportDialStarted, a: 1, c: 42))
+        log.ingest(DiagnosticEvent(
+            .appLifecycleChanged,
+            a: DiagnosticAppLifecyclePhase.background.rawValue
+        ))
+        log.ingest(DiagnosticEvent(
+            .appFeatureAction,
+            a: DiagnosticAppEventKind.workspaceOpenSucceeded.rawValue
+        ))
+        try await waitForProcessed(log, 4)
+        await log.flushForTesting()
+
+        let app = try contents(of: appURL)
+        let network = try contents(of: networkURL)
+        #expect(app.contains("simulatorStreamLifecycle") || app.contains("Simulator"))
+        #expect(!network.contains("Simulator"))
+        #expect(network.contains("dial") || network.contains("Dial"))
+        #expect(!app.contains("dial") && !app.contains("Dial"))
+        #expect(app.contains("workspaceOpenSucceeded"))
+        #expect(!network.contains("workspaceOpenSucceeded"))
+        // Cross-cutting context lands in both files.
+        let appLifecycleInApp = app.contains("lifecycle") || app.contains("Lifecycle")
+        let appLifecycleInNetwork = network.contains("lifecycle") || network.contains("Lifecycle")
+        #expect(appLifecycleInApp && appLifecycleInNetwork)
+    }
+
+    @Test func mirroredStringLinesLandInAppFile() async throws {
+        let dir = try makeTempDirectory()
+        defer { try? FileManager.default.removeItem(at: dir) }
+        let appURL = dir.appendingPathComponent("app.log")
+        let networkURL = dir.appendingPathComponent("network.log")
+        let log = AppLog(appFileURL: appURL, networkFileURL: networkURL, buildStamp: "test")
+
+        log.mirrorAppLine("sim.stream state=1 panel=7")
+        try await waitForProcessed(log, 1)
+
+        #expect(try contents(of: appURL).contains("sim.stream state=1 panel=7"))
+        #expect(try !contents(of: networkURL).contains("sim.stream"))
+    }
+
+    /// A steady frame stream costs one line plus one summary, not a line per
+    /// frame; the summary flushes when the run breaks.
+    @Test func coalescesConsecutiveFrameEvents() async throws {
+        let dir = try makeTempDirectory()
+        defer { try? FileManager.default.removeItem(at: dir) }
+        let appURL = dir.appendingPathComponent("app.log")
+        let log = AppLog(appFileURL: appURL, networkFileURL: nil, buildStamp: "test")
+
+        for sequence in 1...24 {
+            log.ingest(DiagnosticEvent(
+                .simulatorFrameLifecycle,
+                surface: 7,
+                a: DiagnosticSimulatorFrameLifecycle.received.rawValue,
+                b: sequence
+            ))
+        }
+        log.ingest(DiagnosticEvent(
+            .simulatorStreamLifecycle,
+            surface: 7,
+            a: DiagnosticSimulatorStreamLifecycle.stalled.rawValue
+        ))
+        try await waitForProcessed(log, 25)
+
+        let lines = try contents(of: appURL).split(separator: "\n")
+        let frameLines = lines.filter { $0.contains("frame pipeline") }
+        // First occurrence + one coalesced summary, flushed by the stalled
+        // event that broke the run.
+        #expect(frameLines.count == 2)
+        #expect(frameLines.last?.contains("×24") == true)
+        #expect(lines.last?.contains("Stalled") == true)
+    }
+
+    /// Exceeding the byte budget moves the current generation to a unique
+    /// archive and keeps writing to a fresh active file.
+    @Test func rotatesWhenExceedingMaxBytes() async throws {
+        let dir = try makeTempDirectory()
+        defer { try? FileManager.default.removeItem(at: dir) }
+        let appURL = dir.appendingPathComponent("app.log")
+        let log = AppLog(
+            appFileURL: appURL,
+            networkFileURL: nil,
+            maxFileBytes: 512,
+            buildStamp: "test"
+        )
+
+        for index in 0..<40 {
+            log.mirrorAppLine("filler line \(index) 0123456789 0123456789")
+        }
+        try await waitForProcessed(log, 40)
+
+        let generations = AppLog.logFileURLs(for: appURL)
+        let archives = generations.filter { $0 != appURL }
+        #expect(!archives.isEmpty)
+        let active = try contents(of: appURL)
+        #expect(active.contains("cmux app log"))
+        #expect(archives.contains { (try? contents(of: $0).contains("filler line")) == true })
+    }
+
+    @Test func ordersArchivesByEmbeddedGenerationStamp() throws {
+        let dir = try makeTempDirectory()
+        defer { try? FileManager.default.removeItem(at: dir) }
+        let appURL = dir.appendingPathComponent("app.log")
+        let olderArchive = dir.appendingPathComponent(
+            "app.archive-0000000001000-AAAAAAAA.log"
+        )
+        let newerArchive = dir.appendingPathComponent(
+            "app.archive-0000000002000-BBBBBBBB.log"
+        )
+        let unparseableArchive = dir.appendingPathComponent(
+            "app.archive-unparseable.log"
+        )
+        try Data("active\n".utf8).write(to: appURL)
+        try Data("older\n".utf8).write(to: olderArchive)
+        try Data("newer\n".utf8).write(to: newerArchive)
+        try Data("unparseable\n".utf8).write(to: unparseableArchive)
+
+        let distantFuture = Date(timeIntervalSince1970: 9_000)
+        let distantPast = Date(timeIntervalSince1970: 1_000)
+        try FileManager.default.setAttributes(
+            [.modificationDate: distantFuture],
+            ofItemAtPath: olderArchive.path
+        )
+        try FileManager.default.setAttributes(
+            [.modificationDate: distantPast],
+            ofItemAtPath: newerArchive.path
+        )
+        try FileManager.default.setAttributes(
+            [.modificationDate: distantFuture],
+            ofItemAtPath: unparseableArchive.path
+        )
+
+        let generations = AppLog.logFileURLs(for: appURL)
+        #expect(generations.map(\.lastPathComponent) == [
+            appURL.lastPathComponent,
+            newerArchive.lastPathComponent,
+            olderArchive.lastPathComponent,
+            unparseableArchive.lastPathComponent,
+        ])
+    }
+
+    @Test func reopensExistingGenerationAcrossLaunches() async throws {
+        let dir = try makeTempDirectory()
+        defer { try? FileManager.default.removeItem(at: dir) }
+        let appURL = dir.appendingPathComponent("app.log")
+
+        let firstLaunch = AppLog(
+            appFileURL: appURL,
+            networkFileURL: nil,
+            buildStamp: "test"
+        )
+        firstLaunch.mirrorAppLine("first launch")
+        try await waitForProcessed(firstLaunch, 1)
+
+        let secondLaunch = AppLog(
+            appFileURL: appURL,
+            networkFileURL: nil,
+            buildStamp: "test"
+        )
+        secondLaunch.mirrorAppLine("second launch")
+        try await waitForProcessed(secondLaunch, 1)
+
+        let persisted = try contents(of: appURL)
+        #expect(persisted.contains("first launch"))
+        #expect(persisted.contains("second launch"))
+        #expect(persisted.components(separatedBy: "cmux app log").count == 2)
+        #expect(!FileManager.default.fileExists(
+            atPath: appURL.appendingPathExtension("1").path
+        ))
+    }
+
+    @Test func migratesLegacyRotationWithoutDeletingIt() throws {
+        let dir = try makeTempDirectory()
+        defer { try? FileManager.default.removeItem(at: dir) }
+        let appURL = dir.appendingPathComponent("app.log")
+        let legacyURL = appURL.appendingPathExtension("1")
+        try Data("legacy generation\n".utf8).write(to: legacyURL)
+
+        _ = AppLog(appFileURL: appURL, networkFileURL: nil, buildStamp: "test")
+
+        #expect(!FileManager.default.fileExists(atPath: legacyURL.path))
+        let generations = AppLog.logFileURLs(for: appURL)
+        #expect(generations.contains { (try? contents(of: $0).contains("legacy generation")) == true })
+    }
+
+    @Test func boundsTimestampedArchiveCount() async throws {
+        let dir = try makeTempDirectory()
+        defer { try? FileManager.default.removeItem(at: dir) }
+        let appURL = dir.appendingPathComponent("app.log")
+        let log = AppLog(
+            appFileURL: appURL,
+            networkFileURL: nil,
+            maxFileBytes: 160,
+            buildStamp: "test",
+            maxArchiveCount: 2,
+            maxRetainedBytes: 480
+        )
+
+        for index in 0..<100 {
+            log.mirrorAppLine("bounded line \(index) 0123456789")
+        }
+        try await waitForProcessed(log, 100)
+
+        let archives = AppLog.logFileURLs(for: appURL).filter { $0 != appURL }
+        #expect(archives.count <= 2)
+        #expect(!archives.isEmpty)
+        let totalBytes = AppLog.logFileURLs(for: appURL).reduce(0) { result, url in
+            let size = try? url.resourceValues(forKeys: [.fileSizeKey]).fileSize
+            return result + (size ?? 0)
+        }
+        #expect(totalBytes <= 480)
+    }
+
+    /// A failed size rotation (busy file, read-only directory) must append to
+    /// the existing log instead of truncating away diagnostics a user may be
+    /// about to share.
+    @Test func failedRotationAppendsInsteadOfTruncating() async throws {
+        let dir = try makeTempDirectory()
+        defer {
+            try? FileManager.default.setAttributes(
+                [.posixPermissions: 0o755],
+                ofItemAtPath: dir.path
+            )
+            try? FileManager.default.removeItem(at: dir)
+        }
+        let appURL = dir.appendingPathComponent("app.log")
+        try Data("previous-generation marker\n".utf8).write(to: appURL)
+        // A read-only parent makes the `.1` move fail while the existing
+        // file itself stays writable.
+        try FileManager.default.setAttributes(
+            [.posixPermissions: 0o555],
+            ofItemAtPath: dir.path
+        )
+
+        let log = AppLog(
+            appFileURL: appURL,
+            networkFileURL: nil,
+            maxFileBytes: 32,
+            buildStamp: "test"
+        )
+        log.mirrorAppLine("post-failure line 1")
+        log.mirrorAppLine("post-failure line 2")
+        log.mirrorAppLine("post-failure line 3")
+        try await waitForProcessed(log, 3)
+
+        try FileManager.default.setAttributes(
+            [.posixPermissions: 0o755],
+            ofItemAtPath: dir.path
+        )
+        let contents = try contents(of: appURL)
+        #expect(contents.contains("previous-generation marker"))
+        #expect(contents.contains("post-failure line 1"))
+        #expect(contents.contains("post-failure line 3"))
+        // The fallback appends no session header: a sustained rotate failure
+        // must not grow the file by one header per retried line.
+        #expect(!contents.contains("cmux app log"))
+        #expect(!FileManager.default.fileExists(
+            atPath: appURL.appendingPathExtension("1").path
+        ))
+    }
+
+    @Test func classificationCoversNetworkPlane() {
+        #expect(DiagnosticEventCode.transportDialFailed.appLogDomain == .network)
+        #expect(DiagnosticEventCode.transportDialPlanBuilt.appLogDomain == .network)
+        #expect(DiagnosticEventCode.transportPrivateAddressJoin.appLogDomain == .network)
+        #expect(DiagnosticEventCode.transportLANDiscovery.appLogDomain == .network)
+        #expect(DiagnosticEventCode.transportDialLegSucceeded.appLogDomain == .network)
+        #expect(DiagnosticEventCode.transportDialLegFailed.appLogDomain == .network)
+        #expect(DiagnosticEventCode.lanPublicationState.appLogDomain == .network)
+        #expect(DiagnosticEventCode.sessionClosed.appLogDomain == .network)
+        #expect(DiagnosticEventCode.discoveryFailed.appLogDomain == .network)
+        #expect(DiagnosticEventCode.relayPolicyRefreshFailed.appLogDomain == .network)
+        #expect(DiagnosticEventCode.simulatorInputLifecycle.appLogDomain == .app)
+        #expect(DiagnosticEventCode.browserStreamLifecycle.appLogDomain == .app)
+        #expect(DiagnosticEventCode.composerViewAppear.appLogDomain == .app)
+        #expect(DiagnosticEventCode.appFeatureAction.appLogDomain == .app)
+        #expect(DiagnosticEventCode.appLifecycleChanged.appLogDomain == .both)
+        #expect(DiagnosticEventCode.reachabilityChanged.appLogDomain == .both)
+    }
+}
@@ -4,6 +4,9 @@ import Testing

 private let compactIrohQRCoder = CmxAttachTicketCompactCoder()
 private let compactIrohQREndpointID = String(repeating: "c", count: 64)
+private let compactIrohQRTarget = CmxPairingURLScheme(
+    iOSBundleIdentifier: "dev.cmux.app.beta"
+)!

 private func compactIrohQRExpiry() -> Date {
    Date(timeIntervalSince1970: 4_000_000_000)
@@ -88,11 +91,12 @@ private func compactIrohQRHostPortRoute() throws -> CmxAttachRoute {
    #expect(hints.isEmpty)
    let pairingURL = try #require(CmxPairingQRCode().encode(
        ticket,
-        routeDisclosureMode: .irohIdentityOnly
+        routeDisclosureMode: .irohIdentityOnly,
+        pairingURLScheme: compactIrohQRTarget
    ))
    #expect(
        pairingURL
-            == "\(CmxPairingURLScheme.current)://attach?v=3&i=\(compactIrohQREndpointID)"
+            == "\(compactIrohQRTarget.rawValue)://attach?v=3&i=\(compactIrohQREndpointID)"
    )
    #expect(!pairingURL.contains("payload="))
    #expect(!pairingURL.contains("mac-1"))
@@ -105,19 +109,21 @@ private func compactIrohQRHostPortRoute() throws -> CmxAttachRoute {
        URLComponents(url: parsedURL, resolvingAgainstBaseURL: false)
    )
    let pairingDecoded = try CmxPairingQRCode().decode(components)
-    #expect(pairingDecoded.routes == [
-        try CmxAttachRoute(
-            id: "iroh",
-            kind: .iroh,
-            endpoint: .peer(
-                identity: CmxIrohPeerIdentity(endpointID: compactIrohQREndpointID),
-                pathHints: []
-            )
-        ),
-    ])
+    let expectedPairingRoute = try CmxAttachRoute(
+        id: "iroh",
+        kind: .iroh,
+        endpoint: .peer(
+            identity: CmxIrohPeerIdentity(endpointID: compactIrohQREndpointID),
+            pathHints: []
+        )
+    )
+    #expect(pairingDecoded.routes == [expectedPairingRoute])
    #expect(pairingDecoded.macDeviceID.isEmpty)
    #expect(pairingDecoded.macDisplayName == nil)
    #expect(pairingDecoded.macUserID == nil)
+    // Endpoint-only v3 codes intentionally omit compatibility metadata. Keep
+    // that absence distinguishable from an explicitly incompatible version.
+    #expect(pairingDecoded.macPairingCompatibilityVersion == nil)
    #expect(pairingDecoded.macAppVersion == nil)
    #expect(pairingDecoded.macAppBuild == nil)
    #expect(pairingDecoded.expiresAt == nil)
@@ -128,7 +134,7 @@ private func compactIrohQRHostPortRoute() throws -> CmxAttachRoute {
        .replacingOccurrences(of: "/", with: "_")
        .replacingOccurrences(of: "=", with: "")
    let beforeURL =
-        "\(CmxPairingURLScheme.current)://attach?v=1&payload=\(compactBase64)"
+        "\(compactIrohQRTarget.rawValue)://attach?v=1&payload=\(compactBase64)"
    let beforeImage = try #require(CmxPairingQRBitmap().makeImage(payload: beforeURL))
    let afterImage = try #require(CmxPairingQRBitmap().makeImage(payload: pairingURL))
    let quietZone = CmxPairingQRBitmap.quietZoneModules * 2
@@ -0,0 +1,197 @@
+import Foundation
+import Testing
+@testable import CMUXMobileCore
+
+@Suite
+struct CmxIrohConnectionCheckReportTests {
+    @Test
+    func mobileReportsReadyForAnAuthenticatedPrivateVPNPath() {
+        let report = CmxIrohConnectionCheckReport(
+            role: .mobileClient,
+            snapshot: snapshot(
+                runtimeStatus: .privateNetwork(displayName: ""),
+                selectedPath: .privateNetwork,
+                hasMac: true
+            ),
+            diagnostics: .empty,
+            relayReachability: .reachable,
+            macDiscovery: .found
+        )
+
+        #expect(report.isReady)
+        #expect(report.recommendation == .none)
+        #expect(report.stages.allSatisfy { $0.status == .passed })
+    }
+
+    @Test
+    func relayFailureExplainsCorporateNetworkAllowlisting() {
+        let report = CmxIrohConnectionCheckReport(
+            role: .mobileClient,
+            snapshot: snapshot(runtimeStatus: .active, hasMac: true),
+            diagnostics: diagnosticFailure(.timedOut),
+            relayReachability: .unreachable,
+            macDiscovery: .found
+        )
+
+        #expect(!report.isReady)
+        #expect(report.recommendation == .allowRelayTraffic)
+        #expect(report.stages.first { $0.kind == .relayReachability }?.status == .failed)
+    }
+
+    @Test
+    func relayConfigurationFailureTakesPriorityOverGenericAccountAdvice() {
+        let brokenRelaySnapshot = CmxIrohSettingsSnapshot(
+            runtimeStatus: .degraded,
+            preference: .automatic,
+            managedRelays: [],
+            customRelays: [],
+            policySource: .server,
+            failureDescription: "redacted relay configuration failure"
+        )
+        let report = CmxIrohConnectionCheckReport(
+            role: .macHost,
+            snapshot: brokenRelaySnapshot,
+            diagnostics: .empty,
+            relayReachability: .unavailable
+        )
+
+        #expect(report.recommendation == .reviewRelaySettings)
+    }
+
+    @Test
+    func missingMacIsDistinguishedFromAReachableRelay() {
+        let report = CmxIrohConnectionCheckReport(
+            role: .mobileClient,
+            snapshot: snapshot(runtimeStatus: .active),
+            diagnostics: .empty,
+            relayReachability: .reachable,
+            macDiscovery: .missing
+        )
+
+        #expect(report.recommendation == .openMacApp)
+        #expect(report.stages.first { $0.kind == .macDiscovery }?.status == .failed)
+    }
+
+    @Test
+    func unavailableRelayProbeFailsClosedWhileNoRelayConfigurationIsOptional() {
+        let unavailable = CmxIrohConnectionCheckReport(
+            role: .macHost,
+            snapshot: snapshot(runtimeStatus: .active),
+            diagnostics: .empty,
+            relayReachability: .unavailable
+        )
+        let notConfigured = CmxIrohConnectionCheckReport(
+            role: .macHost,
+            snapshot: snapshot(runtimeStatus: .active),
+            diagnostics: .empty,
+            relayReachability: .notConfigured
+        )
+
+        #expect(!unavailable.isReady)
+        #expect(
+            unavailable.stages.first { $0.kind == .relayReachability }?.status == .failed
+        )
+        #expect(unavailable.recommendation == .retry)
+        #expect(notConfigured.isReady)
+        #expect(
+            notConfigured.stages.first { $0.kind == .relayReachability }?.status
+                == .notApplicable
+        )
+    }
+
+    @Test
+    func administrativelyDisabledRelayFailsSessionWithRetryNotITAdvice() {
+        // Direct Only transport mode maps to a not-configured relay at the
+        // call sites: the relay stage reads Not Needed, and a dead direct
+        // path recommends retrying instead of contacting corporate IT.
+        let report = CmxIrohConnectionCheckReport(
+            role: .mobileClient,
+            snapshot: snapshot(runtimeStatus: .active, hasMac: true),
+            diagnostics: .empty,
+            relayReachability: .notConfigured,
+            macDiscovery: .found
+        )
+
+        #expect(
+            report.stages.first { $0.kind == .relayReachability }?.status == .notApplicable
+        )
+        #expect(report.stages.first { $0.kind == .secureSession }?.status == .failed)
+        #expect(report.recommendation == .retry)
+    }
+
+    @Test
+    func unavailableProbeNeverAdvisesCorporateAllowlisting() {
+        // An unavailable probe means the runtime was inactive or its path
+        // hints were unreadable, not that a relay was probed and blocked.
+        let inactiveRuntime = CmxIrohConnectionCheckReport(
+            role: .macHost,
+            snapshot: snapshot(runtimeStatus: .inactive),
+            diagnostics: .empty,
+            relayReachability: .unavailable
+        )
+
+        #expect(inactiveRuntime.recommendation == .refreshAccount)
+    }
+
+    @Test
+    func relayAllowlistOriginsRejectCredentialsAndNonRootURLs() {
+        #expect([
+            "https://relay.example.test/",
+            "https://relay.example.test",
+            "https://relay.example.test:443",
+            "https://user:[email protected]",
+            "https://relay.example.test/private",
+            "https://relay.example.test?token=secret",
+            "http://relay.example.test",
+        ].cmxIrohCanonicalRelayOrigins() == [
+            "https://relay.example.test",
+            "https://relay.example.test:443",
+        ])
+    }
+
+    @Test
+    func macReadinessDoesNotRequireAnActivePhoneSession() {
+        let report = CmxIrohConnectionCheckReport(
+            role: .macHost,
+            snapshot: snapshot(runtimeStatus: .active),
+            diagnostics: .empty,
+            relayReachability: .reachable
+        )
+
+        #expect(report.isReady)
+        #expect(report.stages.first { $0.kind == .secureSession }?.status == .notApplicable)
+    }
+
+    private func snapshot(
+        runtimeStatus: CmxIrohSettingsSnapshot.RuntimeStatus,
+        selectedPath: CmxIrohSelectedTransportPath = .unavailable,
+        hasMac: Bool = false
+    ) -> CmxIrohSettingsSnapshot {
+        CmxIrohSettingsSnapshot(
+            runtimeStatus: runtimeStatus,
+            selectedTransportPath: selectedPath,
+            preference: .automatic,
+            managedRelays: [],
+            customRelays: [],
+            privateNetworkMacs: hasMac ? [.init(id: "mac", displayName: "Mac")] : [],
+            policySource: .server
+        )
+    }
+
+    private func diagnosticFailure(_ kind: DiagnosticFailureKind) -> DiagnosticReport {
+        DiagnosticReport(
+            role: .mobileClient,
+            generatedAt: Date(timeIntervalSince1970: 1),
+            anchorWallNanos: 1,
+            anchorMonotonicNanos: 1,
+            events: [
+                DiagnosticEvent(
+                    code: .transportDialFailed,
+                    tNanos: 2,
+                    a: Int(DiagnosticTransportKind.iroh.rawValue),
+                    b: Int(kind.rawValue)
+                )
+            ]
+        )
+    }
+}
@@ -18,16 +18,22 @@ struct CmxIrohSettingsSnapshotTests {
        defaults.set("relayOnly", forKey: CmxIrohPathPreference.defaultsKey)
        #expect(CmxIrohPathPreference.stored(in: defaults) == .relayOnly)

+        defaults.set("neverUseRelays", forKey: CmxIrohPathPreference.defaultsKey)
+        #expect(CmxIrohPathPreference.stored(in: defaults) == .neverUseRelays)
+
        defaults.set("unknown", forKey: CmxIrohPathPreference.defaultsKey)
        #expect(CmxIrohPathPreference.stored(in: defaults) == .automatic)
    }

-    @Test func pathPreferenceMapsToTransportVerificationMode() {
+    @Test func retiredPathPreferencesNormalizeToAutomaticTransport() {
        #expect(
            CmxIrohPathPreference.automatic.transportVerificationMode == .automatic
        )
        #expect(
-            CmxIrohPathPreference.relayOnly.transportVerificationMode == .relayOnly
+            CmxIrohPathPreference.relayOnly.transportVerificationMode == .automatic
+        )
+        #expect(
+            CmxIrohPathPreference.neverUseRelays.transportVerificationMode == .directOnly
        )
    }

@@ -47,9 +53,18 @@ struct CmxIrohSettingsSnapshotTests {
            customRelays: [],
            policySource: .server
        )
+        let neverUseRelays = CmxIrohSettingsSnapshot(
+            runtimeStatus: .active,
+            preference: .automatic,
+            pathPreference: .neverUseRelays,
+            managedRelays: [],
+            customRelays: [],
+            policySource: .server
+        )

        #expect(automatic.pathPreference == .automatic)
        #expect(relayOnly.pathPreference == .relayOnly)
+        #expect(neverUseRelays.pathPreference == .neverUseRelays)
    }

    @Test
@@ -56,10 +56,12 @@ import Testing
            try tailscaleRoute(index: 0, host: "100.64.0.5"),
        ])
        let url = try #require(encodeLegacy(ticket))
-        // The scheme is channel-specific: a release Mac emits cmux-ios, a dev
-        // Mac emits cmux-ios-dev, so the system camera routes each channel's QR
-        // to its build. The rest of the URL is identical across channels.
-        #expect(url == "\(CmxPairingURLScheme.current)://attach?v=2&r=100.64.0.5:58465")
+        // The scheme is bundle-specific, so the system camera routes the QR to
+        // the matching installed iOS build. The rest of the URL is unchanged.
+        let scheme = try #require(
+            CmxPairingURLSchemeResolver().resolved?.rawValue
+        )
+        #expect(url == "\(scheme)://attach?v=2&r=100.64.0.5:58465")

        let decoded = try CmxPairingQRCode().decode(try components(url))
        #expect(decoded.routes == ticket.routes)
@@ -148,7 +150,10 @@ import Testing
        let ticket = try pairingTicket(routes: [loopback, tailscale])

        let url = try #require(encodeLegacy(ticket))
-        #expect(url == "\(CmxPairingURLScheme.current)://attach?v=2&r=100.64.0.5:58465")
+        let scheme = try #require(
+            CmxPairingURLSchemeResolver().resolved?.rawValue
+        )
+        #expect(url == "\(scheme)://attach?v=2&r=100.64.0.5:58465")
        let decoded = try CmxPairingQRCode().decode(try components(url))
        #expect(decoded.routes == [tailscale])
    }
@@ -2,52 +2,153 @@ import Foundation
 import Testing
@testable import CMUXMobileCore

-/// The pairing/attach URL scheme is channel-specific so the system Camera app
-/// can never hand a beta/prod QR to a dev build that also claimed the scheme:
-/// dev (Debug/tagged) builds register + emit `cmux-ios-dev`, Release (beta +
-/// prod) registers + emits `cmux-ios`. Parsers accept every channel's scheme so
-/// cross-channel pairing still works from inside the app.
+/// Every installed iOS bundle owns one pairing URL scheme. Parsers accept only
+/// schemes whose release or development lane can be classified for account
+/// preflight, while installed builds still register their exact bundle scheme.
@Suite struct CmxPairingURLSchemeTests {
-    @Test func developmentBuildsEmitDevScheme() {
-        #expect(CmxPairingURLScheme.scheme(isDevelopmentBuild: true) == "cmux-ios-dev")
+    @Test func everyInstalledBundleEmitsItsOwnScheme() {
+        #expect(
+            CmxPairingURLScheme(
+                iOSBundleIdentifier: "dev.cmux.app.internal"
+            )?.rawValue == "cmux-ios-dev.cmux.app.internal"
+        )
+        #expect(
+            CmxPairingURLScheme(
+                iOSBundleIdentifier: "dev.cmux.app.demo"
+            )?.rawValue == "cmux-ios-dev.cmux.app.demo"
+        )
+        #expect(
+            CmxPairingURLScheme(
+                iOSBundleIdentifier: "dev.cmux.ios.feature-a"
+            )?.rawValue == "cmux-ios-dev.cmux.ios.feature-a"
+        )
    }

-    @Test func releaseBuildsEmitReleaseScheme() {
-        #expect(CmxPairingURLScheme.scheme(isDevelopmentBuild: false) == "cmux-ios")
-    }
-
-    @Test func currentMatchesThisBuildsCompileChannel() {
-        // `current` derives from the DEBUG compile flag, so a Debug test run
-        // emits the dev scheme and a Release test run emits the release scheme.
-        #if DEBUG
-        #expect(CmxPairingURLScheme.current == "cmux-ios-dev")
-        #else
-        #expect(CmxPairingURLScheme.current == "cmux-ios")
+    @Test func invalidIdentityDoesNotFallBackToAnotherApp() {
+        #expect(CmxPairingURLScheme(iOSBundleIdentifier: "") == nil)
+        #expect(CmxPairingURLScheme(iOSBundleIdentifier: "invalid bundle") == nil)
+        #expect(
+            CmxPairingURLScheme(
+                iOSBundleIdentifier: "dev.cmux.app.unrecognized"
+            ) == nil
+        )
+        #if !os(iOS)
+        #expect(
+            CmxPairingURLSchemeResolver(
+                currentIOSBundleIdentifier: nil,
+                targetIOSBundleIdentifier: nil,
+                macInstanceTag: "invalid tag",
+                isDevelopmentBuild: true
+            ).resolved == nil
+        )
        #endif
    }

-    @Test func parserAcceptsEverySchemeRegardlessOfChannel() {
-        // Both channels' schemes parse, case-insensitively, so a phone on
-        // either channel can pair from a QR minted by either channel's Mac.
-        #expect(CmxPairingURLScheme.isPairingScheme("cmux-ios"))
-        #expect(CmxPairingURLScheme.isPairingScheme("cmux-ios-dev"))
-        #expect(CmxPairingURLScheme.isPairingScheme("CMUX-IOS-DEV"))
+    #if !os(iOS)
+    @Test func untaggedDebugMacTargetsDefaultDebugIOSBundle() {
+        #if DEBUG
+        #expect(
+            CmxPairingURLSchemeResolver(
+                currentIOSBundleIdentifier: nil,
+                targetIOSBundleIdentifier: nil,
+                macInstanceTag: nil,
+                isDevelopmentBuild: true
+            ).resolved?.rawValue == "cmux-ios-dev.cmux.ios"
+        )
+        #endif
+    }
+
+    @Test func untaggedMacBuildChannelsResolveDistinctExactBundles() {
+        #expect(
+            CmxPairingURLSchemeResolver(
+                currentIOSBundleIdentifier: nil,
+                targetIOSBundleIdentifier: nil,
+                macInstanceTag: nil,
+                isDevelopmentBuild: true
+            ).resolved?.rawValue == "cmux-ios-dev.cmux.ios"
+        )
+        #expect(
+            CmxPairingURLSchemeResolver(
+                currentIOSBundleIdentifier: nil,
+                targetIOSBundleIdentifier: nil,
+                macInstanceTag: nil,
+                isDevelopmentBuild: false
+            ).resolved?.rawValue == "cmux-ios-com.cmux.app"
+        )
+    }
+
+    @Test func macCanExplicitlyTargetEveryReleaseLane() {
+        for bundleIdentifier in [
+            "com.cmux.app",
+            "dev.cmux.app.beta",
+            "dev.cmux.app.internal",
+            "dev.cmux.app.demo",
+        ] {
+            #expect(
+                CmxPairingURLSchemeResolver(
+                    currentIOSBundleIdentifier: nil,
+                    targetIOSBundleIdentifier: bundleIdentifier,
+                    macInstanceTag: nil,
+                    isDevelopmentBuild: false
+                ).resolved?.rawValue
+                    == "cmux-ios-\(bundleIdentifier)"
+            )
+        }
+    }
+    #endif
+
+    @Test func parserAcceptsNamespacedSchemes() {
+        #expect(CmxPairingURLScheme(rawValue: "cmux-ios-dev.cmux.app.internal") != nil)
+        #expect(CmxPairingURLScheme(rawValue: "cmux-ios-dev.cmux.app.demo") != nil)
+        #expect(CmxPairingURLScheme(rawValue: "CMUX-IOS-DEV.CMUX.IOS.FEATURE-A") != nil)
+        // Old QR codes remain scannable inside an already-open app. New builds
+        // do not register these shared schemes with iOS.
+        #expect(CmxPairingURLScheme(rawValue: "cmux-ios") != nil)
+        #expect(CmxPairingURLScheme(rawValue: "cmux-ios-dev") != nil)
    }

    @Test func parserRejectsForeignSchemes() {
-        #expect(!CmxPairingURLScheme.isPairingScheme(nil))
-        #expect(!CmxPairingURLScheme.isPairingScheme(""))
-        #expect(!CmxPairingURLScheme.isPairingScheme("https"))
-        // A different cmux scheme that is not a pairing scheme must not match.
-        #expect(!CmxPairingURLScheme.isPairingScheme("cmux-ios-staging"))
+        #expect(CmxPairingURLScheme(rawValue: nil) == nil)
+        #expect(CmxPairingURLScheme(rawValue: "") == nil)
+        #expect(CmxPairingURLScheme(rawValue: "https") == nil)
+        #expect(CmxPairingURLScheme(rawValue: "cmux-ios-*") == nil)
    }

-    @Test func prefixCheckAcceptsBothChannelsAndRejectsOthers() {
-        #expect(CmxPairingURLScheme.hasPairingScheme("cmux-ios://attach?v=2&r=100.64.0.5:58465"))
-        #expect(CmxPairingURLScheme.hasPairingScheme("cmux-ios-dev://attach?v=2&r=100.64.0.5:58465"))
-        #expect(CmxPairingURLScheme.hasPairingScheme("CMUX-IOS://attach?v=2"))
-        #expect(!CmxPairingURLScheme.hasPairingScheme("https://example.com"))
-        // A bare scheme name without "://" is not a deep link.
-        #expect(!CmxPairingURLScheme.hasPairingScheme("cmux-ios"))
+    @Test func channelClassificationRecognizesOnlyAuthoritativeLanes() throws {
+        for bundleIdentifier in [
+            "com.cmux.app",
+            "dev.cmux.app.beta",
+            "dev.cmux.app.internal",
+            "dev.cmux.app.demo",
+        ] {
+            let scheme = try #require(
+                CmxPairingURLScheme(
+                    iOSBundleIdentifier: bundleIdentifier
+                )
+            )
+            #expect(scheme.isRelease)
+            #expect(!scheme.isDevelopment)
+        }
+        let development = try #require(
+            CmxPairingURLScheme(
+                iOSBundleIdentifier: "dev.cmux.ios.feature-a"
+            )
+        )
+        #expect(development.isDevelopment)
+        #expect(!development.isRelease)
+        #expect(CmxPairingURLScheme(rawValue: "cmux-ios-dev.cmux.app.unrecognized") == nil)
+    }
+
+    @Test func prefixCheckAcceptsNamespacedSchemesAndRejectsOthers() {
+        #expect(CmxPairingURLScheme(urlString:
+            "cmux-ios-dev.cmux.app.internal://attach?v=2&r=100.64.0.5:58465"
+        ) != nil)
+        #expect(CmxPairingURLScheme(urlString:
+            "CMUX-IOS-DEV.CMUX.IOS.FEATURE-A://attach?v=2"
+        ) != nil)
+        #expect(CmxPairingURLScheme(urlString: "cmux-ios://attach?v=2") != nil)
+        #expect(CmxPairingURLScheme(urlString: "cmux-ios-dev://attach?v=2") != nil)
+        #expect(CmxPairingURLScheme(urlString: "https://example.com") == nil)
+        #expect(CmxPairingURLScheme(urlString: "cmux-ios-dev.cmux.app.internal") == nil)
    }
 }
--- a/Show More
+++ b/Show More
				`@@ -0,0 +1 @@`
				`"CFBundleDisplayName" = "ピン留めラボ";`