fix: trace UI review findings — unpublished-port survival, probe gap, 127.0.0.1

Per review on #426:
- docker port exits non-zero for unpublished mappings; under
  set -euo pipefail that killed the launch — swallow it, keep the warn
- probe loop could publish an untested port when 9317-9328 were all
  busy; publish only a confirmed-free port, warn and skip otherwise
- URLs use 127.0.0.1 to match the bind (localhost can resolve ::1
  first); docs/changelog aligned, port shown as placeholder

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: lroolle

CHANGELOG.md

@@ -32,7 +32,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   instead of silently attaching a stale CLI to the same config home.
   Label-less images keep the bare agent name (#420)
 - Traced sessions publish the cctrace live UI to the host loopback:
-  free port probed from 9317, `Trace UI: http://localhost:<port>` printed
+  free port probed from 9317, `Trace UI: http://127.0.0.1:<port>` printed
   before the TUI starts, and the host browser opens the moment the UI
   answers (poll-then-open; `DEVA_TRACE_OPEN=0` disables). Attaching to a
   persistent container created without the port warns instead (#425)

agents/shared_auth.sh

@@ -233,15 +233,23 @@ DEVA_TRACE_UI_URL=""
 setup_trace_ui_port() {
     local port=9317
     local tries=0
+    local free_port=""
     while [ "$tries" -lt 12 ]; do
         if ! (exec 3<>"/dev/tcp/127.0.0.1/$port") 2>/dev/null; then
+            free_port="$port"
             break
         fi
         port=$((port + 1))
         tries=$((tries + 1))
     done
-    DOCKER_ARGS+=("-p" "127.0.0.1:${port}:9317")
-    DEVA_TRACE_UI_URL="http://localhost:${port}"
+
+    if [ -z "$free_port" ]; then
+        echo "warning: no free host port in 9317-9328; trace UI will not be reachable from the host" >&2
+        return 0
+    fi
+
+    DOCKER_ARGS+=("-p" "127.0.0.1:${free_port}:9317")
+    DEVA_TRACE_UI_URL="http://127.0.0.1:${free_port}"
 }
 
 # Print the trace UI URL before the TUI takes the screen, and open the host
@@ -253,13 +261,15 @@ announce_trace_ui() {
 
     local url="$DEVA_TRACE_UI_URL"
     if [ "${1:-new}" = "existing" ]; then
+        # docker port exits non-zero for unpublished mappings; under
+        # set -euo pipefail that must not kill the launch.
         local mapping
-        mapping=$(docker port "$CONTAINER_NAME" 9317/tcp 2>/dev/null | head -1)
+        mapping=$(docker port "$CONTAINER_NAME" 9317/tcp 2>/dev/null | head -1 || true)
         if [ -z "$mapping" ]; then
             echo "warning: trace UI not reachable — container was created without the trace port; recreate it (deva rm) or use --rm" >&2
             return 0
         fi
-        url="http://localhost:${mapping##*:}"
+        url="http://127.0.0.1:${mapping##*:}"
     fi
     [ -n "$url" ] || return 0
 

docs/advanced-usage.md

@@ -186,7 +186,7 @@ published to the host loopback. deva prints the URL before the TUI takes
 the screen and opens your host browser the moment the UI answers:
 
 ```text
-Trace UI: http://localhost:9317 (live once the agent starts)
+Trace UI: http://127.0.0.1:<port> (live once the agent starts)
 ```
 
 Set `DEVA_TRACE_OPEN=0` to keep the banner but skip the auto-open.