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

## Summary

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

### 1. Cross-platform `open_browser()`

Previously Linux-only (`xdg-open` / `firefox` / `chromium`) despite
the standard's stated cross-platform commitment (design principle 2:
*"The same launcher script works on Linux, macOS, and Windows."*).
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 has `wslview` and Git Bash has `start`.

Now:

| Step | Action |
|------|--------|
| 1 | Honour `\$BROWSER` env var (de-facto Unix convention; lets users
override without re-minting) |
| 2 | Platform dispatch via `uname -s`: macOS → `open`; Linux → WSL
detection (`/proc/version contains "microsoft"`) → `wslview`, else
`xdg-open` → `firefox` → `chromium`; Windows (MINGW/MSYS/CYGWIN) →
`start` |
| 3 | Fallback unchanged: print `"Open manually: \$URL"` |

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

### 2. `wait_for_server()` honours the env-var override

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
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 with `--max-time`

Fix to template:
\`\`\`bash
local max_wait="\${1:-\${WAIT_FOR_URL_TIMEOUT_SECONDS:-15}}" # arg → env
→ default
local poll_interval="\${WAIT_FOR_URL_POLL_INTERVAL:-1}"
local per_request_timeout=2

curl -fsS --max-time "\$per_request_timeout" "\$URL" >/dev/null 2>&1
\`\`\`

Error message now tells operators how to extend the timeout.

## Compatibility

- Existing launchers that pass an explicit timeout (`wait_for_server
30`)
  still work — the new template prefers the arg over the env var.
- Existing launchers without `\$BROWSER` set get the platform-aware
  ladder, which is strictly more capable than the old Linux-only chain
  (Linux-with-no-WSL behaves identically since `wslview` won't be
  found and `xdg-open` runs).

## Lock-step + coordination

Both files in the same commit per §Sync requirement (and the gate
introduced in #172, which will go green on first push).

Independent of #170, #171, #172, #173, #175, #176. No file overlap
with #176 (which is keepopen.sh).

## Test plan

- [x] a2ml parses (python tomllib); new `[browser-launch]` table and
      4 new `[runtime]` keys round-trip cleanly
- [x] `open_browser()` and `wait_for_server()` bash blocks pass
      `bash -n` syntax check
- [ ] Manual test on macOS / WSL hosts (deferred — needs those
      hosts; logic matches well-documented `uname -s` / `/proc/version`
      conventions used by `wslview` itself)
- [ ] Live lock-step gate (#172) goes green on first push

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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.