feat(trace): publish live UI to host, banner before TUI, poll-then-open

cctrace prints its Live UI URL inside the container where no browser can
reach it, then the TUI paints over it. Fix the host side:

- traced sessions publish container 9317 to a probed free host loopback
  port (9317, 9318, ... — concurrent traced containers get neighbors)
- deva prints "Trace UI: http://localhost:<port>" before the agent takes
  the screen
- host browser opens the moment the UI answers: background poll-then-open,
  never a connection-refused page; DEVA_TRACE_OPEN=0 disables
- port publish is create-time only: traced attach to a container created
  without it warns with the recreate hint

Closes #425

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

Author: lroolle

CHANGELOG.md

@@ -31,6 +31,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   containers pin old images; a CLI bump now creates a distinct container
   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
+  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)
 
 ### Changed
 - cctrace pin bumped 0.4.0 -> 0.11.0 (client profiles, shape-first

agents/claude.sh

@@ -51,6 +51,7 @@ agent_prepare() {
         # into the container system trust store (#414)
         DOCKER_ARGS+=("-e" "DEVA_TRACE=1")
         DEVA_TRACE_ACTIVE=true
+        setup_trace_ui_port
         AGENT_COMMAND=("cctrace" "--no-open" "--")
         if [ "$has_dangerously" = false ]; then
             AGENT_COMMAND+=("--dangerously-skip-permissions")

agents/codex.sh

@@ -94,6 +94,7 @@ agent_prepare() {
         # DEVA_TRACE=1 installs the MITM CA into the container store (#414).
         DOCKER_ARGS+=("-e" "DEVA_TRACE=1")
         DEVA_TRACE_ACTIVE=true
+        setup_trace_ui_port
         AGENT_COMMAND=("cctrace" "codex" "--no-open" "--" "${AGENT_COMMAND[@]:1}")
     fi
 

agents/grok.sh

@@ -42,6 +42,7 @@ agent_prepare() {
         # DEVA_TRACE=1 installs the MITM CA into the container store (#414).
         DOCKER_ARGS+=("-e" "DEVA_TRACE=1")
         DEVA_TRACE_ACTIVE=true
+        setup_trace_ui_port
         AGENT_COMMAND=("cctrace" "grok" "--no-open" "--" "${AGENT_COMMAND[@]:1}")
     fi
 

agents/shared_auth.sh

@@ -226,6 +226,74 @@ is_file_path() {
     [[ "$arg" == /* ]] || [[ "$arg" == ~* ]] || [[ "$arg" == ./* ]] || [[ "$arg" == ../* ]] || [[ "$arg" == *.json ]]
 }
 
+# Publish the cctrace live UI (container port 9317, binds 0.0.0.0) to the
+# host loopback so the browser can reach it. Probe host ports from 9317 so
+# concurrent traced containers land on predictable neighbors (#425).
+DEVA_TRACE_UI_URL=""
+setup_trace_ui_port() {
+    local port=9317
+    local tries=0
+    while [ "$tries" -lt 12 ]; do
+        if ! (exec 3<>"/dev/tcp/127.0.0.1/$port") 2>/dev/null; then
+            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}"
+}
+
+# Print the trace UI URL before the TUI takes the screen, and open the host
+# browser the moment the UI answers. "new" trusts DEVA_TRACE_UI_URL (the
+# container doesn't exist yet); "existing" asks docker for the live mapping.
+announce_trace_ui() {
+    [ "${DEVA_TRACE_ACTIVE:-false}" = true ] || return 0
+    [ "${DRY_RUN:-false}" = true ] && return 0
+
+    local url="$DEVA_TRACE_UI_URL"
+    if [ "${1:-new}" = "existing" ]; then
+        local mapping
+        mapping=$(docker port "$CONTAINER_NAME" 9317/tcp 2>/dev/null | head -1)
+        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##*:}"
+    fi
+    [ -n "$url" ] || return 0
+
+    echo "Trace UI: $url (live once the agent starts)" >&2
+    maybe_open_trace_ui "$url"
+}
+
+# Poll-then-open in the background: the browser opens exactly when the UI
+# is up, never against a connection-refused page. DEVA_TRACE_OPEN=0 disables.
+maybe_open_trace_ui() {
+    local url="$1"
+    [ "${DEVA_TRACE_OPEN:-1}" = "1" ] || return 0
+
+    local opener=""
+    if command -v open >/dev/null 2>&1; then
+        opener="open"
+    elif command -v xdg-open >/dev/null 2>&1; then
+        opener="xdg-open"
+    fi
+    [ -n "$opener" ] || return 0
+
+    (
+        local i=0
+        while [ "$i" -lt 60 ]; do
+            if curl -sf -o /dev/null --max-time 1 "$url/" 2>/dev/null; then
+                "$opener" "$url" >/dev/null 2>&1 || true
+                exit 0
+            fi
+            sleep 0.5
+            i=$((i + 1))
+        done
+    ) >/dev/null 2>&1 &
+}
+
 AUTH_PROVISION_MODE=false
 
 expand_auth_file_tilde() {

deva.sh

@@ -3732,6 +3732,10 @@ if [ "$EPHEMERAL_MODE" = false ]; then
     _trace_env="DEVA_TRACE=0"
     [ "${DEVA_TRACE_ACTIVE:-false}" = true ] && _trace_env="DEVA_TRACE=1"
 
+    # Trace UI reachability is fixed at container create (port publish);
+    # attaching to a container created without it cannot gain the mapping.
+    announce_trace_ui existing
+
     if [ "$AUTH_PROVISION_MODE" = true ]; then
         docker exec -e "$_trace_env" "${DOCKER_TERMINAL_ARGS[@]}" "$CONTAINER_NAME" /usr/local/bin/docker-entrypoint.sh "${AGENT_COMMAND[@]}" || true
         finish_auth_provision
@@ -3741,6 +3745,7 @@ if [ "$EPHEMERAL_MODE" = false ]; then
 else
     echo "Launching ${ACTIVE_AGENT} (ephemeral mode) via $(docker_image_ref)"
     write_session_file
+    announce_trace_ui new
     if [ "$AUTH_PROVISION_MODE" = true ]; then
         docker "${DOCKER_ARGS[@]}" "${AGENT_COMMAND[@]}" || true
         finish_auth_provision

docs/advanced-usage.md

@@ -181,6 +181,20 @@ tools that ignore `NODE_EXTRA_CA_CERTS`/`SSL_CERT_FILE` still verify. The
 container is the blast radius: trust never touches the host store and is
 removed at the next non-traced start.
 
+The live trace UI (cctrace's web view, port 9317 in the container) is
+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)
+```
+
+Set `DEVA_TRACE_OPEN=0` to keep the banner but skip the auto-open.
+Concurrent traced containers get neighboring host ports (9318, ...).
+Port publishing is fixed at container create: attaching to a persistent
+container created without `--trace` prints a warning instead — recreate
+it (`deva rm`) or use `--rm` for traced sessions.
+
 Traces land in `.cctrace/` inside your workspace, so they survive the
 container. Each run writes a JSONL log plus a self-contained HTML snapshot you
 can open in a browser on the host. Credentials are redacted before anything