diff --git a/bin/framework-pull-upstream.sh b/bin/framework-pull-upstream.sh
index 8f0673eb1..81d2d9269 100755
--- a/bin/framework-pull-upstream.sh
+++ b/bin/framework-pull-upstream.sh
@@ -87,9 +87,39 @@ echo ""
 
 # Detect current branch and set upstream branch
 CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>&1)
+
+# Handle detached HEAD state (common in git submodules)
+if [ "$CURRENT_BRANCH" = "HEAD" ]; then
+    echo "⚠  Detected detached HEAD state (git submodule)"
+    echo "   Checking out master branch..."
+    if ! git checkout master 2>&1; then
+        echo "ERROR: Failed to checkout master branch"
+        exit 1
+    fi
+    CURRENT_BRANCH="master"
+    echo "   ✓ Now on master branch"
+    echo ""
+fi
+
 UPSTREAM_BRANCH="rspade_upstream/${CURRENT_BRANCH}"
 
-# Verify upstream branch exists
+if [ "$IS_PROJECT_MODE" = true ]; then
+    echo "Mode: Project (./rsx will be preserved)"
+else
+    echo "Mode: Framework development (./rsx will be updated)"
+fi
+echo "Branch: $CURRENT_BRANCH → $UPSTREAM_BRANCH"
+echo ""
+
+# Fetch updates first (before verifying branch exists)
+echo "Fetching updates from rspade_upstream..."
+if ! git fetch rspade_upstream 2>&1; then
+    echo "ERROR: Failed to fetch updates"
+    exit 1
+fi
+echo "  ✓ Updates fetched"
+
+# Verify upstream branch exists (after fetch)
 if ! git rev-parse "$UPSTREAM_BRANCH" >/dev/null 2>&1; then
     echo "ERROR: Upstream branch $UPSTREAM_BRANCH not found"
     echo ""
@@ -101,22 +131,6 @@ if ! git rev-parse "$UPSTREAM_BRANCH" >/dev/null 2>&1; then
     exit 1
 fi
 
-if [ "$IS_PROJECT_MODE" = true ]; then
-    echo "Mode: Project (./rsx will be preserved)"
-else
-    echo "Mode: Framework development (./rsx will be updated)"
-fi
-echo "Branch: $CURRENT_BRANCH → $UPSTREAM_BRANCH"
-echo ""
-
-# Fetch updates
-echo "Fetching updates from rspade_upstream..."
-if ! git fetch rspade_upstream 2>&1; then
-    echo "ERROR: Failed to fetch updates"
-    exit 1
-fi
-echo "  ✓ Updates fetched"
-
 # Check if already up-to-date
 CURRENT_HEAD=$(git rev-parse HEAD 2>&1)
 UPSTREAM_HEAD=$(git rev-parse "$UPSTREAM_BRANCH" 2>&1)