esp-donut 0.1.0__tar.gz

esp_donut-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.pytest_cache/
+.ruff_cache/
+build/
+dist/
+
+# Editors / tooling
+.claude/
+.idea/
+.vscode/
+
+# OS
+.DS_Store
+
+# Frontend
+frontend/node_modules/
+frontend/dist/
+
+# Local env (real secrets; .env.sample is the committed template)
+.env
+.env.local
+
+# Local SQLite database (created/migrated on hub startup; WAL sidecars too)
+donut.db
+donut.db-wal
+donut.db-shm

esp_donut-0.1.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: esp-donut
+Version: 0.1.0
+Summary: Donut client tools for ESP devices: the donut CLI and the donut-hands daemon
+Requires-Python: >=3.13
+Requires-Dist: esptool>=5.0
+Requires-Dist: nanoid<3,>=2
+Requires-Dist: platformdirs<5,>=4
+Requires-Dist: pyserial>=3.5
+Requires-Dist: websockets>=14
+Description-Content-Type: text/markdown
+
+# esp-donut
+
+Client tools for [Donut](https://donut.espressif.tools), the remote-hands
+service for ESP devices:
+
+- **`donut`** — the user-facing CLI. Lists devices exposed by connected
+  hands boxes and attaches a local rfc2217 port to a remote device.
+- **`donut-hands`** — the daemon that runs on a lab box next to the
+  hardware, dials the hub, and serves its serial ports.
+
+## Install
+
+```sh
+pip install esp-donut
+```
+
+## Quick start
+
+```sh
+export DONUT_TOKEN=...   # mint one with `donut-admin token mint --role agent`
+donut ls
+```
+
+For the hands daemon, create a config with `donut-hands --init` and run
+`donut-hands`. See the hub's documentation for the config schema and the
+wire protocol.

esp_donut-0.1.0/README.md

@@ -0,0 +1,26 @@
+# esp-donut
+
+Client tools for [Donut](https://donut.espressif.tools), the remote-hands
+service for ESP devices:
+
+- **`donut`** — the user-facing CLI. Lists devices exposed by connected
+  hands boxes and attaches a local rfc2217 port to a remote device.
+- **`donut-hands`** — the daemon that runs on a lab box next to the
+  hardware, dials the hub, and serves its serial ports.
+
+## Install
+
+```sh
+pip install esp-donut
+```
+
+## Quick start
+
+```sh
+export DONUT_TOKEN=...   # mint one with `donut-admin token mint --role agent`
+donut ls
+```
+
+For the hands daemon, create a config with `donut-hands --init` and run
+`donut-hands`. See the hub's documentation for the config schema and the
+wire protocol.

esp_donut-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "esp-donut"
+# Version is single-sourced from src/donut/__init__.py and kept in
+# lockstep with donut-hub (enforced by tests/test_smoke.py).
+dynamic = ["version"]
+description = "Donut client tools for ESP devices: the donut CLI and the donut-hands daemon"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "websockets>=14",
+    "pyserial>=3.5",
+    "esptool>=5.0",
+    "nanoid>=2,<3",
+    "platformdirs>=4,<5",
+]
+
+[project.scripts]
+donut = "donut.cli:main"
+donut-hands = "donut.hands:main"
+
+[tool.hatch.version]
+path = "src/donut/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/donut"]
+
+# Rebuild editable metadata when the version file changes, not just
+# pyproject.toml — otherwise the installed version goes stale on bumps.
+[tool.uv]
+cache-keys = [{ file = "pyproject.toml" }, { file = "src/donut/__init__.py" }]

esp_donut-0.1.0/src/donut/__init__.py

@@ -0,0 +1,3 @@
+"""Donut client — the ``donut`` CLI and the ``donut-hands`` daemon."""
+
+__version__ = "0.1.0"

esp_donut-0.1.0/src/donut/cli.py

@@ -0,0 +1,254 @@
+"""Donut CLI — the user-facing ``donut`` command.
+
+v0.1 ships a single subcommand, ``ls``, which lists the devices on every
+connected hands box over ``/api/ws/control``. Config comes from the
+environment: ``DONUT_TOKEN`` (required bearer) and ``DONUT_HUB_URL``
+(optional, defaults to the production hub).
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+from collections.abc import Callable
+
+from websockets.asyncio.client import connect as ws_connect
+from websockets.exceptions import InvalidStatus, WebSocketException
+
+DEFAULT_HUB_URL = "wss://donut.espressif.tools"
+ENV_HUB_URL = "DONUT_HUB_URL"
+ENV_TOKEN = "DONUT_TOKEN"
+
+# Binary control sentinel sent on the data WS when a fresh local rfc2217
+# client attaches, telling hands to start a new rfc2217 session. Must equal
+# ``donut.hands.RFC2217_RESET``. See that module for the rationale.
+RFC2217_RESET = b"\x00donut\x00rfc2217-reset\x00"
+
+
+class CliError(Exception):
+    """A user-facing error (bad config, connection failure)."""
+
+
+def resolve_hub_url() -> str:
+    return os.environ.get(ENV_HUB_URL) or DEFAULT_HUB_URL
+
+
+def resolve_token() -> str:
+    token = os.environ.get(ENV_TOKEN)
+    if not token:
+        raise CliError(
+            f"{ENV_TOKEN} is not set "
+            "(mint one with `donut-admin token mint --role agent`)"
+        )
+    return token
+
+
+async def fetch_devices(hub_url: str, token: str) -> list[dict]:
+    """Connect as an agent and return the hub's aggregated device list."""
+    url = hub_url.rstrip("/") + "/api/ws/control"
+    async with ws_connect(
+        url, additional_headers=[("Authorization", f"Bearer {token}")]
+    ) as ws:
+        await ws.send(json.dumps({"op": "hello", "role": "agent"}))
+        await _recv_op(ws, "hello-ok")
+        await ws.send(json.dumps({"op": "device.list", "id": "1"}))
+        resp = await _recv_op(ws, "device.list-ok")
+        return resp.get("devices", [])
+
+
+async def acquire_lease(hub_url: str, token: str, tags: list[str]) -> dict:
+    """Acquire a lease over the control WS; return the lease.acquire-ok.
+
+    The lease lives in the hub independent of this control connection, so
+    we close it once acquired — the data WS (dialed next) carries the
+    session, and dropping the data WS is what releases the lease.
+    """
+    url = hub_url.rstrip("/") + "/api/ws/control"
+    async with ws_connect(
+        url, additional_headers=[("Authorization", f"Bearer {token}")]
+    ) as ws:
+        await ws.send(json.dumps({"op": "hello", "role": "agent"}))
+        await _recv_op(ws, "hello-ok")
+        await ws.send(json.dumps({"op": "lease.acquire", "id": "1", "tags": tags}))
+        return await _recv_op(ws, "lease.acquire-ok")
+
+
+async def serve_local_rfc2217(
+    data_ws,
+    *,
+    host: str = "127.0.0.1",
+    port: int = 0,
+    on_listening: Callable[[int], None] | None = None,
+) -> None:
+    """Bridge a local TCP port to the data WS until the WS closes.
+
+    This is the *transparent* half of rfc2217. The listener never parses
+    the protocol: idf.py's pyserial rfc2217 client (dialing this port) and
+    the hands-side ``PortManager`` are the real endpoints, so DTR/RTS, baud
+    changes and modem state travel end-to-end through here untouched.
+
+    One TCP client at a time. ``idf.py flash monitor`` opens the port twice
+    (esptool, then the monitor) — both reuse the same data WS / lease, so
+    we keep listening across client disconnects, sending ``RFC2217_RESET``
+    on each new attach so hands starts a fresh rfc2217 session for it.
+    ``on_listening`` fires once bound with the chosen port (0 means the OS
+    picks a free one).
+    """
+    current_writer: asyncio.StreamWriter | None = None
+
+    async def handle_client(reader: asyncio.StreamReader, writer) -> None:
+        nonlocal current_writer
+        if current_writer is not None:
+            # Single byte stream per lease; refuse a second concurrent client.
+            writer.close()
+            return
+        current_writer = writer
+        try:
+            # Tell hands a fresh rfc2217 client attached so it greets us with
+            # a new negotiation instead of the previous client's stale state.
+            await data_ws.send(RFC2217_RESET)
+            while True:
+                chunk = await reader.read(4096)
+                if not chunk:
+                    return
+                await data_ws.send(chunk)
+        finally:
+            current_writer = None
+            writer.close()
+
+    async def ws_to_tcp() -> None:
+        async for msg in data_ws:
+            data = msg.encode() if isinstance(msg, str) else msg
+            writer = current_writer
+            if writer is not None and not writer.is_closing():
+                writer.write(data)
+                await writer.drain()
+            # No client attached → drop. This is the hands greeting emitted
+            # before the first client, or device chatter between clients;
+            # each client gets its own greeting via the RFC2217_RESET above.
+
+    server = await asyncio.start_server(handle_client, host, port)
+    if on_listening is not None:
+        on_listening(server.sockets[0].getsockname()[1])
+    pump = asyncio.create_task(ws_to_tcp())
+    async with server:
+        # Serve until the data WS closes (lease released / hub gone).
+        await pump
+
+
+async def connect_session(hub_url: str, token: str, tags: list[str]) -> None:
+    """Acquire a lease and expose it as a local rfc2217 port for idf.py."""
+    ok = await acquire_lease(hub_url, token, tags)
+
+    def announce(port: int) -> None:
+        # ?ign_set_control: the hands-side EspPortManager handles DTR/RTS
+        # out of band (reset-into-bootloader) and never echoes them, so the
+        # client must not wait for control acks. This is the URL form
+        # esp_rfc2217_server documents for esptool / idf.py.
+        print(f"ESPPORT=rfc2217://127.0.0.1:{port}?ign_set_control")
+        print(
+            f"lease {ok['lease_id']} active — point idf.py at $ESPPORT; "
+            "Ctrl-C to release",
+            file=sys.stderr,
+        )
+
+    # Dial the data WS on the same hub we just leased from, built from our
+    # own hub_url — not from ok["data_url"]. Behind a TLS-terminating proxy
+    # the hub can't reliably know its own public scheme, so its data_url can
+    # come back as ws/http and get 301-redirected to https (which the WS
+    # client rejects). hands does the same: it uses its configured hub_url.
+    data_ws_url = hub_url.rstrip("/") + "/api/ws/data"
+    async with ws_connect(data_ws_url) as data_ws:
+        # Ticket rides the first frame, not the URL (keeps it out of logs).
+        await data_ws.send(json.dumps({"ticket": ok["ticket"]}))
+        await serve_local_rfc2217(data_ws, on_listening=announce)
+
+
+async def _recv_op(ws, expected: str) -> dict:
+    """Read frames until one with ``op == expected``; raise on error frame."""
+    while True:
+        msg = json.loads(await ws.recv())
+        op = msg.get("op")
+        if op == expected:
+            return msg
+        if op == "error":
+            raise CliError(msg.get("error", "hub returned an error"))
+        # Ignore any other frame (e.g. an unsolicited push) and keep reading.
+
+
+def format_table(devices: list[dict]) -> str:
+    """Render the device list as an aligned NAME / TAGS / HANDS table."""
+    if not devices:
+        return "no devices available"
+
+    rows = [(d["name"], ", ".join(d.get("tags", [])), d["hands"]) for d in devices]
+    headers = ("NAME", "TAGS", "HANDS")
+    widths = [max(len(headers[i]), *(len(row[i]) for row in rows)) for i in range(3)]
+    lines = [
+        "  ".join(cell.ljust(widths[i]) for i, cell in enumerate(headers)),
+        *(
+            "  ".join(cell.ljust(widths[i]) for i, cell in enumerate(row))
+            for row in rows
+        ),
+    ]
+    return "\n".join(lines)
+
+
+def _cmd_ls(args: argparse.Namespace) -> None:
+    token = resolve_token()
+    hub_url = resolve_hub_url()
+    devices = asyncio.run(fetch_devices(hub_url, token))
+    if args.json:
+        print(json.dumps(devices, indent=2))
+    else:
+        print(format_table(devices))
+
+
+def _cmd_connect(args: argparse.Namespace) -> None:
+    token = resolve_token()
+    hub_url = resolve_hub_url()
+    asyncio.run(connect_session(hub_url, token, args.tags))
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Console entry point for ``donut``."""
+    parser = argparse.ArgumentParser(prog="donut")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    ls = sub.add_parser("ls", help="list devices on connected hands boxes")
+    ls.add_argument("--json", action="store_true", help="emit JSON instead of a table")
+    ls.set_defaults(func=_cmd_ls)
+
+    connect = sub.add_parser(
+        "connect", help="lease a device and expose it as a local rfc2217 port"
+    )
+    connect.add_argument(
+        "--tags",
+        nargs="+",
+        required=True,
+        metavar="TAG",
+        help="device tags to match (all must be present)",
+    )
+    connect.set_defaults(func=_cmd_connect)
+
+    args = parser.parse_args(argv)
+    try:
+        args.func(args)
+    except CliError as exc:
+        print(f"donut: {exc}", file=sys.stderr)
+        sys.exit(2)
+    except InvalidStatus as exc:
+        if exc.response.status_code in (401, 403):
+            print("donut: authentication failed — check DONUT_TOKEN", file=sys.stderr)
+        else:
+            print(
+                f"donut: hub rejected connection (HTTP {exc.response.status_code})",
+                file=sys.stderr,
+            )
+        sys.exit(1)
+    except (OSError, WebSocketException) as exc:
+        print(f"donut: cannot reach hub: {exc}", file=sys.stderr)
+        sys.exit(1)

esp_donut-0.1.0/src/donut/hands.py

@@ -0,0 +1,760 @@
+"""Donut hands daemon — dial the hub, send `hello`, run forever.
+
+See ``docs/hands-setup.md`` for the config schema and
+``docs/design.md`` §"Wire protocol" for the `hello` frame.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import os
+import random
+import stat
+import sys
+import time
+import tomllib
+from collections.abc import Awaitable, Callable
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import serial
+import serial.tools.list_ports
+from esp_rfc2217_server.esp_port_manager import EspPortManager
+from esp_rfc2217_server.esp_port_manager import cfg as _esptool_cfg
+from esptool.loader import ESPLoader
+from esptool.reset import (
+    DEFAULT_RESET_DELAY,
+    ClassicReset,
+    CustomReset,
+    HardReset,
+    UnixTightReset,
+    USBJTAGSerialReset,
+)
+from nanoid import generate as nanoid_generate
+from platformdirs import user_config_dir
+from websockets.asyncio.client import connect as ws_connect
+from websockets.exceptions import InvalidStatus, WebSocketException
+
+logger = logging.getLogger(__name__)
+
+
+DEFAULT_ETC_DIR = Path("/etc/donut")
+CONFIG_FILENAME = "hands.toml"
+ENV_CONFIG = "DONUT_HANDS_CONFIG"
+DEFAULT_HUB_URL = "wss://donut.espressif.tools/"
+
+# Reconnect backoff: exponential ceiling with full jitter. The ceiling
+# resets to INITIAL only after a session that stayed up at least
+# STABLE_SESSION_SECONDS — otherwise an accept-then-instant-close
+# flapping hub would pin us to a sub-second redial loop forever. HTTP
+# 401/403 on the upgrade is fatal (bad/revoked token — retrying can't
+# help).
+INITIAL_BACKOFF = 1.0
+MAX_BACKOFF = 30.0
+STABLE_SESSION_SECONDS = 5.0
+FATAL_AUTH_STATUSES = frozenset({401, 403})
+WS_SCHEMES = ("ws://", "wss://")
+
+# Control sentinel the CLI sends on the data WS when a fresh local rfc2217
+# client attaches, so we start a new rfc2217 session (esptool then the
+# monitor are two clients on one lease, and telnet option state is sticky —
+# a reused PortManager won't re-ACK the second client's negotiation). Sent
+# as a binary frame so the hub's binary byte-pump relays it untouched; the
+# exact-match magic can't collide with a real rfc2217/telnet frame.
+# Must equal ``donut.cli.RFC2217_RESET``.
+RFC2217_RESET = b"\x00donut\x00rfc2217-reset\x00"
+
+# How long to keep reopening a serial port that dropped mid-session before
+# giving up. Native-USB devkits re-enumerate during reset, so the port
+# briefly disappears and returns at the same path.
+SERIAL_REOPEN_TIMEOUT = 10.0
+
+
+class ConfigError(Exception):
+    """Raised for any problem reading or resolving the hands config."""
+
+
+@dataclass(frozen=True)
+class DeviceConfig:
+    name: str
+    path: str
+    tags: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class HandsConfig:
+    name: str
+    hands_id: str
+    hub_url: str
+    token: str
+    devices: list[DeviceConfig] = field(default_factory=list)
+
+
+_REQUIRED_TOP_LEVEL = ("name", "hands_id", "hub_url", "token")
+_ALLOWED_TOP_LEVEL = {*_REQUIRED_TOP_LEVEL, "devices"}
+_REQUIRED_DEVICE = ("name", "path")
+_ALLOWED_DEVICE = {*_REQUIRED_DEVICE, "tags"}
+
+
+def load_config(path: Path) -> HandsConfig:
+    """Read and validate ``hands.toml`` at *path*."""
+    if not path.exists():
+        raise ConfigError(f"hands config not found: {path}")
+
+    _warn_if_world_readable(path)
+
+    try:
+        raw = tomllib.loads(path.read_text())
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"hands config is not valid TOML: {exc}") from exc
+
+    extra_top = set(raw) - _ALLOWED_TOP_LEVEL
+    if extra_top:
+        raise ConfigError(f"unknown key(s) in {path}: {', '.join(sorted(extra_top))}")
+
+    missing = [k for k in _REQUIRED_TOP_LEVEL if k not in raw]
+    if missing:
+        raise ConfigError(f"missing required key(s) in {path}: {', '.join(missing)}")
+
+    if not str(raw["hub_url"]).startswith(WS_SCHEMES):
+        raise ConfigError(
+            f"hub_url in {path} must start with ws:// or wss:// "
+            f"(got {raw['hub_url']!r})"
+        )
+
+    devices = [_parse_device(d, path=path) for d in raw.get("devices", [])]
+
+    return HandsConfig(
+        name=raw["name"],
+        hands_id=raw["hands_id"],
+        hub_url=raw["hub_url"],
+        token=raw["token"],
+        devices=devices,
+    )
+
+
+def _parse_device(raw: dict, *, path: Path) -> DeviceConfig:
+    extra = set(raw) - _ALLOWED_DEVICE
+    if extra:
+        raise ConfigError(
+            f"unknown device key(s) in {path}: {', '.join(sorted(extra))}"
+        )
+    missing = [k for k in _REQUIRED_DEVICE if k not in raw]
+    if missing:
+        raise ConfigError(
+            f"device entry in {path} missing key(s): {', '.join(missing)}"
+        )
+    return DeviceConfig(
+        name=raw["name"],
+        path=raw["path"],
+        tags=list(raw.get("tags", [])),
+    )
+
+
+def _warn_if_world_readable(path: Path) -> None:
+    try:
+        mode = stat.S_IMODE(path.stat().st_mode)
+    except OSError:
+        return
+    if mode & 0o077:
+        logger.warning(
+            "hands config %s has loose permissions %o (recommend 0600)",
+            path,
+            mode,
+        )
+
+
+def _ws_scheme_error(value: str) -> str | None:
+    if not value.startswith(WS_SCHEMES):
+        return "must start with ws:// or wss://"
+    return None
+
+
+def _prompt_required(
+    prompt_fn: Callable[[str], str],
+    question: str,
+    *,
+    default: str | None = None,
+    validate: Callable[[str], str | None] | None = None,
+) -> str:
+    """Prompt until a valid answer is given.
+
+    Blank input takes ``default`` when one is set; otherwise it re-prompts.
+    ``validate`` returns an error string to reject + re-prompt, or ``None``
+    to accept.
+    """
+    hint = f" [{default}]" if default else ""
+    while True:
+        answer = prompt_fn(f"{question}{hint}: ").strip()
+        if not answer:
+            if default is not None:
+                return default
+            print("  value required", file=sys.stderr)
+            continue
+        if validate is not None and (err := validate(answer)):
+            print(f"  {err}", file=sys.stderr)
+            continue
+        return answer
+
+
+def init_config(
+    path: Path,
+    *,
+    prompt_fn: Callable[[str], str],
+) -> HandsConfig:
+    """Interactively create a ``hands.toml`` at *path*.
+
+    Refuses to clobber an existing file. Prompts for the operator-facing
+    bits (``name``, ``hub_url``, ``token``), mints a fresh ``hands_id``,
+    and writes the file at mode 0600.
+    """
+    if path.exists():
+        raise ConfigError(
+            f"hands config already exists: {path} (refusing to overwrite)"
+        )
+
+    name = _prompt_required(
+        prompt_fn, "Human-readable name for this hands box (e.g. lab-bench-1)"
+    )
+    hub_url = _prompt_required(
+        prompt_fn,
+        "Hub url",
+        default=DEFAULT_HUB_URL,
+        validate=_ws_scheme_error,
+    )
+    token = _prompt_required(
+        prompt_fn, "Bearer token (from `donut-admin token mint --role hands`)"
+    )
+
+    hands_id = f"h_{nanoid_generate(size=21)}"
+
+    cfg = HandsConfig(
+        name=name,
+        hands_id=hands_id,
+        hub_url=hub_url,
+        token=token,
+        devices=[],
+    )
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # Open with O_CREAT|O_EXCL and the right mode to avoid a brief
+    # world-readable window between create and chmod.
+    fd = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    with os.fdopen(fd, "w") as fp:
+        fp.write(_render_init_toml(cfg))
+
+    return cfg
+
+
+def _render_init_toml(cfg: HandsConfig) -> str:
+    # TOML basic strings share JSON's escape syntax for the cases we hit
+    # (", \, control chars), so json.dumps yields a safely-escaped,
+    # valid TOML right-hand side even when a bench name contains quotes.
+    return (
+        f"name      = {json.dumps(cfg.name)}\n"
+        f"hands_id  = {json.dumps(cfg.hands_id)}\n"
+        f"hub_url   = {json.dumps(cfg.hub_url)}\n"
+        f"token     = {json.dumps(cfg.token)}\n"
+        "\n"
+        "# Declare each USB devkit attached to this hands box:\n"
+        "# [[devices]]\n"
+        '# name = "c3-1"\n'
+        '# path = "/dev/ttyACM0"\n'
+        '# tags = ["esp32c3", "usb-jtag"]\n'
+    )
+
+
+async def run(
+    config: HandsConfig,
+    *,
+    on_connected: Callable[[], None] | None = None,
+) -> None:
+    """Dial the hub, send ``hello``, read frames until the socket closes.
+
+    Returns on clean disconnect; raises on connect / handshake failures.
+    ``on_connected`` (if given) fires once the WS handshake succeeds —
+    ``run_forever`` uses it to reset its backoff. Reconnection itself is
+    the caller's job; this coroutine handles a single session.
+    """
+    url = config.hub_url.rstrip("/") + "/api/ws/control"
+    hello = {
+        "op": "hello",
+        "role": "hands",
+        "hands_id": config.hands_id,
+        "name": config.name,
+        "devices": [
+            {"name": d.name, "path": d.path, "tags": list(d.tags)}
+            for d in config.devices
+        ],
+    }
+
+    # name → local device path, so we can resolve the hub-assigned
+    # device_id (returned in hello-ok) back to the port a port.open names.
+    name_to_path = {d.name: d.path for d in config.devices}
+    id_to_path: dict[str, str] = {}
+    sessions: set[asyncio.Task] = set()
+
+    logger.info("connecting to %s as %s (%s)", url, config.name, config.hands_id)
+    async with ws_connect(
+        url,
+        additional_headers=[("Authorization", f"Bearer {config.token}")],
+    ) as ws:
+        if on_connected is not None:
+            on_connected()
+        logger.info(
+            "connected to hub; sent hello for %d device(s)", len(config.devices)
+        )
+        await ws.send(json.dumps(hello))
+        try:
+            async for raw in ws:
+                msg = _parse_frame(raw)
+                op = msg.get("op") if msg else None
+                if op == "hello-ok":
+                    id_to_path = {
+                        d["device_id"]: name_to_path.get(d["name"])
+                        for d in msg.get("devices", [])
+                    }
+                    logger.info("registered with hub as %s", config.hands_id)
+                elif op == "port.open":
+                    task = asyncio.create_task(
+                        _run_port_session(config, ws, id_to_path, msg)
+                    )
+                    sessions.add(task)
+                    task.add_done_callback(sessions.discard)
+                elif op == "lease.released":
+                    # The hub force-closes the data WS too, which tears the
+                    # bridge down; this is just an informational signal.
+                    logger.info("lease released by hub: %s", msg.get("lease_id"))
+                else:
+                    logger.debug("ignored hub frame: %s", raw)
+        finally:
+            for task in sessions:
+                task.cancel()
+    logger.info("hub closed control WS; will reconnect")
+
+
+def _port_vid_pid(serial_port: serial.Serial) -> tuple[int | None, int | None] | None:
+    """USB ``(vid, pid)`` for an open pyserial port, or ``None``.
+
+    Back-port of esptool's ``get_port_vid_pid`` (added in MR 942, absent
+    from our 5.2.0 pin). Trimmed to the Linux lab-box case: resolve
+    ``/dev`` symlinks and match against ``list_ports.comports()``.
+    """
+    name = getattr(serial_port, "port", None)
+    if not name:
+        return None
+    target = os.path.realpath(name) if name.startswith("/dev/") else name
+    for p in serial.tools.list_ports.comports():
+        if p.device in (target, name):
+            return p.vid, p.pid
+    return None
+
+
+class DonutPortManager(EspPortManager):
+    """``EspPortManager`` + USB-Serial-JTAG reset, back-ported from esptool
+    MR 942 onto our released esptool pin.
+
+    Stock ``EspPortManager`` (esptool 5.2.0) only knows the UART-bridge
+    DTR/RTS reset sequence. On a native-USB devkit (e.g. esp32c3) that
+    sequence fights the chip's own USB stack and causes spurious resets,
+    so flashing over rfc2217 fails. This shim detects the USB-JTAG/Serial
+    PID and swaps in esptool's ``USBJTAGSerialReset``.
+
+    **Delete this class** once MR 942 lands in a released esptool and our
+    pin moves past it — at that point stock ``EspPortManager`` does the
+    right thing on its own.
+    """
+
+    def __init__(self, serial_port, connection, esp32r0_delay=False, logger=None):
+        vid_pid = _port_vid_pid(serial_port)
+        pid = vid_pid[1] if vid_pid else None
+        self.uses_usb_jtag_serial = pid == ESPLoader.USB_JTAG_SERIAL_PID
+        super().__init__(serial_port, connection, esp32r0_delay, logger)
+
+    def _hard_reset_thread(self):
+        if self.logger:
+            self.logger.info("Activating hard reset in thread")
+        custom = _esptool_cfg.get("custom_hard_reset_sequence")
+        if custom is not None:
+            CustomReset(self.serial, custom)()
+        else:
+            HardReset(self.serial, uses_usb=self.uses_usb_jtag_serial)()
+
+    def _reset_thread(self):
+        if self.logger:
+            self.logger.info("Activating reset in thread")
+        delay = DEFAULT_RESET_DELAY
+        if self.esp32r0_delay:
+            delay += 0.5
+        custom = _esptool_cfg.get("custom_reset_sequence")
+        if custom is not None:
+            CustomReset(self.serial, custom)()
+        elif self.uses_usb_jtag_serial:
+            USBJTAGSerialReset(self.serial)()
+        elif os.name != "nt":
+            UnixTightReset(self.serial, delay)()
+        else:
+            ClassicReset(self.serial, delay)()
+
+
+async def _run_port_session(
+    config: HandsConfig,
+    control_ws: object,
+    id_to_path: dict[str, str],
+    msg: dict,
+) -> None:
+    """Open the named port, ACK, then bridge it to the data WS.
+
+    On any failure to open the port the hub is told ``port.open-failed``
+    (which rolls back the pending lease) and the session ends. Otherwise
+    we ACK ``port.open-ok`` so the hub can hand the agent its lease, dial
+    the data WS, and shuttle bytes until either side closes.
+    """
+    req_id = msg.get("id")
+    device_id = msg.get("device_id")
+    ticket = msg.get("ticket")
+    baud = msg.get("baud", 115200)
+    path = id_to_path.get(device_id)
+
+    if path is None:
+        await control_ws.send(
+            json.dumps(
+                {
+                    "op": "port.open-failed",
+                    "id": req_id,
+                    "error": f"unknown device_id {device_id}",
+                }
+            )
+        )
+        return
+
+    loop = asyncio.get_running_loop()
+    try:
+        # Blocking pyserial port (not serial_asyncio): EspPortManager's reset
+        # sequences toggle DTR/RTS on a plain serial.Serial. serial_for_url
+        # opens real /dev paths and URL handlers (loop://, socket://) alike.
+        serial_instance = await loop.run_in_executor(
+            None, lambda: serial.serial_for_url(path, baudrate=baud, timeout=0.1)
+        )
+    except Exception as exc:
+        logger.warning("could not open %s: %s", path, exc)
+        await control_ws.send(
+            json.dumps({"op": "port.open-failed", "id": req_id, "error": str(exc)})
+        )
+        return
+
+    await control_ws.send(json.dumps({"op": "port.open-ok", "id": req_id}))
+    data_url = config.hub_url.rstrip("/") + "/api/ws/data"
+    logger.info("opened %s; bridging rfc2217 to data WS", path)
+    try:
+        async with ws_connect(data_url) as data_ws:
+            # Ticket rides the first frame, not the URL (keeps it out of logs).
+            await data_ws.send(json.dumps({"ticket": ticket}))
+            await _bridge_rfc2217_ws(serial_instance, data_ws)
+    finally:
+        serial_instance.close()
+        logger.info("closed %s", path)
+
+
+def _parse_frame(raw: object) -> dict | None:
+    try:
+        msg = json.loads(raw)
+    except (TypeError, ValueError):
+        return None
+    return msg if isinstance(msg, dict) else None
+
+
+async def _bridge_rfc2217_ws(
+    serial_instance: serial.Serial,
+    ws: object,
+) -> None:
+    """Run an rfc2217 server over the data WS against a real serial port.
+
+    A ``DonutPortManager`` owns the rfc2217/telnet protocol: ``filter``
+    extracts pure serial payload from inbound WS frames (handling option
+    negotiation, baud changes, and DTR/RTS reset out of band), ``escape``
+    re-frames outbound serial bytes. The agent's pyserial rfc2217 client
+    and this server are the protocol endpoints; the WS and hub in between
+    just carry bytes.
+
+    Two real-world wrinkles are handled here:
+
+    * **Per-client sessions.** ``RFC2217_RESET`` on the WS recreates the
+      PortManager so each fresh local client (esptool, then the monitor)
+      renegotiates cleanly instead of hitting sticky telnet option state.
+    * **Re-enumeration.** Native-USB devkits drop off the bus during reset;
+      a read that errors triggers a reopen-with-backoff rather than killing
+      the session.
+
+    ``serial.Serial`` is blocking, so reads and writes run in a dedicated
+    two-thread executor that is shut down when the bridge ends — never the
+    asyncio default pool, whose threads would otherwise outlive the session
+    and wedge interpreter shutdown. A single outbound queue + sender keeps
+    the PortManager's negotiation writes ordered with escaped serial data.
+    """
+    loop = asyncio.get_running_loop()
+    executor = ThreadPoolExecutor(max_workers=2, thread_name_prefix="donut-serial")
+    outbound: asyncio.Queue[bytes] = asyncio.Queue()
+
+    class _WSConnection:
+        """PortManager writes telnet negotiation here; we relay to the WS."""
+
+        def write(self, data) -> None:
+            outbound.put_nowait(bytes(data))
+
+    connection = _WSConnection()
+
+    def _new_port_manager() -> DonutPortManager:
+        # Constructing the manager emits the initial telnet option requests
+        # (via connection.write → outbound), so the client can negotiate.
+        return DonutPortManager(serial_instance, connection)
+
+    port_manager = _new_port_manager()
+
+    def _reopen_serial() -> None:
+        if serial_instance.is_open:
+            serial_instance.close()
+        serial_instance.open()
+
+    async def _recover_serial() -> bool:
+        deadline = loop.time() + SERIAL_REOPEN_TIMEOUT
+        while loop.time() < deadline:
+            try:
+                await loop.run_in_executor(executor, _reopen_serial)
+                logger.info("reopened %s after disconnect", serial_instance.port)
+                return True
+            except serial.SerialException:
+                await asyncio.sleep(0.2)
+        return False
+
+    async def sender() -> None:
+        while True:
+            await ws.send(await outbound.get())
+
+    async def serial_to_ws() -> None:
+        while True:
+            try:
+                data = await loop.run_in_executor(
+                    executor,
+                    lambda: serial_instance.read(serial_instance.in_waiting or 1),
+                )
+            except serial.SerialException as exc:
+                logger.info(
+                    "serial read on %s failed (%s); reopening",
+                    serial_instance.port,
+                    exc,
+                )
+                if not await _recover_serial():
+                    logger.warning(
+                        "could not reopen %s; ending bridge", serial_instance.port
+                    )
+                    return
+                continue
+            if data:
+                outbound.put_nowait(b"".join(port_manager.escape(data)))
+
+    async def ws_to_serial() -> None:
+        nonlocal port_manager
+        async for msg in ws:
+            if isinstance(msg, bytes | bytearray) and bytes(msg) == RFC2217_RESET:
+                # A fresh local rfc2217 client attached: start a new session
+                # so its negotiation isn't ignored as already-active.
+                port_manager = _new_port_manager()
+                continue
+            if isinstance(msg, str):
+                msg = msg.encode()
+            # filter() extracts serial payload and handles telnet/rfc2217
+            # negotiation (baud, line params, DTR/RTS) out of band.
+            payload = b"".join(port_manager.filter(msg))
+            if payload:
+                try:
+                    await loop.run_in_executor(executor, serial_instance.write, payload)
+                except serial.SerialException:
+                    logger.debug("serial write dropped during reset", exc_info=True)
+
+    async def modem_poll() -> None:
+        while True:
+            await asyncio.sleep(1.0)
+            try:
+                port_manager.check_modem_lines()
+            except serial.SerialException:
+                logger.debug("modem-line poll skipped during reset", exc_info=True)
+
+    tasks = [
+        asyncio.create_task(coro())
+        for coro in (sender, serial_to_ws, ws_to_serial, modem_poll)
+    ]
+    try:
+        done, _ = await asyncio.wait(
+            (tasks[1], tasks[2]), return_when=asyncio.FIRST_COMPLETED
+        )
+        for task in done:
+            if (exc := task.exception()) is not None:
+                logger.warning("rfc2217 bridge ended on error: %r", exc)
+    finally:
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        # Don't wait: a read may be blocked in-flight, but it returns within
+        # the port's read timeout and the thread then exits. wait=True here
+        # would stall teardown for that window.
+        executor.shutdown(wait=False, cancel_futures=True)
+
+
+async def run_forever(
+    config: HandsConfig,
+    *,
+    sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+    jitter: Callable[[], float] = random.random,
+    clock: Callable[[], float] = time.monotonic,
+) -> None:
+    """Run ``run`` in a loop, reconnecting with exponential backoff.
+
+    Backoff ceiling doubles on each consecutive failed/short session
+    (capped at ``MAX_BACKOFF``); the actual delay is ``jitter() *
+    ceiling`` (full jitter, so a fleet of hands boxes doesn't stampede a
+    recovering hub). The ceiling resets to ``INITIAL_BACKOFF`` only after
+    a session that stayed up at least ``STABLE_SESSION_SECONDS`` — a hub
+    that accepts the upgrade then drops the socket instantly would
+    otherwise keep us in a sub-second redial loop.
+
+    A clean close by the hub (e.g. a deploy) and any network/WS error are
+    retryable. An HTTP 401/403 on the upgrade is fatal — the token is bad
+    or revoked, so we re-raise instead of spinning forever.
+    """
+    backoff = INITIAL_BACKOFF
+    while True:
+        connected_at: float | None = None
+
+        def _mark_connected() -> None:
+            nonlocal connected_at
+            connected_at = clock()
+
+        try:
+            await run(config, on_connected=_mark_connected)
+            logger.info("hub closed connection; reconnecting")
+        except InvalidStatus as exc:
+            if exc.response.status_code in FATAL_AUTH_STATUSES:
+                logger.error(
+                    "hub rejected auth (HTTP %s); not retrying",
+                    exc.response.status_code,
+                )
+                raise
+            logger.warning(
+                "hub rejected upgrade (HTTP %s); reconnecting", exc.response.status_code
+            )
+        except (OSError, WebSocketException) as exc:
+            logger.warning("control connection lost (%s); reconnecting", exc)
+
+        stable = (
+            connected_at is not None
+            and (clock() - connected_at) >= STABLE_SESSION_SECONDS
+        )
+        if stable:
+            backoff = INITIAL_BACKOFF
+
+        delay = jitter() * backoff
+        logger.info("reconnecting in %.1fs", delay)
+        await sleep(delay)
+        backoff = min(backoff * 2, MAX_BACKOFF)
+
+
+def resolve_config_path(
+    *,
+    explicit: Path | None,
+    etc_dir: Path = DEFAULT_ETC_DIR,
+) -> Path:
+    """Pick a config path per the documented search order.
+
+    --config wins; then $DONUT_HANDS_CONFIG; then the per-user config
+    dir reported by ``platformdirs.user_config_dir('donut')`` (on Linux
+    that's ``$XDG_CONFIG_HOME/donut`` or ``~/.config/donut``; macOS
+    and Windows pick their own conventional location); then
+    ``<etc_dir>/hands.toml``.
+
+    For the explicit and env-var cases the file is returned even if
+    missing — the user named it, so they get the missing-file error
+    against the exact path they typed. For the user/etc fallbacks we
+    only return paths that exist; the search continues otherwise, and
+    raises ``ConfigError`` if nothing is found.
+    """
+    if explicit is not None:
+        return explicit
+
+    env = os.environ.get(ENV_CONFIG)
+    if env:
+        return Path(env)
+
+    candidates = [
+        Path(user_config_dir("donut")) / CONFIG_FILENAME,
+        etc_dir / CONFIG_FILENAME,
+    ]
+
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+
+    tried = "\n  ".join(str(c) for c in candidates)
+    raise ConfigError(
+        f"no donut/hands.toml found; tried:\n  {tried}\n"
+        "run `donut-hands --init` to create one"
+    )
+
+
+def _default_init_path() -> Path:
+    """Per-user default where ``--init`` writes when ``--config`` isn't given."""
+    return Path(user_config_dir("donut")) / CONFIG_FILENAME
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Console entry point for ``donut-hands``.
+
+    Default: dial the hub from the resolved ``hands.toml`` and stay
+    connected, reconnecting with backoff across hub restarts and network
+    blips. Exits non-zero only on a fatal error — bad config, or an
+    auth rejection (revoked/invalid token) — so systemd can surface it.
+
+    ``--init``: interactively create a fresh ``hands.toml`` and exit 0.
+    """
+    parser = argparse.ArgumentParser(prog="donut-hands")
+    parser.add_argument(
+        "--init",
+        action="store_true",
+        help="interactively create hands.toml and exit",
+    )
+    parser.add_argument(
+        "--config",
+        type=str,
+        default=None,
+        help="explicit path to hands.toml (overrides search)",
+    )
+    args = parser.parse_args(argv)
+
+    explicit = Path(args.config) if args.config else None
+
+    try:
+        if args.init:
+            target = explicit if explicit is not None else _default_init_path()
+            init_config(target, prompt_fn=input)
+            print(f"wrote {target}")
+            return
+        cfg_path = resolve_config_path(explicit=explicit)
+        cfg = load_config(cfg_path)
+    except ConfigError as exc:
+        print(f"donut-hands: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    # The daemon is an application entry point, so it owns log config —
+    # without this, logger.info on (re)connect is invisible under systemd.
+    logging.basicConfig(level=logging.INFO)
+    try:
+        asyncio.run(run_forever(cfg))
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except Exception as exc:
+        print(f"hands daemon exiting: {exc}", file=sys.stderr)
+        sys.exit(1)