diff --git a/README.md b/README.md
index 43e07feb2..931eb9144 100644
--- a/README.md
+++ b/README.md
@@ -40,6 +40,8 @@ The most capable agent surface that ships. Continuously tuned by real-world use
 curl -fsSL https://omp.sh/install | sh
 ```
 
+> **Alpine / musl:** the prebuilt musl binary links `libstdc++`/`libgcc` dynamically, which stock Alpine does not ship. Install them first: `apk add libstdc++ libgcc`.
+
 **Homebrew**
 
 ```sh
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 40b91d9dd..cf610969c 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -12,6 +12,9 @@
 - Fixed bug where `agent()` calls in eval cells ignored turn cancellation and continued running indefinitely
 - Fixed the built-in `tail` printing `tail: Broken pipe` and failing when a downstream pipeline reader exited early (e.g. `tail -c N file.jsonl | jq …` with jq aborting on a parse error); it now exits silently with 141 (128+SIGPIPE) like a real tail, in every output path including `--follow`.
 - Fixed the in-process ps shell builtin rejecting common procps/BSD format specifiers (`ps -o tpgid,...` failed with `unknown output format specifier`); added `tpgid`, `pri`, `flags`, real/effective user and group columns, `wchan`, fault counters, `sz`, and the STAT `+` foreground flag.
+### Fixed
+
+- Fixed `install.sh` reporting success (exit 0) for a musl binary that cannot start: the installer now smoke-runs the downloaded binary and, on failure, prints the captured error plus the `apk add libstdc++ libgcc` remediation for musl targets and exits non-zero. Documented the Alpine/musl runtime requirement in the README ([#7545](https://github.com/can1357/oh-my-pi/issues/7545)).
 
 ## [17.2.6] - 2026-08-03
 
diff --git a/scripts/install.sh b/scripts/install.sh
index ae40e0161..29e7adbff 100755
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -267,6 +267,28 @@ install_binary() {
     echo "Downloading ${BINARY}..."
     curl -fsSL --connect-timeout 10 --speed-limit 1024 --speed-time 30 "$BINARY_URL" -o "${INSTALL_DIR}/omp"
     chmod +x "${INSTALL_DIR}/omp"
+
+    # Verify the freshly installed binary can actually start before reporting
+    # success. Bun's musl-target binaries link libstdc++/libgcc dynamically,
+    # which stock Alpine/musl systems do not ship, so the download succeeds while
+    # the binary exits 127 with relocation errors. Never claim success for a
+    # binary that cannot run.
+    if ! SMOKE_OUTPUT="$("${INSTALL_DIR}/omp" --version 2>&1)"; then
+        echo ""
+        echo "✗ omp was downloaded to ${INSTALL_DIR}/omp but cannot start:"
+        echo "$SMOKE_OUTPUT" | sed 's/^/    /'
+        if [ "$PLATFORM" = "linux-musl" ]; then
+            echo ""
+            echo "The musl build links libstdc++/libgcc dynamically. Install them, then re-run 'omp':"
+            if command -v apk >/dev/null 2>&1; then
+                echo "    apk add libstdc++ libgcc"
+            else
+                echo "    (install the libstdc++ and libgcc runtime packages for your distro)"
+            fi
+        fi
+        exit 1
+    fi
+
     echo ""
     echo "✓ Installed omp to ${INSTALL_DIR}/omp"