Harden installer retries and validate release archive

CHANGELOG.md

@@ -13,6 +13,23 @@
 
 None. No tensor, quantization scale, tokenizer, template, configuration, or MTP weight was modified. The official packed-INT4 checkpoint is consumed directly.
 
+## Installer release-gate hardening — August 10, 2026
+
+- Reconstruct the pinned vLLM commit through a dedicated remote ref and a
+  detached checkout. Re-running the build no longer asks Git to fetch into the
+  branch that the first build left checked out.
+- Resolve literal `$HOME`/`$PWD` spellings in every direct path-taking helper,
+  quote virtual-environment executables, and reject whitespace or `:` in the
+  runtime root before Linux `LD_PRELOAD` can split it.
+- Reject empty, unknown, and surplus script arguments instead of silently
+  ignoring them or handing option-like paths to `mkdir`.
+- Verify every allowlisted checkpoint file after `hf download` and validate the
+  checkpoint config/index before launch.
+- Support host-dependency installation when already running as root, while
+  retaining `sudo` for normal users.
+- Replace the WSL Git-clone path—which could pull the full 77 GB checkpoint—with
+  the checksummed 115 MB runtime archive path.
+
 ## Installer path and bootstrap correction — August 10, 2026
 
 - Resolve literal agent-supplied `'$HOME'`, `'${HOME}'`, `'$PWD'`, and

Ling-3.0-Flash-CIRU-int4-Strix-native.tar.gz

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:21931f0293e940ab89d69a5e7235d8855bba195f351cb78861eac5e73d73f06c
-size 114584371
+oid sha256:ebda74c970ce2794942c259d52eea4666de000a54788575849f8a2dd2dd37d1f
+size 114586870

MANIFEST.json

@@ -27,7 +27,7 @@
     "net_files_changed": 8,
     "net_insertions": 459,
     "net_deletions": 28,
-    "engine_revision": "2026-08-10-rocr-installer-recovery",
+    "engine_revision": "2026-08-10-installer-release-gate",
     "rocr_idle_fix": {
       "upstream_repo": "https://github.com/ROCm/rocm-systems.git",
       "upstream_commit": "44be71b52284948e58c93f65f46910399773fdcd",

README.md

@@ -66,6 +66,15 @@ immediately after path resolution, before downloads or builds, so it remains
 available with the intended paths even when a later dependency or build step
 fails. Other unresolved `$...` path expressions are rejected.
 
+The same release gate also found and corrected three retry/portability defects:
+the bundled vLLM branch is now fetched through a detached release ref so a
+second build does not fail on its checked-out branch; all direct build,
+download, and ROCr entry points resolve quoted `$HOME`/`$PWD` paths and reject
+unknown or surplus arguments; and virtual-environment command paths are fully
+quoted. Because Linux `LD_PRELOAD` uses whitespace and colons as separators,
+the runtime install root must not contain either character. The installer now
+rejects such a root immediately instead of producing a broken launch later.
+
 **A 97.5x native ROCm serving campaign:** the first working upstream-compatible build decoded at 0.269 tok/s; this distribution reaches 26.23 tok/s with native MTP K1, while retaining the official vendor checkpoint, OpenAI-compatible serving, continuous batching, and Ling's structured tool parser.
 
 ## What this release changes
@@ -160,6 +169,21 @@ The named release archive is `Ling-3.0-Flash-CIRU-int4-Strix-native.tar.gz`. It
 
 The exact validated environment is Python 3.12, Torch `2.13.0+rocm7.15.0a20260728`, HIP `7.15.0`, Triton `3.8.0+git4cff872c.rocm7.15.0a20260728`, FlashAttention `2.8.3`, and the CIRU vLLM source at `91fab4e6d`.
 
+For a clean runtime installation, download the 115 MB release archive instead
+of cloning this model repository. A normal Git LFS clone can also download the
+77 GB checkpoint at the repository root.
+
+```bash
+mkdir -p ling3-ciru-release
+cd ling3-ciru-release
+curl -fLO https://huggingface.co/jcbtc/Ling-3.0-Flash-CIRU-int4-Strix-native/resolve/main/Ling-3.0-Flash-CIRU-int4-Strix-native.tar.gz
+curl -fLO https://huggingface.co/jcbtc/Ling-3.0-Flash-CIRU-int4-Strix-native/resolve/main/SHA256SUMS.release
+sha256sum --check --ignore-missing SHA256SUMS.release
+tar -xzf Ling-3.0-Flash-CIRU-int4-Strix-native.tar.gz
+cd Ling-3.0-Flash-CIRU-int4-Strix-native
+sha256sum --check SHA256SUMS
+```
+
 For a guided install, run this from the repository root:
 
 ```bash
@@ -173,6 +197,10 @@ and defaults to **no**. The installer writes a sourceable
 to download or provide the model later. Declining the model download still
 builds and validates the runtime without weights.
 
+Use an install root without whitespace or `:`. This is a Linux
+`LD_PRELOAD` restriction for the checksum-verified ROCr override; model paths
+may contain spaces.
+
 Agents and automation can avoid prompts:
 
 ```bash

SHA256SUMS

@@ -1,23 +1,23 @@
-7b77dda00cc6bd6d0ce15f7c055f9e997f56e1cf1709c61cca5a57283ce3f008  .gitattributes
-ae71a415f3c8e8ad7274f19c453bed5dcc35f8764c86ec71098752559d3d0653  CHANGELOG.md
-c0ee30e0ee4f23a18fadffe09c6f3f8eebd629354965aaf6dc0fca8e8a8ab9c8  MANIFEST.json
-8195349992dccbfd3b05bb2c0efac1600e611f9d760176b2b8279fc8f7def521  README.md
-411ac21b4849cb3bf65f84a55263550dcd658e0623c2b117233ba1fced1c17ff  assets/ling30int4.png
-dbf3f912d175e69d30b9d352bb01446f231d72112181be6ba3d5b34be741a869  config/experimental-yarn-1m.env
-725bb450e9df2f76bc34604ec6c08c55aa7e19034f244e76a6cc57d0b9ebcbaa  config/native-256k.env
-c9fb6ed33fa8f98e1c4969f5e06118836da733f719b24f7a95a5a48bcb85b3f6  docs/BENCHMARKS.md
-8abecb9df6c5c41058b31dbb8008a5dbd88a5ebd2e0c99079cbf35ec5fa0820f  docs/UBUNTU_BUILD.md
-cb071718556c99c46e7168e02a6ed645daaad0d078f96d9d948217e261a30e4d  docs/VALIDATED_ENVIRONMENT.md
-d6865f2006ad668e0f821c9647a3ad9a412a08d7e8a18e166302a491dfa75298  docs/WINDOWS_WSL2.md
-bd312a67ce39ac6b00416aea121e7637a6835e334d1e3a32a5bd8f8465f39bbc  install.sh
-a14fcd3747829be98a73a453057bd451a492d87a236c2affcf57db1cbbf18386  runtime/COMMITS.txt
-9cbcbbef5e113e22b753801ee141bd877b20c84f25f15cc159d0ae508aaf4324  runtime/Ling-3.0-Flash-CIRU-int4-Strix-native-vllm.bundle
-c0c1446ea2c7334ef8b888f3104ec660d2ab41d2cb08bb9d90a3f589dba040e8  runtime/Ling-3.0-Flash-CIRU-int4-Strix-native-vllm.patch
-ecab16a7d189d48ff85942ebefd49f2c206445a4e4a85de440ebde19b6555551  runtime/SHA256SUMS.runtime
-f71fd4a1831c8f811dc097cb68bc3c9bacb035b91a8c778b8a85866b5c5227df  scripts/build-vllm-gfx1151.sh
-e6e987937ae4cb544b0aa9b3c90c29acd99c0a9bb8569d42bc95ea7169be245e  scripts/download-model.sh
-b410c642e06d1c3fdc6398e4e3e7d3d4eaf9001538e48bd56cd56ab665ff156f  scripts/install-host-deps.sh
-73a9b45bb809b0dd97bf37b94437445ad6f025da0fc9d8bef609ebd08587c9a5  scripts/install-rocr-idle-fix.sh
-27d3cfba9f4178f83cbd2d7e44db098ab69e515f76e5c98c40ac219b7b0597ca  scripts/run-1m-yarn-experimental.sh
-296ee94a925db5b97e21afb6ffd4ae3c0cc1c2be67af81e21350f43efaa59ead  scripts/run-256k.sh
-ccdff390a6cc99d37b5e7f8888d8df8bdf645c9458e31b2e8e7b6cd5db8d2333  scripts/run-common.sh
+7b77dda00cc6bd6d0ce15f7c055f9e997f56e1cf1709c61cca5a57283ce3f008  ./.gitattributes
+b3a12fee0f8e5187dcb389bbb8fc944b84e132b395a43edd8feee1c9e725a057  ./CHANGELOG.md
+95d15a4b46e2c38c1c2af5e098166d43bdd192653a12cc53ad7159420f81e711  ./MANIFEST.json
+9151f96f0a7322d759e1c2f9aa95530fa621f4a78a10f8e85e2fa04bf59e61bb  ./README.md
+411ac21b4849cb3bf65f84a55263550dcd658e0623c2b117233ba1fced1c17ff  ./assets/ling30int4.png
+dbf3f912d175e69d30b9d352bb01446f231d72112181be6ba3d5b34be741a869  ./config/experimental-yarn-1m.env
+725bb450e9df2f76bc34604ec6c08c55aa7e19034f244e76a6cc57d0b9ebcbaa  ./config/native-256k.env
+c9fb6ed33fa8f98e1c4969f5e06118836da733f719b24f7a95a5a48bcb85b3f6  ./docs/BENCHMARKS.md
+801506edabd1e1f3e15c41a3890084d8e15946123652d8677379699009866ace  ./docs/UBUNTU_BUILD.md
+cb071718556c99c46e7168e02a6ed645daaad0d078f96d9d948217e261a30e4d  ./docs/VALIDATED_ENVIRONMENT.md
+eb927bfb99e64911dbc0f6bc0b41f692a07f8d9aed4b551de2de3b1a1acbfd64  ./docs/WINDOWS_WSL2.md
+06c78a1ef6f5ee0c3571bd5d35a0ea0f32e2620d999d02f2c9e9f175141851e1  ./install.sh
+a14fcd3747829be98a73a453057bd451a492d87a236c2affcf57db1cbbf18386  ./runtime/COMMITS.txt
+9cbcbbef5e113e22b753801ee141bd877b20c84f25f15cc159d0ae508aaf4324  ./runtime/Ling-3.0-Flash-CIRU-int4-Strix-native-vllm.bundle
+c0c1446ea2c7334ef8b888f3104ec660d2ab41d2cb08bb9d90a3f589dba040e8  ./runtime/Ling-3.0-Flash-CIRU-int4-Strix-native-vllm.patch
+ecab16a7d189d48ff85942ebefd49f2c206445a4e4a85de440ebde19b6555551  ./runtime/SHA256SUMS.runtime
+0831d1f5c296525333323250227b20be8cee450c33a398d5f2629893b634e1ce  ./scripts/build-vllm-gfx1151.sh
+e41ff92b71b146a745161f6b6b09f1c85d4b828e68aa1e2a151311656c19a7d7  ./scripts/download-model.sh
+566b45b97266bdf215c2da2765b52465c515808223098819ac4086335e6759e4  ./scripts/install-host-deps.sh
+2ace002dc64d1ccd20df9ad02b8d3d0212c05c50ced8f26be9c24cf889c0f925  ./scripts/install-rocr-idle-fix.sh
+72f4024af2ad19ee58af201d4fc29f84481b521a80e36c88ae1ab0b6edf7e0e1  ./scripts/run-1m-yarn-experimental.sh
+f3fa5364ce194b6676bbe3566604f73d2df9ac381fe1937bf7abc465dde8fd2c  ./scripts/run-256k.sh
+581792ad19506e9db61fddcf1c077c8b81dc72e8e5a5ac72eba722597052dfb6  ./scripts/run-common.sh

SHA256SUMS.release

@@ -1,25 +1,25 @@
-21931f0293e940ab89d69a5e7235d8855bba195f351cb78861eac5e73d73f06c  ./Ling-3.0-Flash-CIRU-int4-Strix-native.tar.gz
+ebda74c970ce2794942c259d52eea4666de000a54788575849f8a2dd2dd37d1f  ./Ling-3.0-Flash-CIRU-int4-Strix-native.tar.gz
 7b77dda00cc6bd6d0ce15f7c055f9e997f56e1cf1709c61cca5a57283ce3f008  ./Ling-3.0-Flash-CIRU-int4-Strix-native/.gitattributes
-ae71a415f3c8e8ad7274f19c453bed5dcc35f8764c86ec71098752559d3d0653  ./Ling-3.0-Flash-CIRU-int4-Strix-native/CHANGELOG.md
-c0ee30e0ee4f23a18fadffe09c6f3f8eebd629354965aaf6dc0fca8e8a8ab9c8  ./Ling-3.0-Flash-CIRU-int4-Strix-native/MANIFEST.json
-8195349992dccbfd3b05bb2c0efac1600e611f9d760176b2b8279fc8f7def521  ./Ling-3.0-Flash-CIRU-int4-Strix-native/README.md
-52495e76d74c6b17a8af08f116deaa040d9713d9bbad595004dff2df8af20984  ./Ling-3.0-Flash-CIRU-int4-Strix-native/SHA256SUMS
+b3a12fee0f8e5187dcb389bbb8fc944b84e132b395a43edd8feee1c9e725a057  ./Ling-3.0-Flash-CIRU-int4-Strix-native/CHANGELOG.md
+95d15a4b46e2c38c1c2af5e098166d43bdd192653a12cc53ad7159420f81e711  ./Ling-3.0-Flash-CIRU-int4-Strix-native/MANIFEST.json
+9151f96f0a7322d759e1c2f9aa95530fa621f4a78a10f8e85e2fa04bf59e61bb  ./Ling-3.0-Flash-CIRU-int4-Strix-native/README.md
+5a7af736e6c1e1d51717f32cdb9b0331261f3b5d0c2491c474905ee8b1c6639c  ./Ling-3.0-Flash-CIRU-int4-Strix-native/SHA256SUMS
 411ac21b4849cb3bf65f84a55263550dcd658e0623c2b117233ba1fced1c17ff  ./Ling-3.0-Flash-CIRU-int4-Strix-native/assets/ling30int4.png
 dbf3f912d175e69d30b9d352bb01446f231d72112181be6ba3d5b34be741a869  ./Ling-3.0-Flash-CIRU-int4-Strix-native/config/experimental-yarn-1m.env
 725bb450e9df2f76bc34604ec6c08c55aa7e19034f244e76a6cc57d0b9ebcbaa  ./Ling-3.0-Flash-CIRU-int4-Strix-native/config/native-256k.env
 c9fb6ed33fa8f98e1c4969f5e06118836da733f719b24f7a95a5a48bcb85b3f6  ./Ling-3.0-Flash-CIRU-int4-Strix-native/docs/BENCHMARKS.md
-8abecb9df6c5c41058b31dbb8008a5dbd88a5ebd2e0c99079cbf35ec5fa0820f  ./Ling-3.0-Flash-CIRU-int4-Strix-native/docs/UBUNTU_BUILD.md
+801506edabd1e1f3e15c41a3890084d8e15946123652d8677379699009866ace  ./Ling-3.0-Flash-CIRU-int4-Strix-native/docs/UBUNTU_BUILD.md
 cb071718556c99c46e7168e02a6ed645daaad0d078f96d9d948217e261a30e4d  ./Ling-3.0-Flash-CIRU-int4-Strix-native/docs/VALIDATED_ENVIRONMENT.md
-d6865f2006ad668e0f821c9647a3ad9a412a08d7e8a18e166302a491dfa75298  ./Ling-3.0-Flash-CIRU-int4-Strix-native/docs/WINDOWS_WSL2.md
-bd312a67ce39ac6b00416aea121e7637a6835e334d1e3a32a5bd8f8465f39bbc  ./Ling-3.0-Flash-CIRU-int4-Strix-native/install.sh
+eb927bfb99e64911dbc0f6bc0b41f692a07f8d9aed4b551de2de3b1a1acbfd64  ./Ling-3.0-Flash-CIRU-int4-Strix-native/docs/WINDOWS_WSL2.md
+06c78a1ef6f5ee0c3571bd5d35a0ea0f32e2620d999d02f2c9e9f175141851e1  ./Ling-3.0-Flash-CIRU-int4-Strix-native/install.sh
 a14fcd3747829be98a73a453057bd451a492d87a236c2affcf57db1cbbf18386  ./Ling-3.0-Flash-CIRU-int4-Strix-native/runtime/COMMITS.txt
 9cbcbbef5e113e22b753801ee141bd877b20c84f25f15cc159d0ae508aaf4324  ./Ling-3.0-Flash-CIRU-int4-Strix-native/runtime/Ling-3.0-Flash-CIRU-int4-Strix-native-vllm.bundle
 c0c1446ea2c7334ef8b888f3104ec660d2ab41d2cb08bb9d90a3f589dba040e8  ./Ling-3.0-Flash-CIRU-int4-Strix-native/runtime/Ling-3.0-Flash-CIRU-int4-Strix-native-vllm.patch
 ecab16a7d189d48ff85942ebefd49f2c206445a4e4a85de440ebde19b6555551  ./Ling-3.0-Flash-CIRU-int4-Strix-native/runtime/SHA256SUMS.runtime
-f71fd4a1831c8f811dc097cb68bc3c9bacb035b91a8c778b8a85866b5c5227df  ./Ling-3.0-Flash-CIRU-int4-Strix-native/scripts/build-vllm-gfx1151.sh
-e6e987937ae4cb544b0aa9b3c90c29acd99c0a9bb8569d42bc95ea7169be245e  ./Ling-3.0-Flash-CIRU-int4-Strix-native/scripts/download-model.sh
-b410c642e06d1c3fdc6398e4e3e7d3d4eaf9001538e48bd56cd56ab665ff156f  ./Ling-3.0-Flash-CIRU-int4-Strix-native/scripts/install-host-deps.sh
-73a9b45bb809b0dd97bf37b94437445ad6f025da0fc9d8bef609ebd08587c9a5  ./Ling-3.0-Flash-CIRU-int4-Strix-native/scripts/install-rocr-idle-fix.sh
-27d3cfba9f4178f83cbd2d7e44db098ab69e515f76e5c98c40ac219b7b0597ca  ./Ling-3.0-Flash-CIRU-int4-Strix-native/scripts/run-1m-yarn-experimental.sh
-296ee94a925db5b97e21afb6ffd4ae3c0cc1c2be67af81e21350f43efaa59ead  ./Ling-3.0-Flash-CIRU-int4-Strix-native/scripts/run-256k.sh
-ccdff390a6cc99d37b5e7f8888d8df8bdf645c9458e31b2e8e7b6cd5db8d2333  ./Ling-3.0-Flash-CIRU-int4-Strix-native/scripts/run-common.sh
+0831d1f5c296525333323250227b20be8cee450c33a398d5f2629893b634e1ce  ./Ling-3.0-Flash-CIRU-int4-Strix-native/scripts/build-vllm-gfx1151.sh
+e41ff92b71b146a745161f6b6b09f1c85d4b828e68aa1e2a151311656c19a7d7  ./Ling-3.0-Flash-CIRU-int4-Strix-native/scripts/download-model.sh
+566b45b97266bdf215c2da2765b52465c515808223098819ac4086335e6759e4  ./Ling-3.0-Flash-CIRU-int4-Strix-native/scripts/install-host-deps.sh
+2ace002dc64d1ccd20df9ad02b8d3d0212c05c50ced8f26be9c24cf889c0f925  ./Ling-3.0-Flash-CIRU-int4-Strix-native/scripts/install-rocr-idle-fix.sh
+72f4024af2ad19ee58af201d4fc29f84481b521a80e36c88ae1ab0b6edf7e0e1  ./Ling-3.0-Flash-CIRU-int4-Strix-native/scripts/run-1m-yarn-experimental.sh
+f3fa5364ce194b6676bbe3566604f73d2df9ac381fe1937bf7abc465dde8fd2c  ./Ling-3.0-Flash-CIRU-int4-Strix-native/scripts/run-256k.sh
+581792ad19506e9db61fddcf1c077c8b81dc72e8e5a5ac72eba722597052dfb6  ./Ling-3.0-Flash-CIRU-int4-Strix-native/scripts/run-common.sh

docs/UBUNTU_BUILD.md

@@ -56,6 +56,12 @@ builds and validates `vllm`.
 The model download defaults to **no**; declining it produces a valid runtime-only
 installation and a copyable command for obtaining the model later.
 
+Use the archive-based clean-install commands in the main README rather than a
+normal Git LFS clone when you do not already need the 77 GB checkpoint at the
+repository root. The runtime install root must not contain whitespace or `:`
+because Linux uses both as `LD_PRELOAD` separators; model paths may contain
+spaces.
+
 For non-interactive agents, see `bash install.sh --help`. The numbered steps
 below remain available for manual diagnosis and custom automation.
 
@@ -134,6 +140,8 @@ The command argument is the install root. Use `.venv` beneath that exact same
 path as `VENV` when launching. If the build exits before the two lines above,
 the environment is partial even if ROCm tools such as `hipcc` already exist;
 rerun the corrected build command against the same install root.
+The pinned source reconstruction is explicitly rerunnable and checks out the
+release commit detached, so recovery does not fetch into a checked-out branch.
 
 ## 5. Download the unchanged checkpoint and serve
 

docs/WINDOWS_WSL2.md

@@ -51,18 +51,30 @@ rocminfo | grep -A4 -B2 gfx1151
 
 Do not proceed until `rocminfo` identifies `gfx1151`. Native-Linux `/dev/kfd` instructions do not apply to the WSL bridge.
 
-## 3. Clone and build the CIRU runtime
+## 3. Download and build the CIRU runtime
 
 Inside WSL:
 
 ```bash
-git clone https://huggingface.co/jcbtc/Ling-3.0-Flash-CIRU-int4-Strix-native
+mkdir -p "$HOME/ling3-ciru-release"
+cd "$HOME/ling3-ciru-release"
+curl -fLO https://huggingface.co/jcbtc/Ling-3.0-Flash-CIRU-int4-Strix-native/resolve/main/Ling-3.0-Flash-CIRU-int4-Strix-native.tar.gz
+curl -fLO https://huggingface.co/jcbtc/Ling-3.0-Flash-CIRU-int4-Strix-native/resolve/main/SHA256SUMS.release
+sha256sum --check --ignore-missing SHA256SUMS.release
+tar -xzf Ling-3.0-Flash-CIRU-int4-Strix-native.tar.gz
 cd Ling-3.0-Flash-CIRU-int4-Strix-native
+sha256sum --check SHA256SUMS
 
 bash scripts/install-host-deps.sh
 bash scripts/build-vllm-gfx1151.sh "$HOME/ciru-ling-runtime"
 ```
 
+Use the release archive for a runtime-only checkout. A normal Git LFS clone of
+the model repository can download the 77 GB checkpoint before the build and is
+unnecessary when the model will live under `$HOME/models`. The runtime install
+root must not contain whitespace or `:` because the ROCr override is loaded
+through `LD_PRELOAD`.
+
 The build script detects WSL and refuses to continue when `/dev/dxg` is absent. It installs the release's pinned Linux ROCm/Torch userspace in its own virtual environment; do not install a separate PyTorch into that environment.
 
 ## 4. Download and serve

install.sh

@@ -22,6 +22,8 @@ Options:
   --interactive          Ask for paths and optional actions.
   --install-root PATH    Runtime root; defaults to the current directory.
                          The vLLM environment is created at PATH/.venv.
+                         PATH cannot contain whitespace or a colon because
+                         the ROCr override is loaded through LD_PRELOAD.
   --model-path PATH      Exact checkpoint directory; defaults to
                          ./Ling-3.0-Flash-CIRU-int4-Strix-native.
   --install-host-deps    Run scripts/install-host-deps.sh (may use sudo).
@@ -54,7 +56,7 @@ absolute_path() {
   local path="$1"
   case "$path" in
     '~') path="$HOME" ;;
-    '~/'*) path="$HOME/${path#\~/}" ;;
+    [~]/*) path="$HOME/${path#\~/}" ;;
     '$HOME') path="$HOME" ;;
     '$HOME/'*) path="$HOME/${path#\$HOME/}" ;;
     '${HOME}') path="$HOME" ;;
@@ -139,11 +141,13 @@ while [ "$#" -gt 0 ]; do
       ;;
     --install-root)
       [ "$#" -ge 2 ] || die '--install-root requires a path'
+      [ -n "$2" ] || die '--install-root requires a non-empty path'
       install_root="$2"
       shift 2
       ;;
     --model-path)
       [ "$#" -ge 2 ] || die '--model-path requires a path'
+      [ -n "$2" ] || die '--model-path requires a non-empty path'
       model_path="$2"
       shift 2
       ;;
@@ -206,6 +210,11 @@ if [ "$interactive" = 1 ]; then
 fi
 
 install_root="$(absolute_path "${install_root:-$PWD}")"
+case "$install_root" in
+  *[[:space:]:]*)
+    die "install root cannot contain whitespace or ':' because ROCr is loaded through LD_PRELOAD: $install_root"
+    ;;
+esac
 venv="$install_root/.venv"
 env_file="$install_root/ling3-runtime.env"
 if [ "$upgrade" != 1 ]; then

scripts/build-vllm-gfx1151.sh

@@ -1,9 +1,53 @@
 #!/usr/bin/env bash
 set -Eeuo pipefail
 
-install_root="${1:-$PWD/ciru-ling-runtime}"
 script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
 package_root="$(cd -- "$script_dir/.." && pwd)"
+release_branch=ciru/ling3-gfx1151-rocm715
+bundle_ref=refs/remotes/ciru-release/ling3-gfx1151-rocm715
+export PATH="$HOME/.local/bin:$PATH"
+
+die() {
+  printf 'build-vllm-gfx1151.sh: %s\n' "$*" >&2
+  exit 2
+}
+
+absolute_path() {
+  local path="$1"
+  case "$path" in
+    '~') path="$HOME" ;;
+    [~]/*) path="$HOME/${path#\~/}" ;;
+    '$HOME') path="$HOME" ;;
+    '$HOME/'*) path="$HOME/${path#\$HOME/}" ;;
+    '${HOME}') path="$HOME" ;;
+    '${HOME}/'*) path="$HOME/${path#\$\{HOME\}/}" ;;
+    '$PWD') path="$PWD" ;;
+    '$PWD/'*) path="$PWD/${path#\$PWD/}" ;;
+    '${PWD}') path="$PWD" ;;
+    '${PWD}/'*) path="$PWD/${path#\$\{PWD\}/}" ;;
+  esac
+  case "$path" in
+    *'$'*) die "unexpanded shell variable in path: $path" ;;
+  esac
+  if command -v realpath >/dev/null 2>&1; then
+    realpath -m -- "$path"
+  elif [[ "$path" = /* ]]; then
+    printf '%s\n' "$path"
+  else
+    printf '%s/%s\n' "$PWD" "${path#./}"
+  fi
+}
+
+[ "$#" -le 1 ] || die 'usage: build-vllm-gfx1151.sh [INSTALL_ROOT]'
+if [ "$#" -eq 1 ] && [ -z "$1" ]; then
+  die 'install root cannot be empty'
+fi
+install_root="$(absolute_path "${1:-$PWD/ciru-ling-runtime}")"
+case "$install_root" in
+  *[[:space:]:]*)
+    die "install root cannot contain whitespace or ':' because ROCr is loaded through LD_PRELOAD: $install_root"
+    ;;
+esac
 venv="$install_root/.venv"
 source_dir="$install_root/vllm"
 index=https://rocm.nightlies.amd.com/whl-multi-arch/
@@ -12,12 +56,11 @@ head=91fab4e6dcaa683911655630dae8a5b140a7cb91
 bundle="$package_root/runtime/Ling-3.0-Flash-CIRU-int4-Strix-native-vllm.bundle"
 flash_source="$install_root/flash-attention"
 flash_commit=0e60e39473e8df549a20fb5353760f7a65b30e2d
-export PATH="$HOME/.local/bin:$PATH"
 
 printf 'CIRU build install root: %s\n' "$install_root"
 printf 'CIRU runtime virtual environment: %s\n' "$venv"
 
-command -v git >/dev/null
+command -v git >/dev/null || die 'missing git; run scripts/install-host-deps.sh first'
 command -v uv >/dev/null || {
   echo "Missing uv. Run scripts/install-host-deps.sh first." >&2
   exit 2
@@ -44,7 +87,7 @@ else
   }
 fi
 
-mkdir -p "$install_root"
+mkdir -p -- "$install_root"
 if [ ! -x "$venv/bin/python" ]; then
   UV_CACHE_DIR="${UV_CACHE_DIR:-$install_root/uv-cache}" uv python install 3.12
   UV_CACHE_DIR="${UV_CACHE_DIR:-$install_root/uv-cache}" uv venv --python 3.12 "$venv"
@@ -67,11 +110,16 @@ fi
 
 git -C "$source_dir" fetch origin "$base"
 git -C "$source_dir" fetch "$bundle" \
-  refs/heads/ciru/ling3-gfx1151-rocm715:refs/heads/ciru/ling3-gfx1151-rocm715
-git -C "$source_dir" checkout ciru/ling3-gfx1151-rocm715
+  "+refs/heads/$release_branch:$bundle_ref"
+test "$(git -C "$source_dir" rev-parse "$bundle_ref")" = "$head"
+if ! git -C "$source_dir" diff --quiet || \
+   ! git -C "$source_dir" diff --cached --quiet; then
+  die "refusing to replace tracked local changes in $source_dir"
+fi
+git -C "$source_dir" checkout --detach "$head"
 test "$(git -C "$source_dir" rev-parse HEAD)" = "$head"
 
-site="$($venv/bin/python - <<'PY'
+site="$("$venv/bin/python" - <<'PY'
 import site
 print(site.getsitepackages()[0])
 PY

scripts/download-model.sh

@@ -9,6 +9,37 @@ destination_root="$PWD/models"
 destination=
 export PATH="$HOME/.local/bin:$PATH"
 
+die() {
+  printf 'download-model.sh: %s\n' "$*" >&2
+  exit 2
+}
+
+absolute_path() {
+  local path="$1"
+  case "$path" in
+    '~') path="$HOME" ;;
+    [~]/*) path="$HOME/${path#\~/}" ;;
+    '$HOME') path="$HOME" ;;
+    '$HOME/'*) path="$HOME/${path#\$HOME/}" ;;
+    '${HOME}') path="$HOME" ;;
+    '${HOME}/'*) path="$HOME/${path#\$\{HOME\}/}" ;;
+    '$PWD') path="$PWD" ;;
+    '$PWD/'*) path="$PWD/${path#\$PWD/}" ;;
+    '${PWD}') path="$PWD" ;;
+    '${PWD}/'*) path="$PWD/${path#\$\{PWD\}/}" ;;
+  esac
+  case "$path" in
+    *'$'*) die "unexpanded shell variable in path: $path" ;;
+  esac
+  if command -v realpath >/dev/null 2>&1; then
+    realpath -m -- "$path"
+  elif [[ "$path" = /* ]]; then
+    printf '%s\n' "$path"
+  else
+    printf '%s/%s\n' "$PWD" "${path#./}"
+  fi
+}
+
 usage() {
   cat <<EOF
 Download the pinned Ling checkpoint from $source_repo.
@@ -30,13 +61,20 @@ if [ "${1:-}" = --model-path ]; then
 elif [ "${1:-}" = -h ] || [ "${1:-}" = --help ]; then
   usage
   exit 0
-elif [ "$#" -le 1 ]; then
-  destination_root="${1:-$destination_root}"
+elif [[ "${1:-}" = -* ]]; then
+  die "unknown option: $1"
+elif [ "$#" -eq 0 ]; then
+  destination="$destination_root/$release_name"
+elif [ "$#" -eq 1 ]; then
+  [ -n "$1" ] || die 'destination root cannot be empty'
+  destination_root="$1"
   destination="$destination_root/$release_name"
 else
   usage >&2
   exit 2
 fi
+[ -n "$destination" ] || die 'destination cannot be empty'
+destination="$(absolute_path "$destination")"
 
 if command -v hf >/dev/null 2>&1; then
   hf_cmd=(hf)
@@ -47,7 +85,7 @@ else
   exit 2
 fi
 
-mkdir -p "$destination"
+mkdir -p -- "$destination"
 model_files=(
   chat_template.jinja
   config.json
@@ -67,5 +105,16 @@ done
   --revision "$revision" \
   --local-dir "$destination"
 
+missing_files=()
+for model_file in "${model_files[@]}"; do
+  [ -f "$destination/$model_file" ] || missing_files+=("$model_file")
+done
+if [ "${#missing_files[@]}" -ne 0 ]; then
+  printf 'download-model.sh: download completed without %s expected file(s):\n' \
+    "${#missing_files[@]}" >&2
+  printf '  %s\n' "${missing_files[@]}" >&2
+  exit 2
+fi
+
 printf 'model_path=%s\nsource_repo=%s\nsource_revision=%s\nupstream_model_revision=%s\n' \
   "$destination" "$source_repo" "$revision" "$upstream_model_revision"

scripts/install-host-deps.sh

@@ -1,6 +1,11 @@
 #!/usr/bin/env bash
 set -Eeuo pipefail
 
+if [ "$#" -ne 0 ]; then
+  printf 'install-host-deps.sh: this command takes no arguments.\n' >&2
+  exit 2
+fi
+
 if [ "$(uname -s)" != Linux ]; then
   echo "Run this inside native Linux or WSL2, not native Windows." >&2
   exit 2
@@ -15,19 +20,30 @@ fi
 source /etc/os-release
 distro="${ID:-unknown} ${ID_LIKE:-}"
 
+run_as_root() {
+  if [ "${EUID:-$(id -u)}" -eq 0 ]; then
+    "$@"
+  elif command -v sudo >/dev/null 2>&1; then
+    sudo "$@"
+  else
+    printf 'install-host-deps.sh: sudo is required when not running as root.\n' >&2
+    exit 2
+  fi
+}
+
 if [[ "$distro" =~ (ubuntu|debian) ]]; then
-  sudo apt-get update
-  sudo apt-get install -y \
+  run_as_root apt-get update
+  run_as_root apt-get install -y \
     build-essential git curl ca-certificates pkg-config \
     libnuma-dev libdrm-dev libelf-dev xxd python3-dev
 elif [[ "$distro" =~ (fedora|rhel|centos) ]]; then
-  sudo dnf install -y \
+  run_as_root dnf install -y \
     gcc gcc-c++ make git curl ca-certificates pkgconf-pkg-config \
     numactl-devel libdrm-devel elfutils-libelf-devel xxd python3-devel
 elif [[ "$distro" =~ (arch) ]]; then
-  sudo pacman -Syu --needed --noconfirm \
+  run_as_root pacman -Syu --needed --noconfirm \
     base-devel git curl ca-certificates pkgconf numactl libdrm python
-  sudo pacman -S --needed --noconfirm libelf tinyxxd
+  run_as_root pacman -S --needed --noconfirm libelf tinyxxd
 else
   echo "Unsupported automatic dependency install for: $distro" >&2
   echo "Install a C/C++ toolchain, git, curl, pkg-config, NUMA/DRM/ELF headers, xxd, and Python 3; then install uv." >&2

scripts/install-rocr-idle-fix.sh

@@ -1,26 +1,75 @@
 #!/usr/bin/env bash
 set -Eeuo pipefail
 
-install_root="${1:-$PWD}"
-force="${2:-}"
-venv="$install_root/.venv"
 rocm_systems_repo=https://github.com/ROCm/rocm-systems.git
 rocm_systems_commit=44be71b52284948e58c93f65f46910399773fdcd
-source_root="${CIRU_ROCR_SOURCE_DIR:-$install_root/rocr-idle-fix/source}"
-build_dir="${CIRU_ROCR_BUILD_DIR:-$install_root/rocr-idle-fix/build}"
-override_dir="$install_root/runtime-overrides/rocr-7.15-gcc-idle"
-runtime_name=libhsa-runtime64.so.1.21.0
-runtime_path="$override_dir/$runtime_name"
-provenance="$override_dir/BUILD-PROVENANCE.txt"
 
 die() {
   printf 'install-rocr-idle-fix.sh: %s\n' "$*" >&2
   exit 2
 }
 
-if [ "$force" != "" ] && [ "$force" != "--force" ]; then
-  die "unknown option: $force"
-fi
+absolute_path() {
+  local path="$1"
+  case "$path" in
+    '~') path="$HOME" ;;
+    [~]/*) path="$HOME/${path#\~/}" ;;
+    '$HOME') path="$HOME" ;;
+    '$HOME/'*) path="$HOME/${path#\$HOME/}" ;;
+    '${HOME}') path="$HOME" ;;
+    '${HOME}/'*) path="$HOME/${path#\$\{HOME\}/}" ;;
+    '$PWD') path="$PWD" ;;
+    '$PWD/'*) path="$PWD/${path#\$PWD/}" ;;
+    '${PWD}') path="$PWD" ;;
+    '${PWD}/'*) path="$PWD/${path#\$\{PWD\}/}" ;;
+  esac
+  case "$path" in
+    *'$'*) die "unexpanded shell variable in path: $path" ;;
+  esac
+  if command -v realpath >/dev/null 2>&1; then
+    realpath -m -- "$path"
+  elif [[ "$path" = /* ]]; then
+    printf '%s\n' "$path"
+  else
+    printf '%s/%s\n' "$PWD" "${path#./}"
+  fi
+}
+
+install_root_arg="$PWD"
+force=
+case "$#" in
+  0) ;;
+  1)
+    if [ "$1" = --force ]; then
+      force=--force
+    else
+      [ -n "$1" ] || die 'install root cannot be empty'
+      install_root_arg="$1"
+    fi
+    ;;
+  2)
+    [ -n "$1" ] || die 'install root cannot be empty'
+    [ "$2" = --force ] || die "unknown option: $2"
+    install_root_arg="$1"
+    force=--force
+    ;;
+  *) die 'usage: install-rocr-idle-fix.sh [INSTALL_ROOT] [--force]' ;;
+esac
+
+install_root="$(absolute_path "$install_root_arg")"
+case "$install_root" in
+  *[[:space:]:]*)
+    die "install root cannot contain whitespace or ':' because ROCr is loaded through LD_PRELOAD: $install_root"
+    ;;
+esac
+venv="$install_root/.venv"
+source_root="$(absolute_path "${CIRU_ROCR_SOURCE_DIR:-$install_root/rocr-idle-fix/source}")"
+build_dir="$(absolute_path "${CIRU_ROCR_BUILD_DIR:-$install_root/rocr-idle-fix/build}")"
+override_dir="$install_root/runtime-overrides/rocr-7.15-gcc-idle"
+runtime_name=libhsa-runtime64.so.1.21.0
+runtime_path="$override_dir/$runtime_name"
+provenance="$override_dir/BUILD-PROVENANCE.txt"
+
 if [ "$(uname -s)" != Linux ]; then
   die 'the ROCr idle-runtime build requires Linux'
 fi
@@ -40,7 +89,7 @@ for command_name in git gcc g++ pkg-config sha256sum xxd; do
     die "missing $command_name; run scripts/install-host-deps.sh"
 done
 
-site="$($venv/bin/python - <<'PY'
+site="$("$venv/bin/python" - <<'PY'
 import site
 print(site.getsitepackages()[0])
 PY
@@ -151,8 +200,8 @@ mv -f "$runtime_path.new" "$runtime_path"
   printf 'rocm_systems_commit=%s\n' "$rocm_systems_commit"
   printf 'runtime_name=%s\n' "$runtime_name"
   printf 'runtime_sha256=%s\n' "$(sha256sum "$runtime_path" | awk '{print $1}')"
-  printf 'cc=%s\n' "$($cc --version | head -n 1)"
-  printf 'cxx=%s\n' "$($cxx --version | head -n 1)"
+  printf 'cc=%s\n' "$("$cc" --version | head -n 1)"
+  printf 'cxx=%s\n' "$("$cxx" --version | head -n 1)"
 } >"$provenance"
 (cd "$override_dir" && sha256sum --check SHA256SUMS)
 

scripts/run-1m-yarn-experimental.sh

@@ -1,6 +1,11 @@
 #!/usr/bin/env bash
 set -Eeuo pipefail
 
+if [ "$#" -ne 0 ]; then
+  printf 'run-1m-yarn-experimental.sh: this command takes no arguments; use HOST, PORT, and documented environment overrides.\n' >&2
+  exit 2
+fi
+
 script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
 package_root="$(cd -- "$script_dir/.." && pwd)"
 # shellcheck disable=SC1091

scripts/run-256k.sh

@@ -1,6 +1,11 @@
 #!/usr/bin/env bash
 set -Eeuo pipefail
 
+if [ "$#" -ne 0 ]; then
+  printf 'run-256k.sh: this command takes no arguments; use HOST, PORT, and documented environment overrides.\n' >&2
+  exit 2
+fi
+
 script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
 package_root="$(cd -- "$script_dir/.." && pwd)"
 # shellcheck disable=SC1091

scripts/run-common.sh

@@ -1,6 +1,11 @@
 #!/usr/bin/env bash
 set -Eeuo pipefail
 
+if [ "$#" -ne 0 ]; then
+  printf 'run-common.sh: internal launcher takes no arguments.\n' >&2
+  exit 2
+fi
+
 release_name=Ling-3.0-Flash-CIRU-int4-Strix-native
 venv="${VENV:?Set VENV to the built runtime virtual environment}"
 model_path="${MODEL_PATH:?Set MODEL_PATH to the downloaded checkpoint directory}"
@@ -9,6 +14,14 @@ port="${PORT:-18081}"
 cache_root="${CACHE_ROOT:-$HOME/.cache/ciru-ling3-vllm}"
 max_num_batched_tokens="${MAX_NUM_BATCHED_TOKENS:-8192}"
 
+case "$venv" in
+  *[[:space:]:]*)
+    printf "VENV cannot contain whitespace or ':' because ROCr is loaded through LD_PRELOAD: %s\n" \
+      "$venv" >&2
+    exit 2
+    ;;
+esac
+
 if [ ! -x "$venv/bin/python" ]; then
   printf 'Runtime virtual environment is missing Python: %s\n' \
     "$venv/bin/python" >&2
@@ -26,7 +39,15 @@ if [ ! -d "$model_path" ]; then
   printf 'Set MODEL_PATH to the directory containing the downloaded Ling checkpoint.\n' >&2
   exit 2
 fi
-site="$($venv/bin/python - <<'PY'
+for required_model_file in config.json model.safetensors.index.json; do
+  if [ ! -f "$model_path/$required_model_file" ]; then
+    printf 'Model checkpoint is missing %s: %s\n' \
+      "$required_model_file" "$model_path/$required_model_file" >&2
+    printf 'MODEL_PATH must be the exact downloaded checkpoint directory, not its parent.\n' >&2
+    exit 2
+  fi
+done
+site="$("$venv/bin/python" - <<'PY'
 import site
 print(site.getsitepackages()[0])
 PY
@@ -40,6 +61,13 @@ if [ ! -x "$sdk/bin/hipcc" ]; then
 fi
 install_root="$(cd -- "$(dirname -- "$venv")" && pwd -P)"
 rocr_override_dir="${ROCR_IDLE_RUNTIME_DIR:-$install_root/runtime-overrides/rocr-7.15-gcc-idle}"
+case "$rocr_override_dir" in
+  *[[:space:]:]*)
+    printf "ROCR_IDLE_RUNTIME_DIR cannot contain whitespace or ':' because it is loaded through LD_PRELOAD: %s\n" \
+      "$rocr_override_dir" >&2
+    exit 2
+    ;;
+esac
 rocr_idle_runtime="$rocr_override_dir/libhsa-runtime64.so.1.21.0"
 if [ "${CIRU_DISABLE_ROCR_IDLE_FIX:-0}" = 1 ]; then
   printf 'WARNING: CIRU ROCr idle-runtime override is disabled.\n' >&2
@@ -56,7 +84,6 @@ else
       "$rocr_idle_runtime" >&2
     exit 2
   fi
-  export LD_PRELOAD="$rocr_idle_runtime${LD_PRELOAD:+:$LD_PRELOAD}"
 fi
 mkdir -p "$cache_root/vllm" "$cache_root/triton" "$cache_root/huggingface-modules"
 
@@ -115,6 +142,10 @@ if [ "${DRY_RUN:-0}" = 1 ]; then
   exit 0
 fi
 
+if [ "${CIRU_DISABLE_ROCR_IDLE_FIX:-0}" != 1 ]; then
+  export LD_PRELOAD="$rocr_idle_runtime${LD_PRELOAD:+:$LD_PRELOAD}"
+fi
+
 printf 'Launching %s\n' "$release_name"
 printf '  vLLM: %s\n  model: %s\n  listen: %s:%s\n' \
   "$venv/bin/vllm" "$model_path" "$host" "$port"