refactor(entrypoint): dual-mode ray-job.sh + auto-delegate

# ♻️ Refactor

## Make ray-job.sh support both entry-point and source modes

- Detect mode via BASH_SOURCE vs $0 plus first-arg .sh file check, so
  sourced callers cannot accidentally trigger entry-point exec from
  leaked positional args
- Entry-point mode: set up env then exec the run script (unchanged CLI)
- Source mode: set up env only and fall through to the caller
- Drop duplicate DIR= assignment and unused SLIME_HOST_IP comment
- Add RELAX_ENTRYPOINT_MODE guard to match local.sh

## Auto-delegate local.sh to ray-job.sh inside an existing cluster

- At the top of local.sh, when RAY_ADDRESS is set and `ray status`
  succeeds, source ray-job.sh instead of tearing down and restarting
  a local Ray head node
- Preserves existing single-node flow otherwise

Author: Yangruipis

scripts/entrypoint/local.sh

@@ -7,6 +7,10 @@
 # It is designed to be *sourced* by run-*.sh scripts when no external entrypoint
 # (spmd-multinode.sh or ray-job.sh) has been used.
 #
+# When an existing Ray cluster is detected (RAY_ADDRESS set and `ray status` OK),
+# this script delegates to `ray-job.sh` (source mode) instead of starting a new
+# local Ray head node.
+#
 # Usage (from a run script):
 #   source scripts/entrypoint/local.sh
 #
@@ -22,6 +26,19 @@ if [ -n "${RELAX_ENTRYPOINT_MODE:-}" ]; then
     return 0 2>/dev/null || exit 0
 fi
 
+_LOCAL_SH_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)"
+
+# ── delegate to ray-job.sh when inside an existing Ray cluster ─────────────
+# When RAY_ADDRESS is set AND `ray status` succeeds, we're already part of an
+# externally-managed Ray cluster. Skip local Ray startup / process cleanup and
+# fall through to ray-job.sh (source mode) for env setup.
+if [ -n "${RAY_ADDRESS:-}" ] && timeout 5 ray status >/dev/null 2>&1; then
+    echo "=== Detected existing Ray cluster (RAY_ADDRESS=$RAY_ADDRESS); delegating to ray-job.sh ==="
+    # shellcheck source=./ray-job.sh
+    source "${_LOCAL_SH_DIR}/ray-job.sh"
+    return 0 2>/dev/null || exit 0
+fi
+
 set -eo pipefail
 
 # ── process cleanup ─────────────────────────────────────────────────────────
@@ -38,7 +55,6 @@ pkill -9 python 2>/dev/null || true
 set -x
 
 # ── environment setup ───────────────────────────────────────────────────────
-_LOCAL_SH_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)"
 unset MASTER_ADDR 2>/dev/null || true
 export PYTHONUNBUFFERED=1
 export CUDA_DEVICE_MAX_CONNECTIONS=1

scripts/entrypoint/ray-job.sh

@@ -2,39 +2,52 @@
 
 # Copyright (c) 2026 Relax Authors. All Rights Reserved.
 #
-# Entrypoint for Ray Job tasks.
+# Entrypoint / source helper for Ray Job tasks.
 # The Ray cluster is already running. This script MUST NOT kill ray or stop the
-# cluster. It only cleans up residual python/sglang processes and then runs the
-# training script directly via python3.
+# cluster. It only cleans up residual python/sglang processes and then sets up
+# the environment for running training against an existing Ray cluster.
 #
-# Usage:
-#   bash scripts/entrypoint/ray-job.sh <run-script> [extra-args...]
+# Two usage modes:
+#   1) Entry-point mode — first argument is a .sh script path:
+#        bash scripts/entrypoint/ray-job.sh <run-script> [extra-args...]
+#      Sets up env, cleans residual processes, then execs the run script.
 #
-# Example:
-#   bash scripts/entrypoint/ray-job.sh scripts/training/text/run-qwen35-9B-8xgpu-async.sh
-#   bash scripts/entrypoint/ray-job.sh scripts/training/text/run-qwen35-9B-8xgpu-async.sh --lr 5e-7
+#      Example:
+#        bash scripts/entrypoint/ray-job.sh scripts/training/text/run-qwen35-9B-8xgpu-async.sh
+#        bash scripts/entrypoint/ray-job.sh scripts/training/text/run-qwen35-9B-8xgpu-async.sh --lr 5e-7
+#
+#   2) Source mode — no .sh script arg (like local.sh):
+#        source scripts/entrypoint/ray-job.sh
+#      Sets up env only, so the caller can continue execution.
 #
 # Environment variables (optional):
 #   MEGATRON      - Path to Megatron-LM (default: /root/Megatron-LM/)
 #   RELAX         - Path to Relax project (default: ../../)
 
-set -eo pipefail
-
-DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)"
-
-# ── argument parsing ────────────────────────────────────────────────────────
-RUN_SCRIPT="${1:-}"
-if [ -z "$RUN_SCRIPT" ]; then
-    echo "Usage: $0 <run-script> [extra-args...]" >&2
-    exit 1
+# Guard: skip if already sourced by another entrypoint
+if [ -n "${RELAX_ENTRYPOINT_MODE:-}" ]; then
+    return 0 2>/dev/null || exit 0
 fi
-shift  # remaining args are extra overrides
 
-if [ ! -f "$RUN_SCRIPT" ]; then
-    echo "ERROR: run script not found: $RUN_SCRIPT" >&2
-    exit 1
+# ── mode detection ──────────────────────────────────────────────────────────
+# Entry-point mode: directly executed AND first arg is an existing .sh file.
+# Otherwise act as a sourced setup script.
+_RAY_JOB_RUN_SCRIPT=""
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    _RAY_JOB_FIRST_ARG="${1:-}"
+    if [ -n "$_RAY_JOB_FIRST_ARG" ] && [ -f "$_RAY_JOB_FIRST_ARG" ] && [[ "$_RAY_JOB_FIRST_ARG" == *.sh ]]; then
+        _RAY_JOB_RUN_SCRIPT="$_RAY_JOB_FIRST_ARG"
+        shift
+    else
+        echo "Usage: $0 <run-script.sh> [extra-args...]" >&2
+        exit 1
+    fi
 fi
 
+set -eo pipefail
+
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)"
+
 # ── clean up residual python/sglang processes (NOT ray) ─────────────────────
 # IMPORTANT: Do NOT pkill ray or run ray stop — the cluster is managed externally.
 echo "=== Cleaning up residual python/sglang processes ==="
@@ -46,14 +59,13 @@ ray job list | grep RUNNING | grep -v job_id=None | grep -oP "submission_id='\\K
 set -x
 
 # ── environment setup ───────────────────────────────────────────────────────
-# Use the first GPU node as MASTER_ADDR and SLIME_HOST_IP (prefer head node)
+# Use the first GPU node as MASTER_ADDR (prefer head node)
 export MASTER_ADDR=$(ray list nodes --format json | jq -r '
   map(select(.state == "ALIVE" and (.resources_total.GPU // 0) > 0)) |
   sort_by(.is_head_node | not) |
   .[0].node_ip
 ')
 
-DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)"
 export PYTHONUNBUFFERED=1
 export CUDA_DEVICE_MAX_CONNECTIONS=1
 export MEGATRON=${MEGATRON:-/root/Megatron-LM/}
@@ -74,13 +86,12 @@ else
 fi
 echo "HAS_NVLINK: $HAS_NVLINK (detected $NVLINK_COUNT NVLink references)"
 
-# ── delegate to run script ──────────────────────────────────────────────────
-echo "=== Launching training script: $RUN_SCRIPT ==="
+# ── entrypoint mode & runtime env ──────────────────────────────────────────
 export RELAX_ENTRYPOINT_MODE="ray-job"
 RAY_DEBUG=${RAY_DEBUG:-"0"}
 RAY_DEBUG_POST_MORTEM=${RAY_DEBUG_POST_MORTEM:-"0"}
 
-# Runtime env for ray-job mode (empty, env inherited from Ray cluster)
+# Runtime env for ray-job mode (env inherited from Ray cluster)
 export RUNTIME_ENV_JSON="{
 \"env_vars\": {
    \"PYTHONUNBUFFERED\": \"1\",
@@ -93,4 +104,11 @@ export RUNTIME_ENV_JSON="{
    \"RAY_DEBUG_POST_MORTEM\": \"${RAY_DEBUG_POST_MORTEM}\"
 }
 }"
-exec bash "$RUN_SCRIPT" "$@"
+
+echo "=== Ray-job environment ready ==="
+
+# ── delegate to run script (entry-point mode only) ─────────────────────────
+if [ -n "$_RAY_JOB_RUN_SCRIPT" ]; then
+    echo "=== Launching training script: $_RAY_JOB_RUN_SCRIPT ==="
+    exec bash "$_RAY_JOB_RUN_SCRIPT" "$@"
+fi