unbreak macOS Apple Silicon install, atomic Linux install, real version smoke test

Three independently-motivated bug fixes in scripts/install.sh:

1. macOS Apple Silicon: nightly Mach-O is SIGKILLed at exec
   The lightpanda-aarch64-macos asset is killed by the kernel even
   with an ad-hoc / linker signature; ad-hoc re-signing locally does
   not help. Route ONLY Apple Silicon through the upstream Homebrew
   tap (lightpanda-io/browser/lightpanda), which builds from source.
   Intel macOS keeps the GitHub Release Mach-O path — there's no
   evidence the SIGKILL applies to x86_64 and switching working users
   to a brew dependency unprompted would be over-aggressive.

2. Failed reruns destroy existing working binary
   SKILL.md documents reruns as the update path, but
   curl -L -o "$INSTALL_DIR/$BINARY_NAME" overwrites the install
   target during download. Atomic install via mktemp + verify +
   smoke-test + mv preserves the existing binary on any failure.

3. --version smoke test silently accepts broken binaries
   Lightpanda's CLI has no --version flag; running it logs
   '$msg=exit err=UnknownCommand' and exits 1. The current
   2>/dev/null + --help fallback masks this, and the head -1 pipe at
   the end of the test means it succeeds on broken binaries that
   produce no output. Use the 'version' subcommand and capture stderr
   to surface real diagnostics like 'GLIBC_2.32 not found' on failure.

Other adjacent changes — happy to split into follow-up PRs if you
prefer narrower scope:

- set -euo pipefail (was set -e); pipefail catches a failing curl in
  curl | jq that would otherwise be hidden by jq exiting 0 on empty
  input.
- chmod 0755 instead of chmod a+x — mktemp creates 0600 so a+x yields
  0711 (owner-only readable). Only relevant because of the atomic
  install change.
- Optional $GITHUB_TOKEN raises the API quota from 60->5000/hr.
- PATH-shadow check warns when an older lightpanda is earlier in PATH
  than the freshly installed one.
- SKILL.md Install section gains a per-OS callout describing the
  Apple-Silicon-via-brew vs Intel-+-Linux-via-release split.

Author: staylor

SKILL.md

@@ -25,7 +25,9 @@ Prefer the built-in Web Search tool when it is available and sufficient for your
 bash scripts/install.sh
 ```
 
-Lightpanda is available on Linux and macOS only. Windows is supported via WSL2.
+Lightpanda is available on Linux and macOS only. Windows is supported via WSL2. The script picks the right method per OS:
+- **macOS, Apple Silicon** — installs via the upstream Homebrew tap (`brew install lightpanda-io/browser/lightpanda`). Requires Homebrew. The nightly Mach-O binaries from GitHub Releases get SIGKILLed by the kernel at exec on Apple Silicon despite shipping with an ad-hoc / linker signature, so the script delegates to the tap, which builds from source.
+- **macOS Intel + Linux** — downloads the nightly binary from GitHub Releases, verifies its SHA-256, smoke-tests it, and atomically installs to `$HOME/.local/bin/lightpanda` (override with `LIGHTPANDA_DIR=...`). On rerun, the existing binary is left in place if any step fails.
 
 The binary is a nightly build that evolves quickly. If you encounter crashes or issues, run `scripts/install.sh` again to update to the latest version (max once per day).
 

scripts/install.sh

@@ -1,16 +1,26 @@
 #!/bin/bash
 # Lightpanda Setup Script
-# Run once to install Lightpanda browser
+# Run to install or update the Lightpanda browser binary.
+#
+# macOS arm64 — installs via the upstream Homebrew tap. The nightly
+#                Mach-O is SIGKILLed at exec on Apple Silicon despite
+#                shipping with an ad-hoc / linker signature, so we
+#                delegate to brew which builds from source.
+# macOS x86_64,
+# Linux        — downloads the nightly asset, verifies its SHA-256,
+#                smoke-tests it, and atomically `mv`s it into
+#                $LIGHTPANDA_DIR (default $HOME/.local/bin). The
+#                existing binary is left in place if any step fails —
+#                this is the documented update path.
+
+# `pipefail` propagates a failing curl in `curl | jq` (jq exits 0 on
+# empty input). `-u` turns variable typos into hard errors.
+set -euo pipefail
 
-set -e
-
-INSTALL_DIR="${LIGHTPANDA_DIR:-$HOME/.local/bin}"
 BINARY_NAME="lightpanda"
 
 echo "=== Lightpanda Setup ==="
-echo "Install directory: $INSTALL_DIR"
 
-# Detect OS and architecture
 OS="$(uname -s)"
 ARCH="$(uname -m)"
 
@@ -32,10 +42,70 @@ case "$OS" in
     Darwin)
         case "$ARCH" in
             x86_64)
+                # Intel Macs: the Mach-O release asset runs fine, so
+                # use the same download/verify/atomic-mv path as Linux.
                 DOWNLOAD_URL="https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-macos"
                 ;;
             arm64|aarch64)
-                DOWNLOAD_URL="https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-aarch64-macos"
+                # Apple Silicon: the nightly Mach-O is SIGKILLed at exec
+                # by the kernel even with an ad-hoc / linker signature
+                # (ad-hoc re-signing locally does not help). Route
+                # through the upstream Homebrew tap, which builds from
+                # source and produces a binary that runs.
+                if ! command -v brew &> /dev/null; then
+                    echo "ERROR: Apple Silicon install requires Homebrew (https://brew.sh)."
+                    echo "Install Homebrew, then re-run this script. Or install Lightpanda directly:"
+                    echo "  brew install lightpanda-io/browser/lightpanda"
+                    exit 1
+                fi
+                echo "Detected: $OS $ARCH — installing via Homebrew tap (lightpanda-io/browser/lightpanda)."
+                # `install` is idempotent on an up-to-date install but
+                # does not auto-upgrade an existing one; `upgrade` keeps
+                # reruns current. Both exit 0 in the up-to-date case
+                # and non-zero on real errors — let `set -e` propagate.
+                brew install lightpanda-io/browser/lightpanda
+                brew upgrade lightpanda-io/browser/lightpanda
+                # Anchor verification to the brew prefix (general, not
+                # keg-specific): a stale `~/.local/bin/lightpanda` from
+                # an earlier curl-on-arm64 attempt could shadow the
+                # brew binary and make us report success for a broken
+                # one.
+                BREW_PREFIX="$(brew --prefix)"
+                BIN_PATH="$BREW_PREFIX/bin/$BINARY_NAME"
+                if [ ! -x "$BIN_PATH" ]; then
+                    echo "ERROR: Homebrew install completed but $BIN_PATH is missing."
+                    echo "Try: brew link --overwrite lightpanda"
+                    exit 1
+                fi
+                # Hard-fail smoke test — brew can produce a binary that
+                # crashes at exec (formula regression, missing dep).
+                # Capture stderr so we can show real diagnostics.
+                DARWIN_SMOKE_STDERR=$(mktemp)
+                trap 'rm -f "$DARWIN_SMOKE_STDERR"' EXIT
+                if VERSION_OUT=$("$BIN_PATH" version 2>"$DARWIN_SMOKE_STDERR") && [ -n "$VERSION_OUT" ]; then
+                    : # ok
+                else
+                    echo "ERROR: Homebrew-installed lightpanda failed its version smoke test (\`$BIN_PATH version\` returned no output or non-zero exit)."
+                    if [ -s "$DARWIN_SMOKE_STDERR" ]; then
+                        echo "  Binary stderr:"
+                        sed 's/^/    /' "$DARWIN_SMOKE_STDERR"
+                    fi
+                    echo "  Try: brew reinstall lightpanda-io/browser/lightpanda"
+                    exit 1
+                fi
+                echo ""
+                echo "Lightpanda installed via Homebrew: $VERSION_OUT"
+                echo "Binary location: $BIN_PATH"
+                # Warn if something earlier in PATH shadows the brew binary.
+                PATH_RESOLVED="$(command -v lightpanda 2>/dev/null || true)"
+                if [ -n "$PATH_RESOLVED" ] && [ "$PATH_RESOLVED" != "$BIN_PATH" ]; then
+                    echo ""
+                    echo "WARNING: another 'lightpanda' is earlier in your PATH:"
+                    echo "  $PATH_RESOLVED"
+                    echo "Remove it or reorder PATH so $BREW_PREFIX/bin takes precedence."
+                fi
+                echo "Run with: lightpanda serve --host 127.0.0.1 --port 9222"
+                exit 0
                 ;;
             *)
                 echo "ERROR: Unsupported architecture: $ARCH"
@@ -50,10 +120,12 @@ case "$OS" in
         ;;
 esac
 
+# --- Shared download flow (Linux + Intel macOS) ---
+INSTALL_DIR="${LIGHTPANDA_DIR:-$HOME/.local/bin}"
 echo "Detected: $OS $ARCH"
+echo "Install directory: $INSTALL_DIR"
 echo "Download URL: $DOWNLOAD_URL"
 
-# Check for required tools
 if ! command -v curl &> /dev/null; then
     echo "ERROR: curl not found. Please install curl."
     exit 1
@@ -69,65 +141,101 @@ if ! command -v sha256sum &> /dev/null && ! command -v shasum &> /dev/null; then
     exit 1
 fi
 
-# Create install directory
 mkdir -p "$INSTALL_DIR"
 
-# Determine asset name from URL
 ASSET_NAME="${DOWNLOAD_URL##*/}"
 
-# Fetch expected SHA256 digest from GitHub release API
+# api.github.com unauthenticated quota is 60/hr/IP; collide on shared
+# NAT or in CI. $GITHUB_TOKEN raises it to 5000/hr. Branch the curl
+# call rather than building an array of header args — `"${arr[@]}"`
+# under `set -u` errors on Bash <=4.3 (RHEL 7, old containers).
+GITHUB_API_URL="https://api.github.com/repos/lightpanda-io/browser/releases/tags/nightly"
 echo "Fetching expected checksum from GitHub API..."
-EXPECTED_DIGEST=$(curl -sL "https://api.github.com/repos/lightpanda-io/browser/releases/tags/nightly" \
-    | jq -r --arg name "$ASSET_NAME" '.assets[] | select(.name == $name) | .digest')
+if [ -n "${GITHUB_TOKEN:-}" ]; then
+    EXPECTED_DIGEST=$(curl -fSL -H "Authorization: Bearer $GITHUB_TOKEN" "$GITHUB_API_URL" \
+        | jq -r --arg name "$ASSET_NAME" '.assets[] | select(.name == $name) | .digest')
+else
+    EXPECTED_DIGEST=$(curl -fSL "$GITHUB_API_URL" \
+        | jq -r --arg name "$ASSET_NAME" '.assets[] | select(.name == $name) | .digest')
+fi
 
 if [ -z "$EXPECTED_DIGEST" ] || [ "$EXPECTED_DIGEST" = "null" ]; then
     echo "ERROR: Could not retrieve checksum for $ASSET_NAME from GitHub API."
     exit 1
 fi
 
-# Strip the "sha256:" prefix
 EXPECTED_SHA256="${EXPECTED_DIGEST#sha256:}"
 echo "Expected SHA256: $EXPECTED_SHA256"
 
-# Download binary
-echo "Downloading Lightpanda..."
-curl -L -o "$INSTALL_DIR/$BINARY_NAME" "$DOWNLOAD_URL"
+# Download to a temp file in the same directory, verify, smoke-test,
+# THEN atomically `mv` into place. SKILL.md documents reruns as the
+# update path, so a failed download must not destroy a working binary.
+TMP_BINARY=$(mktemp "$INSTALL_DIR/.${BINARY_NAME}.XXXXXX")
+SMOKE_STDERR=$(mktemp)
+trap 'rm -f "$TMP_BINARY" "$SMOKE_STDERR"' EXIT
+
+echo "Downloading Lightpanda to $TMP_BINARY..."
+curl -fSL -o "$TMP_BINARY" "$DOWNLOAD_URL"
 
-# Verify checksum
 echo "Verifying checksum..."
 if command -v sha256sum &> /dev/null; then
-    ACTUAL_SHA256=$(sha256sum "$INSTALL_DIR/$BINARY_NAME" | awk '{print $1}')
+    ACTUAL_SHA256=$(sha256sum "$TMP_BINARY" | awk '{print $1}')
 else
-    ACTUAL_SHA256=$(shasum -a 256 "$INSTALL_DIR/$BINARY_NAME" | awk '{print $1}')
+    ACTUAL_SHA256=$(shasum -a 256 "$TMP_BINARY" | awk '{print $1}')
 fi
 
 if [ "$ACTUAL_SHA256" != "$EXPECTED_SHA256" ]; then
     echo "ERROR: Checksum verification FAILED!"
     echo "  Expected: $EXPECTED_SHA256"
     echo "  Actual:   $ACTUAL_SHA256"
-    rm -f "$INSTALL_DIR/$BINARY_NAME"
+    echo "  Existing binary (if any) at $INSTALL_DIR/$BINARY_NAME was NOT replaced."
     exit 1
 fi
 
 echo "Checksum verified OK."
-chmod a+x "$INSTALL_DIR/$BINARY_NAME"
+# 0755 (conventional executable mode) rather than `chmod a+x` over
+# mktemp's 0600, which would yield 0711 (owner-only readable).
+chmod 0755 "$TMP_BINARY"
+
+# Smoke-test BEFORE replacing. Use the `version` subcommand — Lightpanda's
+# `--version` flag exits 1 with `UnknownCommand`, so it would falsely
+# reject a working binary. Capturing stdout to a variable means the `if`
+# exit status is the binary's exit status (no pipe to mask it).
+echo "Smoke-testing the downloaded binary..."
+if ! VERSION_OUT=$("$TMP_BINARY" version 2>"$SMOKE_STDERR") || [ -z "$VERSION_OUT" ]; then
+    echo "ERROR: Downloaded binary failed to run (\`version\` subcommand returned no output or non-zero exit)."
+    echo "  This may indicate an incompatible system, missing libc, or a corrupted release asset."
+    if [ -s "$SMOKE_STDERR" ]; then
+        echo "  Binary stderr:"
+        sed 's/^/    /' "$SMOKE_STDERR"
+    fi
+    echo "  Existing binary (if any) at $INSTALL_DIR/$BINARY_NAME was NOT replaced."
+    exit 1
+fi
+
+# `mv` within the same filesystem is atomic.
+mv "$TMP_BINARY" "$INSTALL_DIR/$BINARY_NAME"
+# Leave the EXIT trap registered so $SMOKE_STDERR still gets cleaned;
+# `rm -f` on the moved-away $TMP_BINARY is a silent no-op.
 
-# Check if install directory is in PATH
+# Check PATH membership AND shadow (something else earlier in PATH).
 if [[ ":$PATH:" != *":$INSTALL_DIR:"* ]]; then
     echo ""
     echo "WARNING: $INSTALL_DIR is not in your PATH"
     echo "Add this to your shell profile (~/.bashrc or ~/.zshrc):"
     echo "  export PATH=\"\$PATH:$INSTALL_DIR\""
+else
+    PATH_RESOLVED="$(command -v lightpanda 2>/dev/null || true)"
+    if [ -n "$PATH_RESOLVED" ] && [ "$PATH_RESOLVED" != "$INSTALL_DIR/$BINARY_NAME" ]; then
+        echo ""
+        echo "WARNING: another 'lightpanda' is earlier in your PATH:"
+        echo "  $PATH_RESOLVED"
+        echo "Remove it or reorder PATH so $INSTALL_DIR takes precedence."
+    fi
 fi
 
-# Test installation
 echo ""
-echo "Testing Lightpanda..."
-if "$INSTALL_DIR/$BINARY_NAME" --version 2>/dev/null || "$INSTALL_DIR/$BINARY_NAME" --help 2>/dev/null | head -1; then
-    echo "Lightpanda installed successfully!"
-else
-    echo "Binary installed at: $INSTALL_DIR/$BINARY_NAME"
-fi
+echo "Lightpanda installed successfully: ${VERSION_OUT:-OK}"
 
 echo ""
 echo "=== Setup Complete ==="