release: v0.7.1 — provider error pass + standalone binary fix

Combines two pre-release-reviewed passes since v0.7.0:

1. Provider error handling (PRs #789, #794 — already on main) — surfaces
   inner provider message instead of `Bad Request: {?:?}`, extracts Bedrock
   `errorMessage` shape, plain-text 429 retry detection, `model_not_found`
   retry-storm carve-out, telemetry maskString redacts emails + internal
   hostnames, metadata.url internal-host + basic-auth masking, 4KB
   responseBody cap. Documented in `docs/docs/reference/troubleshooting.md`.

2. Standalone binary fix + rename (PR #820 + 16 review-driven fixes added
   on top in this commit):
   - Curl-installed binary no longer crashes with
     `Cannot find module '@altimateai/altimate-core'` on first run. NAPI
     prebuild is embedded into bunfs via a per-target staged shim + Bun
     `onResolve` plugin. Result: 176 MB self-contained binary, no NODE_PATH
     dance.
   - Curl-install binary renamed `altimate-code` → `altimate` to match the
     npm primary `bin`. npm + Homebrew keep both names.
   - Alpine/musl + Windows-on-ARM hit clear early-exit across all four
     install surfaces (curl install, npm wrapper, npm postinstall, build).
   - Build matrix drops linux-*-musl + win32-arm64 (no NAPI prebuilds).
   - Curl install uses `curl --fail` so 404s exit non-zero (no more
     HTML-written-to-disk → tar dies "not in gzip format").

Post-review fixes layered on top of PR #820 (the user-approved 16):
   - `Installation.method()` recognises `~/.altimate/bin` as a curl install
     (was missing — would have broken curl-upgrade in the same release).
   - Install script: stale `altimate-code` cleanup, dual `check_version`
     probe, cp-on-self guard, explicit tar/zip member extraction, Rosetta
     notice, npm-on-musl gcompat clarification, get-started banner mirrors
     npm postinstall, docs URL alignment.
   - `build.ts`: `_requiredExports` JSON.parse + shape-check (prevents JS
     injection from a malicious altimate-core into shipped binary),
     resolved version assertion against package.json, pre-loop staging
     cleanup.
   - Smoke test filters `findLocalBinary` by host OS+arch (no more confused
     status:null from a stale Linux ELF on a Darwin host).
   - README documents the curl install option.
   - Troubleshooting doc covers all four install error classes.

Two 5-persona pre-release reviews drove the surface — provider-error pass
first, then binary-fix + rename pass. 48 new adversarial tests in
`release-v0.7.1-binary-adversarial.test.ts` pin the regression classes
(install-method detection, curl-install hardening, JSON.parse rejection,
version pinning, staging cleanup, build guards, smoke-test hermeticity,
npm-wrapper + postinstall parity, doc surface, cross-file invariants,
release.yml hermetic CI).

Deferred to follow-up issues: #821 (supply-chain hardening — sha256 verify
in install, npm audit signatures, SBOM, cosign), #822 (isMusl refactor),
#823 (build-guard test gaps), #824 (multi-binary PATH warning).

CHANGELOG entry: 10 Fixed / 3 Added / 9 Changed / 1 Removed / 3 Privacy /
3 Testing.

Closes #788 (provider error message surfacing).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: anandgupta42

CHANGELOG.md

@@ -5,12 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.7.1] - 2026-05-06
+## [0.7.1] - 2026-05-20
 
-A focused pass on provider error handling, surfaced by a 5-persona pre-release review.
+A focused provider-error pass plus the standalone-binary fix: the curl-installed binary now starts (previously crashed with `Cannot find module '@altimateai/altimate-core'`), is renamed to match the npm primary `bin` (`altimate-code` → `altimate` for the curl path only), and Alpine + Windows-on-ARM hit a clear early-exit instead of a cryptic gzip failure. Two 5-persona pre-release reviews (provider-error pass, then binary-fix + rename pass) drove the surface — 86 adversarial tests total pin the regression classes.
 
 ### Fixed
 
+- **Curl-installed standalone binary no longer crashes with `Cannot find module '@altimateai/altimate-core'` on first run.** The `script/build.ts` marked altimate-core as `external` (NAPI native modules can't live inside Bun's single-file bunfs), and the release archive shipped only the raw Bun binary — no companion `node_modules`, no NODE_PATH-aware wrapper. CI smoke tests hid the bug by pre-setting NODE_PATH against the developer checkout before invoking the binary. The fix stages a per-target copy of altimate-core whose loader is rewritten to a one-line shim `module.exports = require('./altimate-core.<platform>.node')`, drops the matching `.node` file next to it, and uses a `Bun.build` `onResolve` plugin to redirect every `@altimateai/altimate-core` import to that shim. Bun statically sees a single require and embeds that one `.node` into bunfs. Result: ~176 MB self-contained binary, no companion files, no NODE_PATH dance. CI smoke tests now run with `NODE_PATH` cleared from `$RUNNER_TEMP`, plus an independent `strings`-based content assertion that exactly one platform `.node` is embedded — the v0.5.10 / v0.7.0 class of regression is pinned by three independent guards. (#820)
+- **Alpine Linux (musl) and Windows on ARM64 install paths now fail fast with actionable messages instead of silent 404 → tar/unzip errors.** Pre-fix, `curl … | bash` on an unsupported target would write GitHub's 404 HTML to disk and die "not in gzip format". The curl `install` script, the npm bin wrapper (`packages/opencode/bin/altimate`), the npm `postinstall.mjs`, and `script/build.ts` all detect these platforms early and point to `apk add gcompat` (Alpine) or x64 emulation / WSL (Windows ARM). The musl-detection logic is also `pipefail`-safe (`ldd --version` exits non-zero on musl by design; the previous pipeline-form inherited that failure and silently missed every non-Alpine musl distro). (#820)
+- **Curl install `--fail` on both download paths.** A 404 / WAF block / TLS-rewriting corporate proxy no longer writes the error page to disk and gets unzipped as a binary; `curl --fail` exits non-zero and the install bails cleanly. (#820)
+- **`script/build.ts --target-index=N` for an out-of-range index exits non-zero.** Pre-fix, after the musl/win32-arm64 cull, an invalid index silently produced zero artifacts and CI "succeeded" with no binary. (#820)
+- **`script/build.ts --single` on a musl-linux host refuses to build the unrunnable glibc target.** Pre-fix the build would succeed but the resulting binary couldn't load on the host. (#820)
+- **`Installation.method()` recognises `~/.altimate/bin` as a curl install.** The same release that renames the curl-install dir would have broken `altimate upgrade` for curl-installed users without this; the `.opencode/bin` and `.local/bin` branches stay for back-compat. (#820)
 - **Provider 4xx errors now show the inner error message instead of a raw JSON dump.** When any provider returned the standard `{error: {message, type, code}}` shape (OpenAI, Azure OpenAI, OpenRouter, etc.), `parseAPICallError`'s extraction chain short-circuited on the truthy parent `error` object, the `typeof errMsg === "string"` guard rejected it, and the parser fell through to dumping the raw response body — which appeared as `APIError: Bad Request: {?:?}` after telemetry redaction collapsed string values to `?`. Telemetry caught users retrying broken model selections 3+ times in the same session because the surfaced error gave no clue about the cause. Users now see actionable text such as `APIError: Bad Request: The model 'gpt-5-codex' does not exist or you do not have access to it.` The OR-chain is replaced with explicit-typeof ternaries that mirror `parseStreamError`'s pattern, so a truthy non-string at any tier cannot block a valid string further down the chain. (#789, closes #788)
 - **Bedrock / AWS Lambda `errorMessage` shape is now extracted.** AWS APIs that return `{errorMessage: "...", errorType: "..."}` (Lambda style) previously fell through the OpenAI/Anthropic-shaped chain to a raw-body dump. Added `body.errorMessage` to the extraction ladder in both `parseAPICallError` and `parseStreamError`.
 - **Streaming error path no longer dumps `Unknown: {"type":"error",...}` for non-OpenAI codes.** `parseStreamError` previously handled only 4 OpenAI error codes (`context_length_exceeded`, `insufficient_quota`, `usage_not_included`, `invalid_prompt`); everything else fell through to `JSON.stringify(e)`. Added a default fallback that runs the same string-typeof chain as `parseAPICallError`, so any extractable provider message becomes a clean api_error.
@@ -20,6 +26,24 @@ A focused pass on provider error handling, surfaced by a 5-persona pre-release r
 
 - **`altimate models` discoverability hint on model-not-found errors.** When `error.code === "model_not_found"`, the surfaced message now ends with `Run \`altimate models\` to see available models.` so the next step is one command away.
 - **Provider-API-Errors troubleshooting reference** at `docs/docs/reference/troubleshooting.md` covering model-not-found, unauthorized, rate-limited, context-overflow, and HTML-page error classes.
+- **Install-path troubleshooting section** at `docs/docs/reference/troubleshooting.md` covering "standalone binary not found after curl install" (the `altimate-code` → `altimate` rename), the legacy `Cannot find module '@altimateai/altimate-core'` crash with recovery instructions, Alpine/musl unsupported (with `apk add gcompat` workaround), and Windows-on-ARM unsupported (with WSL workaround). README also documents the curl-install option alongside the npm one.
+
+### Changed
+
+- **Curl-installed binary renamed `altimate-code` → `altimate`** to match the npm package's primary `bin` entry. The npm path continues to expose **both** `altimate` and `altimate-code`, so existing `npm install -g`/`pnpm i -g` users see no behavioural change. Homebrew installs are unchanged (the formula installs `altimate` and symlinks `altimate-code` for back-compat). Only the standalone (`curl … | bash`) channel is affected — it now ships a single self-contained `altimate` binary to `~/.altimate/bin/` (was `~/.altimate-code/bin/altimate-code`). CI users with scripts that called `altimate-code` after the curl install should switch to `altimate` or install via npm. The install script removes any stale `~/.altimate/bin/altimate-code` left over from a pre-v0.7.1 install. (#820)
+- **`check_version` probes both `altimate` and `altimate-code` on PATH** so an upgrade from v0.7.0 doesn't always re-download even when the version already matches. (#820)
+- **Curl install final banner mirrors the npm postinstall**: `altimate`, `altimate run "hello"`, `altimate --help`, and the same `https://altimate-code.dev` docs URL. Rosetta-detected x64 → arm64 swap now emits a one-line muted notice instead of being silent. (#820)
+- **`Installation.method()` upgrade detection recognises `~/.altimate/bin`** as a curl install (in addition to the legacy `~/.opencode/bin` and `~/.local/bin` paths). (#820)
+- **`_requiredExports` literal extracted from `@altimateai/altimate-core/index.js` is JSON.parsed and shape-checked** before being inlined into the per-target staged shim. Pre-fix, the regex match group was inlined verbatim — a malicious altimate-core that published an `index.js` whose `_requiredExports = ["x"]; <attacker JS>; const _foo = [` form would have embedded attacker JavaScript into every shipped binary. The validator now requires a pure JSON array of non-empty short string literals; anything else aborts the build. (#820)
+- **`build.ts` asserts the on-disk `@altimateai/altimate-core` version matches `package.json` declaration** after `bun install --os=* --cpu=*`. Catches the stale-hoist scenario where a previous version lingers in `node_modules/.bun/` and the new build silently embeds yesterday's `.node`. (#820)
+- **Per-target staging dir is wiped before each build** (pre-loop cleanup), not just after, so a previous build that crashed between staging and post-build cleanup can never leak a stale `.altimate-core-staged/` into the next build's resolution. (#820)
+- **Curl install extracts only the expected binary member** from tar/zip archives (`tar --no-same-owner -xzf … "$binary_name"` / `unzip … "$binary_name"`), so a future build mistake that tars a directory of attacker-controlled paths can't write them outside the explicit member. (#820)
+- **`install_from_binary` guards against cp-on-self**: `--binary ~/.altimate/bin/altimate` no longer truncates the destination to empty via POSIX `cp` semantics. (#820)
+- **Build matrix and standalone install matrix now align** — only platforms with a published `@altimateai/altimate-core` NAPI prebuild produce a release archive. (#820)
+
+### Removed
+
+- **`linux-arm64-musl`, `linux-x64-musl`, `linux-x64-baseline-musl`, and `win32-arm64` archives** from the release build matrix. `@altimateai/altimate-core` has no NAPI prebuild for these targets; archives for them were never going to work. The npm wrapper (`bin/altimate`) and npm `postinstall.mjs` hard-error on these platforms with the same `apk add gcompat` / WSL workarounds the curl-install script uses. Re-added when upstream prebuilds ship. (#820)
 
 ### Privacy
 
@@ -30,6 +54,8 @@ A focused pass on provider error handling, surfaced by a 5-persona pre-release r
 ### Testing
 
 - 46 adversarial tests covering JSON-scalar bodies, prototype-pollution attempts, 100KB error messages, malformed JSON, every-tier null/numeric extraction, Bedrock `errorMessage` precedence, the `parseStreamError` fallback for unknown codes, the `model_not_found` retry-storm carve-out, the `altimate models` hint, the responseBody cap, the metadata.url internal-host masking (incl. IPv6 loopback/ULA/link-local, AWS IMDS, public-host basic-auth userinfo strip, RFC1918 boundary checks, lookalike-hostname guards), and the new email / internal-host `maskString` patterns (incl. IMDS, IPv6, and query-fragment leak guards).
+- 48 adversarial tests in `release-v0.7.1-binary-adversarial.test.ts` pinning the binary-fix + rename surface — install-method upgrade-path detection (`.altimate`/`.opencode`/`.local` triple-cover), curl-install hardening (Rosetta notice, cp-on-self guard, stale `altimate-code` cleanup, explicit tar/zip member extraction, dual `check_version` probe, musl + npm gcompat messaging, `--fail` on both curl paths, `pipefail`-safe ldd capture, no musl target-suffix construction), `_requiredExports` JSON.parse + shape-check rejection, altimate-core version pinning + actionable rebuild hint, staging-dir pre-loop wipe + post-build cleanup, empty-targets and musl-host build guards, build matrix excluding linux-musl + win32-arm64, smoke-test hermeticity (host-platform `findLocalBinary` filter + tmpdir cwd + content-level `strings` assertion), npm-wrapper + postinstall fail-fast parity for musl + win32-arm64, troubleshooting and README doc surface, archive-name + bin-rename cross-file invariants, and `release.yml` hermetic CI smoke tests + narrowed `publish-npm` permissions. Tests run together with the provider-error suite as the release-critical gate (`test/branding/ test/install/ test/skill/release-v0.7.1*`).
+- Smoke tests (`test/install/smoke-test-binary.test.ts`) gained: hermetic `NODE_PATH`-cleared invocation from a fresh tmpdir (so Bun's compiled binary cannot walk the worktree for `node_modules`), and a content-level `strings`-based assertion that exactly one platform `.node` is embedded in the compiled binary — independent of any runtime resolution path, so a silent `onResolve` regression that embeds 5 platforms' worth of `.node` files would fire here even if the runtime test passes by accident. (#820)
 
 ## [0.7.0] - 2026-05-03
 

README.md

@@ -28,6 +28,14 @@ into CI pipelines and orchestration DAGs. Precision data tooling for any LLM.
 npm install -g altimate-code
 ```
 
+Or via curl (installs the `altimate` binary to `~/.altimate/bin`):
+
+```bash
+curl -fsSL https://altimate.ai/install | bash
+```
+
+The curl install drops a single self-contained binary named `altimate`. The npm install exposes both `altimate` and `altimate-code` on PATH; the curl install only exposes `altimate`. Alpine Linux (musl) and Windows on ARM64 are not currently supported by the standalone binary — use `apk add gcompat` on Alpine, or use WSL on Windows-on-ARM.
+
 Then — in order:
 
 **Step 1: Configure your LLM provider** (required before anything works):

docs/docs/reference/troubleshooting.md

@@ -1,5 +1,57 @@
 # Troubleshooting
 
+## Installation
+
+### Standalone binary not found after curl install
+
+**Symptoms:** `altimate-code: command not found` after running `curl -fsSL https://altimate.ai/install | bash`.
+
+As of v0.7.1 the curl-installed binary is named `altimate`, not `altimate-code`. The npm package continues to ship both names. If you scripted against the curl install:
+
+```bash
+# Before (v0.7.0 and earlier curl install):
+~/.altimate-code/bin/altimate-code run "..."
+
+# After (v0.7.1+ curl install):
+~/.altimate/bin/altimate run "..."
+```
+
+Or stay on the `altimate-code` name by installing via npm: `npm install -g altimate-code`.
+
+### `Cannot find module '@altimateai/altimate-code-core'`
+
+**Symptoms:** Binary crashes on first run with the above error (curl-installed v0.7.0 and earlier).
+
+The v0.7.0 curl install shipped without the NAPI native module. Fixed in v0.7.1 — the native module is now embedded directly into the binary. Re-install with:
+
+```bash
+curl -fsSL https://altimate.ai/install | bash
+```
+
+### Alpine Linux (musl) not supported
+
+**Symptoms:** `Alpine Linux (musl) is not currently supported by the standalone install` during curl install, or `altimate-code is not currently supported on Alpine Linux (musl)` during `npm install` postinstall.
+
+`@altimateai/altimate-core` has no NAPI prebuild for musl. Workarounds:
+
+```bash
+# Run the glibc binary under Alpine (recommended):
+apk add gcompat
+
+# Then either:
+curl -fsSL https://altimate.ai/install | bash   # standalone binary
+# or:
+apk add gcompat && npm install -g altimate-code  # npm install
+```
+
+Or use a glibc-based base image (`debian`, `ubuntu`, `node:slim`).
+
+### Windows on ARM64 not supported
+
+**Symptoms:** `altimate-code is not currently built for Windows on ARM64` during install.
+
+Run the x64 build under Windows-on-ARM's x64 emulation layer, or use WSL.
+
 ## Log Files
 
 Logs are stored at:

install

@@ -96,6 +96,7 @@ else
       rosetta_flag=$(sysctl -n sysctl.proc_translated 2>/dev/null || echo 0)
       if [ "$rosetta_flag" = "1" ]; then
         arch="arm64"
+        echo -e "${MUTED}Rosetta detected — installing arm64 build${NC}"
       fi
     fi
 
@@ -141,7 +142,8 @@ else
       echo -e "${RED}Alpine Linux (musl) is not currently supported by the standalone install.${NC}"
       echo -e "${MUTED}altimate-core has no NAPI prebuild for musl yet. Workarounds:${NC}"
       echo -e "  • apk add gcompat   ${MUTED}# run glibc binaries on Alpine${NC}"
-      echo -e "  • Use npm: npm install -g altimate-code"
+      echo -e "  • Use npm + gcompat: apk add gcompat && npm install -g altimate-code"
+      echo -e "    ${MUTED}(the npm postinstall also bails on raw musl; gcompat is required either way)${NC}"
       exit 1
     fi
 
@@ -240,16 +242,23 @@ print_message() {
 }
 
 check_version() {
+    # Probe both names: the curl-installed binary is `altimate` (v0.7.1+) but
+    # earlier curl installs and the npm alias still expose `altimate-code`.
+    # Without probing both, an upgrade from v0.7.0 would always re-download.
+    local probe=""
     if command -v altimate >/dev/null 2>&1; then
-        altimate_path=$(which altimate)
+        probe="altimate"
+    elif command -v altimate-code >/dev/null 2>&1; then
+        probe="altimate-code"
+    fi
 
-        ## Check the installed version
-        installed_version=$(altimate --version 2>/dev/null || echo "")
+    if [ -n "$probe" ]; then
+        installed_version=$("$probe" --version 2>/dev/null || echo "")
 
         if [[ "$installed_version" != "$specific_version" ]]; then
             print_message info "${MUTED}Installed version: ${NC}$installed_version."
         else
-            print_message info "${MUTED}Version ${NC}$specific_version${MUTED} already installed"
+            print_message info "${MUTED}Version ${NC}$specific_version${MUTED} already installed${NC}"
             exit 0
         fi
     fi
@@ -358,14 +367,28 @@ download_and_install() {
         curl --fail -# -L -o "$tmp_dir/$filename" "$url"
     fi
 
+    # Extract only the expected binary member rather than the whole archive.
+    # The current build only puts a single file in each archive, but listing
+    # the member explicitly makes a future "tars a whole directory" mistake
+    # incapable of writing attacker-controlled paths to disk.
     if [ "$os" = "linux" ]; then
-        tar -xzf "$tmp_dir/$filename" -C "$tmp_dir"
+        tar --no-same-owner -xzf "$tmp_dir/$filename" -C "$tmp_dir" "$binary_name"
     else
-        unzip -q "$tmp_dir/$filename" -d "$tmp_dir"
+        unzip -q "$tmp_dir/$filename" "$binary_name" -d "$tmp_dir"
     fi
 
     mv "$tmp_dir/$binary_name" "${INSTALL_DIR}/$binary_name"
     chmod 755 "${INSTALL_DIR}/$binary_name"
+
+    # If the previous install dropped `altimate-code` here (pre-v0.7.1 curl
+    # install), remove it so users don't end up running a stale binary by
+    # name. The npm/Homebrew/AUR paths still expose both names; only the
+    # standalone $INSTALL_DIR has the rename collapse.
+    if [ "$os" != "windows" ] && [ -f "${INSTALL_DIR}/altimate-code" ]; then
+        rm -f "${INSTALL_DIR}/altimate-code"
+        print_message info "${MUTED}Removed stale ${NC}altimate-code${MUTED} from ${NC}$INSTALL_DIR${MUTED} (renamed to altimate in v0.7.1)${NC}"
+    fi
+
     rm -rf "$tmp_dir"
 }
 
@@ -374,9 +397,21 @@ install_from_binary() {
     # caller's basename so the installed file matches what was supplied.
     local dest_name
     dest_name=$(basename "$binary_path")
+    local dest_path="${INSTALL_DIR}/$dest_name"
+
+    # Guard against cp-on-self: `--binary ~/.altimate/bin/altimate` would
+    # truncate the destination first and produce an empty file. Compare
+    # canonical paths (`-ef` checks inode equality; portable across coreutils
+    # and BusyBox).
+    if [ -f "$dest_path" ] && [ "$binary_path" -ef "$dest_path" ]; then
+        print_message info "${MUTED}Source and destination are the same file — nothing to do: ${NC}$dest_path"
+        chmod 755 "$dest_path"
+        return 0
+    fi
+
     print_message info "\n${MUTED}Installing ${NC}$dest_name ${MUTED}from: ${NC}$binary_path"
-    cp "$binary_path" "${INSTALL_DIR}/$dest_name"
-    chmod 755 "${INSTALL_DIR}/$dest_name"
+    cp "$binary_path" "$dest_path"
+    chmod 755 "$dest_path"
 }
 
 if [ -n "$binary_path" ]; then
@@ -474,11 +509,12 @@ fi
 echo -e ""
 echo -e ""
 echo -e ""
-echo -e "${MUTED}To start:${NC}"
+echo -e "${MUTED}Get started:${NC}"
 echo -e ""
-echo -e "cd <project>  ${MUTED}# Open directory${NC}"
-echo -e "altimate      ${MUTED}# Run command${NC}"
+echo -e "altimate                 ${MUTED}# Open the TUI${NC}"
+echo -e "altimate run \"hello\"     ${MUTED}# Run a quick task${NC}"
+echo -e "altimate --help          ${MUTED}# See all commands${NC}"
 echo -e ""
-echo -e "${MUTED}For more information visit ${NC}https://altimate.ai"
+echo -e "${MUTED}Docs: ${NC}https://altimate-code.dev"
 echo -e ""
 echo -e ""