Tell participants about a busy dashboard port instead of letting ssh fail

sfbox dashboard already took --port, but nothing checked whether the local
port was free before exec ssh -L, so a participant whose machine already had
that port hit ssh's bare "bind: Address already in use" with no mention that
--port exists.

A busy default now moves to the next free port and says which. A port the
participant named is never moved: that case stops and names a free one to try.
The probe is a bash /dev/tcp connect, so it needs no lsof, ss or netstat.

City: city · Agent: local-core.builder-2

Author: austinborn

participant-box-cli/README.md

@@ -94,6 +94,8 @@ sfbox dashboard
 
 The dashboard's built into the `gc` binary and served by the supervisor, so there's nothing to deploy or start. `sfbox` forwards it over SSH and prints you a local URL. Leave the command running; Ctrl-C closes the tunnel.
 
+If the default port is already busy on your laptop, `sfbox` moves the tunnel to the next free one and tells you which it picked, so the URL it prints is always the one to open. Pass `--port <local-port>` to choose for yourself. A port you named is never moved: if it's taken the command stops and names a free one to try, because choosing a port usually means something else of yours expects the dashboard there.
+
 Tunnelling is the whole point. Your security group opens `:22` and nothing else, and because you're reaching the dashboard same-origin through the tunnel, it stays fully read-write. Bind it to a public interface instead and you'd leave reads open to anyone who found the address, plus the API would drop to read-only unless you'd explicitly switched mutations on.
 
 ## Where your state lives

participant-box-cli/SKILL.md

@@ -89,6 +89,8 @@ sfbox dashboard
 
 This just opens an SSH tunnel and prints a `127.0.0.1` URL. The dashboard's embedded in the `gc` binary and served by the supervisor, so nothing needs starting on the box. It'll run in the foreground until Ctrl-C.
 
+A busy port on the user's own laptop is the common snag here, and the command handles the two cases differently. If the default port is taken it moves to the next free one and says which, so read the port back off its output rather than assuming. If they passed `--port` and that port is taken, the command stops and names a free one to try. That's deliberate: ask them which port they want instead of choosing one for them.
+
 Never suggest binding the API port publicly, or opening it up in the security group. Only `:22` belongs there, really. Binding it non-loopback also drops the API to read-only unless mutations are explicitly enabled, and it'll leave reads open to anyone who finds the address.
 
 ## Restarting

participant-box-cli/sfbox

@@ -32,6 +32,13 @@ SFBOX_PROTECTED_IMPORTS="core bd"
 SFBOX_DEFAULT_USER="ubuntu"
 SFBOX_DEFAULT_PORT="22"
 SFBOX_DEFAULT_DASHBOARD_PORT="8372"
+
+# How far above a busy default the dashboard looks for a free local port before
+# it gives up and says so. Small on purpose: a participant reading a port number
+# off their own screen should not have to check it is the one in the room's
+# instructions plus fifty.
+SFBOX_DASHBOARD_PORT_SCAN=20
+
 SFBOX_SERVICE="gas-city.service"
 
 # ---------------------------------------------------------------- output ----
@@ -756,12 +763,77 @@ restart_factory() { # box wait_secs
   return 1
 }
 
+# ------------------------------------------------------------- dashboard ----
+
+# Is something already listening on this local port?
+#
+# /dev/tcp is a bash builtin rather than a device, which is what makes this the
+# portable check. lsof, ss and netstat are each absent from some stock macOS or
+# slim Linux, and this runs on whatever laptop a participant walked in with.
+#
+# A completed connect is the only answer trusted here. Refused, unreachable, and
+# a bash built without /dev/tcp all report free, so the worst this can do is hand
+# the participant the ssh bind error they would have got anyway. Guessing the
+# other way is the costlier mistake: it would refuse to tunnel over a port
+# nothing was holding.
+port_in_use() { # port -> 0 in use, 1 free or undetectable
+  ( exec 3<>"/dev/tcp/127.0.0.1/$1" ) >/dev/null 2>&1
+}
+
+# The first free port at or above the one given, within SFBOX_DASHBOARD_PORT_SCAN
+# tries. Prints nothing when they are all taken, which the caller reports rather
+# than searching further: someone holding that many consecutive ports is better
+# told than moved somewhere they would never think to look.
+dashboard_free_port() { # start -> prints a free port, or nothing
+  local p="$1" tried=0
+  while [ "$tried" -lt "$SFBOX_DASHBOARD_PORT_SCAN" ] && [ "$p" -le 65535 ]; do
+    port_in_use "$p" || { printf '%s' "$p"; return 0; }
+    p=$((p + 1))
+    tried=$((tried + 1))
+  done
+  return 1
+}
+
+# Settle which local port the tunnel binds.
+#
+# An explicit --port is never moved. The participant named that port, usually
+# because something else of theirs expects the dashboard there, so a collision is
+# theirs to see; moving them quietly would hide both the collision and the port
+# they ended up on. The default is moved, because someone who never chose a port
+# has no stake in which one they get, and the alternative is ssh's own "bind:
+# Address already in use", which names neither the port nor the flag that fixes it.
+dashboard_resolve_port() { # port explicit -> prints the port to bind
+  local port="$1" explicit="$2" free=""
+
+  port_in_use "$port" || { printf '%s' "$port"; return 0; }
+  free="$(dashboard_free_port "$((port + 1))")"
+
+  if [ -n "$explicit" ]; then
+    err "dashboard: local port $port is already in use on this machine."
+    if [ -n "$free" ]; then
+      err "Stop whatever is listening there, or use a free one: sfbox dashboard --port $free"
+    else
+      err "Stop whatever is listening there, or pass --port with a free port."
+    fi
+    return 1
+  fi
+
+  if [ -z "$free" ]; then
+    err "dashboard: local port $port is in use, and so are the next $SFBOX_DASHBOARD_PORT_SCAN."
+    err "Free one of them, or pass --port with a port you know is free."
+    return 1
+  fi
+
+  warn "local port $port is in use, so this tunnel uses $free instead."
+  printf '%s' "$free"
+}
+
 cmd_dashboard() {
-  local box_arg="" port="$SFBOX_DEFAULT_DASHBOARD_PORT"
+  local box_arg="" port="$SFBOX_DEFAULT_DASHBOARD_PORT" port_explicit=""
   while [ $# -gt 0 ]; do
     case "$1" in
       --box)  box_arg="${2:-}"; shift 2 || die "'$1' needs a value" ;;
-      --port) port="${2:-}"; shift 2 || die "'$1' needs a value" ;;
+      --port) port="${2:-}"; port_explicit=yes; shift 2 || die "'$1' needs a value" ;;
       -h|--help) echo "usage: sfbox dashboard [--box <boxId>] [--port <local-port>]"; return 0 ;;
       *) die "dashboard: unknown argument '$1'" ;;
     esac
@@ -771,6 +843,7 @@ cmd_dashboard() {
   esac
   state_init
   local box; box="$(resolve_box "$box_arg")" || exit $?
+  port="$(dashboard_resolve_port "$port" "$port_explicit")" || exit 1
 
   say "Tunnelling the dashboard from '$box' to http://127.0.0.1:$port"
   say "The SPA is embedded in the gc binary and served by the supervisor, so there"

participant-box-cli/tests/run-tests.sh

@@ -23,9 +23,13 @@ trap 'rm -rf "$SFBOX_TEST_ROOT"' EXIT
 
 PASS=0
 FAIL=0
+SKIP=0
 
 ok()   { PASS=$((PASS + 1)); printf '  ok   %s\n' "$1"; }
 bad()  { FAIL=$((FAIL + 1)); printf '  FAIL %s\n' "$1"; printf '       %s\n' "$2"; }
+# A test that could not run is neither a pass nor a failure, and counting it as
+# either hides it. The summary reports these separately for the same reason.
+skip() { SKIP=$((SKIP + 1)); printf '  SKIP %s\n' "$1"; }
 
 is() { # actual expected label
   if [ "$1" = "$2" ]; then ok "$3"; else bad "$3" "want [$2], got [$1]"; fi
@@ -144,6 +148,103 @@ rc_is 1 "get-box rejects a non-numeric --lines"        cmd_get_box --lines abc
 rc_is 1 "restart-factory rejects a non-numeric --wait" cmd_restart_factory --wait soon
 rc_is 1 "dashboard rejects a non-numeric --port"       cmd_dashboard --port http
 
+# -------------------------------------------------- dashboard local port ---
+
+# Two halves, tested apart. The policy is what the command decides once it knows
+# a port is busy, and a stubbed probe drives it here so the answers do not depend
+# on what happens to be listening on the machine running the suite. The probe is
+# the other half, and it goes against a real listener below.
+
+real_port_in_use="$(declare -f port_in_use)"
+busy_ports=""
+port_in_use() { case " $busy_ports " in *" $1 "*) return 0 ;; *) return 1 ;; esac; }
+
+echo "dashboard: a free port is used as asked"
+busy_ports=""
+is "$(dashboard_resolve_port 8372 '')"  "8372" "the default is left alone"
+is "$(dashboard_resolve_port 9999 yes)" "9999" "an explicit port is left alone"
+
+echo "dashboard: a busy default moves, and says where"
+busy_ports="8372"
+is "$(dashboard_resolve_port 8372 '' 2>/dev/null)" "8373" "moves to the next free port"
+out="$(dashboard_resolve_port 8372 '' 2>&1 >/dev/null)"
+contains "$out" "8372" "names the port that was busy"
+contains "$out" "8373" "names the port it moved to"
+
+busy_ports="8372 8373 8374"
+is "$(dashboard_resolve_port 8372 '' 2>/dev/null)" "8375" "walks past a run of busy ports"
+
+# The half of the ask that is easy to get backwards. Someone who typed a port
+# wants to hear it is taken, not to be moved off it without being told.
+echo "dashboard: an explicit port is never moved"
+busy_ports="8372"
+rc_is 1 "refuses rather than relocating" dashboard_resolve_port 8372 yes
+is "$(dashboard_resolve_port 8372 yes 2>/dev/null)" "" "offers no port to bind"
+out="$(dashboard_resolve_port 8372 yes 2>&1 >/dev/null)"
+contains "$out" "already in use" "says what is wrong"
+contains "$out" "--port 8373"    "points at the flag, with a port that is free"
+
+echo "dashboard: every port in the scan window is busy"
+saved_scan="$SFBOX_DASHBOARD_PORT_SCAN"
+SFBOX_DASHBOARD_PORT_SCAN=2
+busy_ports="8372 8373 8374"
+rc_is 1 "gives up rather than scanning on" dashboard_resolve_port 8372 ''
+contains "$(dashboard_resolve_port 8372 '' 2>&1 >/dev/null)" "8372" \
+  "names the port it started from"
+contains "$(dashboard_resolve_port 8372 yes 2>&1 >/dev/null)" "pass --port" \
+  "still gives advice when it has no port to suggest"
+SFBOX_DASHBOARD_PORT_SCAN="$saved_scan"
+
+echo "dashboard: the scan stays inside the port range"
+busy_ports="65535"
+is "$(dashboard_free_port 65535)" "" "never suggests a port above 65535"
+
+eval "$real_port_in_use"
+unset busy_ports
+
+# ---- the probe, against a real listener -------------------------------------
+#
+# The stubs above prove the decisions. This proves the one thing they cannot:
+# that /dev/tcp really does see a held port, which is the assumption the rest of
+# the feature rests on. python3 holds the port because the repo already depends
+# on it for scripts/check_links.py, and because nc's flags differ across the BSD
+# and GNU builds this suite has to run on.
+
+echo "dashboard: the probe against a real listener"
+if command -v python3 >/dev/null 2>&1; then
+  probe_port="$(dashboard_free_port 18372)"
+  spare_port=""
+  [ -n "$probe_port" ] && spare_port="$(dashboard_free_port "$((probe_port + 1))")"
+  if [ -n "$probe_port" ] && [ -n "$spare_port" ]; then
+    python3 -c 'import socket, sys, time
+s = socket.socket()
+s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+s.bind(("127.0.0.1", int(sys.argv[1])))
+s.listen(8)
+sys.stdout.write("up\n")
+sys.stdout.flush()
+time.sleep(30)' "$probe_port" >"$SFBOX_TEST_ROOT/listener" 2>/dev/null &
+    listener_pid=$!
+    waited=0
+    while [ "$waited" -lt 50 ] && ! grep -q up "$SFBOX_TEST_ROOT/listener" 2>/dev/null; do
+      sleep 0.1
+      waited=$((waited + 1))
+    done
+    if grep -q up "$SFBOX_TEST_ROOT/listener" 2>/dev/null; then
+      rc_is 0 "sees a port a listener is holding" port_in_use "$probe_port"
+      rc_is 1 "sees a port nothing is holding"    port_in_use "$spare_port"
+    else
+      skip "the test listener never came up"
+    fi
+    kill "$listener_pid" 2>/dev/null
+    wait "$listener_pid" 2>/dev/null
+  else
+    skip "no free local port to hold for the probe test"
+  fi
+else
+  skip "no python3, so the probe never met a real listener"
+fi
+
 # ------------------------------------------------------ size guardrail -----
 
 echo "prompt-size guardrail"
@@ -1058,5 +1159,7 @@ is "$(wc -c <"$PROBE_LOG" | tr -d ' ')" "0" "never offers the key to a box that
 # ------------------------------------------------------------------ done ---
 
 echo
-printf '%s passed, %s failed\n' "$PASS" "$FAIL"
+printf '%s passed, %s failed' "$PASS" "$FAIL"
+[ "$SKIP" = 0 ] || printf ', %s skipped' "$SKIP"
+printf '\n'
 [ "$FAIL" = 0 ] || exit 1