feat(launcher-standard): cross-platform browser launch + env-overridable wait timing

Two related template improvements that the standard had already partly
declared but never specified or implemented in the reference templates.

The prose template covered only `xdg-open` / `firefox` / `chromium` —
Linux-only despite the standard's stated cross-platform commitment
(launcher-standard.adoc §System Integration Modes design principle 2).
On macOS the template fell through to "Open manually: $URL"; on
Windows-via-Git-Bash and on WSL it did too, even though every modern
WSL install has `wslview` and Git Bash has `start`.

Fix:
- `$BROWSER` env var honoured first (de-facto Unix convention; lets
  users / operators override without re-minting the launcher).
- Platform dispatch via `uname -s`:
  - macOS: `open`
  - Linux: WSL detection via `/proc/version contains "microsoft"` →
    `wslview` preferred (opens in Windows-side default browser; native
    Linux browsers either land in WSLg or fail). Otherwise the
    existing `xdg-open` → `firefox` → `chromium` chain.
  - Windows (MINGW/MSYS/CYGWIN under Git Bash): `start` (cmd builtin)
- Fallback unchanged: print "Open manually: $URL"

a2ml gains `[browser-launch]` declaring the resolution order
declaratively so consumers (`launch-scaffolder`, audit tools) can
reason about it without re-parsing the bash.

The a2ml had `wait-for-url-timeout-seconds = 15` but the bash template
hardcoded `wait_for_server 15` — operators on slow hosts had no way
to extend the timeout short of editing the script. Also the template
had no per-request timeout: a single hung TCP connection could block
the whole polling loop.

Fix to `[runtime]`:
- `wait-for-url-timeout-env-var = "WAIT_FOR_URL_TIMEOUT_SECONDS"` —
  formalises the override name
- `wait-for-url-poll-interval-seconds = 1` + env var (was implicit in
  the template's `sleep 1`)
- `wait-for-url-per-request-timeout-seconds = 2` — caps each curl probe

Fix to template:
- `local max_wait="${1:-${WAIT_FOR_URL_TIMEOUT_SECONDS:-15}}"` — chain
  arg → env → default
- `curl -fsS --max-time "$per_request_timeout"` — bounded per-request
- Error message now tells operators how to extend the timeout

Both files in the same commit per the lock-step requirement and the
gate in PR #172. Bash blocks pass `bash -n` syntax check.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

docs/UX-standards/launcher-standard.adoc

@@ -75,47 +75,89 @@ stop_server() {
 [source,bash]
 ----
 wait_for_server() {
-  local max_wait=$1
+  # All three values are env-overridable per [runtime] in launcher-standard.a2ml.
+  local max_wait="${1:-${WAIT_FOR_URL_TIMEOUT_SECONDS:-15}}"
+  local poll_interval="${WAIT_FOR_URL_POLL_INTERVAL:-1}"
+  local per_request_timeout=2   # curl --max-time; caps each probe so a
+                                # hung server can't eat the whole budget
   local waited=0
-  
-  while [ $waited -lt $max_wait ]; do
-    if curl -fsS "$URL" >/dev/null 2>&1; then
+
+  while [ "$waited" -lt "$max_wait" ]; do
+    if curl -fsS --max-time "$per_request_timeout" "$URL" >/dev/null 2>&1; then
       return 0  # Success
     fi
-    sleep 1
-    waited=$((waited + 1))
+    sleep "$poll_interval"
+    waited=$((waited + poll_interval))
   done
-  
+
   return 1  # Timeout
 }
 
-# Usage
-if ! wait_for_server 15; then
-  err "Server did not start within 15 seconds"
+# Usage — pass nothing so the env-var/constant chain applies.
+if ! wait_for_server; then
+  err "Server did not start within ${WAIT_FOR_URL_TIMEOUT_SECONDS:-15}s"
   err "Check log: $LOG_FILE"
+  err "Override with WAIT_FOR_URL_TIMEOUT_SECONDS=<N> if the host needs longer"
   return 1
 fi
 ----
 
 === Browser Launching
 
+Resolution order, per `[browser-launch]` in `launcher-standard.a2ml`:
+
+1. `$BROWSER` env var (de-facto Unix convention; user/operator override)
+2. Platform-specific ladder, dispatched via `uname -s`:
+   - **macOS**: `open`
+   - **Linux**: if WSL (detected via `/proc/version` containing
+     "microsoft"), prefer `wslview` so the URL opens in the Windows-side
+     default browser. Otherwise: `xdg-open` → `firefox` → `chromium`.
+   - **Windows** (Git Bash / MSYS / Cygwin): `start` (cmd builtin)
+3. Fallback: print `"Open manually: $URL"` so the user is never silently
+   left without a URL.
+
 [source,bash]
 ----
 open_browser() {
   if ! is_running; then
     err "Server is not running"
     return 1
   fi
-  
-  if command -v xdg-open >/dev/null 2>&1; then
-    xdg-open "$URL" &
-  elif command -v firefox >/dev/null 2>&1; then
-    firefox "$URL" &
-  elif command -v chromium >/dev/null 2>&1; then
-    chromium "$URL" &
-  else
-    log "Open manually: $URL"
+
+  # 1. $BROWSER override (canonical Unix convention)
+  if [[ -n "${BROWSER:-}" ]]; then
+    "$BROWSER" "$URL" &
+    return $?
   fi
+
+  # 2. Platform-specific ladder
+  case "$(uname -s)" in
+    Darwin*)
+      open "$URL" &
+      ;;
+    Linux*)
+      # WSL detection: /proc/version mentions "microsoft" under WSL1/2
+      if grep -qi microsoft /proc/version 2>/dev/null && \
+         command -v wslview >/dev/null 2>&1; then
+        wslview "$URL" &
+      elif command -v xdg-open >/dev/null 2>&1; then
+        xdg-open "$URL" &
+      elif command -v firefox >/dev/null 2>&1; then
+        firefox "$URL" &
+      elif command -v chromium >/dev/null 2>&1; then
+        chromium "$URL" &
+      else
+        log "Open manually: $URL"
+      fi
+      ;;
+    MINGW*|MSYS*|CYGWIN*)
+      # Git Bash / MSYS / Cygwin all carry `start` from cmd
+      start "$URL" &
+      ;;
+    *)
+      log "Open manually: $URL"
+      ;;
+  esac
 }
 ----
 

launcher/launcher-standard.a2ml

@@ -92,12 +92,37 @@ pid-file-pattern = "${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}}/{app-name}-server.pid"
 # Per-user, survives reboot, not world-writable. The {app-name} subdir
 # isolates each launcher's logs.
 log-file-pattern = "${XDG_STATE_HOME:-$HOME/.local/state}/{app-name}/server.log"
+# URL-readiness polling after start. The launcher polls the app's URL
+# until either it responds or total-timeout-seconds elapses.
+# All three timing values are env-var overridable so operators can tune
+# without re-minting the launcher.
 wait-for-url-timeout-seconds = 15
+wait-for-url-timeout-env-var = "WAIT_FOR_URL_TIMEOUT_SECONDS"
+wait-for-url-poll-interval-seconds = 1
+wait-for-url-poll-interval-env-var = "WAIT_FOR_URL_POLL_INTERVAL"
+# Per-request timeout: cap each individual curl probe so a hung server
+# does not eat the entire poll budget on a single request.
+wait-for-url-per-request-timeout-seconds = 2
 startup-command-search = [
     "{repo-dir}/scripts/run.sh",
     "{repo-dir}/dev.sh",
 ]
 
+[browser-launch]
+# How open_browser() resolves which command to invoke. Implementations
+# MUST honour env-var-override first (de-facto $BROWSER convention),
+# then fall back to the platform-specific ladder. Platform detected via
+# `uname -s`; on Linux, additionally probe /proc/version for "microsoft"
+# to detect WSL — under WSL, wslview is preferred so the URL opens in
+# the Windows-side default browser (Linux-side browsers either land in
+# WSLg or fail).
+env-var-override = "BROWSER"
+linux       = ["wslview", "xdg-open", "firefox", "chromium"]
+linux-wsl-detect = "/proc/version contains 'microsoft' (case-insensitive)"
+macos       = ["open"]
+windows     = ["start"]   # cmd builtin; works under Git Bash / MSYS / Cygwin
+fallback    = "log 'Open manually: <URL>'"
+
 [error-visibility]
 # When the launcher runs in a GUI context (no tty + DISPLAY/WAYLAND_DISPLAY set),
 # errors must be visible to the user via a GUI dialog, not only to stderr.