reload: add explicit build-only validation mode

Author: teamleaderleo

CLAUDE.md

@@ -15,10 +15,13 @@ Always build with a tag. **Never run bare `xcodebuild` or `open` an untagged `cm
 ```bash
 ./scripts/reload.sh --tag <branch-slug>            # build Debug, kill same-tag app, do not launch
 ./scripts/reload.sh --tag <branch-slug> --launch   # also open it
+./scripts/reload.sh --tag <branch-slug> --build-only # validate without replacing the running app
 ```
 
 A tag gives the app its own name, bundle ID, socket, and derived data path, so it runs side-by-side with the user's main app. Report the build to the user as a markdown link to `http://127.0.0.1:17320/<tag>`. Never put a `file://` URL, a raw `.app` path, or `/tmp/cmux-<tag>/...` in chat output.
 
+Use `--build-only` only when the task explicitly asks for compile/validation without a reload. It leaves the active tagged app, `cmuxd`, and tag state untouched and keeps the newly built bundle staged separately; it does not make the running app current.
+
 Other variants: `reloadp.sh` (Release), `reloads.sh` (Release as isolated "cmux STAGING"), `reload2.sh --tag <tag>` (both).
 
 ## Shared Mac fleet capacity

scripts/reload.sh

@@ -16,6 +16,7 @@ BUNDLE_SET=0
 DERIVED_SET=0
 TAG=""
 LAUNCH=0
+BUILD_ONLY=0
 CMUX_DEBUG_LOG=""
 CMUX_DEV_PORT=""
 CMUX_DEV_PORT_END=""
@@ -893,6 +894,9 @@ Options:
                          so macOS launches the freshly-built binary on cmd-click or --launch.
   --launch               Launch the app after building. Without this flag, the script
                          builds and prints the app path but does not open it.
+  --build-only           Build and validate a tagged app without replacing or
+                         stopping the running tagged app, daemon, or tag state.
+                         Cannot be combined with --launch.
   --prod-auth            Point this tagged Debug build at production Stack auth,
                          cmux APIs, and the production Iroh broker.
   --credentials-file <path>
@@ -1141,6 +1145,10 @@ while [[ $# -gt 0 ]]; do
       LAUNCH=1
       shift
       ;;
+    --build-only)
+      BUILD_ONLY=1
+      shift
+      ;;
     --prod-auth)
       PROD_AUTH=1
       shift
@@ -1204,6 +1212,11 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
+if [[ "$BUILD_ONLY" -eq 1 && "$LAUNCH" -eq 1 ]]; then
+  echo "error: --build-only cannot be combined with --launch" >&2
+  exit 1
+fi
+
 if [[ -z "$TAG" ]]; then
   echo "error: --tag is required (example: ./scripts/reload.sh --tag fix-sidebar-theme)" >&2
   usage
@@ -1395,7 +1408,10 @@ reload_finalize() {
     echo "Swift workaround:"
     echo "  batch mode, debug symbols, and AArch64 GlobalISel disabled for this reload"
   fi
-  if [[ "$LAUNCH" -eq 0 ]]; then
+  if [[ "$BUILD_ONLY" -eq 1 ]]; then
+    echo
+    echo "Build-only validation complete. The running tagged app, cmuxd, and tag state were left unchanged."
+  elif [[ "$LAUNCH" -eq 0 ]]; then
     echo
     echo "Build complete. Pass --launch to open the app, or cmd-click the path above."
   fi
@@ -1735,8 +1751,12 @@ if [[ -n "$TAG" && "$APP_NAME" != "$SEARCH_APP_NAME" ]]; then
       set_plist_env "$INFO_PLIST" CMUX_SOCKET_MODE "allowAll"
       set_plist_env "$INFO_PLIST" CMUX_REMOTE_DAEMON_ALLOW_LOCAL_BUILD "1"
       set_plist_env "$INFO_PLIST" CMUXTERM_REPO_ROOT "$PWD"
-      set_plist_env "$INFO_PLIST" CMUX_BUNDLED_CLI_PATH "$TAG_APP_FINAL_PATH/Contents/Resources/bin/cmux"
-      set_plist_env "$INFO_PLIST" CMUX_SHELL_INTEGRATION_DIR "$TAG_APP_FINAL_PATH/Contents/Resources/shell-integration"
+      BUNDLED_APP_PATH="$TAG_APP_FINAL_PATH"
+      if [[ "$BUILD_ONLY" -eq 1 ]]; then
+        BUNDLED_APP_PATH="$TAG_APP_STAGING_PATH"
+      fi
+      set_plist_env "$INFO_PLIST" CMUX_BUNDLED_CLI_PATH "$BUNDLED_APP_PATH/Contents/Resources/bin/cmux"
+      set_plist_env "$INFO_PLIST" CMUX_SHELL_INTEGRATION_DIR "$BUNDLED_APP_PATH/Contents/Resources/shell-integration"
       set_plist_env "$INFO_PLIST" CMUX_PORT "$CMUX_DEV_PORT"
       set_plist_env "$INFO_PLIST" CMUX_PORT_END "$CMUX_DEV_PORT_END"
       set_plist_env "$INFO_PLIST" CMUX_PORT_RANGE "$CMUX_DEV_PORT_RANGE"
@@ -1764,7 +1784,7 @@ if [[ -n "$TAG" && "$APP_NAME" != "$SEARCH_APP_NAME" ]]; then
         set_plist_env "$INFO_PLIST" CMUX_DEV_AUTH_PROFILE "$AUTH_PROFILE"
         set_plist_env "$INFO_PLIST" CMUX_DEV_AUTH_REPLACE_SESSION "1"
       fi
-      if [[ -S "$CMUXD_SOCKET" ]]; then
+      if [[ "$BUILD_ONLY" -ne 1 && -S "$CMUXD_SOCKET" ]]; then
         for PID in $(lsof -t "$CMUXD_SOCKET" 2>/dev/null); do
           kill "$PID" 2>/dev/null || true
         done
@@ -1838,7 +1858,11 @@ if ! /usr/bin/codesign --force --sign - --timestamp=none --generate-entitlement-
     exit 1
   fi
 fi
-if [[ -n "${TAG_APP_FINAL_PATH:-}" && -n "${TAG_APP_STAGING_PATH:-}" ]]; then
+if [[ "$BUILD_ONLY" -eq 1 && -n "${TAG_APP_STAGING_PATH:-}" ]]; then
+  # Keep the staged artifact separate from the running tagged app. This mode is
+  # explicitly for compilation/validation and must not mutate the active bundle.
+  APP_PATH="$TAG_APP_STAGING_PATH"
+elif [[ -n "${TAG_APP_FINAL_PATH:-}" && -n "${TAG_APP_STAGING_PATH:-}" ]]; then
   rm -rf "$TAG_APP_FINAL_PATH"
   mv "$TAG_APP_STAGING_PATH" "$TAG_APP_FINAL_PATH"
   APP_PATH="$TAG_APP_FINAL_PATH"
@@ -1856,7 +1880,7 @@ fi
 # even without --launch. A stale tagged app pinned to this bundle id would otherwise
 # keep running against freshly-overwritten resources, and macOS would foreground it
 # instead of launching the newly built binary when the user cmd-clicks the .app.
-if [[ -n "$TAG" ]]; then
+if [[ -n "$TAG" && "$BUILD_ONLY" -ne 1 ]]; then
   /usr/bin/osascript -e "tell application id \"${BUNDLE_ID}\" to quit" >/dev/null 2>&1 || true
   sleep 0.3
   pkill -f "${APP_NAME}.app/Contents/MacOS/${BASE_APP_NAME}" || true
@@ -1868,7 +1892,10 @@ if [[ -n "$TAG" ]]; then
   /bin/launchctl remove "$TAG_LAUNCHD_LABEL" >/dev/null 2>&1 || true
 fi
 
-if [[ -n "$TAG" ]] && ! wait_for_tag_socket_lock_release "/tmp/cmux-debug-${TAG_SLUG}.sock"; then
+if [[ "$BUILD_ONLY" -eq 1 ]]; then
+  CAN_PUBLISH_RELOAD_STATE=0
+  RELOAD_PUBLICATION_SKIP_REASON="build-only mode left the running tagged app and tag state unchanged"
+elif [[ -n "$TAG" ]] && ! wait_for_tag_socket_lock_release "/tmp/cmux-debug-${TAG_SLUG}.sock"; then
   CAN_PUBLISH_RELOAD_STATE=0
 fi
 if [[ "$CAN_PUBLISH_RELOAD_STATE" -eq 1 && -n "${TAG_SLUG:-}" ]]; then

skills/cmux-dev-workflow/references/tagged-builds.md

@@ -3,11 +3,13 @@
 Tagged builds isolate app name, bundle ID, debug socket, and DerivedData path so multiple agents and the user's normal app do not collide.
 
 ```bash
-./scripts/reload.sh --tag <tag>            # build only (default)
+./scripts/reload.sh --tag <tag>            # build and replace same-tag runtime
 ./scripts/reload.sh --tag <tag> --launch   # build, then open
+./scripts/reload.sh --tag <tag> --build-only # validate without replacing the running app
 ```
 
 After a successful build `reload.sh` terminates any running app with the same tag, so opening the printed app path launches the fresh binary.
+Use `--build-only` only for an explicit compile/validation pass. It leaves the running tagged app, `cmuxd`, and tag state untouched, and stages the new bundle separately; the active app remains on its previous revision.
 
 ## App path links