feat(launcher): commit a prebuilt binary via LFS to close the cold-start race

docs/cloud-environment-setup.md documents that on Claude Code on the web,
the MCP client dials configured servers concurrently with (not after)
SessionStart hooks, so a cold `cargo build -p ci-cli` (~59s) easily
outlasts the client's ~7s retry budget — the server gets marked failed for
the rest of the session. The only structural fix was previously a Cloud
environment Setup Script, which is external config (not stored in this
repo) that every user has to paste in manually.

This adds a stronger layer that needs no manual setup at all: a prebuilt
`ci` binary committed to .ci-bin/x86_64-unknown-linux-musl/ci via Git LFS
(already used in this repo for the embedding model weights), rebuilt on
every push to main by .github/workflows/prebuild-mcp-binary.yml. Since a
git checkout necessarily completes before Claude Code can even read
.mcp.json, a binary already present in the checkout has no race to lose.

mcp-launcher.sh gets a new Tier 1.5 trying this path (Linux x86_64 only
for now), subject to the same is_binary_fresh staleness check as a local
target/debug build. Also adds is_lfs_pointer: exec-ing an unresolved LFS
pointer stub (git-lfs not installed, smudge filter skipped) does not fail
gracefully — bash's ENOEXEC fallback interprets the pointer's text content
as a new shell script instead of returning control to the launcher,
verified directly against a synthetic stub. Without the check, a missing
git-lfs would crash the launcher instead of falling through to the
existing tiers.

Kept the Setup Script recommendation in the docs as defense-in-depth: this
depends on the cloud checkout actually resolving the LFS pointer, which
isn't independently verifiable from here, and only covers one platform.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: Your Name

.gitattributes

@@ -1 +1,2 @@
 crates/ci-core/assets/potion-code-16m/*.safetensors filter=lfs diff=lfs merge=lfs -text
+.ci-bin/**/ci filter=lfs diff=lfs merge=lfs -text

.github/workflows/prebuild-mcp-binary.yml

@@ -0,0 +1,55 @@
+name: Prebuild MCP binary
+
+# Keeps a ready-to-run `ci` binary committed at .ci-bin/x86_64-unknown-linux-musl/ci
+# (via Git LFS) so scripts/mcp-launcher.sh has it the instant a fresh clone
+# happens — no compile, no download, no tagged-release requirement. This is
+# what closes the Claude-Code-on-the-web cold-start race that a Setup
+# Script/SessionStart hook can only race, never structurally win — see
+# docs/cloud-environment-setup.md.
+#
+# `paths-ignore: ['.ci-bin/**']` is load-bearing: without it, this workflow's
+# own commit back to main would retrigger itself.
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - '.ci-bin/**'
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          lfs: true
+
+      - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
+        with:
+          targets: x86_64-unknown-linux-musl
+
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        with:
+          key: x86_64-unknown-linux-musl-prebuild
+
+      - name: Install cross
+        run: cargo install cross --locked
+
+      - name: Build
+        run: cross build --release --bin ci --target x86_64-unknown-linux-musl
+
+      - name: Commit prebuilt binary
+        run: |
+          mkdir -p .ci-bin/x86_64-unknown-linux-musl
+          cp target/x86_64-unknown-linux-musl/release/ci .ci-bin/x86_64-unknown-linux-musl/ci
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add .ci-bin/x86_64-unknown-linux-musl/ci
+          if git diff --cached --quiet; then
+            echo "Binary unchanged, nothing to commit"
+            exit 0
+          fi
+          git commit -m "chore(ci-bin): update prebuilt ci binary for $(git rev-parse --short HEAD)"
+          git push

docs/cloud-environment-setup.md

@@ -31,6 +31,37 @@ of this repo's setup relied on that hook alone and believed it had fixed
 the problem; it hadn't — it had just usually won the race, until a session
 where it didn't.
 
+## A stronger layer: a binary already sitting in the checkout
+
+Everything below this point (Setup Script, `MCP_TIMEOUT`) works by trying
+to *win* a race against the MCP client's dial attempt. There's a way to
+avoid the race entirely: `.ci-bin/x86_64-unknown-linux-musl/ci`, a
+prebuilt binary committed to the repo via Git LFS and kept current by
+[`.github/workflows/prebuild-mcp-binary.yml`](../.github/workflows/prebuild-mcp-binary.yml)
+on every push to `main`. `scripts/mcp-launcher.sh` execs it directly
+(subject to the same `is_binary_fresh` staleness check as a local
+`target/debug/ci`) — if it's there, there is no compile step for the MCP
+dial to race against, because the checkout itself (which necessarily
+completes before Claude Code can even read `.mcp.json`) already contains a
+working binary.
+
+**This is not a certainty, only a strong improvement**, for two concrete
+reasons:
+
+- It depends on the cloud checkout mechanism actually resolving the Git
+  LFS pointer to real content (running the smudge filter) rather than
+  leaving a ~130-byte text stub in place. `scripts/mcp-launcher.sh` detects
+  an unresolved pointer and falls through safely instead of crashing (see
+  `is_lfs_pointer`'s comment for why that needed an explicit check — a
+  plain `exec` on a pointer stub does *not* fail gracefully), but a
+  fallthrough here still means you're back to racing the Setup Script
+  against a cold build.
+- It only covers `x86_64-unknown-linux-musl` today. A different sandbox
+  architecture falls through to the tiers below, unaffected either way.
+
+Keep the Setup Script below as defense-in-depth regardless — it's the only
+one of the two that's a guaranteed fix rather than a "very likely" one.
+
 ## The actual fix: a Cloud environment Setup Script
 
 Setup Scripts and `SessionStart` hooks look similar but solve different
@@ -113,6 +144,9 @@ session before any cache exists, or right after the ~7-day cache expiry)
 
 ## What's already handled in this repo (defense in depth, not a substitute)
 
+- `.ci-bin/x86_64-unknown-linux-musl/ci` — see the section above. The one
+  layer that can eliminate the race outright rather than just narrowing it,
+  when it applies.
 - `scripts/mcp-launcher.sh` — `.mcp.json`'s actual entrypoint now (shared
   across every MCP client, not just Claude Code; see
   `docs/mcp-client-setup.md`). Execs an already-cached binary directly if

scripts/mcp-launcher.sh

@@ -6,20 +6,38 @@
 #
 # Resolution order (first usable binary wins, no exceptions):
 #   1. Fast path   — an already-usable binary: $CI_MCP_BIN override, a
-#                     cached verified download, or a local dev build
-#                     (target/release/ci, target/debug/ci) — the dev build
-#                     candidates are only trusted if `is_binary_fresh` says
-#                     they're at least as new as every source file (see that
-#                     function's comment for the incident this guards
-#                     against: a stale target/debug/ci silently served an
-#                     entire MCP session because nothing checked it against
-#                     the checked-out source before exec'ing it).
+#                     cached verified download, a local dev build
+#                     (target/release/ci, target/debug/ci), or a prebuilt
+#                     binary committed to .ci-bin/ via Git LFS — the dev
+#                     build and .ci-bin candidates are only trusted if
+#                     `is_binary_fresh` says they're at least as new as
+#                     every source file (see that function's comment for
+#                     the incident this guards against: a stale
+#                     target/debug/ci silently served an entire MCP session
+#                     because nothing checked it against the checked-out
+#                     source before exec'ing it).
 #                     $CI_MCP_BIN and the cached download are NOT freshness-
 #                     checked here — one is an explicit override (the caller
 #                     is asserting "use exactly this"), the other is an
 #                     immutable, checksum-verified artifact for an exact
 #                     tagged commit (its own consistency check is the tag
 #                     match + `--version` check in download_and_verify).
+#                     .ci-bin/ closes the exact cold-start race
+#                     docs/cloud-environment-setup.md documents for Claude
+#                     Code on the web: a Setup Script or SessionStart hook
+#                     can only race a cold `cargo build` against the MCP
+#                     client's dial attempt, but a binary already sitting in
+#                     the checkout the instant it's cloned has no race to
+#                     lose. Built by .github/workflows/prebuild-mcp-binary.yml
+#                     on every push to main; may lag HEAD by one commit,
+#                     which `is_binary_fresh` catches the same way it catches
+#                     a stale local dev build. Only covers
+#                     x86_64-unknown-linux-musl today. Also guarded against
+#                     an unresolved Git LFS pointer (git-lfs not installed,
+#                     or a checkout that skipped the smudge filter) — see
+#                     `is_lfs_pointer`'s comment for why that specific
+#                     failure mode needs an explicit check instead of
+#                     falling through on its own.
 #   2. Verified download — Linux x86_64/aarch64 only, and only when HEAD is
 #                     exactly a released git tag (never guesses a version).
 #                     Downloads the matching GitHub Release asset, verifies
@@ -89,9 +107,25 @@ is_binary_fresh() {
   [ -z "$newer" ]
 }
 
+# True if `bin` looks like an unresolved Git LFS pointer stub rather than
+# real binary content — happens when `git lfs pull`/the smudge filter never
+# ran during checkout (e.g. git-lfs not installed in the environment). A
+# real `ci` binary is tens of MB; an LFS pointer is a ~130-byte text file
+# starting with this exact line. This matters because `exec`-ing one does
+# NOT fail gracefully: the kernel's ENOEXEC (no shebang, not an ELF) makes
+# bash fall back to interpreting the file's *text content* as a new shell
+# script, which runs (and errors on "version: command not found") INSTEAD
+# OF returning control to this script — verified directly against a
+# synthetic pointer stub, not assumed. Without this check, an unresolved
+# .ci-bin/ pointer would crash the whole launcher instead of falling
+# through to the next tier.
+is_lfs_pointer() {
+  [ "$(head -c 7 -- "$1" 2>/dev/null)" = "version" ]
+}
+
 try_exec_if_fresh() {
   local bin="$1"
-  if [ -x "$bin" ]; then
+  if [ -x "$bin" ] && ! is_lfs_pointer "$bin"; then
     if is_binary_fresh "$bin"; then
       exec "$bin" "${serve_args[@]}"
     else
@@ -110,6 +144,12 @@ cache_key="${resolved_tag:-$workspace_version}"
 try_exec_if_fresh "target/release/ci"
 try_exec_if_fresh "target/debug/ci"
 
+# ---- Tier 1.5: prebuilt binary committed via Git LFS (see header) ----
+# Only the one platform .github/workflows/prebuild-mcp-binary.yml builds.
+if [ "$(uname -s)" = "Linux" ] && [ "$(uname -m)" = "x86_64" ]; then
+  try_exec_if_fresh ".ci-bin/x86_64-unknown-linux-musl/ci"
+fi
+
 # ---- Tier 2: verified download (Linux only, tagged commit only unless opted in) ----
 download_and_verify() {
   local os arch target_triple tag asset_name asset_url sums_url tmp_dir downloaded_version cache_dir