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: AMFI rejects the release Mach-O at exec
   The lightpanda-aarch64-macos asset has a linker-signed ad-hoc
   signature without a CMS blob (`codesign -dv` shows
   flags=0x20002(adhoc,linker-signed)). AMFI on Apple Silicon
   enforces stricter requirements outside trusted prefixes; from
   /tmp or ~/.local/bin the kernel rejects it as
   'Unrecoverable CT signature issue, bailing out' and SIGKILLs
   at exec. Re-signing locally with `codesign -s -` adds a CMS
   blob but AMFI then rejects with error -423 (adhoc signed by
   unknown chain).

   Verified empirically: same byte-identical Mach-O runs from
   /opt/homebrew/Cellar/lightpanda/.../bin/lightpanda but is
   SIGKILLed from /tmp/. Copying the broken curl-downloaded
   bytes INTO the brew path makes them run. So the trust is
   path-based, not byte-based.

   The Lightpanda brew formula does NOT build from source
   (verified via `brew cat`) — it just downloads the same
   Mach-O and runs `bin.install` to place it at
   /opt/homebrew/Cellar/.../bin/lightpanda, which AMFI exempts
   from the strict ad-hoc signature check.

   Reproducing on M3 Pro / macOS 14.x; should be uniform across
   Apple Silicon but not directly tested on M1/M2/M4. Intel
   macOS keeps the GitHub Release Mach-O path — Apple Silicon's
   stricter AMFI enforcement is arm64-specific and I don't have
   an Intel Mac to test.

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 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.

Smaller adjacent changes, each tightly motivated by the three above:

- set -euo pipefail (was set -e); curl -fSL (was -sL/-L). pipefail
  + -f propagate curl HTTP errors through curl | jq, replacing the
  misleading 'could not retrieve checksum' message.
- chmod 0755 instead of chmod a+x. Required because fix #2 uses
  mktemp (0600); chmod a+x on top yields 0711 (owner-only readable).
- Apple Silicon PATH-shadow warning. A user upgrading from a pre-
  this-PR version still has the rejected ~/.local/bin/lightpanda
  (the linker-signed Mach-O) which shadows the new working brew
  binary in PATH — without the warning they still get SIGKILL after
  a successful brew install.
- LIGHTPANDA_DIR warning on Apple Silicon (brew owns the install
  path; the variable is silently ignored without this).
- SKILL.md Install section: per-OS callout describing the flow split.

Better long-term fix (out of scope for this PR): upstream-side, the
build pipeline producing the GitHub Release assets should apply a
proper ad-hoc signature with a CMS blob (or, better, Developer ID +
notarization). The release Mach-O would then run from anywhere and
this workaround wouldn't be needed.

Intentionally not included (offered as follow-ups):
- Optional $GITHUB_TOKEN for API quota
- PATH-shadow check on the shared download flow
- Upstream-side signing fix (separate repo)

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,14 +1,14 @@
 #!/bin/bash
 # Lightpanda Setup Script
-# Run once to install Lightpanda browser
+# Run to install or update Lightpanda. macOS arm64 → Homebrew tap;
+# macOS x86_64 + Linux → GitHub Release download + atomic install.
 
-set -e
+# pipefail catches a failing curl in `curl | jq` that jq would otherwise swallow.
+set -euo pipefail
 
-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)"
@@ -32,10 +32,59 @@ 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: AMFI rejects the release Mach-O's linker-signed signature
+                # (no CMS blob) when it's executed from arbitrary user paths like /tmp or
+                # ~/.local/bin — the binary gets SIGKILLed at exec with kernel log
+                # "AMFI: ... Unrecoverable CT signature issue, bailing out.". The brew tap's
+                # bin.install puts the same byte-identical binary at /opt/homebrew/Cellar/...,
+                # which AMFI exempts from the strict ad-hoc signature check, so it runs.
+                # (Re-signing locally with `codesign -s -` doesn't help — AMFI then rejects
+                # with error -423 "adhoc signed or signed by an unknown certificate chain".)
+                if ! command -v brew &> /dev/null; then
+                    echo "ERROR: Apple Silicon install requires Homebrew (https://brew.sh)."
+                    echo "Install Homebrew, then re-run. Or: brew install lightpanda-io/browser/lightpanda"
+                    exit 1
+                fi
+                if [ -n "${LIGHTPANDA_DIR:-}" ]; then
+                    echo "Note: LIGHTPANDA_DIR is ignored on Apple Silicon — brew owns the install path."
+                fi
+                echo "Detected: $OS $ARCH — installing via Homebrew tap."
+                # `install` is a no-op when current; `upgrade` keeps reruns fresh. Both exit 0 in the
+                # up-to-date case and non-zero on real errors, so `set -e` propagates genuine failures.
+                brew install lightpanda-io/browser/lightpanda
+                brew upgrade lightpanda-io/browser/lightpanda
+                # Anchor on `brew --prefix` (general, not keg-specific) so a stale ~/.local/bin/lightpanda
+                # from a pre-this-PR run can't shadow the brew binary undetected.
+                BREW_PREFIX="$(brew --prefix)"
+                BIN_PATH="$BREW_PREFIX/bin/$BINARY_NAME"
+                [ -x "$BIN_PATH" ] || { echo "ERROR: brew install completed but $BIN_PATH is missing. Try: brew link --overwrite lightpanda"; exit 1; }
+                # Hard-fail smoke test — brew can ship a binary that crashes at exec; surface stderr.
+                DARWIN_SMOKE_STDERR=$(mktemp)
+                trap 'rm -f "$DARWIN_SMOKE_STDERR"' EXIT
+                if ! VERSION_OUT=$("$BIN_PATH" version 2>"$DARWIN_SMOKE_STDERR") || [ -z "$VERSION_OUT" ]; then
+                    echo "ERROR: Homebrew-installed lightpanda failed its version smoke test."
+                    [ -s "$DARWIN_SMOKE_STDERR" ] && { echo "  Binary stderr:"; sed 's/^/    /' "$DARWIN_SMOKE_STDERR"; }
+                    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 about PATH-shadow: a pre-this-PR run left the SIGKILL Mach-O at ~/.local/bin/lightpanda;
+                # without this check the user still runs the broken one despite brew installing a working 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: $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,7 +99,10 @@ 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
@@ -75,9 +127,12 @@ mkdir -p "$INSTALL_DIR"
 # Determine asset name from URL
 ASSET_NAME="${DOWNLOAD_URL##*/}"
 
-# Fetch expected SHA256 digest from GitHub release API
+# Fetch expected SHA256 digest from GitHub release API. -f makes curl
+# exit non-zero on HTTP errors (4xx/5xx) so set -e + pipefail catch
+# them; without it curl exits 0 on 503 and jq fails on the error body
+# with a misleading "could not retrieve checksum" message.
 echo "Fetching expected checksum from GitHub API..."
-EXPECTED_DIGEST=$(curl -sL "https://api.github.com/repos/lightpanda-io/browser/releases/tags/nightly" \
+EXPECTED_DIGEST=$(curl -fSL "https://api.github.com/repos/lightpanda-io/browser/releases/tags/nightly" \
     | jq -r --arg name "$ASSET_NAME" '.assets[] | select(.name == $name) | .digest')
 
 if [ -z "$EXPECTED_DIGEST" ] || [ "$EXPECTED_DIGEST" = "null" ]; then
@@ -89,28 +144,57 @@ fi
 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 — the
+# `--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
 if [[ ":$PATH:" != *":$INSTALL_DIR:"* ]]; then
@@ -120,14 +204,8 @@ if [[ ":$PATH:" != *":$INSTALL_DIR:"* ]]; then
     echo "  export PATH=\"\$PATH:$INSTALL_DIR\""
 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 ==="