fix: improve novice error messages, gated by automated smoke

internal/hostcmd/exitcode.go

@@ -46,7 +46,13 @@ func NewJoinSessionResponseError(statusCode int, status string, body []byte, cau
 	message := gatewayErrorMessage(status, body, cause)
 	protocolErr, complete := completeProtocolErrorEnvelope(body)
 	if complete {
-		message = protocolErr.Message
+		// user_summary is the human-readable copy written for operators;
+		// prefer it over the terse protocol message.
+		if strings.TrimSpace(protocolErr.UserSummary) != "" {
+			message = protocolErr.UserSummary
+		} else {
+			message = protocolErr.Message
+		}
 	}
 	joinErr := fmt.Errorf("join session failed: %s", message)
 	if statusCode >= 400 && statusCode <= 499 && complete && !protocolErr.Recoverable {

internal/hostcmd/hostcmd.go

@@ -171,8 +171,7 @@ func (a App) runServe(ctx context.Context, opts serveOptions) error {
 		return err
 	}
 	if opts.JoinCode == "" {
-		_, err := fmt.Fprintf(a.Stdout, "rdev-host foreground placeholder\nmode=%s\ngateway=%s\nstatus=not-connected\nnote=provide --gateway and --join-code for a Control Plane session\n", opts.Mode, opts.GatewayURL)
-		return err
+		return fmt.Errorf("--join-code is required; ask the operator (or the Agent) for a session join code, then run: rdev host serve --join-code CODE --gateway URL")
 	}
 	if strings.TrimSpace(opts.GatewayURL) == "" {
 		return fmt.Errorf("gateway is required when --join-code is provided")

internal/hostcmd/route_pool.go

@@ -12,7 +12,7 @@ import (
 	"github.com/EitanWong/remote-dev-skillkit/internal/controlplane"
 )
 
-var errNoHealthyRoutes = errors.New("no healthy gateway routes")
+var errNoHealthyRoutes = errors.New("cannot reach the gateway; check the gateway URL and your network connection")
 
 const (
 	maxGatewayRoutes     = 16

scripts/ux-smoke.sh

@@ -144,7 +144,41 @@ else
   bad "task round trip failed: $(printf '%s' "${RESULT:-}" | head -c 300)"
 fi
 
-# 6. close
+# 7. error paths a novice will hit -- assert human-readable guidance
+step "exercising novice error paths"
+OUT=""
+OUT="$("$WORK/rdev" bogus 2>&1 || true)"
+if [[ "$OUT" == *"available commands"* ]]; then
+  ok "unknown command names available commands"
+else
+  bad "unknown command error lacks guidance: $(printf '%s' "$OUT" | head -c 120)"
+fi
+OUT="$("$WORK/rdev-host" serve 2>&1 || true)"
+if [[ "$OUT" == *"--join-code is required"* ]]; then
+  ok "missing --join-code explains what to do"
+else
+  bad "missing --join-code error not actionable: $(printf '%s' "$OUT" | head -c 120)"
+fi
+OUT="$(timeout 8 "$WORK/rdev-host" serve --join-code ABCD-1234 --gateway "$GW" 2>&1 || true)"
+if [[ "$OUT" =~ invalid|no\ longer\ active ]]; then
+  ok "bad join code error is human-readable"
+else
+  bad "bad join code error unclear: $(printf '%s' "$OUT" | head -c 120)"
+fi
+OUT="$(timeout 8 "$WORK/rdev-host" serve --join-code ABCD-1234 --gateway 'http://127.0.0.1:9' 2>&1 || true)"
+if [[ "$OUT" == *"cannot reach the gateway"* ]]; then
+  ok "unreachable gateway error is human-readable"
+else
+  bad "unreachable gateway error unclear: $(printf '%s' "$OUT" | head -c 120)"
+fi
+OUT="$("$WORK/rdev" gateway serve --dev --addr "127.0.0.1:${PORT}" 2>&1 || true)"
+if [[ "$OUT" == *"already in use"* || "$OUT" == *"try a different port"* ]]; then
+  ok "port-in-use error suggests an alternative"
+else
+  bad "port-in-use error lacks guidance: $(printf '%s' "$OUT" | head -c 120)"
+fi
+
+# 8. close
 step "closing session"
 if curl -sf -X POST "${GW}/v1/sessions/${SID}/close" -H 'Content-Type: application/json' -d '{"reason":"ux smoke complete"}' >/dev/null 2>&1; then
   ok "session closed"