---
model: claude-opus-4-6
service: claude
timestamp: 2026-04-14T16:33:00Z
git_ref: befedc49
---

### Add a `prefer_addr()` helper

Added transport preference selection to
`tractor/discovery/_api.py` with two new functions:

#### `_is_local_addr(addr: Address) -> bool`

Determines whether an `Address` is reachable on the
local host:

- `UDSAddress`: always returns `True`
  (filesystem-bound, inherently local)
- `TCPAddress`: checks if `._host` is a loopback IP
  via `ipaddress.ip_address().is_loopback`, then
  falls back to comparing against the machine's own
  interface IPs via
  `socket.getaddrinfo(socket.gethostname(), None)`

#### `prefer_addr(addrs: list[UnwrappedAddress]) -> UnwrappedAddress`

Selects the "best" transport address from a
multihomed actor's address list. Wraps each
candidate via `wrap_address()` to get typed
`Address` objects, then classifies into three tiers:

1. **UDS** (same-host guaranteed, lowest overhead)
2. **TCP loopback / same-host IP** (local network)
3. **TCP remote** (only option for distributed)

Within each tier, the last-registered (latest) entry
is preferred. Falls back to `addrs[-1]` if no
heuristic matches.

#### Integration

- `Registrar.find_actor()` in `_registry.py`: changed
  return type from `UnwrappedAddress|None` to
  `list[UnwrappedAddress]|None` — returns the full
  addr list so callers can apply transport preference.

- `query_actor()` in `_api.py`: now calls
  `prefer_addr(addrs)` on the list returned by
  `Registrar.find_actor()` instead of receiving a
  single pre-selected addr.

- `wait_for_actor()` in `_api.py`: replaced
  `addrs[-1]` with `prefer_addr(addrs)` for
  consistent transport selection.

### Verification

All discovery tests pass (13/13 non-daemon).
`test_local.py` and `test_multi_program.py` also
pass (daemon fixture teardown failures are
pre-existing and unrelated).