diff --git a/README.md b/README.md
index fffd522d8..9a5850dd5 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 46d565c01..df2e3f647 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### 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
 
 ### Added
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"