From 5cccceb4f69feb227a6ffd4cfb00b27f2f46c9bb Mon Sep 17 00:00:00 2001
From: Jer Miller <jeremie.miller@gmail.com>
Date: Mon, 27 Jul 2026 22:46:45 -0600
Subject: [PATCH] refactor(link): retire Python caller CLI

Remove the caller-side Python sol link modules now that join and serve dispatch natively. The solstone.think.link package remains for home-side modules, but it no longer re-exports a caller CLI entry point and the compat inventory drops only the link line.

Remove journal link from the journal-host command surface and its generated command expectations. This is a real user-visible removal, not cleanup; expected-differs.

Delete the caller-side link CLI tests with the retired modules, relocate the CSR helper into the surviving certless test helpers, and repair the remaining TLS and pairing tests without compatibility shims.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../build_native_sol_journal_host_commands.py |    2 +-
 solstone/think/link/__init__.py               |   12 +-
 solstone/think/link/__main__.py               |    9 -
 solstone/think/link/cli.py                    |   46 -
 solstone/think/link/direct_admission.py       |   33 -
 solstone/think/link/join_cli.py               |  983 ---------------
 solstone/think/link/observer_paths.py         |   19 -
 solstone/think/link/serve_cli.py              |  420 -------
 solstone/think/sol_cli.py                     |    1 -
 solstone/think/sol_compat_inventory.py        |    1 -
 tests/link/certless_helpers.py                |  387 +++++-
 tests/link/test_certless_pair.py              |    4 +-
 tests/link/test_direct_admission.py           |   55 -
 tests/link/test_link_cli_namespace.py         |  101 --
 tests/link/test_link_join_existing_dir.py     |  155 ---
 tests/link/test_link_join_label_validation.py |   87 --
 tests/link/test_link_join_observer.py         |   65 -
 tests/link/test_link_join_pairing.py          | 1115 -----------------
 .../link/test_link_join_peer_existing_dir.py  |  128 --
 tests/link/test_link_join_peer_happy.py       |  102 --
 ...t_link_join_peer_instance_id_validation.py |  119 --
 .../test_link_join_peer_sends_instance_id.py  |    4 -
 tests/link/test_link_join_publication.py      |   92 --
 tests/link/test_link_join_refusals.py         |  235 ----
 tests/link/test_link_join_relay.py            |  309 -----
 tests/link/test_link_serve.py                 |  441 -------
 .../link/test_secure_listener_pairing_e2e.py  |   35 +-
 tests/link/test_tls_contexts.py               |    6 +-
 tests/spl/test_service.py                     |   10 -
 .../test_native_sol_journal_host_commands.py  |    6 +-
 30 files changed, 418 insertions(+), 4564 deletions(-)
 delete mode 100644 solstone/think/link/__main__.py
 delete mode 100644 solstone/think/link/cli.py
 delete mode 100644 solstone/think/link/direct_admission.py
 delete mode 100644 solstone/think/link/join_cli.py
 delete mode 100644 solstone/think/link/observer_paths.py
 delete mode 100644 solstone/think/link/serve_cli.py
 delete mode 100644 tests/link/test_direct_admission.py
 delete mode 100644 tests/link/test_link_cli_namespace.py
 delete mode 100644 tests/link/test_link_join_existing_dir.py
 delete mode 100644 tests/link/test_link_join_label_validation.py
 delete mode 100644 tests/link/test_link_join_observer.py
 delete mode 100644 tests/link/test_link_join_pairing.py
 delete mode 100644 tests/link/test_link_join_peer_existing_dir.py
 delete mode 100644 tests/link/test_link_join_peer_happy.py
 delete mode 100644 tests/link/test_link_join_peer_instance_id_validation.py
 delete mode 100644 tests/link/test_link_join_peer_sends_instance_id.py
 delete mode 100644 tests/link/test_link_join_publication.py
 delete mode 100644 tests/link/test_link_join_refusals.py
 delete mode 100644 tests/link/test_link_join_relay.py
 delete mode 100644 tests/link/test_link_serve.py

diff --git a/scripts/build_native_sol_journal_host_commands.py b/scripts/build_native_sol_journal_host_commands.py
index ed9519fc6..7f1e977ae 100644
--- a/scripts/build_native_sol_journal_host_commands.py
+++ b/scripts/build_native_sol_journal_host_commands.py
@@ -15,7 +15,7 @@ OUTPUT = (
     REPO_ROOT / "core/crates/solstone-core-sol/src/generated/journal_host_commands.rs"
 )
 EXPECTED_SERVICE_COMMANDS_COUNT = 42
-EXPECTED_UNIVERSAL_COMMANDS = frozenset({"doctor", "check", "contract", "link"})
+EXPECTED_UNIVERSAL_COMMANDS = frozenset({"doctor", "check", "contract"})
 EXPECTED_SERVICE_ALIASES = frozenset({"up", "down"})
 EXPECTED_UNIVERSAL_ALIASES = frozenset()
 SERVICE_SENTINELS = frozenset({"think", "setup"})
diff --git a/solstone/think/link/__init__.py b/solstone/think/link/__init__.py
index ec2406492..82a0ffffd 100644
--- a/solstone/think/link/__init__.py
+++ b/solstone/think/link/__init__.py
@@ -1,15 +1,11 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 # Copyright (c) 2026 sol pbc
 
-"""Caller-side link commands and shared pairing/runtime helpers.
+"""Shared private-link pairing/runtime helpers.
 
-`sol link` dispatches caller-side commands such as `join` and `serve`. The
-supervised home-side spl rendezvous daemon lives in `solstone.think.spl` and
-runs as `journal spl`.
+Public caller-side `sol link` commands are native. This package still owns
+home-side and shared link state, pairing, tunnel, and runtime helpers used by
+Convey, observe, and SPL.
 """
 
 __version__ = "0.1.0"
-
-from .cli import main  # noqa: E402 — re-exported so `sol link` can import it
-
-__all__ = ["main"]
diff --git a/solstone/think/link/__main__.py b/solstone/think/link/__main__.py
deleted file mode 100644
index c868068d6..000000000
--- a/solstone/think/link/__main__.py
+++ /dev/null
@@ -1,9 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright (c) 2026 sol pbc
-
-"""python -m solstone.think.link — entry point for caller-side `sol link`."""
-
-from solstone.think.link.cli import main
-
-if __name__ == "__main__":
-    raise SystemExit(main())
diff --git a/solstone/think/link/cli.py b/solstone/think/link/cli.py
deleted file mode 100644
index df357f77f..000000000
--- a/solstone/think/link/cli.py
+++ /dev/null
@@ -1,46 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright (c) 2026 sol pbc
-
-"""Caller-side `sol link` command namespace."""
-
-from __future__ import annotations
-
-import argparse
-import sys
-
-from solstone.think.link import join_cli, serve_cli
-
-
-def _build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(description="solstone link access commands")
-    subparsers = parser.add_subparsers(
-        dest="command",
-        metavar="{join,serve}",
-        title="commands",
-    )
-    join_parser = subparsers.add_parser(
-        "join",
-        help="join a solstone with a short code or pair link",
-    )
-    join_cli.add_arguments(join_parser)
-    serve_parser = subparsers.add_parser(
-        "serve",
-        help="serve a loopback proxy over a link tunnel",
-    )
-    serve_cli.add_arguments(serve_parser)
-    return parser
-
-
-def main(argv: list[str] | None = None) -> int:
-    """CLI entry point for `sol link`."""
-    args = list(sys.argv[1:] if argv is None else argv)
-    parser = _build_parser()
-    namespace = parser.parse_args(args)
-    if namespace.command is None:
-        parser.print_help()
-        return 0
-    if namespace.command == "join":
-        return join_cli.main(namespace)
-    if namespace.command == "serve":
-        return serve_cli.main(namespace)
-    return 0
diff --git a/solstone/think/link/direct_admission.py b/solstone/think/link/direct_admission.py
deleted file mode 100644
index 92227a177..000000000
--- a/solstone/think/link/direct_admission.py
+++ /dev/null
@@ -1,33 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright (c) 2026 sol pbc
-
-"""Direct pair-link consumer address admission.
-
-This is deliberately not shared with ``pairing.config.is_usable_ipv4`` or
-``interface_watcher._classify``. Those modules decide what the home should
-advertise from configured or observed interface state; this module decides what
-the joining process will dial from an operator-pasted direct pair-link. The
-authoritative allow-list is ``DIRECT_PAIR_ALLOWED_NETWORKS``.
-"""
-
-from __future__ import annotations
-
-import ipaddress
-
-DIRECT_PAIR_ALLOWED_NETWORKS: tuple[ipaddress.IPv4Network, ...] = (
-    ipaddress.IPv4Network("10.0.0.0/8"),
-    ipaddress.IPv4Network("172.16.0.0/12"),
-    ipaddress.IPv4Network("192.168.0.0/16"),
-    ipaddress.IPv4Network("169.254.0.0/16"),
-    ipaddress.IPv4Network("100.64.0.0/10"),
-    ipaddress.IPv4Network("127.0.0.0/8"),
-)
-
-
-def is_direct_pair_candidate_allowed(ipv4: ipaddress.IPv4Address) -> bool:
-    """Return whether a decoded direct pair-link IPv4 candidate may be dialed."""
-
-    return any(ipv4 in network for network in DIRECT_PAIR_ALLOWED_NETWORKS)
-
-
-__all__ = ["DIRECT_PAIR_ALLOWED_NETWORKS", "is_direct_pair_candidate_allowed"]
diff --git a/solstone/think/link/join_cli.py b/solstone/think/link/join_cli.py
deleted file mode 100644
index c59e6dabf..000000000
--- a/solstone/think/link/join_cli.py
+++ /dev/null
@@ -1,983 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright (c) 2026 sol pbc
-
-"""Caller-side `sol link join` implementation.
-
-The direct pair-link forms (0x04 and 0x05) decode to an ordered set of local
-candidate endpoints that share one nonce and one CA-cert-DER pin. The whole
-embedded set must satisfy `direct_admission` before key generation or dialing;
-`--home`, when supplied, is only the operator-chosen dial override after that
-structural and policy check and may legitimately name a host instead of an
-IPv4 address. The selected target receives one framed mTLS POST to
-`/app/network/pair?token=<nonce>`. The request invocation is the commit point:
-once it starts, no later candidate is tried.
-
-The relay pair-window form (0x06) dials the relay, then runs the same inner
-pairing request through the pinned TLS tunnel.
-
-Role-less linked-system credentials are written under
-`$XDG_CONFIG_HOME/solstone-observer/spl/<label>/` when XDG_CONFIG_HOME is set,
-otherwise `~/.config/solstone-observer/spl/<label>/`.
-
-Peer credentials are written under `<journal_root>/peers/<instance_id>/`,
-where `instance_id` is the receiver instance_id returned by the pair response,
-not the local `--label`. Label-to-instance_id resolution for
-`journal transfer send --to <label>` is a follow-on lode that will walk
-`peer.json` files.
-
-Both layouts contain `private.pem`, `cert.pem`, `chain.pem`,
-`home_attestation.jwt`, and `peer.json`. `peer.json` fields are deterministic:
-`label`, `paired_at`, `instance_id`, `home_label`, `fingerprint`,
-`local_endpoints`, and `role`; role is `peer` or `""` for role-less linked
-systems. `peer` is provenance, not a behavioral authorization role: pairing a
-peer provisions a journal-content source, records the sender `instance_id`, and
-leaves durable in-data provenance through per-segment `sender_instance_id` /
-`sender_fingerprint` and identity-derived source directories.
-"""
-
-from __future__ import annotations
-
-import argparse
-import asyncio
-import contextlib
-import datetime as dt
-import hashlib
-import ipaddress
-import json
-import os
-import re
-import shutil
-import socket
-import sys
-import tempfile
-import urllib.parse
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Any
-
-import websockets
-from cryptography import x509
-from cryptography.exceptions import InvalidSignature
-from cryptography.hazmat.primitives import hashes, serialization
-from cryptography.hazmat.primitives.asymmetric import ec
-from cryptography.x509.oid import NameOID
-from websockets.exceptions import InvalidStatus
-
-from solstone.apps.network.crockford32 import decode as crockford_decode
-from solstone.apps.network.relay_link import decode_pair_window_link, derive_rk
-from solstone.think.link.auth import is_peer
-from solstone.think.link.ca import ca_pin_matches
-from solstone.think.link.client import (
-    _CONNECT_TIMEOUT_SECONDS,
-    _HTTP_TIMEOUT_SECONDS,
-    Client,
-    ClientIdentity,
-    StreamResetError,
-    TunnelSession,
-    _open_pairing_session,
-    _TcpEncryptedTransport,
-    _to_ws,
-    _WsEncryptedTransport,
-)
-from solstone.think.link.direct_admission import is_direct_pair_candidate_allowed
-from solstone.think.link.mark import jid_from_spki
-from solstone.think.link.observer_paths import observer_bundle_dir
-from solstone.think.link.paths import DEFAULT_RELAY_URL, LinkState
-from solstone.think.link.tls import TlsError
-from solstone.think.utils import get_journal
-
-VALID_ROLES = {"", "phone", "observer", "peer"}
-LABEL_RE = re.compile(r"^[A-Za-z0-9_.-]+$")
-DEFAULT_CLIENT_LABEL = "linked-system"
-BUNDLE_FILES = {
-    "private.pem",
-    "cert.pem",
-    "chain.pem",
-    "home_attestation.jwt",
-    "peer.json",
-}
-_INSTANCE_ID_RE = re.compile(r"^[A-Za-z0-9-]{1,256}$")
-
-
-@dataclass(frozen=True)
-class DirectPairCandidate:
-    ip: ipaddress.IPv4Address
-    port: int
-
-    @property
-    def host(self) -> str:
-        return str(self.ip)
-
-
-@dataclass(frozen=True)
-class DirectPairRequest:
-    candidates: tuple[DirectPairCandidate, ...]
-    path: str
-    ca_fingerprint_pin: str
-    home: str | None = None
-
-
-@dataclass(frozen=True)
-class PairTarget:
-    host: str
-    port: int
-    path: str
-
-
-@dataclass(frozen=True)
-class RelayPairRequest:
-    relay_endpoint: str
-    rk: bytes
-    s: bytes
-    ca_fp_spki: bytes
-    inner_path: str
-
-
-@dataclass(frozen=True)
-class PairResponse:
-    client_cert: str
-    ca_chain: list[str]
-    instance_id: str
-    home_label: str
-    home_attestation: str
-    local_endpoints: list[Any]
-
-
-def add_arguments(parser: argparse.ArgumentParser) -> None:
-    parser.add_argument("--home", help="Receiver base URL")
-    parser.add_argument("--code", required=True, help="pair-link URL")
-    parser.add_argument("--as", dest="as_role", help="Optional tag to join as")
-    parser.add_argument(
-        "--label",
-        required=False,
-        default=None,
-        help="Local credentials label (defaults to this machine's hostname)",
-    )
-
-
-def main(args: argparse.Namespace) -> int:
-    as_role = args.as_role or ""
-    if as_role not in VALID_ROLES:
-        return _fail("invalid role; expected one of: phone, observer, peer", code=2)
-
-    if args.label is not None:
-        label = str(args.label)
-        label_error = _label_error(label)
-        if label_error is not None:
-            return _fail(label_error, code=2)
-    else:
-        label = _hostname_client_label()
-
-    try:
-        pair_request = _parse_pair_request(str(args.code).strip(), args.home)
-    except ValueError as exc:
-        return _fail(str(exc), code=1)
-
-    if isinstance(pair_request, RelayPairRequest):
-        return _join_via_relay(pair_request, label, as_role)
-
-    if is_peer(as_role):
-        private_key, private_key_pem, csr_pem = _build_csr(label)
-        body = {
-            "csr": csr_pem,
-            "device_label": label,
-        }
-        body["sender_instance_id"] = LinkState.load_or_create().instance_id
-        try:
-            response = _post_pair(pair_request, body, private_key)
-        except ValueError as exc:
-            return _fail(str(exc), code=1)
-        instance_id_error = _validate_instance_id(response.instance_id)
-        if instance_id_error is not None:
-            return _fail(instance_id_error, code=1)
-        bundle_dir = _peer_dir(response.instance_id)
-        existing_error = _existing_path_error(bundle_dir)
-        if existing_error is not None:
-            return _fail(existing_error, code=1)
-    else:
-        bundle_dir = observer_bundle_dir(label)
-        existing_error = _existing_path_error(bundle_dir)
-        if existing_error is not None:
-            return _fail(existing_error, code=1)
-
-        private_key, private_key_pem, csr_pem = _build_csr(label)
-        body = {
-            "csr": csr_pem,
-            "device_label": label,
-        }
-        try:
-            response = _post_pair(pair_request, body, private_key)
-        except ValueError as exc:
-            return _fail(str(exc), code=1)
-
-    chain_pem = _join_chain(response.ca_chain)
-    try:
-        ca_fp = _ca_fingerprint(chain_pem)
-    except ValueError as exc:
-        return _fail(str(exc), code=1)
-
-    peer = {
-        "label": label,
-        "paired_at": dt.datetime.now(dt.UTC).strftime("%Y-%m-%dT%H:%M:%SZ"),
-        "instance_id": response.instance_id,
-        "home_label": response.home_label,
-        "fingerprint": ca_fp,
-        "local_endpoints": response.local_endpoints,
-        "role": "peer" if is_peer(as_role) else "",
-    }
-    files = {
-        "private.pem": private_key_pem,
-        "cert.pem": response.client_cert.encode("utf-8"),
-        "chain.pem": chain_pem.encode("utf-8"),
-        "home_attestation.jwt": response.home_attestation.encode("utf-8"),
-        "peer.json": (json.dumps(peer, indent=2) + "\n").encode("utf-8"),
-    }
-    try:
-        _publish_bundle_atomic(bundle_dir, files)
-    except OSError as exc:
-        return _fail(str(exc), code=1)
-
-    suffix = " as peer" if is_peer(as_role) else ""
-    print(f"Linked {label}{suffix}.")
-    print(f"Credentials: {bundle_dir}")
-    return 0
-
-
-def _parse_pair_request(
-    code: str,
-    home: str | None,
-) -> DirectPairRequest | RelayPairRequest:
-    from solstone.apps.network.copy import PAIR_LINK_HOST, PAIR_LINK_PATH
-
-    if code.startswith(f"https://{PAIR_LINK_HOST}{PAIR_LINK_PATH}#"):
-        return _parse_pair_link(code, home)
-    raise ValueError(
-        f"Pair code did not match an accepted form. Use a pair-link like "
-        f"https://{PAIR_LINK_HOST}{PAIR_LINK_PATH}#... from 'sol call link pair'."
-    )
-
-
-def _parse_pair_link(
-    pair_link: str, home: str | None
-) -> DirectPairRequest | RelayPairRequest:
-
-    parsed = urllib.parse.urlparse(pair_link)
-    fragment = parsed.fragment
-    try:
-        blob = crockford_decode(fragment)
-    except ValueError as exc:
-        raise ValueError(_malformed_pair_link_message()) from exc
-    if not blob:
-        raise ValueError(_malformed_pair_link_message())
-    if blob[0] == 0x06:
-        return _parse_relay_pair_link(pair_link)
-    candidates, nonce_hex, ca_fingerprint_pin = _decode_direct_pair_blob(blob)
-    _check_direct_candidate_policy(candidates)
-    return DirectPairRequest(
-        candidates=candidates,
-        path=_direct_pair_path(nonce_hex),
-        ca_fingerprint_pin=ca_fingerprint_pin,
-        home=home.rstrip("/") if home else None,
-    )
-
-
-def _malformed_pair_link_message() -> str:
-    from solstone.apps.network.copy import PAIR_LINK_HOST, PAIR_LINK_PATH
-
-    return (
-        f"Malformed pair-link. Use the full "
-        f"https://{PAIR_LINK_HOST}{PAIR_LINK_PATH}#... value from the pairing "
-        f"output."
-    )
-
-
-def _decode_direct_pair_blob(
-    blob: bytes,
-) -> tuple[tuple[DirectPairCandidate, ...], str, str]:
-    if len(blob) < 2 or blob[0] not in {0x04, 0x05} or blob[1] != 0x01:
-        raise ValueError(_malformed_pair_link_message())
-
-    version = blob[0]
-    if version == 0x04:
-        if len(blob) != 40:
-            raise ValueError(_malformed_pair_link_message())
-        port = int.from_bytes(blob[6:8], "big")
-        nonce_hex = blob[8:24].hex()
-        ca_fingerprint_pin = blob[24:40].hex()
-        return (
-            (DirectPairCandidate(ipaddress.IPv4Address(blob[2:6]), port),),
-            nonce_hex,
-            ca_fingerprint_pin,
-        )
-
-    if len(blob) < 5:
-        raise ValueError(_malformed_pair_link_message())
-    count = blob[2]
-    if count < 1 or count > 4:
-        raise ValueError(_malformed_pair_link_message())
-    expected_len = 37 + 4 * count
-    if len(blob) != expected_len:
-        raise ValueError(_malformed_pair_link_message())
-    port = int.from_bytes(blob[3:5], "big")
-    address_start = 5
-    address_end = address_start + 4 * count
-    candidates = tuple(
-        DirectPairCandidate(ipaddress.IPv4Address(blob[offset : offset + 4]), port)
-        for offset in range(address_start, address_end, 4)
-    )
-    nonce_hex = blob[address_end : address_end + 16].hex()
-    ca_fingerprint_pin = blob[address_end + 16 : address_end + 32].hex()
-    return candidates, nonce_hex, ca_fingerprint_pin
-
-
-def _check_direct_candidate_policy(
-    candidates: tuple[DirectPairCandidate, ...],
-) -> None:
-    if all(is_direct_pair_candidate_allowed(candidate.ip) for candidate in candidates):
-        return
-    raise ValueError(
-        "Pair-link points at an address outside the local network this joiner will dial."
-    )
-
-
-def _direct_pair_path(nonce_hex: str) -> str:
-    return f"/app/network/pair?token={nonce_hex}"
-
-
-def _parse_relay_pair_link(pair_link: str) -> RelayPairRequest:
-    parsed = decode_pair_window_link(pair_link)
-    relay_endpoint = parsed.relay_origin or DEFAULT_RELAY_URL
-    return RelayPairRequest(
-        relay_endpoint=relay_endpoint,
-        rk=derive_rk(parsed.s),
-        s=parsed.s,
-        ca_fp_spki=parsed.ca_fp_spki,
-        inner_path=f"/app/network/pair?token={parsed.s.hex()}",
-    )
-
-
-def _label_error(label: str) -> str | None:
-    if not label:
-        return "--label must not be empty"
-    if len(label) > 80:
-        return "--label must be 80 characters or fewer"
-    if "/" in label or "\\" in label:
-        return "--label must not contain path separators"
-    if ".." in label:
-        return "--label must not contain '..'"
-    if label.startswith("."):
-        return "--label must not start with '.'"
-    if not LABEL_RE.fullmatch(label):
-        return "--label may contain only letters, numbers, '-', '_', and '.'"
-    return None
-
-
-def _sanitize_client_label(raw: str) -> str:
-    if not re.search(r"[A-Za-z0-9_.-]", raw):
-        return ""
-    label = re.sub(r"[^A-Za-z0-9_.-]", "-", raw)
-    label = re.sub(r"\.{2,}", "-", label)
-    label = label.lstrip(".")[:80]
-    if not label or _label_error(label) is not None:
-        return ""
-    return label
-
-
-def _hostname_client_label() -> str:
-    try:
-        raw = socket.gethostname()
-    except OSError:
-        raw = ""
-    return _sanitize_client_label(raw) or DEFAULT_CLIENT_LABEL
-
-
-def _validate_instance_id(value: str) -> str | None:
-    if not _INSTANCE_ID_RE.fullmatch(value):
-        return f"bad instance_id from receiver: {value!r}"
-    return None
-
-
-def _peer_dir(instance_id: str) -> Path:
-    return Path(get_journal()) / "peers" / instance_id
-
-
-def _existing_path_error(bundle_dir: Path) -> str | None:
-    if not os.path.lexists(bundle_dir):
-        return None
-    return (
-        f"Credentials path already exists: {bundle_dir}. "
-        "Remove it and rerun if re-pairing."
-    )
-
-
-def _build_csr(label: str) -> tuple[ec.EllipticCurvePrivateKey, bytes, str]:
-    private_key = ec.generate_private_key(ec.SECP256R1())
-    csr = (
-        x509.CertificateSigningRequestBuilder()
-        .subject_name(x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, label[:64])]))
-        .sign(private_key, hashes.SHA256())
-    )
-    private_key_pem = private_key.private_bytes(
-        serialization.Encoding.PEM,
-        serialization.PrivateFormat.PKCS8,
-        serialization.NoEncryption(),
-    )
-    csr_pem = csr.public_bytes(serialization.Encoding.PEM).decode("ascii")
-    return private_key, private_key_pem, csr_pem
-
-
-def _post_pair(
-    pair_request: DirectPairRequest,
-    body: dict[str, str],
-    private_key: ec.EllipticCurvePrivateKey,
-) -> PairResponse:
-    return _post_pair_framed(pair_request, body, private_key)
-
-
-def _join_via_relay(req: RelayPairRequest, label: str, as_role: str) -> int:
-    # Keep the relay orchestration isolated instead of refactoring the working
-    # direct path: both tails intentionally mirror the same bundle contract.
-    _private_key, private_key_pem, csr_pem = _build_csr(label)
-    body: dict[str, str] = {"csr": csr_pem, "device_label": label}
-    if is_peer(as_role):
-        body["sender_instance_id"] = LinkState.load_or_create().instance_id
-
-    try:
-        response = _post_pair_relay(req, body)
-    except ValueError as exc:
-        return _fail(str(exc), code=1)
-
-    if is_peer(as_role):
-        instance_id_error = _validate_instance_id(response.instance_id)
-        if instance_id_error is not None:
-            return _fail(instance_id_error, code=1)
-        bundle_dir = _peer_dir(response.instance_id)
-    else:
-        bundle_dir = observer_bundle_dir(label)
-    existing_error = _existing_path_error(bundle_dir)
-    if existing_error is not None:
-        return _fail(existing_error, code=1)
-
-    chain_pem = _join_chain(response.ca_chain)
-    try:
-        ca_fp = _ca_fingerprint(chain_pem)
-    except ValueError as exc:
-        return _fail(str(exc), code=1)
-
-    identity = ClientIdentity(
-        private_key_pem=private_key_pem.decode("ascii"),
-        client_cert_pem=response.client_cert,
-        ca_chain_pem=chain_pem,
-        fingerprint=ca_fp,
-        home_instance_id=response.instance_id,
-        home_label=response.home_label,
-        home_attestation=response.home_attestation,
-        local_endpoints=tuple(response.local_endpoints),
-    )
-    try:
-        Client.enroll_device(req.relay_endpoint, identity)
-    except Exception as exc:  # noqa: BLE001 - fail loudly on any enroll rejection.
-        return _fail(f"Relay rejected device enrollment: {exc}", code=1)
-
-    peer = {
-        "label": label,
-        "paired_at": dt.datetime.now(dt.UTC).strftime("%Y-%m-%dT%H:%M:%SZ"),
-        "instance_id": response.instance_id,
-        "home_label": response.home_label,
-        "fingerprint": ca_fp,
-        "local_endpoints": response.local_endpoints,
-        "role": "peer" if is_peer(as_role) else "",
-    }
-    files = {
-        "private.pem": private_key_pem,
-        "cert.pem": response.client_cert.encode("utf-8"),
-        "chain.pem": chain_pem.encode("utf-8"),
-        "home_attestation.jwt": response.home_attestation.encode("utf-8"),
-        "peer.json": (json.dumps(peer, indent=2) + "\n").encode("utf-8"),
-    }
-    try:
-        _publish_bundle_atomic(bundle_dir, files)
-    except OSError as exc:
-        return _fail(str(exc), code=1)
-
-    suffix = " as peer" if is_peer(as_role) else ""
-    print(f"Linked {label}{suffix}.")
-    print(f"Credentials: {bundle_dir}")
-    return 0
-
-
-def _post_pair_relay(req: RelayPairRequest, body: dict[str, str]) -> PairResponse:
-    try:
-        return asyncio.run(_pair_exchange_relay(req, body))
-    except StreamResetError as exc:
-        raise ValueError(
-            "Pairing stream reset or closed before a response was received."
-        ) from exc
-    except TlsError as exc:
-        raise ValueError(f"Inner TLS handshake failed: {exc}") from exc
-    except InvalidStatus as exc:
-        raise ValueError(
-            "The pairing window is closed or was already used (relay declined the dial)."
-        ) from exc
-    except (asyncio.TimeoutError, TimeoutError) as exc:
-        raise ValueError("Timed out dialing the relay pairing window.") from exc
-    except (ConnectionError, OSError) as exc:
-        raise ValueError(f"Could not reach the relay: {exc}") from exc
-
-
-async def _pair_exchange_relay(
-    req: RelayPairRequest,
-    body: dict[str, str],
-) -> PairResponse:
-    ws_url = _to_ws(req.relay_endpoint.rstrip("/")) + "/session/pair-dial"
-    async with websockets.connect(
-        ws_url,
-        additional_headers={"Sec-Pair-Key": req.rk.hex()},
-        max_size=None,
-    ) as ws:
-        session = await _open_pairing_session(_WsEncryptedTransport(ws))
-        try:
-            status, _headers, body_bytes = await session.request(
-                "POST",
-                req.inner_path,
-                headers={"content-type": "application/json"},
-                body=json.dumps(body).encode("utf-8"),
-            )
-            if status != 200:
-                raise ValueError(
-                    f"Pairing failed (HTTP {status}): the pairing window is closed "
-                    "or the code was already used."
-                )
-            try:
-                payload = json.loads(body_bytes.decode("utf-8"))
-            except (json.JSONDecodeError, UnicodeDecodeError) as exc:
-                raise ValueError("Pair response was not valid JSON") from exc
-            response = _parse_pair_response(payload)
-            _verify_relay_pair(response, session.peer_certificate(), req.ca_fp_spki)
-            return response
-        finally:
-            await session.close()
-
-
-def _verify_relay_pair(
-    response: PairResponse,
-    peer_leaf: x509.Certificate | None,
-    ca_fp_spki: bytes,
-) -> None:
-    """Fail closed unless the pinned CA, live TLS leaf, and jid all agree."""
-    chain_pem = _join_chain(response.ca_chain)
-    ca_cert, spki_der = _load_ca_cert_and_spki(chain_pem)
-    if hashlib.sha256(spki_der).digest()[:16] != ca_fp_spki:
-        raise ValueError(
-            "CA fingerprint mismatch: the pinned CA does not match the pair-link."
-        )
-    if peer_leaf is None:
-        raise ValueError(
-            "Pairing TLS peer presented no certificate to verify against the pinned CA."
-        )
-    _verify_leaf_signed_by_pinned_ca(peer_leaf, ca_cert)
-    expected = str(jid_from_spki(spki_der))
-    if response.instance_id != expected:
-        raise ValueError(
-            "Home instance_id does not match the pinned CA identity "
-            f"(got {response.instance_id!r}, expected {expected!r})."
-        )
-
-
-def _load_ca_cert_and_spki(chain_pem: str) -> tuple[x509.Certificate, bytes]:
-    cert_pem = _first_cert_pem(chain_pem)
-    ca_cert = x509.load_pem_x509_certificate(cert_pem.encode("ascii"))
-    spki_der = ca_cert.public_key().public_bytes(
-        serialization.Encoding.DER,
-        serialization.PublicFormat.SubjectPublicKeyInfo,
-    )
-    return ca_cert, spki_der
-
-
-def _post_pair_framed(
-    req: DirectPairRequest,
-    body: dict[str, str],
-    private_key: ec.EllipticCurvePrivateKey,
-) -> PairResponse:
-    try:
-        return asyncio.run(_pair_exchange(req, body, private_key))
-    except StreamResetError as exc:
-        raise ValueError(
-            "Pairing stream reset or closed before a response was received."
-        ) from exc
-    except TlsError as exc:
-        raise ValueError(f"Pairing request TLS failed: {exc}") from exc
-    except (ConnectionError, OSError) as exc:
-        raise ValueError(f"Pairing request failed: {exc}") from exc
-
-
-def _framed_target(url: str) -> tuple[str, int, str]:
-    parsed = urllib.parse.urlparse(url)
-    host = parsed.hostname
-    if not host:
-        raise ValueError("Pair-link target missing host.")
-    port = parsed.port
-    if port is None:
-        raise ValueError("Pair-link target missing explicit port.")
-    path = parsed.path or "/"
-    if parsed.query:
-        path = f"{path}?{parsed.query}"
-    return host, port, path
-
-
-async def _pair_exchange(
-    req: DirectPairRequest,
-    body: dict[str, str],
-    private_key: ec.EllipticCurvePrivateKey,
-) -> PairResponse:
-    body_bytes = json.dumps(body).encode("utf-8")
-    last_error: str | None = None
-    for target in _dedupe_targets(_dial_targets(req)):
-        try:
-            session = await _open_ready_pairing_session(
-                target,
-                req.ca_fingerprint_pin,
-            )
-        except Exception as exc:  # noqa: BLE001 - normalized per-candidate error.
-            last_error = _pre_request_error_message(target, exc)
-            continue
-        try:
-            status, _headers, body_bytes_response = await _committed_pair_request(
-                session,
-                target,
-                body_bytes,
-            )
-            response = _parse_pair_http_response(status, body_bytes_response)
-            returned_ca = _verify_returned_ca(response, req.ca_fingerprint_pin)
-            _validate_returned_client_cert(response, private_key, returned_ca)
-            return response
-        finally:
-            await session.close()
-    raise ValueError(last_error or "Could not connect to the pairing listener.")
-
-
-def _dial_targets(req: DirectPairRequest) -> tuple[PairTarget, ...]:
-    if req.home is not None:
-        host, port, path = _framed_target(f"{req.home}{req.path}")
-        return (PairTarget(host=host, port=port, path=path),)
-    return tuple(
-        PairTarget(host=candidate.host, port=candidate.port, path=req.path)
-        for candidate in req.candidates
-    )
-
-
-def _dedupe_targets(targets: tuple[PairTarget, ...]) -> tuple[PairTarget, ...]:
-    seen: set[tuple[str, int]] = set()
-    deduped: list[PairTarget] = []
-    for target in targets:
-        key = (target.host, target.port)
-        if key in seen:
-            continue
-        seen.add(key)
-        deduped.append(target)
-    return tuple(deduped)
-
-
-async def _open_ready_pairing_session(
-    target: PairTarget,
-    ca_fingerprint_pin: str,
-) -> TunnelSession:
-    session = None
-    transport = None
-    writer = None
-    ready = False
-
-    async def open_session() -> TunnelSession:
-        nonlocal session, transport, writer, ready
-        try:
-            reader, writer = await asyncio.open_connection(target.host, target.port)
-            transport = _TcpEncryptedTransport(reader, writer)
-            session = await _open_pairing_session(transport)
-            _verify_direct_ready(session, ca_fingerprint_pin)
-            ready = True
-            return session
-        finally:
-            if not ready:
-                await _close_unready_session(session, transport, writer)
-
-    return await asyncio.wait_for(open_session(), timeout=_CONNECT_TIMEOUT_SECONDS)
-
-
-async def _close_unready_session(
-    session: TunnelSession | None,
-    transport: Any,
-    writer: Any,
-) -> None:
-    if session is not None:
-        with contextlib.suppress(Exception):
-            await session.close()
-        return
-    if transport is not None:
-        with contextlib.suppress(Exception):
-            await transport.close()
-        return
-    if writer is not None:
-        writer.close()
-        with contextlib.suppress(Exception):
-            await writer.wait_closed()
-
-
-def _verify_direct_ready(
-    session: TunnelSession,
-    ca_fingerprint_pin: str,
-) -> None:
-    chain = tuple(session.peer_certificate_chain())
-    if not chain:
-        raise ValueError(
-            "Pairing TLS peer presented no certificate to verify against the pinned CA."
-        )
-    ca_cert = _find_pinned_ca_in_presented_chain(chain, ca_fingerprint_pin)
-    if ca_cert is None:
-        raise ValueError("Pairing TLS peer did not match the pair-link.")
-    _verify_leaf_signed_by_pinned_ca(chain[0], ca_cert)
-
-
-def _find_pinned_ca_in_presented_chain(
-    chain: tuple[x509.Certificate, ...],
-    ca_fingerprint_pin: str,
-) -> x509.Certificate | None:
-    for cert in chain:
-        der = cert.public_bytes(serialization.Encoding.DER)
-        if ca_pin_matches(
-            f"sha256:{hashlib.sha256(der).hexdigest()}", ca_fingerprint_pin
-        ):
-            return cert
-    return None
-
-
-def _pre_request_error_message(target: PairTarget, exc: Exception) -> str:
-    if isinstance(exc, (asyncio.TimeoutError, TimeoutError)):
-        return f"Timed out connecting to {target.host}:{target.port}."
-    if isinstance(exc, TlsError):
-        return f"TLS handshake with {target.host}:{target.port} failed: {exc}"
-    if isinstance(exc, (ConnectionError, OSError)):
-        return f"Could not connect to {target.host}:{target.port}: {exc}"
-    return str(exc)
-
-
-async def _committed_pair_request(
-    session: TunnelSession,
-    target: PairTarget,
-    body_bytes: bytes,
-) -> tuple[int, dict[str, str], bytes]:
-    try:
-        return await asyncio.wait_for(
-            session.request(
-                "POST",
-                target.path,
-                headers={"content-type": "application/json"},
-                body=body_bytes,
-            ),
-            timeout=_HTTP_TIMEOUT_SECONDS,
-        )
-    except (asyncio.TimeoutError, TimeoutError) as exc:
-        raise ValueError(
-            f"Timed out waiting for the pairing response from {target.host}:{target.port}."
-        ) from exc
-
-
-def _parse_pair_http_response(status: int, body_bytes: bytes) -> PairResponse:
-    if status != 200:
-        raise ValueError(
-            f"Pairing failed (HTTP {status}): the pairing window is closed "
-            "or the code was already used."
-        )
-    try:
-        payload = json.loads(body_bytes.decode("utf-8"))
-    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
-        raise ValueError("Pair response was not valid JSON") from exc
-    return _parse_pair_response(payload)
-
-
-def _verify_returned_ca(
-    response: PairResponse,
-    ca_fingerprint_pin: str,
-) -> x509.Certificate:
-    chain_pem = _join_chain(response.ca_chain)
-    cert = x509.load_pem_x509_certificate(_first_cert_pem(chain_pem).encode("ascii"))
-    der = cert.public_bytes(serialization.Encoding.DER)
-    fingerprint = f"sha256:{hashlib.sha256(der).hexdigest()}"
-    # Pin response chain position 0 because that is the CA the bundle persists
-    # first in chain.pem and fingerprints in peer.json for later trust.
-    if not ca_pin_matches(fingerprint, ca_fingerprint_pin):
-        raise ValueError(
-            "CA fingerprint mismatch: the pinned CA does not match the pair-link."
-        )
-    return cert
-
-
-def _validate_returned_client_cert(
-    response: PairResponse,
-    private_key: ec.EllipticCurvePrivateKey,
-    ca_cert: x509.Certificate,
-) -> None:
-    try:
-        client_cert = x509.load_pem_x509_certificate(
-            response.client_cert.encode("ascii")
-        )
-    except (ValueError, UnicodeEncodeError) as exc:
-        raise ValueError("Pair response client certificate is invalid.") from exc
-    try:
-        _verify_leaf_signed_by_pinned_ca(client_cert, ca_cert)
-    except ValueError as exc:
-        raise ValueError(
-            "Pair response client certificate is not signed by the pinned CA."
-        ) from exc
-    if _public_key_spki(client_cert.public_key()) != _public_key_spki(
-        private_key.public_key()
-    ):
-        raise ValueError(
-            "Pair response client certificate does not match the generated key."
-        )
-
-
-def _public_key_spki(public_key: Any) -> bytes:
-    return public_key.public_bytes(
-        serialization.Encoding.DER,
-        serialization.PublicFormat.SubjectPublicKeyInfo,
-    )
-
-
-def _parse_pair_response(payload: Any) -> PairResponse:
-    if not isinstance(payload, dict):
-        raise ValueError("Pair response was not a JSON object")
-    client_cert = _required_str(payload, "client_cert")
-    ca_chain = payload.get("ca_chain")
-    if not isinstance(ca_chain, list) or not ca_chain:
-        raise ValueError("Pair response missing ca_chain")
-    if not all(isinstance(item, str) and item for item in ca_chain):
-        raise ValueError("Pair response field ca_chain is invalid")
-    instance_id = _required_str(payload, "instance_id")
-    home_attestation = _required_str(payload, "home_attestation")
-    home_label = payload.get("home_label")
-    local_endpoints = payload.get("local_endpoints")
-    return PairResponse(
-        client_cert=client_cert,
-        ca_chain=ca_chain,
-        instance_id=instance_id,
-        home_label=home_label if isinstance(home_label, str) else "",
-        home_attestation=home_attestation,
-        local_endpoints=local_endpoints if isinstance(local_endpoints, list) else [],
-    )
-
-
-def _required_str(payload: dict[str, Any], field: str) -> str:
-    value = payload.get(field)
-    if not isinstance(value, str) or not value:
-        raise ValueError(f"Pair response missing {field}")
-    return value
-
-
-def _join_chain(ca_chain: list[str]) -> str:
-    return "".join(cert if cert.endswith("\n") else f"{cert}\n" for cert in ca_chain)
-
-
-def _ca_fingerprint(chain_pem: str) -> str:
-    cert_pem = _first_cert_pem(chain_pem)
-    cert = x509.load_pem_x509_certificate(cert_pem.encode("ascii"))
-    der = cert.public_bytes(serialization.Encoding.DER)
-    return f"sha256:{hashlib.sha256(der).hexdigest()}"
-
-
-def _verify_leaf_signed_by_pinned_ca(
-    leaf: x509.Certificate,
-    ca_cert: x509.Certificate,
-) -> None:
-    """Raise unless ``leaf`` carries a valid signature from ``ca_cert``.
-
-    The link stack issues EC P-256 CAs and leaves, so verification is ECDSA.
-    Any other key type, or an invalid signature, fails closed.
-    """
-    public_key = ca_cert.public_key()
-    if not isinstance(public_key, ec.EllipticCurvePublicKey):
-        raise ValueError(
-            "Pinned CA uses an unexpected key type; refusing to trust the pairing peer."
-        )
-    try:
-        public_key.verify(
-            leaf.signature,
-            leaf.tbs_certificate_bytes,
-            ec.ECDSA(leaf.signature_hash_algorithm),
-        )
-    except InvalidSignature as exc:
-        raise ValueError(
-            "Pairing TLS peer certificate is not signed by the pinned CA "
-            "(possible man-in-the-middle during pairing)."
-        ) from exc
-
-
-def _first_cert_pem(chain_pem: str) -> str:
-    marker = "-----BEGIN CERTIFICATE-----"
-    start = chain_pem.find(marker)
-    if start < 0:
-        raise ValueError("CA chain contained no certificate")
-    end_marker = "-----END CERTIFICATE-----"
-    end = chain_pem.find(end_marker, start)
-    if end < 0:
-        raise ValueError("CA chain contained an incomplete certificate")
-    end += len(end_marker)
-    return chain_pem[start:end] + "\n"
-
-
-def _publish_bundle_atomic(
-    bundle_dir: Path,
-    files: dict[str, bytes],
-) -> None:
-    parent = bundle_dir.parent
-    parent.mkdir(parents=True, exist_ok=True)
-    existing_error = _existing_path_error(bundle_dir)
-    if existing_error is not None:
-        raise OSError(existing_error)
-    staging = Path(
-        tempfile.mkdtemp(
-            prefix=f".{bundle_dir.name}.",
-            dir=parent,
-        )
-    )
-    try:
-        staging.chmod(0o700)
-        for name, content in files.items():
-            _write_bundle_file(staging / name, content)
-        _fsync_directory(staging)
-        # A concurrent creator between lexists() and rename() can still win; this
-        # join path has no cross-process lock, so the refuse-first check is the
-        # intended guard for ordinary reruns.
-        os.rename(staging, bundle_dir)
-        _fsync_directory(parent)
-    except BaseException:
-        if os.path.lexists(staging):
-            shutil.rmtree(staging, ignore_errors=True)
-        raise
-
-
-def _write_bundle_file(path: Path, content: bytes) -> None:
-    try:
-        with open(path, "wb") as f:
-            f.write(content)
-            f.flush()
-            os.fsync(f.fileno())
-        path.chmod(0o600)
-    except OSError as exc:
-        raise OSError(f"failed to write {path}: {exc}") from exc
-
-
-def _fsync_directory(path: Path) -> None:
-    try:
-        fd = os.open(path, os.O_RDONLY)
-    except OSError:
-        return
-    try:
-        with contextlib.suppress(OSError):
-            os.fsync(fd)
-    finally:
-        os.close(fd)
-
-
-def _fail(message: str, *, code: int) -> int:
-    print(message, file=sys.stderr)
-    return code
diff --git a/solstone/think/link/observer_paths.py b/solstone/think/link/observer_paths.py
deleted file mode 100644
index 747d73efb..000000000
--- a/solstone/think/link/observer_paths.py
+++ /dev/null
@@ -1,19 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright (c) 2026 sol pbc
-
-"""Caller-side observer SPL bundle path helpers."""
-
-from __future__ import annotations
-
-import os
-from pathlib import Path
-
-
-def observer_spl_root() -> Path:
-    config_home = os.environ.get("XDG_CONFIG_HOME")
-    base = Path(config_home) if config_home else Path.home() / ".config"
-    return base / "solstone-observer" / "spl"
-
-
-def observer_bundle_dir(label: str) -> Path:
-    return observer_spl_root() / label
diff --git a/solstone/think/link/serve_cli.py b/solstone/think/link/serve_cli.py
deleted file mode 100644
index 50568e45c..000000000
--- a/solstone/think/link/serve_cli.py
+++ /dev/null
@@ -1,420 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright (c) 2026 sol pbc
-
-"""Resident loopback proxy for `sol link serve`."""
-
-from __future__ import annotations
-
-import argparse
-import errno
-import json
-import logging
-import queue
-import sys
-from collections.abc import Iterable
-from concurrent.futures import Future
-from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
-from pathlib import Path
-from typing import NamedTuple, Protocol, cast
-from urllib.parse import urlsplit
-
-from solstone.think.link.bundle import load_client_identity
-from solstone.think.link.client import RECOMMENDED_CHUNK, BodySource
-from solstone.think.link.dialer import (
-    TunnelClient,
-    TunnelLifecycleError,
-    TunnelRequestError,
-    TunnelResponseHead,
-)
-from solstone.think.link.observer_paths import observer_bundle_dir, observer_spl_root
-from solstone.think.link.paths import relay_url
-
-LOG = logging.getLogger(__name__)
-LOOPBACK_HOST = "127.0.0.1"
-DEFAULT_PORT = 5015
-RESPONSE_QUEUE_MAX_ITEMS = 8
-RESPONSE_HEAD_TIMEOUT_SECONDS = 30.0
-STATUS_PATH = "/_solstone/link/status"
-REQUEST_HOP_BY_HOP = {
-    "connection",
-    "keep-alive",
-    "proxy-authenticate",
-    "proxy-authorization",
-    "te",
-    "trailers",
-    "transfer-encoding",
-    "upgrade",
-}
-RESPONSE_HOP_BY_HOP = {
-    "connection",
-    "keep-alive",
-    "proxy-authenticate",
-    "proxy-authorization",
-    "te",
-    "trailers",
-    "upgrade",
-}
-
-
-class _ProxyTunnel(Protocol):
-    def proxy_stream_request(
-        self,
-        method: str,
-        path: str,
-        *,
-        headers: dict[str, str] | None = None,
-        body: bytes | BodySource = b"",
-        chunks: queue.Queue[TunnelResponseHead | bytes | Exception | None],
-    ) -> Future[None]: ...
-
-    def status(self) -> dict[str, object]: ...
-
-
-class _BundleSelection(NamedTuple):
-    label: str
-    bundle_dir: Path
-
-
-class _ProxyServer(ThreadingHTTPServer):
-    tunnel: _ProxyTunnel
-
-
-def add_arguments(parser: argparse.ArgumentParser) -> None:
-    parser.add_argument("--label", help="Observer link bundle label")
-    parser.add_argument(
-        "--port",
-        type=int,
-        default=DEFAULT_PORT,
-        help=f"Loopback port to serve on (default: {DEFAULT_PORT})",
-    )
-    parser.add_argument("--relay-url", help="Override the spl relay URL")
-    parser.add_argument(
-        "--direct",
-        action="store_true",
-        help="PL-direct only: dial the journal over the LAN secure listener, "
-        "never the spl relay. Use when the home is reachable directly "
-        "(same LAN/VPN) to avoid any relay dependency.",
-    )
-
-
-def main(args: argparse.Namespace) -> int:
-    port_error = _port_error(args.port)
-    if port_error is not None:
-        return _fail(port_error, code=2)
-
-    try:
-        selection = _resolve_bundle_dir(args.label)
-        identity = load_client_identity(selection.bundle_dir)
-    except ValueError as exc:
-        return _fail(str(exc), code=1)
-
-    relay = (
-        None if getattr(args, "direct", False) else _resolve_relay_url(args.relay_url)
-    )
-    tunnel = TunnelClient(identity, relay)
-    tunnel.start()
-    try:
-        server = _build_server(args.port, tunnel)
-    except OSError as exc:
-        tunnel.close()
-        return _fail(_bind_error(args.port, exc), code=1)
-
-    LOG.info(
-        "forwarding %s:%d -> home %s over pl",
-        LOOPBACK_HOST,
-        args.port,
-        selection.label,
-    )
-    try:
-        server.serve_forever()
-    except KeyboardInterrupt:
-        return 0
-    finally:
-        server.shutdown()
-        server.server_close()
-        tunnel.close()
-    return 0
-
-
-def _resolve_bundle_dir(label: str | None) -> _BundleSelection:
-    if label:
-        bundle_dir = observer_bundle_dir(label)
-        try:
-            load_client_identity(bundle_dir)
-        except ValueError as exc:
-            raise ValueError(
-                f"invalid link bundle for label '{label}' at {bundle_dir}: {exc}. "
-                "Run `sol link join` to pair this device."
-            ) from exc
-        return _BundleSelection(label, bundle_dir)
-
-    bundles = _valid_observer_bundles()
-    if not bundles:
-        raise ValueError(
-            f"no observer link bundles found under {observer_spl_root()}. "
-            "Run `sol link join` to pair this device."
-        )
-    if len(bundles) > 1:
-        labels = ", ".join(sorted(bundles))
-        raise ValueError(
-            f"multiple observer link bundles found: {labels}. "
-            "Pass --label to choose one."
-        )
-    selected_label, bundle_dir = next(iter(bundles.items()))
-    return _BundleSelection(selected_label, bundle_dir)
-
-
-def _valid_observer_bundles() -> dict[str, Path]:
-    root = observer_spl_root()
-    if not root.is_dir():
-        return {}
-    bundles: dict[str, Path] = {}
-    for bundle_dir in sorted(root.iterdir()):
-        if not bundle_dir.is_dir():
-            continue
-        try:
-            load_client_identity(bundle_dir)
-        except ValueError:
-            continue
-        bundles[bundle_dir.name] = bundle_dir
-    return bundles
-
-
-def _resolve_relay_url(value: str | None) -> str:
-    if value and value.strip():
-        return value.strip().rstrip("/")
-    return relay_url()
-
-
-def _build_server(port: int, tunnel: _ProxyTunnel) -> _ProxyServer:
-    server = _ProxyServer((LOOPBACK_HOST, port), _ProxyHandler)
-    server.tunnel = tunnel
-    return server
-
-
-def _port_error(port: int) -> str | None:
-    if port < 1 or port > 65535:
-        return "--port must be between 1 and 65535"
-    return None
-
-
-def _bind_error(port: int, exc: OSError) -> str:
-    if exc.errno == errno.EADDRINUSE:
-        return (
-            f"cannot bind {LOOPBACK_HOST}:{port}: address already in use. "
-            "Another `sol link serve` or Convey may already be using that port."
-        )
-    return f"cannot bind {LOOPBACK_HOST}:{port}: {exc}"
-
-
-def _fail(message: str, *, code: int) -> int:
-    print(message, file=sys.stderr)
-    return code
-
-
-class _ProxyHandler(BaseHTTPRequestHandler):
-    protocol_version = "HTTP/1.1"
-
-    def do_GET(self) -> None:
-        self._handle()
-
-    def do_POST(self) -> None:
-        self._handle()
-
-    def do_PUT(self) -> None:
-        self._handle()
-
-    def do_DELETE(self) -> None:
-        self._handle()
-
-    def do_PATCH(self) -> None:
-        self._handle()
-
-    def do_HEAD(self) -> None:
-        self._handle()
-
-    def do_OPTIONS(self) -> None:
-        self._handle()
-
-    def _handle(self) -> None:
-        if _origin_path(self.path) == STATUS_PATH:
-            self._send_status()
-            return
-
-        body = self._read_body_source()
-        if body is None:
-            return
-
-        chunks: queue.Queue[TunnelResponseHead | bytes | Exception | None] = (
-            queue.Queue(maxsize=RESPONSE_QUEUE_MAX_ITEMS)
-        )
-        server = cast(_ProxyServer, self.server)
-        future = server.tunnel.proxy_stream_request(
-            self.command,
-            _origin_path(self.path),
-            headers=_forward_request_headers(self.headers.items(), body.length),
-            body=body,
-            chunks=chunks,
-        )
-
-        try:
-            first = chunks.get(timeout=RESPONSE_HEAD_TIMEOUT_SECONDS)
-        except queue.Empty:
-            future.cancel()
-            self._send_gateway_error(TimeoutError("response head timed out"))
-            return
-
-        if isinstance(first, Exception):
-            self._send_gateway_error(first)
-            return
-        if first is None:
-            future.cancel()
-            self._send_gateway_error(RuntimeError("empty response from link tunnel"))
-            return
-        if not isinstance(first, TunnelResponseHead):
-            future.cancel()
-            self._send_gateway_error(RuntimeError("bad response from link tunnel"))
-            return
-
-        self.send_response_only(first.status)
-        for name, value in first.headers.items():
-            if name.lower() in RESPONSE_HOP_BY_HOP:
-                continue
-            self.send_header(name, value)
-        self.end_headers()
-
-        write_body = self.command != "HEAD"
-        while True:
-            item = chunks.get()
-            if item is None:
-                return
-            if isinstance(item, Exception):
-                future.cancel()
-                LOG.warning("link proxy stream failed after response head: %s", item)
-                self.close_connection = True
-                return
-            if not isinstance(item, bytes):
-                future.cancel()
-                LOG.warning("link proxy stream returned unexpected item: %r", item)
-                self.close_connection = True
-                return
-            if not write_body:
-                continue
-            try:
-                self.wfile.write(item)
-                self.wfile.flush()
-            except (BrokenPipeError, ConnectionError, OSError):
-                future.cancel()
-                self.close_connection = True
-                return
-
-    def _read_body_source(self) -> BodySource | None:
-        if self.headers.get("Transfer-Encoding") is not None:
-            LOG.warning("link proxy rejected request with Transfer-Encoding")
-            self._send_bad_request("Transfer-Encoding is not supported")
-            self.close_connection = True
-            return None
-
-        content_length = self.headers.get("Content-Length")
-        if content_length is None:
-            return BodySource(0, ())
-        try:
-            length = int(content_length)
-        except ValueError:
-            self._send_bad_request("Bad Content-Length")
-            self.close_connection = True
-            return None
-        if length < 0:
-            self._send_bad_request("Bad Content-Length")
-            self.close_connection = True
-            return None
-        return BodySource(length, self._body_chunks(length))
-
-    def _body_chunks(self, length: int) -> Iterable[bytes]:
-        remaining = length
-        while remaining > 0:
-            chunk = self.rfile.read(min(RECOMMENDED_CHUNK, remaining))
-            if not chunk:
-                raise ConnectionError("client closed request body early")
-            remaining -= len(chunk)
-            yield chunk
-
-    def _send_bad_request(self, message: str) -> None:
-        try:
-            self.send_error(400, message)
-        except (BrokenPipeError, ConnectionError, OSError) as exc:
-            LOG.debug("link proxy could not send bad request response: %s", exc)
-
-    def _send_gateway_error(self, exc: Exception) -> None:
-        if isinstance(exc, TunnelLifecycleError):
-            self._send_lifecycle_error(exc)
-            return
-        if isinstance(exc, TunnelRequestError):
-            detail = exc.reason
-        else:
-            detail = type(exc).__name__
-        try:
-            self.send_error(502, f"Link tunnel failed: {detail}")
-        except (BrokenPipeError, ConnectionError, OSError) as send_exc:
-            LOG.debug("link proxy could not send gateway error response: %s", send_exc)
-        self.close_connection = True
-
-    def _send_lifecycle_error(self, exc: TunnelLifecycleError) -> None:
-        body = json.dumps(exc.as_dict(), sort_keys=True).encode("utf-8")
-        try:
-            self.send_response_only(503)
-            self.send_header("Content-Type", "application/json")
-            self.send_header("Content-Length", str(len(body)))
-            self.end_headers()
-            if self.command != "HEAD":
-                self.wfile.write(body)
-                self.wfile.flush()
-        except (BrokenPipeError, ConnectionError, OSError) as send_exc:
-            LOG.debug(
-                "link proxy could not send lifecycle error response: %s", send_exc
-            )
-        self.close_connection = True
-
-    def _send_status(self) -> None:
-        server = cast(_ProxyServer, self.server)
-        status = server.tunnel.status()
-        body = json.dumps(status, sort_keys=True).encode("utf-8")
-        try:
-            self.send_response_only(200)
-            self.send_header("Content-Type", "application/json")
-            self.send_header("Content-Length", str(len(body)))
-            self.end_headers()
-            if self.command != "HEAD":
-                self.wfile.write(body)
-                self.wfile.flush()
-        except (BrokenPipeError, ConnectionError, OSError) as exc:
-            LOG.debug("link proxy could not send status response: %s", exc)
-        self.close_connection = True
-
-    def log_message(self, fmt: str, *args: object) -> None:
-        LOG.debug("%s - %s", self.address_string(), fmt % args)
-
-
-def _origin_path(raw_path: str) -> str:
-    if raw_path.startswith("http://") or raw_path.startswith("https://"):
-        parsed = urlsplit(raw_path)
-        path = parsed.path or "/"
-        if parsed.query:
-            return f"{path}?{parsed.query}"
-        return path
-    return raw_path or "/"
-
-
-def _forward_request_headers(
-    headers: Iterable[tuple[str, str]],
-    body_length: int,
-) -> dict[str, str]:
-    forwarded: dict[str, str] = {}
-    for name, value in headers:
-        if name.lower() == "authorization":
-            continue
-        if name.lower() in REQUEST_HOP_BY_HOP:
-            continue
-        forwarded[name] = value
-    forwarded["Content-Length"] = str(body_length)
-    return forwarded
diff --git a/solstone/think/sol_cli.py b/solstone/think/sol_cli.py
index 52ada5610..88e83f817 100644
--- a/solstone/think/sol_cli.py
+++ b/solstone/think/sol_cli.py
@@ -158,7 +158,6 @@ COMMANDS: dict[str, Command] = {
     "facet-candidates": Command("solstone.think.facet_candidates_cli", "service"),
     "cortex": Command("solstone.think.cortex", "service"),
     "talent": Command("solstone.think.talent_cli", "service"),
-    "link": Command("solstone.think.link", "universal"),
     "spl": Command("solstone.think.spl", "service"),
     "navigate": Command("solstone.think.tools.navigate", "service"),
     "identity": Command("solstone.think.tools.sol", "service"),
diff --git a/solstone/think/sol_compat_inventory.py b/solstone/think/sol_compat_inventory.py
index e87f7d11d..51c95e8b3 100644
--- a/solstone/think/sol_compat_inventory.py
+++ b/solstone/think/sol_compat_inventory.py
@@ -25,7 +25,6 @@ PUBLIC_BINARIES = frozenset({"sol", "solstone"})
 TOP_LEVEL_COMPAT_MODULES = {
     "doctor": "solstone.think.doctor",
     "check": "solstone.think.check",
-    "link": "solstone.think.link",
 }
 
 JOURNAL_CALL_PREFIX = ("call", "journal")
diff --git a/tests/link/certless_helpers.py b/tests/link/certless_helpers.py
index 177659868..e22cd58b2 100644
--- a/tests/link/certless_helpers.py
+++ b/tests/link/certless_helpers.py
@@ -4,17 +4,36 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
+import hashlib
 import json
+import urllib.parse
 from concurrent.futures import ThreadPoolExecutor
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Literal
 
 import pytest
+from cryptography import x509
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.x509.oid import NameOID
 
 from solstone.convey.secure_listener.identity import ConveyIdentity
 from solstone.convey.secure_listener.wsgi import DispatchResult, dispatch_stream
-from solstone.think.link.client import _http_head_bytes, _parse_http_response
+from solstone.think.link.ca import ca_pin_matches
+from solstone.think.link.client import (
+    _CONNECT_TIMEOUT_SECONDS,
+    _HTTP_TIMEOUT_SECONDS,
+    StreamResetError,
+    TunnelSession,
+    _http_head_bytes,
+    _open_pairing_session,
+    _parse_http_response,
+    _TcpEncryptedTransport,
+)
+from solstone.think.link.tls import TlsError
 
 
 @dataclass(frozen=True)
@@ -26,6 +45,41 @@ class DispatchResponse:
     writer: FakeStreamWriter
 
 
+@dataclass(frozen=True)
+class DirectPairCandidate:
+    ip: str
+    port: int
+
+    @property
+    def host(self) -> str:
+        return str(self.ip)
+
+
+@dataclass(frozen=True)
+class DirectPairRequest:
+    candidates: tuple[DirectPairCandidate, ...]
+    path: str
+    ca_fingerprint_pin: str
+    home: str | None = None
+
+
+@dataclass(frozen=True)
+class PairTarget:
+    host: str
+    port: int
+    path: str
+
+
+@dataclass(frozen=True)
+class PairResponse:
+    client_cert: str
+    ca_chain: list[str]
+    instance_id: str
+    home_label: str
+    home_attestation: str
+    local_endpoints: list[Any]
+
+
 class FakeStreamWriter:
     stream_id = 1
 
@@ -53,6 +107,337 @@ class FakeStreamWriter:
         self.drain_context = context
 
 
+def build_csr(label: str) -> tuple[ec.EllipticCurvePrivateKey, bytes, str]:
+    private_key = ec.generate_private_key(ec.SECP256R1())
+    csr = (
+        x509.CertificateSigningRequestBuilder()
+        .subject_name(x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, label[:64])]))
+        .sign(private_key, hashes.SHA256())
+    )
+    private_key_pem = private_key.private_bytes(
+        serialization.Encoding.PEM,
+        serialization.PrivateFormat.PKCS8,
+        serialization.NoEncryption(),
+    )
+    csr_pem = csr.public_bytes(serialization.Encoding.PEM).decode("ascii")
+    return private_key, private_key_pem, csr_pem
+
+
+def framed_target(url: str) -> tuple[str, int, str]:
+    parsed = urllib.parse.urlparse(url)
+    host = parsed.hostname
+    if not host:
+        raise ValueError("Pair-link target missing host.")
+    port = parsed.port
+    if port is None:
+        raise ValueError("Pair-link target missing explicit port.")
+    path = parsed.path or "/"
+    if parsed.query:
+        path = f"{path}?{parsed.query}"
+    return host, port, path
+
+
+def post_pair_framed(
+    req: DirectPairRequest,
+    body: dict[str, str],
+    private_key: ec.EllipticCurvePrivateKey,
+) -> PairResponse:
+    try:
+        return asyncio.run(_pair_exchange(req, body, private_key))
+    except StreamResetError as exc:
+        raise ValueError(
+            "Pairing stream reset or closed before a response was received."
+        ) from exc
+    except TlsError as exc:
+        raise ValueError(f"Pairing request TLS failed: {exc}") from exc
+    except (ConnectionError, OSError) as exc:
+        raise ValueError(f"Pairing request failed: {exc}") from exc
+
+
+def parse_pair_response(payload: Any) -> PairResponse:
+    if not isinstance(payload, dict):
+        raise ValueError("Pair response was not a JSON object")
+    client_cert = _required_str(payload, "client_cert")
+    ca_chain = payload.get("ca_chain")
+    if not isinstance(ca_chain, list) or not ca_chain:
+        raise ValueError("Pair response missing ca_chain")
+    if not all(isinstance(item, str) and item for item in ca_chain):
+        raise ValueError("Pair response field ca_chain is invalid")
+    instance_id = _required_str(payload, "instance_id")
+    home_attestation = _required_str(payload, "home_attestation")
+    home_label = payload.get("home_label")
+    local_endpoints = payload.get("local_endpoints")
+    return PairResponse(
+        client_cert=client_cert,
+        ca_chain=ca_chain,
+        instance_id=instance_id,
+        home_label=home_label if isinstance(home_label, str) else "",
+        home_attestation=home_attestation,
+        local_endpoints=local_endpoints if isinstance(local_endpoints, list) else [],
+    )
+
+
+async def _pair_exchange(
+    req: DirectPairRequest,
+    body: dict[str, str],
+    private_key: ec.EllipticCurvePrivateKey,
+) -> PairResponse:
+    body_bytes = json.dumps(body).encode("utf-8")
+    last_error: str | None = None
+    for target in _dedupe_targets(_dial_targets(req)):
+        try:
+            session = await _open_ready_pairing_session(
+                target,
+                req.ca_fingerprint_pin,
+            )
+        except Exception as exc:  # noqa: BLE001 - normalized per-candidate error.
+            last_error = _pre_request_error_message(target, exc)
+            continue
+        try:
+            status, _headers, body_bytes_response = await _committed_pair_request(
+                session,
+                target,
+                body_bytes,
+            )
+            response = _parse_pair_http_response(status, body_bytes_response)
+            returned_ca = _verify_returned_ca(response, req.ca_fingerprint_pin)
+            _validate_returned_client_cert(response, private_key, returned_ca)
+            return response
+        finally:
+            await session.close()
+    raise ValueError(last_error or "Could not connect to the pairing listener.")
+
+
+def _dial_targets(req: DirectPairRequest) -> tuple[PairTarget, ...]:
+    if req.home is not None:
+        host, port, path = framed_target(f"{req.home}{req.path}")
+        return (PairTarget(host=host, port=port, path=path),)
+    return tuple(
+        PairTarget(host=candidate.host, port=candidate.port, path=req.path)
+        for candidate in req.candidates
+    )
+
+
+def _dedupe_targets(targets: tuple[PairTarget, ...]) -> tuple[PairTarget, ...]:
+    seen: set[tuple[str, int]] = set()
+    deduped: list[PairTarget] = []
+    for target in targets:
+        key = (target.host, target.port)
+        if key in seen:
+            continue
+        seen.add(key)
+        deduped.append(target)
+    return tuple(deduped)
+
+
+async def _open_ready_pairing_session(
+    target: PairTarget,
+    ca_fingerprint_pin: str,
+) -> TunnelSession:
+    session = None
+    transport = None
+    writer = None
+    ready = False
+
+    async def open_session() -> TunnelSession:
+        nonlocal session, transport, writer, ready
+        try:
+            reader, writer = await asyncio.open_connection(target.host, target.port)
+            transport = _TcpEncryptedTransport(reader, writer)
+            session = await _open_pairing_session(transport)
+            _verify_direct_ready(session, ca_fingerprint_pin)
+            ready = True
+            return session
+        finally:
+            if not ready:
+                await _close_unready_session(session, transport, writer)
+
+    return await asyncio.wait_for(open_session(), timeout=_CONNECT_TIMEOUT_SECONDS)
+
+
+async def _close_unready_session(
+    session: TunnelSession | None,
+    transport: Any,
+    writer: Any,
+) -> None:
+    if session is not None:
+        with contextlib.suppress(Exception):
+            await session.close()
+        return
+    if transport is not None:
+        with contextlib.suppress(Exception):
+            await transport.close()
+        return
+    if writer is not None:
+        writer.close()
+        with contextlib.suppress(Exception):
+            await writer.wait_closed()
+
+
+def _verify_direct_ready(
+    session: TunnelSession,
+    ca_fingerprint_pin: str,
+) -> None:
+    chain = tuple(session.peer_certificate_chain())
+    if not chain:
+        raise ValueError(
+            "Pairing TLS peer presented no certificate to verify against the pinned CA."
+        )
+    ca_cert = _find_pinned_ca_in_presented_chain(chain, ca_fingerprint_pin)
+    if ca_cert is None:
+        raise ValueError("Pairing TLS peer did not match the pair-link.")
+    _verify_leaf_signed_by_pinned_ca(chain[0], ca_cert)
+
+
+def _find_pinned_ca_in_presented_chain(
+    chain: tuple[x509.Certificate, ...],
+    ca_fingerprint_pin: str,
+) -> x509.Certificate | None:
+    for cert in chain:
+        der = cert.public_bytes(serialization.Encoding.DER)
+        if ca_pin_matches(
+            f"sha256:{hashlib.sha256(der).hexdigest()}", ca_fingerprint_pin
+        ):
+            return cert
+    return None
+
+
+def _pre_request_error_message(target: PairTarget, exc: Exception) -> str:
+    if isinstance(exc, (asyncio.TimeoutError, TimeoutError)):
+        return f"Timed out connecting to {target.host}:{target.port}."
+    if isinstance(exc, TlsError):
+        return f"TLS handshake with {target.host}:{target.port} failed: {exc}"
+    if isinstance(exc, (ConnectionError, OSError)):
+        return f"Could not connect to {target.host}:{target.port}: {exc}"
+    return str(exc)
+
+
+async def _committed_pair_request(
+    session: TunnelSession,
+    target: PairTarget,
+    body_bytes: bytes,
+) -> tuple[int, dict[str, str], bytes]:
+    try:
+        return await asyncio.wait_for(
+            session.request(
+                "POST",
+                target.path,
+                headers={"content-type": "application/json"},
+                body=body_bytes,
+            ),
+            timeout=_HTTP_TIMEOUT_SECONDS,
+        )
+    except (asyncio.TimeoutError, TimeoutError) as exc:
+        raise ValueError(
+            f"Timed out waiting for the pairing response from {target.host}:{target.port}."
+        ) from exc
+
+
+def _parse_pair_http_response(status: int, body_bytes: bytes) -> PairResponse:
+    if status != 200:
+        raise ValueError(
+            f"Pairing failed (HTTP {status}): the pairing window is closed "
+            "or the code was already used."
+        )
+    try:
+        payload = json.loads(body_bytes.decode("utf-8"))
+    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise ValueError("Pair response was not valid JSON") from exc
+    return parse_pair_response(payload)
+
+
+def _verify_returned_ca(
+    response: PairResponse,
+    ca_fingerprint_pin: str,
+) -> x509.Certificate:
+    chain_pem = _join_chain(response.ca_chain)
+    cert = x509.load_pem_x509_certificate(_first_cert_pem(chain_pem).encode("ascii"))
+    der = cert.public_bytes(serialization.Encoding.DER)
+    fingerprint = f"sha256:{hashlib.sha256(der).hexdigest()}"
+    if not ca_pin_matches(fingerprint, ca_fingerprint_pin):
+        raise ValueError(
+            "CA fingerprint mismatch: the pinned CA does not match the pair-link."
+        )
+    return cert
+
+
+def _validate_returned_client_cert(
+    response: PairResponse,
+    private_key: ec.EllipticCurvePrivateKey,
+    ca_cert: x509.Certificate,
+) -> None:
+    try:
+        client_cert = x509.load_pem_x509_certificate(
+            response.client_cert.encode("ascii")
+        )
+    except (ValueError, UnicodeEncodeError) as exc:
+        raise ValueError("Pair response client certificate is invalid.") from exc
+    try:
+        _verify_leaf_signed_by_pinned_ca(client_cert, ca_cert)
+    except ValueError as exc:
+        raise ValueError(
+            "Pair response client certificate is not signed by the pinned CA."
+        ) from exc
+    if _public_key_spki(client_cert.public_key()) != _public_key_spki(
+        private_key.public_key()
+    ):
+        raise ValueError(
+            "Pair response client certificate does not match the generated key."
+        )
+
+
+def _verify_leaf_signed_by_pinned_ca(
+    leaf: x509.Certificate,
+    ca_cert: x509.Certificate,
+) -> None:
+    public_key = ca_cert.public_key()
+    if not isinstance(public_key, ec.EllipticCurvePublicKey):
+        raise ValueError(
+            "Pinned CA uses an unexpected key type; refusing to trust the pairing peer."
+        )
+    try:
+        public_key.verify(
+            leaf.signature,
+            leaf.tbs_certificate_bytes,
+            ec.ECDSA(leaf.signature_hash_algorithm),
+        )
+    except InvalidSignature as exc:
+        raise ValueError(
+            "Pairing TLS peer certificate is not signed by the pinned CA "
+            "(possible man-in-the-middle during pairing)."
+        ) from exc
+
+
+def _public_key_spki(public_key: Any) -> bytes:
+    return public_key.public_bytes(
+        serialization.Encoding.DER,
+        serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+
+
+def _join_chain(ca_chain: list[str]) -> str:
+    return "".join(cert if cert.endswith("\n") else f"{cert}\n" for cert in ca_chain)
+
+
+def _first_cert_pem(chain_pem: str) -> str:
+    marker = "-----BEGIN CERTIFICATE-----"
+    start = chain_pem.find(marker)
+    if start < 0:
+        raise ValueError("CA chain contained no certificate")
+    end_marker = "-----END CERTIFICATE-----"
+    end = chain_pem.find(end_marker, start)
+    if end < 0:
+        raise ValueError("CA chain contained an unterminated certificate")
+    return chain_pem[start : end + len(end_marker)] + "\n"
+
+
+def _required_str(payload: dict[str, Any], field: str) -> str:
+    value = payload.get(field)
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"Pair response missing {field}")
+    return value
+
+
 def make_convey_app(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
diff --git a/tests/link/test_certless_pair.py b/tests/link/test_certless_pair.py
index 9ea598b82..722f28e5a 100644
--- a/tests/link/test_certless_pair.py
+++ b/tests/link/test_certless_pair.py
@@ -9,10 +9,10 @@ from pathlib import Path
 import pytest
 
 from solstone.think.link.auth import AuthorizedClients
-from solstone.think.link.join_cli import _build_csr
 from solstone.think.link.nonces import NonceStore
 from solstone.think.link.paths import authorized_clients_path, nonces_path
 from tests.link.certless_helpers import (
+    build_csr,
     certless_identity,
     dispatch_request,
     make_convey_app,
@@ -32,7 +32,7 @@ async def test_certless_pair_request_executes_handler_and_authorizes_client(
     nonce = "0123456789abcdef"
     device_label = "pytest certless phone"
     NonceStore(nonces_path()).add(nonce, device_label)
-    _private_key, _private_key_pem, csr_pem = _build_csr(device_label)
+    _private_key, _private_key_pem, csr_pem = build_csr(device_label)
     body = json.dumps(
         {
             "nonce": nonce,
diff --git a/tests/link/test_direct_admission.py b/tests/link/test_direct_admission.py
deleted file mode 100644
index e9a6abbc8..000000000
--- a/tests/link/test_direct_admission.py
+++ /dev/null
@@ -1,55 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright (c) 2026 sol pbc
-
-from __future__ import annotations
-
-import ipaddress
-
-import pytest
-
-from solstone.think.link.direct_admission import is_direct_pair_candidate_allowed
-
-
-@pytest.mark.parametrize(
-    ("address", "allowed"),
-    [
-        ("9.255.255.255", False),
-        ("10.0.0.0", True),
-        ("10.255.255.255", True),
-        ("11.0.0.0", False),
-        ("172.15.255.255", False),
-        ("172.16.0.0", True),
-        ("172.31.255.255", True),
-        ("172.32.0.0", False),
-        ("192.167.255.255", False),
-        ("192.168.0.0", True),
-        ("192.168.255.255", True),
-        ("192.169.0.0", False),
-        ("169.253.255.255", False),
-        ("169.254.0.0", True),
-        ("169.254.255.255", True),
-        ("169.255.0.0", False),
-        ("100.63.255.255", False),
-        ("100.64.0.0", True),
-        ("100.127.255.255", True),
-        ("100.128.0.0", False),
-        ("126.255.255.255", False),
-        ("127.0.0.0", True),
-        ("127.255.255.255", True),
-        ("128.0.0.0", False),
-        ("0.0.0.0", False),
-        ("255.255.255.255", False),
-        ("224.0.0.1", False),
-        ("198.18.0.1", False),
-        ("192.0.2.1", False),
-        ("198.51.100.20", False),
-        ("203.0.113.30", False),
-        ("8.8.8.8", False),
-        ("1.1.1.1", False),
-    ],
-)
-def test_direct_pair_candidate_admission_boundaries(
-    address: str,
-    allowed: bool,
-) -> None:
-    assert is_direct_pair_candidate_allowed(ipaddress.IPv4Address(address)) is allowed
diff --git a/tests/link/test_link_cli_namespace.py b/tests/link/test_link_cli_namespace.py
deleted file mode 100644
index debac5597..000000000
--- a/tests/link/test_link_cli_namespace.py
+++ /dev/null
@@ -1,101 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright (c) 2026 sol pbc
-
-from __future__ import annotations
-
-import sys
-
-import pytest
-
-from solstone.think.link import cli
-
-PAIR_LINK = "https://go.solstone.app/p#PAIRLINK"
-
-
-def test_link_join_dispatches_to_join_cli(monkeypatch: pytest.MonkeyPatch) -> None:
-    calls = []
-
-    def fake_join(args) -> int:
-        calls.append((args.home, args.code, args.as_role, args.label))
-        return 0
-
-    monkeypatch.setattr("solstone.think.link.join_cli.main", fake_join)
-
-    assert (
-        cli.main(
-            [
-                "join",
-                "--home",
-                "http://receiver",
-                "--code",
-                PAIR_LINK,
-                "--as",
-                "observer",
-                "--label",
-                "laptop",
-            ]
-        )
-        == 0
-    )
-
-    assert calls == [("http://receiver", PAIR_LINK, "observer", "laptop")]
-
-
-def test_link_no_subcommand_help_lists_commands(
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    assert cli.main([]) == 0
-
-    out = capsys.readouterr().out
-    assert "{join,serve}" in out
-    assert "join" in out
-    assert "serve" in out
-    assert "list" not in out
-
-
-def test_journal_link_routes_to_management_app_help(
-    monkeypatch: pytest.MonkeyPatch,
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    monkeypatch.setattr(sys, "argv", ["journal link", "--help"])
-
-    with pytest.raises(SystemExit) as exc:
-        cli.main(["--help"])
-
-    assert exc.value.code == 0
-    out = capsys.readouterr().out
-    assert "usage: journal link" in out
-    assert "{join,serve}" in out
-    assert "join a solstone with a short code or pair link" in out
-    assert "serve a loopback proxy over a link tunnel" in out
-    assert "authorized-clients" not in out
-
-
-def test_sol_link_list_is_unknown_client_subcommand(
-    monkeypatch: pytest.MonkeyPatch,
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    monkeypatch.setattr(sys, "argv", ["sol link", "list"])
-
-    with pytest.raises(SystemExit) as exc:
-        cli.main(["list"])
-
-    assert exc.value.code == 2
-    captured = capsys.readouterr()
-    output = captured.out + captured.err
-    assert "invalid choice: 'list'" in captured.err
-    assert "Traceback" not in output
-
-
-def test_link_serve_dispatches_to_serve_cli(monkeypatch: pytest.MonkeyPatch) -> None:
-    calls = []
-
-    def fake_serve(args) -> int:
-        calls.append((args.command, args.label, args.port, args.relay_url))
-        return 0
-
-    monkeypatch.setattr("solstone.think.link.serve_cli.main", fake_serve)
-
-    assert cli.main(["serve", "--label", "x", "--port", "5099"]) == 0
-
-    assert calls == [("serve", "x", 5099, None)]
diff --git a/tests/link/test_link_join_existing_dir.py b/tests/link/test_link_join_existing_dir.py
deleted file mode 100644
index 11dd5aa64..000000000
--- a/tests/link/test_link_join_existing_dir.py
+++ /dev/null
@@ -1,155 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright (c) 2026 sol pbc
-
-from __future__ import annotations
-
-import argparse
-
-import pytest
-
-from solstone.apps.network.routes import _build_pair_link
-from solstone.think.link import join_cli
-
-PAIR_LINK = _build_pair_link("10.0.0.42", 7657, "a" * 32, "b" * 64)
-
-
-def _args() -> argparse.Namespace:
-    return argparse.Namespace(
-        home="http://receiver",
-        code=PAIR_LINK,
-        as_role=None,
-        label="laptop",
-    )
-
-
-def _bundle_dir(tmp_path, monkeypatch: pytest.MonkeyPatch):
-    config_home = tmp_path / "config"
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(config_home))
-    bundle = config_home / "solstone-observer" / "spl" / "laptop"
-    bundle.mkdir(parents=True)
-    return bundle
-
-
-def test_existing_bundle_file_refuses_overwrite(
-    tmp_path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    bundle = _bundle_dir(tmp_path, monkeypatch)
-    existing = bundle / "peer.json"
-    existing.write_text("existing", encoding="utf-8")
-
-    result = join_cli.main(_args())
-
-    assert result == 1
-    assert existing.read_text("utf-8") == "existing"
-
-
-def test_existing_bundle_path_file_refuses_before_pair_request(
-    tmp_path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    config_home = tmp_path / "config"
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(config_home))
-    bundle = config_home / "solstone-observer" / "spl" / "laptop"
-    bundle.parent.mkdir(parents=True)
-    bundle.write_text("existing", encoding="utf-8")
-    calls = []
-
-    def fake_post_pair(*args, **_kwargs):
-        calls.append(args)
-        raise ValueError("stop")
-
-    monkeypatch.setattr(join_cli, "_post_pair", fake_post_pair)
-
-    result = join_cli.main(_args())
-
-    assert result == 1
-    assert calls == []
-    assert bundle.read_text("utf-8") == "existing"
-
-
-def test_existing_ds_store_only_refuses_before_pair_request(
-    tmp_path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    bundle = _bundle_dir(tmp_path, monkeypatch)
-    (bundle / ".DS_Store").write_text("", encoding="utf-8")
-    calls = []
-
-    def fake_post_pair(*args, **_kwargs):
-        calls.append(args)
-        raise ValueError("stop")
-
-    monkeypatch.setattr(join_cli, "_post_pair", fake_post_pair)
-
-    result = join_cli.main(_args())
-
-    assert result == 1
-    assert calls == []
-
-
-def test_existing_empty_bundle_dir_refuses_before_pair_request(
-    tmp_path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    _bundle_dir(tmp_path, monkeypatch)
-    calls = []
-
-    def fake_post_pair(*args, **_kwargs):
-        calls.append(args)
-        raise ValueError("stop")
-
-    monkeypatch.setattr(join_cli, "_post_pair", fake_post_pair)
-
-    result = join_cli.main(_args())
-
-    assert result == 1
-    assert calls == []
-
-
-def test_existing_dangling_bundle_symlink_refuses_before_pair_request(
-    tmp_path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    config_home = tmp_path / "config"
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(config_home))
-    bundle = config_home / "solstone-observer" / "spl" / "laptop"
-    bundle.parent.mkdir(parents=True)
-    bundle.symlink_to(tmp_path / "missing")
-    calls = []
-
-    def fake_post_pair(*args, **_kwargs):
-        calls.append(args)
-        raise ValueError("stop")
-
-    monkeypatch.setattr(join_cli, "_post_pair", fake_post_pair)
-
-    result = join_cli.main(_args())
-
-    assert result == 1
-    assert calls == []
-    assert bundle.is_symlink()
-
-
-def test_existing_non_bundle_file_refuses_overwrite(
-    tmp_path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    bundle = _bundle_dir(tmp_path, monkeypatch)
-    (bundle / "notes.txt").write_text("", encoding="utf-8")
-
-    result = join_cli.main(_args())
-
-    assert result == 1
-
-
-def test_existing_hidden_bundle_file_refuses_overwrite(
-    tmp_path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    bundle = _bundle_dir(tmp_path, monkeypatch)
-    (bundle / ".private.pem").write_text("", encoding="utf-8")
-
-    result = join_cli.main(_args())
-
-    assert result == 1
diff --git a/tests/link/test_link_join_label_validation.py b/tests/link/test_link_join_label_validation.py
deleted file mode 100644
index 78836ebbd..000000000
--- a/tests/link/test_link_join_label_validation.py
+++ /dev/null
@@ -1,87 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright (c) 2026 sol pbc
-
-from __future__ import annotations
-
-import argparse
-
-import pytest
-
-from solstone.apps.network.routes import _build_pair_link
-from solstone.think.link import join_cli
-
-PAIR_LINK = _build_pair_link("10.0.0.42", 7657, "a" * 32, "b" * 64)
-
-
-def _args(label: str | None) -> argparse.Namespace:
-    return argparse.Namespace(
-        home="http://receiver",
-        code=PAIR_LINK,
-        as_role=None,
-        label=label,
-    )
-
-
-@pytest.mark.parametrize(
-    "label",
-    ["", "a" * 81, "a/b", "a\\b", "a..b", ".hidden", "foo bar", "foo*", "foo!"],
-)
-def test_invalid_labels_exit_2_without_writing(
-    tmp_path,
-    monkeypatch: pytest.MonkeyPatch,
-    label: str,
-) -> None:
-    config_home = tmp_path / "config"
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(config_home))
-    calls = []
-    monkeypatch.setattr(join_cli, "_post_pair", lambda *a, **k: calls.append(a))
-
-    result = join_cli.main(_args(label))
-
-    assert result == 2
-    assert calls == []
-    assert not (config_home / "solstone-observer" / "spl").exists()
-
-
-@pytest.mark.parametrize(
-    "label",
-    ["laptop", "my-laptop", "my_laptop", "laptop.v2", "a", "a" * 80],
-)
-def test_valid_labels_reach_pair_stage(
-    tmp_path,
-    monkeypatch: pytest.MonkeyPatch,
-    label: str,
-) -> None:
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "config"))
-    calls = []
-
-    def fake_post_pair(*args, **_kwargs):
-        calls.append(args)
-        raise ValueError("stop")
-
-    monkeypatch.setattr(join_cli, "_post_pair", fake_post_pair)
-
-    result = join_cli.main(_args(label))
-
-    assert result == 1
-    assert len(calls) == 1
-
-
-def test_explicit_valid_label_is_sent_verbatim(
-    tmp_path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "config"))
-    calls = []
-
-    def fake_post_pair(_pair_request, body, _private_key):
-        calls.append(body)
-        raise ValueError("stop")
-
-    monkeypatch.setattr(join_cli, "_post_pair", fake_post_pair)
-
-    result = join_cli.main(_args("Laptop.v2"))
-
-    assert result == 1
-    assert len(calls) == 1
-    assert calls[0]["device_label"] == "Laptop.v2"
diff --git a/tests/link/test_link_join_observer.py b/tests/link/test_link_join_observer.py
deleted file mode 100644
index 7bd644a90..000000000
--- a/tests/link/test_link_join_observer.py
+++ /dev/null
@@ -1,65 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright (c) 2026 sol pbc
-
-from __future__ import annotations
-
-import argparse
-import json
-import stat
-from pathlib import Path
-
-import pytest
-
-from solstone.think.link import join_cli
-from tests.link.pairing_harness import pairing_harness
-
-
-def _args(
-    *,
-    code: str,
-    home: str | None = "http://receiver",
-    as_role: str | None = None,
-    label: str | None = "laptop",
-) -> argparse.Namespace:
-    return argparse.Namespace(home=home, code=code, as_role=as_role, label=label)
-
-
-def _configure_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
-    config_home = tmp_path / "config"
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(config_home))
-    return config_home
-
-
-def test_url_happy_path_posts_to_pair_token(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    # Criterion 1: pair-link joins use the secure listener's framed transport.
-    config_home = _configure_home(tmp_path, monkeypatch)
-    nonce = "a1b2c3d4e5f607181122334455667788"
-    with pairing_harness(tmp_path, monkeypatch) as harness:
-        harness.seed_nonce(nonce, "laptop")
-        pair_link = harness.pair_link(nonce)
-
-        result = join_cli.main(_args(code=pair_link, home=None))
-
-    assert result == 0
-    bundle = config_home / "solstone-observer" / "spl" / "laptop"
-    assert stat.S_IMODE(bundle.stat().st_mode) == 0o700
-    for name in join_cli.BUNDLE_FILES:
-        assert (bundle / name).exists()
-        assert stat.S_IMODE((bundle / name).stat().st_mode) == 0o600
-    peer = json.loads((bundle / "peer.json").read_text("utf-8"))
-    assert list(peer.keys()) == [
-        "label",
-        "paired_at",
-        "instance_id",
-        "home_label",
-        "fingerprint",
-        "local_endpoints",
-        "role",
-    ]
-    assert peer["label"] == "laptop"
-    assert peer["home_label"] == "solstone"
-    assert peer["fingerprint"].startswith("sha256:")
-    assert peer["role"] == ""
diff --git a/tests/link/test_link_join_pairing.py b/tests/link/test_link_join_pairing.py
deleted file mode 100644
index a36b0168a..000000000
--- a/tests/link/test_link_join_pairing.py
+++ /dev/null
@@ -1,1115 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright (c) 2026 sol pbc
-
-from __future__ import annotations
-
-import argparse
-import inspect
-import ipaddress
-import json
-import socket
-from pathlib import Path
-from typing import Any
-
-import pytest
-from cryptography.hazmat.primitives import serialization
-
-from solstone.apps.network.routes import _build_pair_link, _build_pair_link_v05
-from solstone.convey.secure_listener.framing import RESET_INTERNAL_ERROR
-from solstone.convey.secure_listener.mux import RESET_CTX_HANDLER_EXCEPTION
-from solstone.convey.secure_listener.tls import issue_server_cert
-from solstone.think.link import client as link_client
-from solstone.think.link import join_cli
-from solstone.think.link.ca import (
-    ca_pin_matches,
-    generate_ca,
-    load_or_generate_ca,
-    sign_csr,
-)
-from solstone.think.link.client import StreamResetError
-from solstone.think.link.paths import LinkState
-from solstone.think.link.tls import TlsError
-from tests.link.pairing_harness import PairingHarness, pairing_harness
-
-
-def _args(
-    *,
-    home: str | None = None,
-    code: str,
-    as_role: str | None = None,
-    label: str = "laptop",
-) -> argparse.Namespace:
-    return argparse.Namespace(home=home, code=code, as_role=as_role, label=label)
-
-
-def _csr_material(label: str = "laptop") -> tuple[Any, dict[str, str]]:
-    private_key, _private_key_pem, csr_pem = join_cli._build_csr(label)
-    return private_key, {"csr": csr_pem, "device_label": label}
-
-
-def _csr_body(label: str = "laptop") -> dict[str, str]:
-    _private_key, body = _csr_material(label)
-    return body
-
-
-def _direct_request_from_url(
-    url: str,
-    ca_fp: str,
-) -> join_cli.DirectPairRequest:
-    host, port, path = join_cli._framed_target(url)
-    return join_cli.DirectPairRequest(
-        candidates=(join_cli.DirectPairCandidate(ipaddress.IPv4Address(host), port),),
-        path=path,
-        ca_fingerprint_pin=ca_fp,
-    )
-
-
-def _direct_request(
-    *,
-    host: str = "127.0.0.1",
-    port: int = 7657,
-    token: str = "x",
-    ca_fp: str = "ab" * 16,
-) -> join_cli.DirectPairRequest:
-    return join_cli.DirectPairRequest(
-        candidates=(join_cli.DirectPairCandidate(ipaddress.IPv4Address(host), port),),
-        path=f"/app/network/pair?token={token}",
-        ca_fingerprint_pin=ca_fp,
-    )
-
-
-def _disable_direct_cert_validation(monkeypatch: pytest.MonkeyPatch) -> None:
-    monkeypatch.setattr(join_cli, "_verify_direct_ready", lambda *_args: None)
-    monkeypatch.setattr(join_cli, "_verify_returned_ca", lambda *_args: object())
-    monkeypatch.setattr(
-        join_cli,
-        "_validate_returned_client_cert",
-        lambda *_args: None,
-    )
-
-
-def _pair_payload(
-    harness: PairingHarness,
-    *,
-    instance_id: str = "inst-1",
-    csr_pem: str | None = None,
-    device_label: str = "laptop",
-    local_endpoints: list[dict[str, Any]] | None = None,
-) -> dict[str, Any]:
-    return _pair_payload_from_ca(
-        harness.ca,
-        instance_id=instance_id,
-        csr_pem=csr_pem,
-        device_label=device_label,
-        local_endpoints=local_endpoints,
-    )
-
-
-def _pair_payload_from_ca(
-    ca: Any,
-    *,
-    instance_id: str = "inst-1",
-    csr_pem: str | None = None,
-    device_label: str = "laptop",
-    local_endpoints: list[dict[str, Any]] | None = None,
-) -> dict[str, Any]:
-    ca_pem = ca.cert.public_bytes(serialization.Encoding.PEM).decode("ascii")
-    if csr_pem is None:
-        _private_key, body = _csr_material(device_label)
-        csr_pem = body["csr"]
-    client_cert, _fingerprint = sign_csr(ca, csr_pem, device_label)
-    return {
-        "client_cert": client_cert,
-        "ca_chain": [ca_pem],
-        "instance_id": instance_id,
-        "home_label": "solstone",
-        "home_attestation": "header.payload.signature",
-        "fingerprint": "sha256:client",
-        "local_endpoints": local_endpoints
-        if local_endpoints is not None
-        else [{"host": "127.0.0.1", "port": 7657}],
-    }
-
-
-def _pair_response_with_client_cert(client_cert: str) -> join_cli.PairResponse:
-    return join_cli.PairResponse(
-        client_cert=client_cert,
-        ca_chain=["unused-in-focused-validation"],
-        instance_id="inst-1",
-        home_label="solstone",
-        home_attestation="header.payload.signature",
-        local_endpoints=[],
-    )
-
-
-def _http_response(
-    body: bytes,
-    *,
-    status: int = 200,
-    reason: str = "OK",
-    content_type: str = "application/json",
-) -> bytes:
-    head = (
-        f"HTTP/1.1 {status} {reason}\r\n"
-        f"Content-Type: {content_type}\r\n"
-        f"Content-Length: {len(body)}\r\n"
-        "Connection: close\r\n"
-        "\r\n"
-    ).encode("ascii")
-    return head + body
-
-
-def _json_response(
-    payload: dict[str, Any],
-    *,
-    status: int = 200,
-    reason: str = "OK",
-) -> bytes:
-    return _http_response(
-        json.dumps(payload).encode("utf-8"),
-        status=status,
-        reason=reason,
-    )
-
-
-async def _read_request_json(reader) -> dict[str, Any]:
-    raw = await reader.read()
-    _head, body = raw.split(b"\r\n\r\n", 1)
-    parsed = json.loads(body.decode("utf-8"))
-    assert isinstance(parsed, dict)
-    return parsed
-
-
-def _closed_loopback_port() -> int:
-    sock = socket.socket()
-    try:
-        sock.bind(("127.0.0.1", 0))
-        return int(sock.getsockname()[1])
-    finally:
-        sock.close()
-
-
-class _FakeWriter:
-    def __init__(self) -> None:
-        self.writes: list[bytes] = []
-        self.closed = False
-        self.wait_closed_called = False
-
-    def write(self, data: bytes) -> None:
-        self.writes.append(data)
-
-    async def drain(self) -> None:
-        return None
-
-    def close(self) -> None:
-        self.closed = True
-
-    async def wait_closed(self) -> None:
-        self.wait_closed_called = True
-
-
-class _AsyncioShim:
-    def __init__(self, real_asyncio: Any, open_connection: Any) -> None:
-        self._real_asyncio = real_asyncio
-        self.open_connection = open_connection
-
-    def __getattr__(self, name: str) -> Any:
-        return getattr(self._real_asyncio, name)
-
-
-class _FakeSession:
-    def __init__(
-        self,
-        exc: Exception | None = None,
-        payload: dict[str, Any] | None = None,
-    ) -> None:
-        self._exc = exc
-        self._payload = payload or {
-            "client_cert": "client-cert",
-            "ca_chain": ["ca-cert"],
-            "instance_id": "inst-1",
-            "home_label": "solstone",
-            "home_attestation": "header.payload.signature",
-            "local_endpoints": [{"host": "127.0.0.1", "port": 7657}],
-        }
-        self.closed = False
-        self.requests: list[tuple[object, ...]] = []
-        self.request_kwargs: list[dict[str, object]] = []
-
-    async def request(
-        self, *_args: object, **_kwargs: object
-    ) -> tuple[int, dict, bytes]:
-        self.requests.append((*_args,))
-        self.request_kwargs.append(dict(_kwargs))
-        if self._exc is not None:
-            raise self._exc
-        return 200, {}, json.dumps(self._payload).encode("utf-8")
-
-    async def close(self) -> None:
-        self.closed = True
-
-
-def _single_line(text: str) -> None:
-    assert "\n" not in text.strip()
-
-
-def test_framed_join_uses_certless_identity(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    # Criterion 3: framed pair-link joins do not construct or require ClientIdentity.
-    config_home = tmp_path / "config"
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(config_home))
-
-    def fail_cert_bearing_path(*_args: object, **_kwargs: object) -> None:
-        raise AssertionError("cert-bearing client path should not be used")
-
-    captured_identities: list[object] = []
-    original_init = link_client.TunnelSession.__init__
-
-    def spy_init(self, *args: object, **kwargs: object) -> None:
-        captured_identities.append(kwargs.get("identity"))
-        original_init(self, *args, **kwargs)
-
-    monkeypatch.setattr(link_client, "ClientIdentity", fail_cert_bearing_path)
-    monkeypatch.setattr(link_client, "_build_tls_client_ctx", fail_cert_bearing_path)
-    monkeypatch.setattr(link_client.TunnelSession, "__init__", spy_init)
-
-    nonce = "10000000000000000000000000000001"
-    with pairing_harness(tmp_path, monkeypatch) as harness:
-        harness.seed_nonce(nonce, "laptop")
-        result = join_cli.main(_args(code=harness.pair_link(nonce)))
-
-    assert result == 0
-    assert captured_identities == [None]
-    assert (config_home / "solstone-observer" / "spl" / "laptop").is_dir()
-
-
-def test_post_pair_framed_checks_ca_pin_after_exchange(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    # A live TLS connection authenticated under CA A must still reject a
-    # response that returns CA B and a B-signed client certificate.
-    ca_b = generate_ca(tmp_path / "ca-b")
-    private_key, body = _csr_material("pin-phone")
-
-    async def handler(reader, writer) -> None:
-        request = await _read_request_json(reader)
-        await writer.write(
-            _json_response(
-                _pair_payload_from_ca(
-                    ca_b,
-                    csr_pem=request["csr"],
-                    device_label=request["device_label"],
-                )
-            )
-        )
-        await writer.close()
-
-    nonce = "10000000000000000000000000000002"
-    with pairing_harness(tmp_path, monkeypatch, handle_stream=handler) as harness:
-        harness.seed_nonce(nonce, "pin-phone")
-        request = _direct_request_from_url(
-            harness.pair_url(nonce),
-            harness.ca.fingerprint_sha256(),
-        )
-        with pytest.raises(ValueError) as exc_info:
-            join_cli._post_pair_framed(request, body, private_key)
-
-    assert "CA fingerprint mismatch" in str(exc_info.value)
-
-
-def test_returned_client_certificate_must_be_parseable(tmp_path: Path) -> None:
-    pinned_ca = generate_ca(tmp_path / "malformed-client-cert-ca")
-    private_key, _body = _csr_material("malformed-client-cert")
-
-    with pytest.raises(ValueError, match="client certificate is invalid"):
-        join_cli._validate_returned_client_cert(
-            _pair_response_with_client_cert("not a certificate"),
-            private_key,
-            pinned_ca.cert,
-        )
-
-
-def test_returned_client_certificate_must_be_signed_by_pinned_ca(
-    tmp_path: Path,
-) -> None:
-    pinned_ca = generate_ca(tmp_path / "pinned-returned-ca")
-    wrong_ca = generate_ca(tmp_path / "wrong-returned-ca")
-    private_key, body = _csr_material("wrong-ca-client-cert")
-    client_cert, _fingerprint = sign_csr(
-        wrong_ca,
-        body["csr"],
-        body["device_label"],
-    )
-
-    with pytest.raises(ValueError, match="not signed by the pinned CA"):
-        join_cli._validate_returned_client_cert(
-            _pair_response_with_client_cert(client_cert),
-            private_key,
-            pinned_ca.cert,
-        )
-
-
-def test_returned_client_certificate_must_match_generated_key(
-    tmp_path: Path,
-) -> None:
-    pinned_ca = generate_ca(tmp_path / "different-key-returned-ca")
-    expected_private_key, _expected_body = _csr_material("expected-key")
-    _different_private_key, different_body = _csr_material("different-key")
-    client_cert, _fingerprint = sign_csr(
-        pinned_ca,
-        different_body["csr"],
-        different_body["device_label"],
-    )
-
-    with pytest.raises(ValueError, match="does not match the generated key"):
-        join_cli._validate_returned_client_cert(
-            _pair_response_with_client_cert(client_cert),
-            expected_private_key,
-            pinned_ca.cert,
-        )
-
-
-def test_returned_ca_pin_binds_first_persisted_chain_cert(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "config"))
-    ca_b = generate_ca(tmp_path / "ca-b-first")
-    ca_b_pem = ca_b.cert.public_bytes(serialization.Encoding.PEM).decode("ascii")
-    requests = 0
-
-    async def handler(reader, writer) -> None:
-        nonlocal requests
-        request = await _read_request_json(reader)
-        requests += 1
-        client_cert, _fingerprint = sign_csr(
-            state["harness"].ca,
-            request["csr"],
-            request["device_label"],
-        )
-        pinned_ca_pem = (
-            state["harness"]
-            .ca.cert.public_bytes(serialization.Encoding.PEM)
-            .decode("ascii")
-        )
-        await writer.write(
-            _json_response(
-                {
-                    "client_cert": client_cert,
-                    "ca_chain": [ca_b_pem, pinned_ca_pem],
-                    "instance_id": "inst-1",
-                    "home_label": "solstone",
-                    "home_attestation": "header.payload.signature",
-                    "fingerprint": "sha256:client",
-                    "local_endpoints": [{"host": "127.0.0.1", "port": 7657}],
-                }
-            )
-        )
-        await writer.close()
-
-    nonce = "10000000000000000000000000000035"
-    state: dict[str, PairingHarness] = {}
-    with pairing_harness(tmp_path, monkeypatch, handle_stream=handler) as harness:
-        state["harness"] = harness
-        harness.seed_nonce(nonce, "laptop")
-        result = join_cli.main(_args(code=harness.pair_link(nonce)))
-
-    err = capsys.readouterr().err.strip()
-    assert result == 1
-    assert requests == 1
-    assert err == (
-        "CA fingerprint mismatch: the pinned CA does not match the pair-link."
-    )
-    _single_line(err)
-    assert harness.ca.fingerprint_sha256() not in err
-    assert ca_b.fingerprint_sha256() not in err
-    assert not (tmp_path / "config" / "solstone-observer" / "spl" / "laptop").exists()
-
-
-def test_peer_pair_link_sends_sender_instance_id_and_writes_peer_bundle(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    # Criterion 7: peer pair-links use framed transport and include sender_instance_id.
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))
-    captured: dict[str, Any] = {}
-    state: dict[str, PairingHarness] = {}
-
-    async def handler(reader, writer) -> None:
-        captured.update(await _read_request_json(reader))
-        await writer.write(
-            _json_response(
-                _pair_payload(
-                    state["harness"],
-                    csr_pem=captured["csr"],
-                    device_label=captured["device_label"],
-                )
-            )
-        )
-        await writer.close()
-
-    nonce = "10000000000000000000000000000005"
-    with pairing_harness(tmp_path, monkeypatch, handle_stream=handler) as harness:
-        state["harness"] = harness
-        expected_instance_id = LinkState.load_or_create().instance_id
-        result = join_cli.main(
-            _args(
-                code=harness.pair_link(nonce),
-                as_role="peer",
-                label="my-peer",
-            )
-        )
-
-    assert result == 0
-    assert captured["sender_instance_id"] == expected_instance_id
-    assert captured["device_label"] == "my-peer"
-    assert isinstance(captured["csr"], str)
-    bundle = tmp_path / "journal" / "peers" / "inst-1"
-    for name in join_cli.BUNDLE_FILES:
-        assert (bundle / name).exists()
-
-
-def test_post_pair_framed_returns_plain_response_and_closes_transport(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    # Criterion 8: sync wrapper returns a PairResponse after closing the transport.
-    private_key, body = _csr_material("sync-phone")
-    sessions = [_FakeSession(), _FakeSession()]
-    _disable_direct_cert_validation(monkeypatch)
-
-    async def fake_open_connection(_host: str, _port: int):
-        return link_client.asyncio.StreamReader(), _FakeWriter()
-
-    async def fake_open_pairing_session(_transport):
-        return sessions.pop(0)
-
-    monkeypatch.setattr(
-        join_cli,
-        "asyncio",
-        _AsyncioShim(join_cli.asyncio, fake_open_connection),
-    )
-    monkeypatch.setattr(join_cli, "_open_pairing_session", fake_open_pairing_session)
-
-    first_session = sessions[0]
-    first = join_cli._post_pair_framed(
-        _direct_request(token="one"),
-        body,
-        private_key,
-    )
-    assert first_session.closed is True
-
-    second_session = sessions[0]
-    second = join_cli._post_pair_framed(
-        _direct_request(token="two"),
-        body,
-        private_key,
-    )
-    assert second_session.closed is True
-
-    assert isinstance(first, join_cli.PairResponse)
-    assert isinstance(second, join_cli.PairResponse)
-    assert not inspect.isawaitable(first)
-
-
-def test_post_pair_framed_requires_explicit_port() -> None:
-    # Criterion 9: pair-link framed targets must include an explicit port.
-    with pytest.raises(ValueError) as exc_info:
-        join_cli._framed_target("https://receiver/app/network/pair?token=x")
-
-    assert "missing explicit port" in str(exc_info.value)
-    _single_line(str(exc_info.value))
-
-
-def test_post_pair_framed_reassembles_multiframe_response(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    # Criterion 10: multiple DATA frames are reassembled before response parsing.
-    state: dict[str, PairingHarness] = {}
-
-    async def handler(reader, writer) -> None:
-        request = await _read_request_json(reader)
-        response = _json_response(
-            _pair_payload(
-                state["harness"],
-                csr_pem=request["csr"],
-                device_label=request["device_label"],
-            )
-        )
-        await writer.write(response[:25])
-        await writer.write(response[25:80])
-        await writer.write(response[80:])
-        await writer.close()
-
-    with pairing_harness(tmp_path, monkeypatch, handle_stream=handler) as harness:
-        state["harness"] = harness
-        private_key, body = _csr_material("multi-phone")
-        response = join_cli._post_pair_framed(
-            _direct_request_from_url(
-                harness.pair_url("10000000000000000000000000000008"),
-                harness.ca.fingerprint_sha256(),
-            ),
-            body,
-            private_key,
-        )
-
-    assert response.instance_id == "inst-1"
-    assert response.local_endpoints == [{"host": "127.0.0.1", "port": 7657}]
-
-
-def test_framed_non_200_is_single_line_window_error(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    # Criterion 11: framed non-200 responses map to the window/used-code message.
-    async def handler(reader, writer) -> None:
-        await reader.read()
-        await writer.write(
-            _http_response(
-                b"gone", status=410, reason="Gone", content_type="text/plain"
-            )
-        )
-        await writer.close()
-
-    with pairing_harness(tmp_path, monkeypatch, handle_stream=handler) as harness:
-        result = join_cli.main(
-            _args(code=harness.pair_link("10000000000000000000000000000009"))
-        )
-
-    err = capsys.readouterr().err.strip()
-    assert result == 1
-    assert "pairing window is closed or the code was already used" in err
-    _single_line(err)
-
-
-def test_framed_midstream_reset_is_single_line_error(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    # Criterion 12: mid-stream RESET has a distinct reset/closed message.
-    async def handler(reader, writer) -> None:
-        await reader.read()
-        await writer.write(b"HTTP/1.1 200 OK\r\n")
-        await writer.reset(RESET_INTERNAL_ERROR, RESET_CTX_HANDLER_EXCEPTION)
-
-    with pairing_harness(tmp_path, monkeypatch, handle_stream=handler) as harness:
-        result = join_cli.main(
-            _args(code=harness.pair_link("1000000000000000000000000000000a"))
-        )
-
-    err = capsys.readouterr().err.strip()
-    assert result == 1
-    assert err == "Pairing stream reset or closed before a response was received."
-    assert "Could not connect" not in err
-    _single_line(err)
-
-
-def test_framed_connect_refused_is_single_line_error() -> None:
-    # Criterion 13: closed loopback ports map to connect errors, not hangs.
-    port = _closed_loopback_port()
-    private_key, body = _csr_material()
-
-    with pytest.raises(ValueError) as exc_info:
-        join_cli._post_pair_framed(
-            _direct_request(port=port),
-            body,
-            private_key,
-        )
-
-    message = str(exc_info.value)
-    assert message.startswith(f"Could not connect to 127.0.0.1:{port}:")
-    _single_line(message)
-
-
-def test_framed_tls_failure_is_single_line_error(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    # Criterion 13: TLS handshake failures get their own single-line message.
-    private_key, body = _csr_material()
-
-    async def fake_open_connection(_host: str, _port: int):
-        return link_client.asyncio.StreamReader(), _FakeWriter()
-
-    async def fail_tls(_transport):
-        raise TlsError("bad test handshake")
-
-    monkeypatch.setattr(
-        join_cli, "asyncio", _AsyncioShim(join_cli.asyncio, fake_open_connection)
-    )
-    monkeypatch.setattr(join_cli, "_open_pairing_session", fail_tls)
-
-    with pytest.raises(ValueError) as exc_info:
-        join_cli._post_pair_framed(
-            _direct_request(port=1),
-            body,
-            private_key,
-        )
-
-    message = str(exc_info.value)
-    assert message == "TLS handshake with 127.0.0.1:1 failed: bad test handshake"
-    _single_line(message)
-
-
-def test_framed_handshake_then_drop_is_single_line_error(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    # Criterion 13: post-handshake drops share the reset/closed taxonomy.
-    private_key, body = _csr_material()
-    _disable_direct_cert_validation(monkeypatch)
-
-    async def fake_open_connection(_host: str, _port: int):
-        return link_client.asyncio.StreamReader(), _FakeWriter()
-
-    async def fake_open_pairing_session(_transport):
-        return _FakeSession(StreamResetError("closed after handshake"))
-
-    monkeypatch.setattr(
-        join_cli, "asyncio", _AsyncioShim(join_cli.asyncio, fake_open_connection)
-    )
-    monkeypatch.setattr(join_cli, "_open_pairing_session", fake_open_pairing_session)
-
-    with pytest.raises(ValueError) as exc_info:
-        join_cli._post_pair_framed(
-            _direct_request(port=1),
-            body,
-            private_key,
-        )
-
-    message = str(exc_info.value)
-    assert message == "Pairing stream reset or closed before a response was received."
-    _single_line(message)
-
-
-def test_framed_connect_timeout_is_single_line_error(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    # Criterion 13: connection timeout maps to a timeout message without waiting 15s.
-    private_key, body = _csr_material()
-
-    async def hang_open_connection(_host: str, _port: int):
-        await link_client.asyncio.sleep(3600)
-
-    monkeypatch.setattr(
-        join_cli, "asyncio", _AsyncioShim(join_cli.asyncio, hang_open_connection)
-    )
-    monkeypatch.setattr(join_cli, "_CONNECT_TIMEOUT_SECONDS", 0.001)
-
-    with pytest.raises(ValueError) as exc_info:
-        join_cli._post_pair_framed(
-            _direct_request(port=1),
-            body,
-            private_key,
-        )
-
-    message = str(exc_info.value)
-    assert message == "Timed out connecting to 127.0.0.1:1."
-    _single_line(message)
-
-
-def test_duplicate_endpoints_prepare_once_and_exhaust_in_order(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    private_key, body = _csr_material()
-    req = join_cli.DirectPairRequest(
-        candidates=(
-            join_cli.DirectPairCandidate(ipaddress.IPv4Address("10.0.0.1"), 7657),
-            join_cli.DirectPairCandidate(ipaddress.IPv4Address("10.0.0.1"), 7657),
-            join_cli.DirectPairCandidate(ipaddress.IPv4Address("10.0.0.2"), 7657),
-        ),
-        path="/app/network/pair?token=one",
-        ca_fingerprint_pin="ab" * 16,
-    )
-    attempts: list[join_cli.PairTarget] = []
-    active = 0
-    max_active = 0
-
-    async def fail_prepare(
-        target: join_cli.PairTarget,
-        _pin: str,
-    ) -> join_cli.TunnelSession:
-        nonlocal active, max_active
-        active += 1
-        max_active = max(max_active, active)
-        attempts.append(target)
-        active -= 1
-        raise ValueError(f"pre-request failure for {target.host}:{target.port}")
-
-    monkeypatch.setattr(join_cli, "_open_ready_pairing_session", fail_prepare)
-
-    with pytest.raises(ValueError) as exc_info:
-        join_cli._post_pair_framed(req, body, private_key)
-
-    assert attempts == [
-        join_cli.PairTarget(
-            host="10.0.0.1",
-            port=7657,
-            path="/app/network/pair?token=one",
-        ),
-        join_cli.PairTarget(
-            host="10.0.0.2",
-            port=7657,
-            path="/app/network/pair?token=one",
-        ),
-    ]
-    assert max_active == 1
-    assert str(exc_info.value) == "pre-request failure for 10.0.0.2:7657"
-
-
-def test_pre_request_failure_advances_then_ready_candidate_receives_sole_request(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))
-    private_key, body = _csr_material("advance-phone")
-    session = _FakeSession()
-    req = join_cli.DirectPairRequest(
-        candidates=(
-            join_cli.DirectPairCandidate(ipaddress.IPv4Address("10.0.0.1"), 7657),
-            join_cli.DirectPairCandidate(ipaddress.IPv4Address("10.0.0.2"), 7657),
-        ),
-        path="/app/network/pair?token=advance",
-        ca_fingerprint_pin="ab" * 16,
-    )
-    attempts: list[join_cli.PairTarget] = []
-    _disable_direct_cert_validation(monkeypatch)
-
-    async def prepare(
-        target: join_cli.PairTarget,
-        _pin: str,
-    ) -> _FakeSession:
-        attempts.append(target)
-        if len(attempts) == 1:
-            raise ValueError("first candidate not ready")
-        return session
-
-    monkeypatch.setattr(join_cli, "_open_ready_pairing_session", prepare)
-
-    response = join_cli._post_pair_framed(req, body, private_key)
-
-    assert response.instance_id == "inst-1"
-    assert [target.host for target in attempts] == ["10.0.0.1", "10.0.0.2"]
-    assert len(session.requests) == 1
-    assert session.closed is True
-
-
-def test_request_invocation_is_terminal_and_closes_without_later_candidate(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    private_key, body = _csr_material("commit-phone")
-    first = _FakeSession(OSError("write failed"))
-    req = join_cli.DirectPairRequest(
-        candidates=(
-            join_cli.DirectPairCandidate(ipaddress.IPv4Address("10.0.0.1"), 7657),
-            join_cli.DirectPairCandidate(ipaddress.IPv4Address("10.0.0.2"), 7657),
-        ),
-        path="/app/network/pair?token=commit",
-        ca_fingerprint_pin="ab" * 16,
-    )
-    attempts: list[join_cli.PairTarget] = []
-
-    async def prepare(
-        target: join_cli.PairTarget,
-        _pin: str,
-    ) -> _FakeSession:
-        attempts.append(target)
-        return first
-
-    monkeypatch.setattr(join_cli, "_open_ready_pairing_session", prepare)
-
-    with pytest.raises(ValueError) as exc_info:
-        join_cli._post_pair_framed(req, body, private_key)
-
-    assert str(exc_info.value) == "Pairing request failed: write failed"
-    assert [target.host for target in attempts] == ["10.0.0.1"]
-    assert len(first.requests) == 1
-    assert first.closed is True
-
-
-def test_request_response_deadline_is_terminal(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    private_key, body = _csr_material("timeout-phone")
-
-    class SlowSession(_FakeSession):
-        async def request(self, *_args: object, **_kwargs: object):
-            self.requests.append((*_args,))
-            await link_client.asyncio.sleep(3600)
-            return await super().request(*_args, **_kwargs)
-
-    session = SlowSession()
-    attempts: list[join_cli.PairTarget] = []
-
-    async def prepare(
-        target: join_cli.PairTarget,
-        _pin: str,
-    ) -> SlowSession:
-        attempts.append(target)
-        return session
-
-    monkeypatch.setattr(join_cli, "_open_ready_pairing_session", prepare)
-    monkeypatch.setattr(join_cli, "_HTTP_TIMEOUT_SECONDS", 0.001)
-
-    with pytest.raises(ValueError) as exc_info:
-        join_cli._post_pair_framed(
-            join_cli.DirectPairRequest(
-                candidates=(
-                    join_cli.DirectPairCandidate(
-                        ipaddress.IPv4Address("10.0.0.1"),
-                        7657,
-                    ),
-                    join_cli.DirectPairCandidate(
-                        ipaddress.IPv4Address("10.0.0.2"),
-                        7657,
-                    ),
-                ),
-                path="/app/network/pair?token=timeout",
-                ca_fingerprint_pin="ab" * 16,
-            ),
-            body,
-            private_key,
-        )
-
-    assert str(exc_info.value) == (
-        "Timed out waiting for the pairing response from 10.0.0.1:7657."
-    )
-    assert [target.host for target in attempts] == ["10.0.0.1"]
-    assert len(session.requests) == 1
-    assert session.closed is True
-
-
-@pytest.mark.parametrize("as_role", ["", "peer"])
-def test_main_builds_one_material_set_across_candidate_advance(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-    as_role: str,
-) -> None:
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))
-    monkeypatch.setenv("SOLSTONE_JOURNAL", str(tmp_path / "journal"))
-    nonce = "10000000000000000000000000000031"
-    code = _build_pair_link_v05(
-        ["10.0.0.1", "10.0.0.2"],
-        7657,
-        nonce,
-        "ab" * 32,
-    )
-    build_calls: list[str] = []
-    publish_calls: list[Path] = []
-    sessions = [_FakeSession()]
-    attempts: list[join_cli.PairTarget] = []
-    real_build_csr = join_cli._build_csr
-    _disable_direct_cert_validation(monkeypatch)
-
-    def spy_build_csr(label: str) -> tuple[Any, bytes, str]:
-        build_calls.append(label)
-        return real_build_csr(label)
-
-    async def prepare(
-        target: join_cli.PairTarget,
-        _pin: str,
-    ) -> _FakeSession:
-        attempts.append(target)
-        if len(attempts) == 1:
-            raise ValueError("first candidate not ready")
-        return sessions[0]
-
-    def record_publish(bundle_dir: Path, _files: dict[str, bytes]) -> None:
-        publish_calls.append(bundle_dir)
-
-    monkeypatch.setattr(join_cli, "_build_csr", spy_build_csr)
-    monkeypatch.setattr(join_cli, "_open_ready_pairing_session", prepare)
-    monkeypatch.setattr(join_cli, "_ca_fingerprint", lambda _chain: "sha256:fake")
-    monkeypatch.setattr(join_cli, "_publish_bundle_atomic", record_publish)
-
-    result = join_cli.main(
-        _args(
-            code=code,
-            as_role=as_role or None,
-            label="material-peer" if as_role == "peer" else "material-observer",
-        )
-    )
-
-    assert result == 0
-    assert build_calls == [
-        "material-peer" if as_role == "peer" else "material-observer"
-    ]
-    assert [target.host for target in attempts] == ["10.0.0.1", "10.0.0.2"]
-    assert len(sessions[0].requests) == 1
-    assert len(publish_calls) == 1
-
-
-def _assert_no_pair_secrets(
-    message: str,
-    *,
-    nonce: str,
-    pair_link: str,
-    ca_fp: str,
-    csr: str = "CSR-SECRET",
-) -> None:
-    fragment = pair_link.split("#", 1)[1]
-    request_url = f"/app/network/pair?token={nonce}"
-    assert nonce not in message
-    assert pair_link not in message
-    assert fragment not in message
-    assert request_url not in message
-    assert ca_fp not in message
-    assert csr not in message
-    _single_line(message)
-
-
-def test_wrong_pin_diagnostic_omits_pair_secrets(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "config"))
-    nonce = "10000000000000000000000000000032"
-    ca_fp = "00" * 32
-    with pairing_harness(tmp_path, monkeypatch) as harness:
-        pair_link = harness.pair_link(nonce, ca_fp=ca_fp)
-        harness.seed_nonce(nonce, "laptop")
-        result = join_cli.main(_args(code=pair_link))
-
-    err = capsys.readouterr().err.strip()
-    assert result == 1
-    _assert_no_pair_secrets(err, nonce=nonce, pair_link=pair_link, ca_fp=ca_fp)
-
-
-def test_malformed_response_diagnostic_omits_pair_secrets(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "config"))
-
-    async def handler(reader, writer) -> None:
-        await reader.read()
-        await writer.write(_http_response(b"{not-json"))
-        await writer.close()
-
-    nonce = "10000000000000000000000000000033"
-    with pairing_harness(tmp_path, monkeypatch, handle_stream=handler) as harness:
-        pair_link = harness.pair_link(nonce)
-        result = join_cli.main(_args(code=pair_link))
-
-    err = capsys.readouterr().err.strip()
-    assert result == 1
-    _assert_no_pair_secrets(
-        err,
-        nonce=nonce,
-        pair_link=pair_link,
-        ca_fp=harness.ca.fingerprint_sha256(),
-    )
-
-
-def test_malformed_home_diagnostic_omits_constructed_request_url(
-    monkeypatch: pytest.MonkeyPatch,
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    nonce = "10000000000000000000000000000034"
-    ca_fp = "ab" * 32
-    pair_link = _build_pair_link("10.0.0.42", 7657, nonce, ca_fp)
-    csr = "CSR-SECRET"
-    monkeypatch.setattr(
-        join_cli,
-        "_build_csr",
-        lambda _label: (object(), b"PRIVATE-SECRET", csr),
-    )
-
-    result = join_cli.main(_args(code=pair_link, home="https://receiver.example"))
-
-    err = capsys.readouterr().err.strip()
-    assert result == 1
-    assert err == "Pair-link target missing explicit port."
-    _assert_no_pair_secrets(
-        err,
-        nonce=nonce,
-        pair_link=pair_link,
-        ca_fp=ca_fp,
-        csr=csr,
-    )
-
-
-def test_parse_pair_link_extracts_embedded_ca_pin() -> None:
-    # The pair-link's last 16 bytes (the CA-fp prefix) must be parsed onto the
-    # DirectPairRequest, not discarded. This is the wiring the CSO review flagged.
-    ca_fp = "ab" * 32  # 64 hex chars; only the first 16 bytes are embedded
-    link = _build_pair_link("127.0.0.1", 7657, "f" * 32, ca_fp)
-
-    request = join_cli._parse_pair_link(link, None)
-
-    assert request.ca_fingerprint_pin == "ab" * 16
-
-
-def test_lan_pair_link_hard_fails_on_ca_pin_mismatch(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    # An attacker-substituted home (wrong CA) must fail the join, not warn.
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "config"))
-    nonce = "1000000000000000000000000000000b"
-    wrong_ca_fp = "00" * 32
-    with pairing_harness(tmp_path, monkeypatch) as harness:
-        harness.seed_nonce(nonce, "laptop")
-        result = join_cli.main(_args(code=harness.pair_link(nonce, ca_fp=wrong_ca_fp)))
-
-    err = capsys.readouterr().err.strip()
-    assert result == 1
-    assert err == "Pairing TLS peer did not match the pair-link."
-    _single_line(err)
-    # The credential bundle must not be written on a failed pin check.
-    assert not (tmp_path / "config" / "solstone-observer" / "spl" / "laptop").exists()
-
-
-def test_lan_pair_link_succeeds_with_matching_embedded_ca_pin(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    # The happy path now exercises a real embedded pin (harness default = real
-    # CA fp) plus the defense-in-depth live-peer binding against that CA.
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "config"))
-    nonce = "1000000000000000000000000000000c"
-    with pairing_harness(tmp_path, monkeypatch) as harness:
-        harness.seed_nonce(nonce, "laptop")
-        result = join_cli.main(_args(code=harness.pair_link(nonce)))
-
-    assert result == 0
-    assert (tmp_path / "config" / "solstone-observer" / "spl" / "laptop").is_dir()
-
-
-def test_verify_leaf_signed_by_pinned_ca(tmp_path: Path) -> None:
-    # Defense in depth: the live peer leaf must verify against the pinned CA.
-    ca_a = load_or_generate_ca(tmp_path / "ca_a")
-    ca_b = load_or_generate_ca(tmp_path / "ca_b")
-    leaf_a, _key = issue_server_cert(ca_a)
-
-    # Signed by the matching CA: no raise.
-    join_cli._verify_leaf_signed_by_pinned_ca(leaf_a, ca_a.cert)
-
-    # Signed by a different CA than the one pinned: fail closed.
-    with pytest.raises(ValueError) as exc_info:
-        join_cli._verify_leaf_signed_by_pinned_ca(leaf_a, ca_b.cert)
-    assert "not signed by the pinned CA" in str(exc_info.value)
-
-
-def test_ca_pin_matches_prefix_and_full_and_failclosed() -> None:
-    full = "sha256:" + ("ab" * 32)
-    # Full-length pin compares the whole digest (back-compat with the old API).
-    assert ca_pin_matches(full, "ab" * 32)
-    assert ca_pin_matches(full, "sha256:" + ("ab" * 32))
-    # 16-byte (32-hex) prefix pin — the LAN pair-link form.
-    assert ca_pin_matches(full, "ab" * 16)
-    # Case-insensitive, prefix on either side.
-    assert ca_pin_matches("AB" * 32, "sha256:" + ("ab" * 16))
-    # Mismatch.
-    assert not ca_pin_matches(full, "cd" * 16)
-    # Fail closed: empty, odd-length, and over-long pins.
-    assert not ca_pin_matches(full, "")
-    assert not ca_pin_matches(full, "abc")
-    assert not ca_pin_matches("ab", "abcd")
diff --git a/tests/link/test_link_join_peer_existing_dir.py b/tests/link/test_link_join_peer_existing_dir.py
deleted file mode 100644
index 0c40d0ffb..000000000
--- a/tests/link/test_link_join_peer_existing_dir.py
+++ /dev/null
@@ -1,128 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright (c) 2026 sol pbc
-
-from __future__ import annotations
-
-import argparse
-from pathlib import Path
-
-import pytest
-from cryptography.hazmat.primitives import serialization
-
-from solstone.apps.network.routes import _build_pair_link
-from solstone.think.link import join_cli
-from solstone.think.link.ca import generate_ca
-
-PAIR_LINK = _build_pair_link("10.0.0.42", 7657, "a" * 32, "b" * 64)
-
-
-def _args() -> argparse.Namespace:
-    return argparse.Namespace(
-        home="http://receiver",
-        code=PAIR_LINK,
-        as_role="peer",
-        label="my-peer",
-    )
-
-
-def _pair_response(tmp_path: Path) -> join_cli.PairResponse:
-    ca = generate_ca(tmp_path / "ca")
-    ca_pem = ca.cert.public_bytes(serialization.Encoding.PEM).decode("ascii")
-    return join_cli.PairResponse(
-        client_cert="-----BEGIN CERTIFICATE-----\nclient\n-----END CERTIFICATE-----\n",
-        ca_chain=[ca_pem],
-        instance_id="inst-1",
-        home_label="solstone",
-        home_attestation="header.payload.signature",
-        local_endpoints=[{"host": "127.0.0.1", "port": 7657}],
-    )
-
-
-def _mock_post_pair(
-    monkeypatch: pytest.MonkeyPatch, response: join_cli.PairResponse
-) -> None:
-    monkeypatch.setattr(join_cli, "_post_pair", lambda *_args, **_kwargs: response)
-
-
-def test_existing_peer_dir_refuses(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    journal = tmp_path / "journal"
-    monkeypatch.setenv("SOLSTONE_JOURNAL", str(journal))
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))
-    bundle = journal / "peers" / "inst-1"
-    bundle.mkdir(parents=True)
-    existing = bundle / "private.pem"
-    existing.write_bytes(b"sentinel")
-    before_listing = sorted(path.name for path in bundle.parent.iterdir())
-    _mock_post_pair(monkeypatch, _pair_response(tmp_path))
-
-    result = join_cli.main(_args())
-
-    assert result == 1
-    err = capsys.readouterr().err
-    assert "Credentials path already exists" in err
-    assert str(bundle) in err
-    assert existing.read_bytes() == b"sentinel"
-    assert sorted(path.name for path in bundle.parent.iterdir()) == before_listing
-    for name in join_cli.BUNDLE_FILES - {"private.pem"}:
-        assert not (bundle / name).exists()
-    assert not (tmp_path / "xdg" / "solstone-observer" / "spl" / "my-peer").exists()
-
-
-def test_existing_peer_dir_with_only_ds_store_refuses(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    journal = tmp_path / "journal"
-    monkeypatch.setenv("SOLSTONE_JOURNAL", str(journal))
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))
-    bundle = journal / "peers" / "inst-1"
-    bundle.mkdir(parents=True)
-    ds_store = bundle / ".DS_Store"
-    ds_store.write_text("", encoding="utf-8")
-    _mock_post_pair(monkeypatch, _pair_response(tmp_path))
-
-    result = join_cli.main(_args())
-
-    assert result == 1
-    assert ds_store.exists()
-    assert sorted(path.name for path in bundle.iterdir()) == [".DS_Store"]
-    assert not (tmp_path / "xdg" / "solstone-observer" / "spl" / "my-peer").exists()
-
-
-def test_existing_empty_peer_dir_refuses(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    journal = tmp_path / "journal"
-    monkeypatch.setenv("SOLSTONE_JOURNAL", str(journal))
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))
-    bundle = journal / "peers" / "inst-1"
-    bundle.mkdir(parents=True)
-    _mock_post_pair(monkeypatch, _pair_response(tmp_path))
-
-    result = join_cli.main(_args())
-
-    assert result == 1
-    assert list(bundle.iterdir()) == []
-
-
-def test_existing_peer_symlink_refuses(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    journal = tmp_path / "journal"
-    monkeypatch.setenv("SOLSTONE_JOURNAL", str(journal))
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))
-    bundle = journal / "peers" / "inst-1"
-    bundle.parent.mkdir(parents=True)
-    bundle.symlink_to(tmp_path / "missing")
-    _mock_post_pair(monkeypatch, _pair_response(tmp_path))
-
-    result = join_cli.main(_args())
-
-    assert result == 1
-    assert bundle.is_symlink()
diff --git a/tests/link/test_link_join_peer_happy.py b/tests/link/test_link_join_peer_happy.py
deleted file mode 100644
index 3c7f8f929..000000000
--- a/tests/link/test_link_join_peer_happy.py
+++ /dev/null
@@ -1,102 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright (c) 2026 sol pbc
-
-from __future__ import annotations
-
-import argparse
-import json
-import stat
-from pathlib import Path
-
-import pytest
-from cryptography import x509
-from cryptography.hazmat.primitives import serialization
-
-from solstone.apps.network.routes import _build_pair_link
-from solstone.think.link import join_cli
-from solstone.think.link.ca import generate_ca, sign_csr
-
-PAIR_LINK = _build_pair_link("10.0.0.42", 7657, "a" * 32, "b" * 64)
-
-
-def _args() -> argparse.Namespace:
-    return argparse.Namespace(
-        home="http://receiver",
-        code=PAIR_LINK,
-        as_role="peer",
-        label="my-peer",
-    )
-
-
-def _pair_response(
-    tmp_path: Path,
-    *,
-    csr_pem: str,
-    device_label: str,
-    local_endpoints: list[dict[str, object]] | None = None,
-) -> join_cli.PairResponse:
-    ca = generate_ca(tmp_path / "ca")
-    ca_pem = ca.cert.public_bytes(serialization.Encoding.PEM).decode("ascii")
-    client_cert, _fingerprint = sign_csr(ca, csr_pem, device_label)
-    return join_cli.PairResponse(
-        client_cert=client_cert,
-        ca_chain=[ca_pem],
-        instance_id="inst-1",
-        home_label="solstone",
-        home_attestation="header.payload.signature",
-        local_endpoints=local_endpoints
-        if local_endpoints is not None
-        else [{"host": "127.0.0.1", "port": 7657}],
-    )
-
-
-def _mock_post_pair(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
-    def fake_post_pair(
-        _request: join_cli.DirectPairRequest,
-        body: dict[str, str],
-        _private_key: object,
-    ) -> join_cli.PairResponse:
-        return _pair_response(
-            tmp_path,
-            csr_pem=body["csr"],
-            device_label=body["device_label"],
-            local_endpoints=[{"host": "8.8.8.8", "port": 7657}],
-        )
-
-    monkeypatch.setattr(join_cli, "_post_pair", fake_post_pair)
-
-
-def test_pair_link_happy_path_writes_peer_bundle(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    monkeypatch.setenv("SOLSTONE_JOURNAL", str(tmp_path / "journal"))
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))
-    _mock_post_pair(monkeypatch, tmp_path)
-
-    result = join_cli.main(_args())
-
-    assert result == 0
-    bundle = tmp_path / "journal" / "peers" / "inst-1"
-    assert stat.S_IMODE(bundle.stat().st_mode) == 0o700
-    for name in join_cli.BUNDLE_FILES:
-        assert (bundle / name).exists()
-        assert stat.S_IMODE((bundle / name).stat().st_mode) == 0o600
-    peer = json.loads((bundle / "peer.json").read_text("utf-8"))
-    assert list(peer.keys()) == [
-        "label",
-        "paired_at",
-        "instance_id",
-        "home_label",
-        "fingerprint",
-        "local_endpoints",
-        "role",
-    ]
-    assert peer["role"] == "peer"
-    assert peer["instance_id"] == "inst-1"
-    assert peer["label"] == "my-peer"
-    assert peer["local_endpoints"] == [{"host": "8.8.8.8", "port": 7657}]
-    ca_cert = x509.load_pem_x509_certificate((bundle / "chain.pem").read_bytes())
-    client_cert = x509.load_pem_x509_certificate((bundle / "cert.pem").read_bytes())
-    join_cli._verify_leaf_signed_by_pinned_ca(client_cert, ca_cert)
-    assert not (tmp_path / "xdg" / "solstone-observer" / "spl" / "my-peer").exists()
diff --git a/tests/link/test_link_join_peer_instance_id_validation.py b/tests/link/test_link_join_peer_instance_id_validation.py
deleted file mode 100644
index 6ea2a7beb..000000000
--- a/tests/link/test_link_join_peer_instance_id_validation.py
+++ /dev/null
@@ -1,119 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright (c) 2026 sol pbc
-
-from __future__ import annotations
-
-import argparse
-from pathlib import Path
-
-import pytest
-from cryptography.hazmat.primitives import serialization
-
-from solstone.apps.network.routes import _build_pair_link
-from solstone.think.link import join_cli
-from solstone.think.link.ca import generate_ca
-
-PAIR_LINK = _build_pair_link("10.0.0.42", 7657, "a" * 32, "b" * 64)
-
-
-def _args() -> argparse.Namespace:
-    return argparse.Namespace(
-        home="http://receiver",
-        code=PAIR_LINK,
-        as_role="peer",
-        label="my-peer",
-    )
-
-
-def _pair_response(
-    tmp_path: Path, *, instance_id: str = "inst-1"
-) -> join_cli.PairResponse:
-    ca = generate_ca(tmp_path / "ca")
-    ca_pem = ca.cert.public_bytes(serialization.Encoding.PEM).decode("ascii")
-    return join_cli.PairResponse(
-        client_cert="-----BEGIN CERTIFICATE-----\nclient\n-----END CERTIFICATE-----\n",
-        ca_chain=[ca_pem],
-        instance_id=instance_id,
-        home_label="solstone",
-        home_attestation="header.payload.signature",
-        local_endpoints=[{"host": "127.0.0.1", "port": 7657}],
-    )
-
-
-def _mock_post_pair(
-    monkeypatch: pytest.MonkeyPatch, response: join_cli.PairResponse
-) -> None:
-    monkeypatch.setattr(join_cli, "_post_pair", lambda *_args, **_kwargs: response)
-
-
-def _set_env(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
-    monkeypatch.setenv("SOLSTONE_JOURNAL", str(tmp_path / "journal"))
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))
-
-
-def _observer_dir(tmp_path: Path) -> Path:
-    return tmp_path / "xdg" / "solstone-observer" / "spl" / "my-peer"
-
-
-def test_traversal_instance_id_rejected(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    _set_env(tmp_path, monkeypatch)
-    _mock_post_pair(monkeypatch, _pair_response(tmp_path, instance_id="../escape"))
-
-    result = join_cli.main(_args())
-
-    assert result == 1
-    assert "bad instance_id from receiver" in capsys.readouterr().err
-    assert not (tmp_path / "journal" / "peers").exists()
-    assert not _observer_dir(tmp_path).exists()
-
-
-def test_oversize_instance_id_rejected(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    _set_env(tmp_path, monkeypatch)
-    _mock_post_pair(monkeypatch, _pair_response(tmp_path, instance_id="x" * 257))
-
-    result = join_cli.main(_args())
-
-    assert result == 1
-    assert "bad instance_id from receiver" in capsys.readouterr().err
-    assert not (tmp_path / "journal" / "peers").exists()
-    assert not _observer_dir(tmp_path).exists()
-
-
-def test_trailing_newline_instance_id_rejected(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    _set_env(tmp_path, monkeypatch)
-    _mock_post_pair(monkeypatch, _pair_response(tmp_path, instance_id="abc123\n"))
-
-    result = join_cli.main(_args())
-
-    assert result == 1
-    assert "bad instance_id from receiver" in capsys.readouterr().err
-    assert not (tmp_path / "journal" / "peers").exists()
-    assert not _observer_dir(tmp_path).exists()
-
-
-def test_alnum_dash_instance_id_accepted(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    _set_env(tmp_path, monkeypatch)
-    _mock_post_pair(monkeypatch, _pair_response(tmp_path, instance_id="abc123-def-456"))
-
-    result = join_cli.main(_args())
-
-    assert result == 0
-    bundle = tmp_path / "journal" / "peers" / "abc123-def-456"
-    for name in join_cli.BUNDLE_FILES:
-        assert (bundle / name).exists()
-    assert not _observer_dir(tmp_path).exists()
diff --git a/tests/link/test_link_join_peer_sends_instance_id.py b/tests/link/test_link_join_peer_sends_instance_id.py
deleted file mode 100644
index 7aa0985b8..000000000
--- a/tests/link/test_link_join_peer_sends_instance_id.py
+++ /dev/null
@@ -1,4 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright (c) 2026 sol pbc
-
-from __future__ import annotations
diff --git a/tests/link/test_link_join_publication.py b/tests/link/test_link_join_publication.py
deleted file mode 100644
index 0f1aa01d0..000000000
--- a/tests/link/test_link_join_publication.py
+++ /dev/null
@@ -1,92 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright (c) 2026 sol pbc
-
-from __future__ import annotations
-
-import os
-import stat
-from pathlib import Path
-
-import pytest
-
-from solstone.think.link import join_cli
-
-
-def _files() -> dict[str, bytes]:
-    return {name: f"{name}\n".encode("utf-8") for name in sorted(join_cli.BUNDLE_FILES)}
-
-
-@pytest.mark.parametrize("fail_index", range(len(join_cli.BUNDLE_FILES)))
-def test_atomic_publish_file_failure_leaves_no_final_or_staging(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-    fail_index: int,
-) -> None:
-    files = _files()
-    final = tmp_path / "bundle"
-    real_write = join_cli._write_bundle_file
-    writes = 0
-
-    def fail_at_position(path: Path, content: bytes) -> None:
-        nonlocal writes
-        if writes == fail_index:
-            raise OSError(f"fail write {path.name}")
-        writes += 1
-        real_write(path, content)
-
-    monkeypatch.setattr(join_cli, "_write_bundle_file", fail_at_position)
-
-    with pytest.raises(OSError, match="fail write"):
-        join_cli._publish_bundle_atomic(final, files)
-
-    assert not os.path.lexists(final)
-    assert list(tmp_path.iterdir()) == []
-
-
-def test_atomic_publish_rename_failure_leaves_no_final_or_staging(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    final = tmp_path / "bundle"
-
-    def fail_rename(_src: object, _dst: object) -> None:
-        raise OSError("rename failed")
-
-    monkeypatch.setattr(join_cli.os, "rename", fail_rename)
-
-    with pytest.raises(OSError, match="rename failed"):
-        join_cli._publish_bundle_atomic(final, _files())
-
-    assert not os.path.lexists(final)
-    assert list(tmp_path.iterdir()) == []
-
-
-def test_atomic_publish_non_oserror_failure_leaves_no_final_or_staging(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    final = tmp_path / "bundle"
-
-    def fail_write(_path: Path, _content: bytes) -> None:
-        raise RuntimeError("unexpected write failure")
-
-    monkeypatch.setattr(join_cli, "_write_bundle_file", fail_write)
-
-    with pytest.raises(RuntimeError, match="unexpected write failure"):
-        join_cli._publish_bundle_atomic(final, _files())
-
-    assert not os.path.lexists(final)
-    assert list(tmp_path.iterdir()) == []
-
-
-def test_atomic_publish_success_sets_directory_and_file_modes(tmp_path: Path) -> None:
-    final = tmp_path / "bundle"
-
-    join_cli._publish_bundle_atomic(final, _files())
-
-    assert stat.S_IMODE(final.stat().st_mode) == 0o700
-    assert sorted(path.name for path in final.iterdir()) == sorted(
-        join_cli.BUNDLE_FILES
-    )
-    for path in final.iterdir():
-        assert stat.S_IMODE(path.stat().st_mode) == 0o600
diff --git a/tests/link/test_link_join_refusals.py b/tests/link/test_link_join_refusals.py
deleted file mode 100644
index 9f1ba27b1..000000000
--- a/tests/link/test_link_join_refusals.py
+++ /dev/null
@@ -1,235 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright (c) 2026 sol pbc
-
-from __future__ import annotations
-
-import argparse
-import ipaddress
-
-import pytest
-
-from solstone.apps.network.copy import PAIR_LINK_HOST, PAIR_LINK_PATH
-from solstone.apps.network.crockford32 import encode as crockford_encode
-from solstone.apps.network.routes import _build_pair_link, _build_pair_link_v05
-from solstone.think.link import join_cli
-
-
-def _args(code: str, *, home: str | None = None) -> argparse.Namespace:
-    return argparse.Namespace(home=home, code=code, as_role=None, label="laptop")
-
-
-def _link_from_blob(blob: bytes) -> str:
-    return f"https://{PAIR_LINK_HOST}{PAIR_LINK_PATH}#{crockford_encode(blob)}"
-
-
-def _v04_blob(
-    *,
-    addr_type: int = 0x01,
-    host: str = "10.0.0.42",
-    port: int = 7657,
-    nonce: str = "a1b2c3d4e5f607181122334455667788",
-    ca_fp: str = "deadbeefcafebabe0123456789abcdef",
-) -> bytes:
-    return (
-        b"\x04"
-        + bytes([addr_type])
-        + ipaddress.IPv4Address(host).packed
-        + port.to_bytes(2, "big")
-        + bytes.fromhex(nonce)
-        + bytes.fromhex(ca_fp)[:16]
-    )
-
-
-def _v05_blob(
-    candidates: list[str],
-    *,
-    addr_type: int = 0x01,
-    count: int | None = None,
-    port: int = 7657,
-    nonce: str = "a1b2c3d4e5f607181122334455667788",
-    ca_fp: str = "deadbeefcafebabe0123456789abcdef",
-) -> bytes:
-    encoded_count = len(candidates) if count is None else count
-    return (
-        b"\x05"
-        + bytes([addr_type, encoded_count])
-        + port.to_bytes(2, "big")
-        + b"".join(ipaddress.IPv4Address(candidate).packed for candidate in candidates)
-        + bytes.fromhex(nonce)
-        + bytes.fromhex(ca_fp)[:16]
-    )
-
-
-def test_direct_v04_parse_returns_one_candidate_collection() -> None:
-    nonce = "a1b2c3d4e5f607181122334455667788"
-    pair_link = _build_pair_link(
-        "10.0.0.42",
-        7657,
-        nonce,
-        "deadbeefcafebabe0123456789abcdef",
-    )
-
-    request = join_cli._parse_pair_link(pair_link, None)
-
-    assert isinstance(request, join_cli.DirectPairRequest)
-    assert request.candidates == (
-        join_cli.DirectPairCandidate(ipaddress.IPv4Address("10.0.0.42"), 7657),
-    )
-    assert request.path == f"/app/network/pair?token={nonce}"
-    assert request.ca_fingerprint_pin == "deadbeefcafebabe0123456789abcdef"
-
-
-def test_direct_v05_parse_returns_ordered_shared_semantics() -> None:
-    nonce = "b1b2c3d4e5f607181122334455667788"
-    pair_link = _build_pair_link_v05(
-        ["10.0.0.42", "100.64.0.1"],
-        7657,
-        nonce,
-        "cafebabedeadbeef0123456789abcdef",
-    )
-
-    request = join_cli._parse_pair_link(pair_link, None)
-
-    assert isinstance(request, join_cli.DirectPairRequest)
-    assert [candidate.host for candidate in request.candidates] == [
-        "10.0.0.42",
-        "100.64.0.1",
-    ]
-    assert {candidate.port for candidate in request.candidates} == {7657}
-    assert request.path == f"/app/network/pair?token={nonce}"
-    assert request.ca_fingerprint_pin == "cafebabedeadbeef0123456789abcdef"
-
-
-@pytest.mark.parametrize(
-    "blob",
-    [
-        _v04_blob(addr_type=0x02),
-        _v04_blob()[:-1],
-        _v04_blob() + b"\x00",
-        _v05_blob(["10.0.0.1"], addr_type=0x02),
-        _v05_blob([], count=0),
-        _v05_blob(
-            ["10.0.0.1", "10.0.0.2", "10.0.0.3", "10.0.0.4", "10.0.0.5"],
-            count=5,
-        ),
-        _v05_blob(["10.0.0.1"])[:-1],
-        _v05_blob(["10.0.0.1"]) + b"\x00",
-    ],
-)
-def test_direct_pair_link_structural_failures_refuse(blob: bytes) -> None:
-    with pytest.raises(ValueError, match="Malformed pair-link"):
-        join_cli._parse_pair_link(_link_from_blob(blob), None)
-
-
-def test_v05_rfc1918_plus_cgnat_admitted_as_whole() -> None:
-    pair_link = _build_pair_link_v05(
-        ["192.168.1.2", "100.127.255.255"],
-        7657,
-        "a1b2c3d4e5f607181122334455667788",
-        "deadbeefcafebabe0123456789abcdef",
-    )
-
-    request = join_cli._parse_pair_link(pair_link, None)
-
-    assert isinstance(request, join_cli.DirectPairRequest)
-    assert [candidate.host for candidate in request.candidates] == [
-        "192.168.1.2",
-        "100.127.255.255",
-    ]
-
-
-def test_v05_rfc1918_plus_test_net_refuses_as_whole() -> None:
-    pair_link = _build_pair_link_v05(
-        ["192.168.1.2", "203.0.113.9"],
-        7657,
-        "a1b2c3d4e5f607181122334455667788",
-        "deadbeefcafebabe0123456789abcdef",
-    )
-
-    with pytest.raises(ValueError, match="outside the local network"):
-        join_cli._parse_pair_link(pair_link, None)
-
-
-def test_canonical_test_net_decodes_then_refuses_before_materials(
-    monkeypatch: pytest.MonkeyPatch,
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    nonce = "a1b2c3d4e5f607181122334455667788"
-    pair_link = _build_pair_link(
-        "192.0.2.42",
-        7657,
-        nonce,
-        "deadbeefcafebabe0123456789abcdef",
-    )
-    material_calls: list[object] = []
-
-    def fail_build_csr(*args: object, **kwargs: object) -> None:
-        material_calls.append((args, kwargs))
-        raise AssertionError("key generation should not run")
-
-    monkeypatch.setattr(join_cli, "_build_csr", fail_build_csr)
-
-    result = join_cli.main(_args(pair_link))
-
-    err = capsys.readouterr().err.strip()
-    assert result == 1
-    assert "outside the local network" in err
-    assert material_calls == []
-
-
-def test_disallowed_embedded_set_cannot_be_rescued_by_home(
-    monkeypatch: pytest.MonkeyPatch,
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    pair_link = _build_pair_link_v05(
-        ["10.0.0.42", "203.0.113.9"],
-        7657,
-        "a1b2c3d4e5f607181122334455667788",
-        "deadbeefcafebabe0123456789abcdef",
-    )
-    material_calls: list[object] = []
-    monkeypatch.setattr(join_cli, "_build_csr", lambda *_args: material_calls.append(1))
-
-    result = join_cli.main(_args(pair_link, home="https://receiver.example:7657"))
-
-    assert result == 1
-    assert "outside the local network" in capsys.readouterr().err
-    assert material_calls == []
-
-
-def test_admitted_embedded_set_with_home_dials_only_override() -> None:
-    pair_link = _build_pair_link_v05(
-        ["10.0.0.42", "100.64.0.1"],
-        7657,
-        "a1b2c3d4e5f607181122334455667788",
-        "deadbeefcafebabe0123456789abcdef",
-    )
-
-    request = join_cli._parse_pair_link(pair_link, "https://receiver.example:9443")
-
-    assert isinstance(request, join_cli.DirectPairRequest)
-    assert join_cli._dial_targets(request) == (
-        join_cli.PairTarget(
-            host="receiver.example",
-            port=9443,
-            path="/app/network/pair?token=a1b2c3d4e5f607181122334455667788",
-        ),
-    )
-
-
-def test_pair_code_error_names_pair_link_form() -> None:
-    with pytest.raises(ValueError) as exc_info:
-        join_cli._parse_pair_request("not-a-code", None)
-
-    message = str(exc_info.value)
-    assert "pair-link" in message
-
-
-def test_malformed_pair_link_error_is_distinct() -> None:
-    with pytest.raises(ValueError) as exc_info:
-        join_cli._parse_pair_request(
-            f"https://{PAIR_LINK_HOST}{PAIR_LINK_PATH}#!",
-            None,
-        )
-
-    assert "Malformed pair-link" in str(exc_info.value)
diff --git a/tests/link/test_link_join_relay.py b/tests/link/test_link_join_relay.py
deleted file mode 100644
index 2cbcfcfab..000000000
--- a/tests/link/test_link_join_relay.py
+++ /dev/null
@@ -1,309 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright (c) 2026 sol pbc
-
-from __future__ import annotations
-
-import hashlib
-import json
-from pathlib import Path
-
-import pytest
-from cryptography import x509
-from cryptography.hazmat.primitives import serialization
-
-from solstone.apps.network.relay_link import (
-    decode_pair_window_link,
-    derive_rk,
-    encode_pair_window_link,
-)
-from solstone.think.link import join_cli
-from solstone.think.link.ca import LoadedCa, load_or_generate_ca, sign_csr
-from solstone.think.link.client import ClientIdentity
-from solstone.think.link.mark import jid_from_spki
-from solstone.think.link.paths import DEFAULT_RELAY_URL
-
-S = bytes.fromhex("0123456789abcdef")
-CA_FP_SPKI = "deadbeefcafebabe0123456789abcdef"
-
-
-def _spki_der(ca: LoadedCa) -> bytes:
-    return ca.cert.public_key().public_bytes(
-        serialization.Encoding.DER,
-        serialization.PublicFormat.SubjectPublicKeyInfo,
-    )
-
-
-def _signed_leaf(
-    ca: LoadedCa, label: str = "relay-client"
-) -> tuple[str, x509.Certificate]:
-    _private_key, _private_key_pem, csr_pem = join_cli._build_csr(label)
-    cert_pem, _fingerprint = sign_csr(ca, csr_pem, label)
-    leaf = x509.load_pem_x509_certificate(cert_pem.encode("ascii"))
-    return cert_pem, leaf
-
-
-def _ca_pem(ca: LoadedCa) -> str:
-    return ca.cert.public_bytes(serialization.Encoding.PEM).decode("ascii")
-
-
-def _pair_response(
-    ca: LoadedCa,
-    client_cert: str,
-    *,
-    instance_id: str,
-) -> join_cli.PairResponse:
-    return join_cli.PairResponse(
-        client_cert=client_cert,
-        ca_chain=[_ca_pem(ca)],
-        instance_id=instance_id,
-        home_label="solstone",
-        home_attestation="header.payload.signature",
-        local_endpoints=[
-            {"host": "127.0.0.1", "port": 7657},
-            {"host": "8.8.8.8", "port": 7657},
-        ],
-    )
-
-
-def _relay_request() -> join_cli.RelayPairRequest:
-    return join_cli.RelayPairRequest(
-        relay_endpoint="https://relay.example",
-        rk=derive_rk(S),
-        s=S,
-        ca_fp_spki=bytes.fromhex(CA_FP_SPKI),
-        inner_path=f"/app/network/pair?token={S.hex()}",
-    )
-
-
-def test_parse_relay_pair_link_default_origin() -> None:
-    link = encode_pair_window_link(S, CA_FP_SPKI, relay_origin=None)
-
-    req = join_cli._parse_pair_request(link, None)
-
-    assert isinstance(req, join_cli.RelayPairRequest)
-    assert req.relay_endpoint == DEFAULT_RELAY_URL
-    assert req.s == S
-    assert req.rk == derive_rk(S)
-    assert req.ca_fp_spki == bytes.fromhex(CA_FP_SPKI)
-    assert req.inner_path == f"/app/network/pair?token={S.hex()}"
-
-
-def test_parse_relay_pair_link_custom_origin() -> None:
-    link = encode_pair_window_link(
-        S,
-        CA_FP_SPKI,
-        relay_origin="https://relay.example",
-    )
-    parsed = decode_pair_window_link(link)
-
-    req = join_cli._parse_pair_request(link, None)
-
-    assert parsed.relay_origin == "https://relay.example"
-    assert isinstance(req, join_cli.RelayPairRequest)
-    assert req.relay_endpoint == "https://relay.example"
-    assert req.s == S
-    assert req.rk == derive_rk(S)
-    assert req.inner_path == f"/app/network/pair?token={S.hex()}"
-
-
-def test_relay_pair_link_dispatch_does_not_touch_direct_decoder_or_policy(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    link = encode_pair_window_link(S, CA_FP_SPKI, relay_origin="https://relay.example")
-
-    def fail_direct(*_args: object, **_kwargs: object) -> object:
-        raise AssertionError("relay dispatch should not touch direct path")
-
-    monkeypatch.setattr(join_cli, "_decode_direct_pair_blob", fail_direct)
-    monkeypatch.setattr(join_cli, "is_direct_pair_candidate_allowed", fail_direct)
-
-    req = join_cli._parse_pair_request(link, None)
-
-    assert isinstance(req, join_cli.RelayPairRequest)
-
-
-def test_verify_relay_pair_accepts_matching_pin_leaf_and_jid(tmp_path: Path) -> None:
-    ca = load_or_generate_ca(tmp_path / "ca")
-    client_cert, leaf = _signed_leaf(ca)
-    spki_der = _spki_der(ca)
-    response = _pair_response(
-        ca,
-        client_cert,
-        instance_id=str(jid_from_spki(spki_der)),
-    )
-
-    join_cli._verify_relay_pair(
-        response,
-        leaf,
-        hashlib.sha256(spki_der).digest()[:16],
-    )
-
-
-def test_verify_relay_pair_rejects_wrong_spki_pin(tmp_path: Path) -> None:
-    ca = load_or_generate_ca(tmp_path / "ca")
-    client_cert, leaf = _signed_leaf(ca)
-    spki_der = _spki_der(ca)
-    response = _pair_response(
-        ca,
-        client_cert,
-        instance_id=str(jid_from_spki(spki_der)),
-    )
-
-    with pytest.raises(ValueError, match="CA fingerprint mismatch"):
-        join_cli._verify_relay_pair(response, leaf, b"\x00" * 16)
-
-
-def test_verify_relay_pair_rejects_leaf_from_different_ca(tmp_path: Path) -> None:
-    ca = load_or_generate_ca(tmp_path / "ca")
-    other_ca = load_or_generate_ca(tmp_path / "other-ca")
-    client_cert, _leaf = _signed_leaf(ca)
-    _other_cert, other_leaf = _signed_leaf(other_ca)
-    spki_der = _spki_der(ca)
-    response = _pair_response(
-        ca,
-        client_cert,
-        instance_id=str(jid_from_spki(spki_der)),
-    )
-
-    with pytest.raises(ValueError, match="not signed by the pinned CA"):
-        join_cli._verify_relay_pair(
-            response,
-            other_leaf,
-            hashlib.sha256(spki_der).digest()[:16],
-        )
-
-
-def test_verify_relay_pair_rejects_wrong_instance_id(tmp_path: Path) -> None:
-    ca = load_or_generate_ca(tmp_path / "ca")
-    client_cert, leaf = _signed_leaf(ca)
-    spki_der = _spki_der(ca)
-    response = _pair_response(
-        ca,
-        client_cert,
-        instance_id="00000000-0000-4000-8000-000000000000",
-    )
-
-    with pytest.raises(ValueError, match="instance_id does not match"):
-        join_cli._verify_relay_pair(
-            response,
-            leaf,
-            hashlib.sha256(spki_der).digest()[:16],
-        )
-
-
-def test_verify_relay_pair_rejects_missing_peer_leaf(tmp_path: Path) -> None:
-    ca = load_or_generate_ca(tmp_path / "ca")
-    client_cert, _leaf = _signed_leaf(ca)
-    spki_der = _spki_der(ca)
-    response = _pair_response(
-        ca,
-        client_cert,
-        instance_id=str(jid_from_spki(spki_der)),
-    )
-
-    with pytest.raises(ValueError, match="presented no certificate"):
-        join_cli._verify_relay_pair(
-            response,
-            None,
-            hashlib.sha256(spki_der).digest()[:16],
-        )
-
-
-def test_join_via_relay_enrolls_then_writes_observer_bundle(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))
-    monkeypatch.setenv("SOLSTONE_JOURNAL", str(tmp_path / "journal"))
-    ca = load_or_generate_ca(tmp_path / "ca")
-    client_cert, _leaf = _signed_leaf(ca)
-    spki_der = _spki_der(ca)
-    response = _pair_response(
-        ca,
-        client_cert,
-        instance_id=str(jid_from_spki(spki_der)),
-    )
-    req = _relay_request()
-    enroll_calls: list[tuple[str, ClientIdentity]] = []
-
-    def _record_post_pair(
-        actual_req: join_cli.RelayPairRequest,
-        body: dict[str, str],
-    ) -> join_cli.PairResponse:
-        assert actual_req is req
-        assert body["device_label"] == "relay-laptop"
-        assert "sender_instance_id" not in body
-        assert body["csr"].startswith("-----BEGIN CERTIFICATE REQUEST-----")
-        return response
-
-    def _record_enroll(relay_endpoint: str, identity: ClientIdentity) -> object:
-        enroll_calls.append((relay_endpoint, identity))
-        return object()
-
-    monkeypatch.setattr(join_cli, "_post_pair_relay", _record_post_pair)
-    monkeypatch.setattr(
-        join_cli.Client,
-        "enroll_device",
-        staticmethod(_record_enroll),
-    )
-
-    result = join_cli._join_via_relay(req, "relay-laptop", "")
-
-    assert result == 0
-    assert len(enroll_calls) == 1
-    relay_endpoint, identity = enroll_calls[0]
-    assert relay_endpoint == req.relay_endpoint
-    assert identity.home_instance_id == response.instance_id
-    assert identity.home_label == "solstone"
-    assert identity.client_cert_pem == response.client_cert
-    bundle = tmp_path / "xdg" / "solstone-observer" / "spl" / "relay-laptop"
-    assert sorted(path.name for path in bundle.iterdir()) == sorted(
-        join_cli.BUNDLE_FILES
-    )
-    peer = json.loads((bundle / "peer.json").read_text("utf-8"))
-    assert peer["label"] == "relay-laptop"
-    assert peer["instance_id"] == response.instance_id
-    assert peer["home_label"] == "solstone"
-    assert peer["fingerprint"] == join_cli._ca_fingerprint(
-        join_cli._join_chain(response.ca_chain)
-    )
-    assert peer["local_endpoints"] == response.local_endpoints
-    assert peer["role"] == ""
-
-
-def test_join_via_relay_does_not_write_bundle_when_enroll_rejects(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))
-    monkeypatch.setenv("SOLSTONE_JOURNAL", str(tmp_path / "journal"))
-    ca = load_or_generate_ca(tmp_path / "ca")
-    client_cert, _leaf = _signed_leaf(ca)
-    spki_der = _spki_der(ca)
-    response = _pair_response(
-        ca,
-        client_cert,
-        instance_id=str(jid_from_spki(spki_der)),
-    )
-    req = _relay_request()
-
-    def _reject_enroll(_relay_endpoint: str, _identity: ClientIdentity) -> object:
-        raise RuntimeError("denied")
-
-    monkeypatch.setattr(
-        join_cli,
-        "_post_pair_relay",
-        lambda _req, _body: response,
-    )
-    monkeypatch.setattr(
-        join_cli.Client,
-        "enroll_device",
-        staticmethod(_reject_enroll),
-    )
-
-    result = join_cli._join_via_relay(req, "relay-laptop", "")
-
-    assert result == 1
-    assert not (
-        tmp_path / "xdg" / "solstone-observer" / "spl" / "relay-laptop"
-    ).exists()
diff --git a/tests/link/test_link_serve.py b/tests/link/test_link_serve.py
deleted file mode 100644
index 856aaf4fb..000000000
--- a/tests/link/test_link_serve.py
+++ /dev/null
@@ -1,441 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright (c) 2026 sol pbc
-
-from __future__ import annotations
-
-import argparse
-import http.client
-import logging
-import queue
-import socket
-import threading
-from concurrent.futures import Future
-from pathlib import Path
-
-import pytest
-
-from solstone.think.link import serve_cli
-from solstone.think.link.client import BodySource
-from solstone.think.link.dialer import (
-    TunnelLifecycleError,
-    TunnelRequestError,
-    TunnelResponseHead,
-)
-from solstone.think.link.paths import DEFAULT_RELAY_URL
-
-
-class _StubTunnel:
-    def __init__(
-        self,
-        items: list[TunnelResponseHead | bytes | Exception | None],
-    ) -> None:
-        self.items = items
-        self.requests: list[tuple[str, str, dict[str, str], bytes | BodySource]] = []
-        self.consumed_bodies: list[bytes] = []
-        self.queue_maxsizes: list[int] = []
-
-    def proxy_stream_request(
-        self,
-        method: str,
-        path: str,
-        *,
-        headers: dict[str, str] | None = None,
-        body: bytes | BodySource = b"",
-        chunks: queue.Queue[TunnelResponseHead | bytes | Exception | None],
-    ) -> Future[None]:
-        self.requests.append((method, path, headers or {}, body))
-        self.queue_maxsizes.append(chunks.maxsize)
-        future: Future[None] = Future()
-
-        def run() -> None:
-            self.consumed_bodies.append(_collect_body(body))
-            for item in self.items:
-                chunks.put(item)
-            future.set_result(None)
-
-        threading.Thread(target=run, daemon=True).start()
-        return future
-
-    def status(self) -> dict[str, object]:
-        return {
-            "health": "healthy",
-            "state": "connected",
-            "manager_alive": True,
-            "connected_age_seconds": 12.0,
-            "last_connected_at": 1_800_000_000.0,
-            "last_failure": None,
-            "next_retry_at": None,
-            "reconnect_count": 0,
-            "active_requests": 0,
-        }
-
-
-def _collect_body(body: bytes | BodySource) -> bytes:
-    if isinstance(body, BodySource):
-        return b"".join(body.chunks)
-    return body
-
-
-def _start_server(tunnel: object) -> tuple[serve_cli._ProxyServer, threading.Thread]:
-    server = serve_cli._build_server(0, tunnel)
-    thread = threading.Thread(target=server.serve_forever, daemon=True)
-    thread.start()
-    return server, thread
-
-
-def _stop_server(server: serve_cli._ProxyServer, thread: threading.Thread) -> None:
-    server.shutdown()
-    server.server_close()
-    thread.join(timeout=2)
-
-
-def _connection(server: serve_cli._ProxyServer) -> http.client.HTTPConnection:
-    return http.client.HTTPConnection(
-        serve_cli.LOOPBACK_HOST,
-        server.server_address[1],
-        timeout=2,
-    )
-
-
-def _configure_xdg(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
-    xdg = tmp_path / "xdg"
-    monkeypatch.setenv("XDG_CONFIG_HOME", str(xdg))
-    return xdg / "solstone-observer" / "spl"
-
-
-def test_serve_request_mapping() -> None:
-    tunnel = _StubTunnel(
-        [
-            TunnelResponseHead(201, {"Content-Length": "2", "X-Test": "yes"}),
-            b"ok",
-            None,
-        ]
-    )
-    server, thread = _start_server(tunnel)
-    try:
-        conn = _connection(server)
-        conn.request(
-            "POST",
-            "/app/path?x=1",
-            body=b"hello",
-            headers={
-                "Authorization": "Bearer secret",
-                "Content-Length": "5",
-                "X-Keep": "value",
-            },
-        )
-        response = conn.getresponse()
-        body = response.read()
-        conn.close()
-    finally:
-        _stop_server(server, thread)
-
-    assert response.status == 201
-    assert response.getheader("X-Test") == "yes"
-    assert body == b"ok"
-    method, path, headers, forwarded_body = tunnel.requests[0]
-    assert method == "POST"
-    assert path == "/app/path?x=1"
-    assert isinstance(forwarded_body, BodySource)
-    assert forwarded_body.length == 5
-    assert tunnel.consumed_bodies == [b"hello"]
-    assert tunnel.queue_maxsizes == [serve_cli.RESPONSE_QUEUE_MAX_ITEMS]
-    assert headers["Content-Length"] == "5"
-    assert headers["Host"] == f"{serve_cli.LOOPBACK_HOST}:{server.server_address[1]}"
-    assert headers["X-Keep"] == "value"
-    assert "Authorization" not in headers
-
-
-def test_serve_streaming_incremental() -> None:
-    release = threading.Event()
-    produced_b = threading.Event()
-
-    class StreamingTunnel:
-        def proxy_stream_request(
-            self,
-            _method: str,
-            _path: str,
-            *,
-            headers: dict[str, str] | None = None,
-            body: bytes | BodySource = b"",
-            chunks: queue.Queue[TunnelResponseHead | bytes | Exception | None],
-        ) -> Future[None]:
-            _ = (headers, body)
-            future: Future[None] = Future()
-
-            def run() -> None:
-                chunks.put(TunnelResponseHead(200, {"Transfer-Encoding": "chunked"}))
-                chunks.put(b"1\r\nA\r\n")
-                release.wait(timeout=2)
-                produced_b.set()
-                chunks.put(b"1\r\nB\r\n0\r\n\r\n")
-                chunks.put(None)
-                future.set_result(None)
-
-            threading.Thread(target=run, daemon=True).start()
-            return future
-
-    server, thread = _start_server(StreamingTunnel())
-    try:
-        conn = _connection(server)
-        conn.request("GET", "/events")
-        response = conn.getresponse()
-        assert response.status == 200
-        assert response.read(1) == b"A"
-        assert not produced_b.is_set()
-        release.set()
-        assert response.read(1) == b"B"
-        assert response.read() == b""
-        conn.close()
-    finally:
-        release.set()
-        _stop_server(server, thread)
-
-
-def test_serve_rejects_transfer_encoding_before_tunnel(
-    caplog: pytest.LogCaptureFixture,
-) -> None:
-    tunnel = _StubTunnel([TunnelResponseHead(200, {"Content-Length": "0"}), None])
-    server, thread = _start_server(tunnel)
-    caplog.set_level(logging.WARNING, logger=serve_cli.LOG.name)
-    try:
-        with socket.create_connection(
-            (serve_cli.LOOPBACK_HOST, server.server_address[1]),
-            timeout=2,
-        ) as sock:
-            sock.sendall(
-                b"POST /chunked HTTP/1.1\r\n"
-                b"Host: localhost\r\n"
-                b"Transfer-Encoding: chunked\r\n\r\n"
-                b"1\r\nx\r\n0\r\n\r\n"
-            )
-            response = sock.recv(4096)
-    finally:
-        _stop_server(server, thread)
-
-    assert b"400" in response
-    assert tunnel.requests == []
-    assert "Transfer-Encoding" in caplog.text
-
-
-def test_serve_times_out_waiting_for_response_head(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    returned_future: Future[None] = Future()
-
-    class HangingTunnel:
-        def proxy_stream_request(
-            self,
-            _method: str,
-            _path: str,
-            *,
-            headers: dict[str, str] | None = None,
-            body: bytes | BodySource = b"",
-            chunks: queue.Queue[TunnelResponseHead | bytes | Exception | None],
-        ) -> Future[None]:
-            _ = (headers, body, chunks)
-            return returned_future
-
-    monkeypatch.setattr(serve_cli, "RESPONSE_HEAD_TIMEOUT_SECONDS", 0.05)
-    server, thread = _start_server(HangingTunnel())
-    try:
-        conn = _connection(server)
-        conn.request("GET", "/hang")
-        response = conn.getresponse()
-        body = response.read()
-        conn.close()
-    finally:
-        _stop_server(server, thread)
-
-    assert response.status == 502
-    assert b"TimeoutError" in body
-    assert returned_future.cancelled()
-
-
-def test_serve_status_path_is_local_json() -> None:
-    tunnel = _StubTunnel([TunnelResponseHead(200, {"Content-Length": "0"}), None])
-    server, thread = _start_server(tunnel)
-    try:
-        conn = _connection(server)
-        conn.request("GET", serve_cli.STATUS_PATH)
-        response = conn.getresponse()
-        payload = response.read()
-        conn.close()
-    finally:
-        _stop_server(server, thread)
-
-    assert response.status == 200
-    assert response.getheader("Content-Type") == "application/json"
-    assert b'"health": "healthy"' in payload
-    assert b'"state": "connected"' in payload
-    assert b"secret" not in payload.lower()
-    assert tunnel.requests == []
-
-
-def test_serve_lifecycle_error_is_retryable_json() -> None:
-    tunnel = _StubTunnel(
-        [
-            TunnelLifecycleError("connecting", "no live tunnel session available"),
-            None,
-        ]
-    )
-    server, thread = _start_server(tunnel)
-    try:
-        conn = _connection(server)
-        conn.request("GET", "/app/path?token=secret")
-        response = conn.getresponse()
-        payload = response.read()
-        conn.close()
-    finally:
-        _stop_server(server, thread)
-
-    assert response.status == 503
-    assert response.getheader("Content-Type") == "application/json"
-    assert b'"error": "link_lifecycle"' in payload
-    assert b'"retryable": true' in payload
-    assert b'"state": "connecting"' in payload
-    assert b"secret" not in payload
-
-
-def test_serve_midstream_failure() -> None:
-    tunnel = _StubTunnel(
-        [
-            TunnelResponseHead(200, {"Content-Length": "6"}),
-            b"abc",
-            ConnectionError("lost"),
-            None,
-        ]
-    )
-    server, thread = _start_server(tunnel)
-    try:
-        conn = _connection(server)
-        conn.request("GET", "/broken")
-        response = conn.getresponse()
-        assert response.status == 200
-        with pytest.raises(http.client.IncompleteRead):
-            response.read()
-        conn.close()
-    finally:
-        _stop_server(server, thread)
-
-
-def test_serve_bundle_resolution(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    root = _configure_xdg(tmp_path, monkeypatch)
-    valid = {"solo"}
-    (root / "solo").mkdir(parents=True)
-
-    def fake_load(bundle_dir: Path) -> object:
-        if bundle_dir.name not in valid:
-            raise ValueError("invalid")
-        return object()
-
-    monkeypatch.setattr(serve_cli, "load_client_identity", fake_load)
-
-    selection = serve_cli._resolve_bundle_dir(None)
-    assert selection.label == "solo"
-    assert selection.bundle_dir == root / "solo"
-
-    valid.update({"alpha", "beta"})
-    (root / "alpha").mkdir()
-    (root / "beta").mkdir()
-    with pytest.raises(ValueError) as multiple:
-        serve_cli._resolve_bundle_dir(None)
-    assert "alpha" in str(multiple.value)
-    assert "beta" in str(multiple.value)
-    assert "--label" in str(multiple.value)
-
-    with pytest.raises(ValueError) as missing:
-        serve_cli._resolve_bundle_dir("missing")
-    assert "missing" in str(missing.value)
-    assert "sol link join" in str(missing.value)
-
-    valid.clear()
-    with pytest.raises(ValueError) as empty:
-        serve_cli._resolve_bundle_dir(None)
-    assert "no observer link bundles" in str(empty.value)
-    assert "sol link join" in str(empty.value)
-
-
-def test_serve_relay_resolution(monkeypatch: pytest.MonkeyPatch) -> None:
-    monkeypatch.setenv("SOL_LINK_RELAY_URL", "https://env.example/")
-    assert serve_cli._resolve_relay_url("https://flag.example/") == (
-        "https://flag.example"
-    )
-    assert serve_cli._resolve_relay_url(None) == "https://env.example"
-
-    monkeypatch.delenv("SOL_LINK_RELAY_URL", raising=False)
-    monkeypatch.setattr("solstone.think.utils.get_config", lambda: {})
-    assert serve_cli._resolve_relay_url(None) == DEFAULT_RELAY_URL
-
-
-def test_serve_loopback_bind() -> None:
-    tunnel = _StubTunnel([TunnelResponseHead(200, {"Content-Length": "0"}), None])
-    server = serve_cli._build_server(0, tunnel)
-    try:
-        assert server.server_address[0] == serve_cli.LOOPBACK_HOST
-        assert serve_cli.LOOPBACK_HOST == "127.0.0.1"
-    finally:
-        server.server_close()
-
-
-def test_serve_port_collision(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    sock = socket.socket()
-    sock.bind((serve_cli.LOOPBACK_HOST, 0))
-    port = sock.getsockname()[1]
-
-    class FakeTunnel:
-        def __init__(self, *_args: object) -> None:
-            self.closed = False
-
-        def start(self) -> None:
-            pass
-
-        def close(self) -> None:
-            self.closed = True
-
-    monkeypatch.setattr(
-        serve_cli,
-        "_resolve_bundle_dir",
-        lambda _label: serve_cli._BundleSelection("label", tmp_path),
-    )
-    monkeypatch.setattr(serve_cli, "load_client_identity", lambda _path: object())
-    monkeypatch.setattr(serve_cli, "TunnelClient", FakeTunnel)
-    try:
-        result = serve_cli.main(
-            argparse.Namespace(label=None, port=port, relay_url=None)
-        )
-    finally:
-        sock.close()
-
-    assert result == 1
-    captured = capsys.readouterr()
-    assert f"{serve_cli.LOOPBACK_HOST}:{port}" in captured.err
-    assert "address already in use" in captured.err
-
-
-def test_serve_gateway_failure() -> None:
-    tunnel = _StubTunnel(
-        [
-            TunnelRequestError("ConnectionError", "down"),
-            None,
-        ]
-    )
-    server, thread = _start_server(tunnel)
-    try:
-        conn = _connection(server)
-        conn.request("GET", "/")
-        response = conn.getresponse()
-        body = response.read()
-        conn.close()
-    finally:
-        _stop_server(server, thread)
-
-    assert response.status == 502
-    assert b"ConnectionError" in body
diff --git a/tests/link/test_secure_listener_pairing_e2e.py b/tests/link/test_secure_listener_pairing_e2e.py
index 386ed97cb..3af1113da 100644
--- a/tests/link/test_secure_listener_pairing_e2e.py
+++ b/tests/link/test_secure_listener_pairing_e2e.py
@@ -16,8 +16,15 @@ from typing import Any
 import pytest
 
 from solstone.think.link import client as link_client
-from solstone.think.link import join_cli
 from solstone.think.link.window import window_open
+from tests.link import certless_helpers
+from tests.link.certless_helpers import (
+    DirectPairCandidate,
+    DirectPairRequest,
+    PairResponse,
+    build_csr,
+    framed_target,
+)
 from tests.link.secure_listener_harness import SecureListenerHarness
 
 
@@ -34,7 +41,7 @@ class _PendingDrain:
 
 
 def _pair_material(label: str) -> tuple[object, dict[str, str]]:
-    private_key, _private_key_pem, csr_pem = join_cli._build_csr(label)
+    private_key, _private_key_pem, csr_pem = build_csr(label)
     return private_key, {"csr": csr_pem, "device_label": label}
 
 
@@ -43,10 +50,10 @@ def _pair_body(label: str) -> dict[str, str]:
     return body
 
 
-def _direct_request_from_url(url: str, ca_fp: str) -> join_cli.DirectPairRequest:
-    host, port, path = join_cli._framed_target(url)
-    return join_cli.DirectPairRequest(
-        candidates=(join_cli.DirectPairCandidate(ipaddress.IPv4Address(host), port),),
+def _direct_request_from_url(url: str, ca_fp: str) -> DirectPairRequest:
+    host, port, path = framed_target(url)
+    return DirectPairRequest(
+        candidates=(DirectPairCandidate(ipaddress.IPv4Address(host), port),),
         path=path,
         ca_fingerprint_pin=ca_fp,
     )
@@ -110,18 +117,18 @@ async def _post_pair_with_payload_capture(
     body: dict[str, str],
     private_key: object,
     ca_fp: str,
-) -> tuple[join_cli.PairResponse, dict[str, Any]]:
+) -> tuple[PairResponse, dict[str, Any]]:
     payloads: list[dict[str, Any]] = []
-    real_parse = join_cli._parse_pair_response
+    real_parse = certless_helpers.parse_pair_response
 
-    def capture(payload: Any) -> join_cli.PairResponse:
+    def capture(payload: Any) -> PairResponse:
         if isinstance(payload, dict):
             payloads.append(payload)
         return real_parse(payload)
 
-    monkeypatch.setattr(join_cli, "_parse_pair_response", capture)
+    monkeypatch.setattr(certless_helpers, "parse_pair_response", capture)
     response = await asyncio.to_thread(
-        join_cli._post_pair_framed,
+        certless_helpers.post_pair_framed,
         _direct_request_from_url(url, ca_fp),
         body,
         private_key,
@@ -132,7 +139,7 @@ async def _post_pair_with_payload_capture(
 
 def _assert_complete_pair_response(
     harness: SecureListenerHarness,
-    response: join_cli.PairResponse,
+    response: PairResponse,
     payload: dict[str, Any],
 ) -> None:
     assert response.client_cert
@@ -356,9 +363,7 @@ async def test_stop_returns_promptly_with_pair_response_in_flight(
         listener_loop=asyncio.get_running_loop(),
         gate_when=lambda: not window_open(),
     )
-    client_task: asyncio.Task[tuple[join_cli.PairResponse, dict[str, Any]]] | None = (
-        None
-    )
+    client_task: asyncio.Task[tuple[PairResponse, dict[str, Any]]] | None = None
     try:
         harness.seed_nonce(nonce, label)
         private_key, body = _pair_material(label)
diff --git a/tests/link/test_tls_contexts.py b/tests/link/test_tls_contexts.py
index edcf26818..e04f90e7d 100644
--- a/tests/link/test_tls_contexts.py
+++ b/tests/link/test_tls_contexts.py
@@ -26,8 +26,8 @@ from solstone.think.link.client import (
     _drive_tls_client,
     _new_tls_client,
 )
-from solstone.think.link.join_cli import _build_csr
 from solstone.think.link.tls import TlsError as ClientTlsError
+from tests.link.certless_helpers import build_csr
 
 
 def test_strict_context_rejects_no_cert(tmp_path: Path) -> None:
@@ -51,7 +51,7 @@ def test_relaxed_context_accepts_no_cert_with_none_fingerprint(tmp_path: Path) -
 
 def test_relaxed_context_keeps_allowlisted_cert_fingerprint(tmp_path: Path) -> None:
     ca, server_cert, server_key, authorized = _server_material(tmp_path)
-    _private_key, private_key_bytes, csr_pem = _build_csr("pytest phone")
+    _private_key, private_key_bytes, csr_pem = build_csr("pytest phone")
     private_key_pem = private_key_bytes.decode("ascii")
     client_cert_pem, fingerprint = sign_csr(ca, csr_pem, "pytest phone")
     authorized.add(fingerprint, "pytest phone", "inst-1")
@@ -77,7 +77,7 @@ def test_relaxed_context_keeps_allowlisted_cert_fingerprint(tmp_path: Path) -> N
 
 def test_relaxed_context_rejects_unauthorized_cert(tmp_path: Path) -> None:
     ca, server_cert, server_key, authorized = _server_material(tmp_path)
-    _private_key, private_key_bytes, csr_pem = _build_csr("pytest stranger")
+    _private_key, private_key_bytes, csr_pem = build_csr("pytest stranger")
     private_key_pem = private_key_bytes.decode("ascii")
     client_cert_pem, fingerprint = sign_csr(ca, csr_pem, "pytest stranger")
     server_ctx = build_relaxed_server_context(ca, server_cert, server_key, authorized)
diff --git a/tests/spl/test_service.py b/tests/spl/test_service.py
index 36090db41..a4262389a 100644
--- a/tests/spl/test_service.py
+++ b/tests/spl/test_service.py
@@ -11,9 +11,7 @@ from unittest.mock import Mock
 
 import pytest
 
-from solstone.think import link as link_module
 from solstone.think import sol_cli
-from solstone.think.link import cli as link_cli
 from solstone.think.link.paths import service_token_path
 from solstone.think.spl import service
 
@@ -280,11 +278,3 @@ def test_dispatch_surfaces_for_journal_spl_and_sol_link(
         "argv": ["journal spl"],
     }
     assert titles == ["journal:spl"]
-
-    module_path, preset_args, surface = sol_cli.resolve_command("link")
-    assert (module_path, preset_args, surface) == (
-        "solstone.think.link",
-        [],
-        "universal",
-    )
-    assert link_module.main is link_cli.main
diff --git a/tests/test_native_sol_journal_host_commands.py b/tests/test_native_sol_journal_host_commands.py
index cc71bafa8..26807bd6a 100644
--- a/tests/test_native_sol_journal_host_commands.py
+++ b/tests/test_native_sol_journal_host_commands.py
@@ -15,7 +15,7 @@ SERVICE_COMMANDS = SERVICE_SENTINELS + tuple(
         journal_host.EXPECTED_SERVICE_COMMANDS_COUNT - len(SERVICE_SENTINELS)
     )
 )
-UNIVERSAL_COMMANDS = ("check", "contract", "doctor", "link")
+UNIVERSAL_COMMANDS = ("check", "contract", "doctor")
 SERVICE_ALIASES = ("down", "up")
 SERVICE_SURFACE_COUNT = journal_host.EXPECTED_SERVICE_COMMANDS_COUNT + len(
     SERVICE_ALIASES
@@ -181,7 +181,6 @@ def test_duplicate_service_command_preserves_old_count_but_is_rejected() -> None
             '    "check": Command("module.check", "universal"),',
             '    "contract": Command("module.contract", "universal"),',
             '    "doctor": Command("module.doctor", "universal"),',
-            '    "link": Command("module.link", "universal"),',
             "}",
             "",
             "ALIASES = {",
@@ -383,7 +382,6 @@ def test_production_registry_extracts_expected_partitions() -> None:
         "doctor",
         "check",
         "contract",
-        "link",
     }
     assert partitions.universal_aliases == ()
 
@@ -453,7 +451,7 @@ def test_service_aliases_report_reclassified_alias(alias: str) -> None:
     )
 
 
-@pytest.mark.parametrize("command", ["doctor", "check", "contract", "link"])
+@pytest.mark.parametrize("command", ["doctor", "check", "contract"])
 def test_universal_commands_reject_missing_expected_command(command: str) -> None:
     commands = _base_commands()
     del commands[command]
-- 
2.51.2