Arms playtest-2 fixes: flip-proof elbow (angle clamp + rate limit, controller-driven), Stage 2b hand coupling (blocked arm holds the hand back)

- Elbow stored as an angle around the arm axis vs a torso-frame reference: 85% hand-suggested,
  from the controller pose (not the physics palm), clamped +-110 deg, 6 rad/s rate limit
  (flip spike: 1.8 cm/tick max vs 13.8 unclamped)
- PhysicsArms.ConstrainHand: while an arm segment is in contact the hand may lead the
  forearm end by 3 cm; PhysicsHands applies it and suspends stuck-snap while active
- ArmSpike: forearm-rest-over-anvil (owner pose: collider fine, drawn forearm 3.9 cm -> 0),
  flip sweep, bar test now asserts the hand is held back; all six spikes PASS x3

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

scripts/ArmSpike.cs

@@ -5,13 +5,16 @@ using Godot;
 // Run: godot-mono --headless --fixed-fps 90 --path . scenes/arm_spike.tscn
 public partial class ArmSpike : Node3D
 {
-    private enum Phase { Settle, Stretch, Hug, Hold, Track, Swing, Push, Pin, Teleport, NanGuard, Done }
+    private enum Phase { Settle, Stretch, Hug, Flip, Hold, Rest, Track, Swing, Push, Pin, Teleport, NanGuard, Done }
 
     private const float GapLimit = 0.04f;
     private const float StretchChestSpeedLimit = 0.05f;
     private const float StretchLeanRangeLimit = 0.01f;
     private const float HugElbowOutMin = 0.05f;
     private const float HoldPenetrationLimit = 0.01f;
+    private const float FlipElbowStepLimit = 0.03f;
+    private const float PinHandLagMin = 0.1f;
+    private const float RestBodyPenLimit = 0.01f;
     private const float HoldAnvilY = 1.25f;  // anvil top ≈ shoulder height, like a seated player at the table
     private const float HoldPitchDeg = 50f;
     private static readonly Vector3 AnvilSize = new(0.28f, 0.16f, 0.13f);
@@ -31,6 +34,7 @@ public partial class ArmSpike : Node3D
     private readonly RigidBody3D[] _hands = new RigidBody3D[2];
     private readonly Transform3D[] _handTarget = new Transform3D[2];
     private readonly Vector3[] _handRest = new Vector3[2];
+    private readonly Node3D[] _orient = new Node3D[2];
     private RigidBody3D _box;
     private Vector3 _boxStart;
     private StaticBody3D _slab;
@@ -46,6 +50,12 @@ public partial class ArmSpike : Node3D
     private ConeTwistJoint3D _holdWeld;
     private float _maxHoldPenetration;
     private bool _holdFinite = true;
+    private float _maxElbowStep;
+    private Vector3 _lastElbow;
+    private float _maxPinHandLag;
+    private float _restBodyPen;
+    private float _restDrawnPen;
+    private float _restAnvilMove;
     private float _maxStretchChestSpeed;
     private Vector3 _stretchOffsetMin = Vector3.One * 9f;
     private Vector3 _stretchOffsetMax = -Vector3.One * 9f;
@@ -87,7 +97,12 @@ public partial class ArmSpike : Node3D
             AddChild(_hands[side]);
         }
 
-        _arms = new PhysicsArms { HeadSource = _head, Torso = _torso, HandLeft = _hands[0], HandRight = _hands[1] };
+        for (int side = 0; side < 2; side++)
+        {
+            _orient[side] = new Node3D();
+            AddChild(_orient[side]);
+        }
+        _arms = new PhysicsArms { HeadSource = _head, Torso = _torso, HandLeft = _hands[0], HandRight = _hands[1], OrientLeft = _orient[0], OrientRight = _orient[1] };
         AddChild(_arms);
         GD.Print("ARM: arm spike scene ready");
     }
@@ -97,7 +112,12 @@ public partial class ArmSpike : Node3D
         float dt = (float)delta;
         _phaseT += dt;
         for (int side = 0; side < 2; side++)
-            PhysicsHands.Drive(_hands[side], _handTarget[side], dt);
+        {
+            _orient[side].GlobalTransform = _handTarget[side];
+            Transform3D driveTarget = _handTarget[side];
+            _arms.ConstrainHand(side, ref driveTarget);
+            PhysicsHands.Drive(_hands[side], driveTarget, dt);
+        }
         if (!_arms.Calibrated || _arms.UpperArm(0) == null)
             return;
 
@@ -144,6 +164,29 @@ public partial class ArmSpike : Node3D
                     Record($"hug: elbows out beyond the shoulders (L {outL:F3} m, R {outR:F3} m, limit > {HugElbowOutMin}; elbows L {_arms.Elbow(0)} R {_arms.Elbow(1)})", outMin > HugElbowOutMin);
                     for (int side = 0; side < 2; side++)
                         _handTarget[side] = new Transform3D(Basis.Identity, _handRest[side]);
+                    Start(Phase.Flip, "flip — right controller's pointing direction sweeps full circles around the arm, elbow must not jump");
+                }
+                break;
+            }
+
+            case Phase.Flip:
+            {
+                // Hand fixed; its forward axis sweeps a 70° cone around the shoulder→hand
+                // direction at 1 rev/s, so the hand-suggested elbow circles the arm axis and
+                // passes the inward/up side every revolution.
+                Vector3 handPos = new(0.2f, 1.25f, -0.4f);
+                Vector3 axis = (handPos - _arms.Shoulder(1)).Normalized();
+                Vector3 perp = axis.Cross(Vector3.Up).Normalized();
+                Vector3 fwd = (axis * Mathf.Cos(1.22f) + perp.Rotated(axis, Mathf.Tau * _phaseT) * Mathf.Sin(1.22f)).Normalized();
+                _handTarget[1] = new Transform3D(Basis.LookingAt(fwd, Mathf.Abs(fwd.Y) > 0.95f ? Vector3.Forward : Vector3.Up), handPos);
+                Vector3 elbow = _arms.ElbowTarget(1);
+                if (_phaseT > 0.5f)
+                    _maxElbowStep = Mathf.Max(_maxElbowStep, elbow.DistanceTo(_lastElbow));
+                _lastElbow = elbow;
+                if (_phaseT > 3.5f)
+                {
+                    Record($"flip: elbow never jumps (max step {_maxElbowStep:F4} m/tick, limit {FlipElbowStepLimit})", _maxElbowStep < FlipElbowStepLimit);
+                    _handTarget[1] = new Transform3D(Basis.Identity, _handRest[1]);
                     _maxHoldPenetration = 0f;
                     Start(Phase.Hold, "hold — right hand grips a 50 kg anvil from the top, forearm must stay out of it");
                 }
@@ -196,6 +239,48 @@ public partial class ArmSpike : Node3D
                     _anvil.QueueFree();
                     _pedestal.QueueFree();
                     _handTarget[1] = new Transform3D(Basis.Identity, _handRest[1]);
+                    _anvil = null;
+                    Start(Phase.Rest, "rest — palm behind a 50 kg anvil, forearm resting over it (owner playtest 2 pose)");
+                }
+                break;
+            }
+
+            case Phase.Rest:
+            {
+                // Anvil top below the shoulder; the hand first goes ABOVE the far side, the anvil
+                // appears, then the hand sinks behind it so the forearm drapes over the top edge.
+                const float anvilY = 1.25f;
+                if (_anvil == null && _phaseT > 0.6f)
+                {
+                    _pedestal = new StaticBody3D { CollisionMask = 0b11101, Position = new Vector3(0.22f, anvilY - 0.13f, -0.30f) };
+                    _pedestal.AddChild(new CollisionShape3D { Shape = new BoxShape3D { Size = new Vector3(0.4f, 0.1f, 0.4f) } });
+                    AddChild(_pedestal);
+                    _anvil = new RigidBody3D { Mass = 50f, Position = new Vector3(0.22f, anvilY, -0.30f), CollisionMask = 0b11101 };
+                    _anvil.AddChild(new CollisionShape3D { Shape = new BoxShape3D { Size = AnvilSize } });
+                    AddChild(_anvil);
+                }
+                float sink = Mathf.Clamp((_phaseT - 1f) / 0.8f, 0f, 1f);
+                Basis down = new Basis(Vector3.Right, Mathf.DegToRad(-20f));
+                _handTarget[1] = new Transform3D(down, new Vector3(0.22f, 1.45f - 0.17f * sink, -0.47f));
+                if (_anvil != null && _phaseT > 1.8f)
+                {
+                    RigidBody3D fore = _arms.Forearm(1);
+                    Vector3 axis = fore.GlobalTransform.Basis.Y * (_arms.ForeLen * 0.5f - 0.02f);
+                    // Collider overlap ≈ forearm center line depth inside the anvil grown by the
+                    // forearm half-thickness (3 cm).
+                    _restBodyPen = Mathf.Max(_restBodyPen, LinePenetration(fore.GlobalPosition - axis, fore.GlobalPosition + axis, _anvil, 0.03f));
+                    Vector3 wrist = _hands[1].GlobalPosition + _hands[1].GlobalTransform.Basis * new Vector3(0f, 0f, 0.06f);
+                    _restDrawnPen = Mathf.Max(_restDrawnPen, LinePenetration(_arms.Elbow(1), wrist, _anvil));
+                    _restAnvilMove = Mathf.Max(_restAnvilMove, _anvil.GlobalPosition.DistanceTo(new Vector3(0.22f, anvilY, -0.30f)));
+                }
+                if (_phaseT > 3.5f)
+                {
+                    GD.Print($"ARM: rest metrics: forearm COLLIDER overlap max {_restBodyPen:F3} m, DRAWN forearm penetration max {_restDrawnPen:F3} m, anvil moved {_restAnvilMove:F3} m, hand {_hands[1].GlobalPosition} elbow {_arms.Elbow(1)}");
+                    Record($"rest: forearm collider stays out of the anvil (overlap {_restBodyPen:F3} m, limit {RestBodyPenLimit})", _restBodyPen < RestBodyPenLimit);
+                    Record($"rest: drawn forearm stays out of the anvil (penetration {_restDrawnPen:F3} m, limit {HoldPenetrationLimit})", _restDrawnPen < HoldPenetrationLimit);
+                    _anvil.QueueFree();
+                    _pedestal.QueueFree();
+                    _handTarget[1] = new Transform3D(Basis.Identity, _handRest[1]);
                     Start(Phase.Track, "track — hands circle, segments must stay connected, chest undisturbed");
                 }
                 break;
@@ -298,12 +383,13 @@ public partial class ArmSpike : Node3D
                         _pinPrevY[side] = c.Y;
                         Vector3 foreTarget = (_arms.ElbowTarget(side) + _arms.WristTarget(side)) * 0.5f;
                         _maxPinObstruction = Mathf.Max(_maxPinObstruction, _arms.Forearm(side).GlobalPosition.DistanceTo(foreTarget));
+                        _maxPinHandLag = Mathf.Max(_maxPinHandLag, _hands[side].GlobalPosition.DistanceTo(_handTarget[side].Origin));
                     }
                 }
                 if (_phaseT > 3.5f)
                 {
-                    Record($"forearm blocked by bar, no tunneling (deviation max {_maxPinObstruction:F3} m, limit > {PinObstructionMin}; tunneled {_pinTunneled})",
-                        _maxPinObstruction > PinObstructionMin && !_pinTunneled);
+                    Record($"forearm blocked by bar holds the hand back, no tunneling (hand lag max {_maxPinHandLag:F3} m, limit > {PinHandLagMin}; forearm deviation {_maxPinObstruction:F3} m; tunneled {_pinTunneled})",
+                        _maxPinHandLag > PinHandLagMin && !_pinTunneled);
                     Record($"pinned under bar: finite and quiet in the last 1 s (segment |v| max {_maxPinSpeed:F3} m/s, limit {PinSpeedLimit})", _pinFinite && _maxPinSpeed < PinSpeedLimit);
                     _slab.QueueFree();
                     for (int side = 0; side < 2; side++)
@@ -343,9 +429,9 @@ public partial class ArmSpike : Node3D
     }
 
     // Deepest point of the segment a→b inside the box body (0 if it never enters).
-    private static float LinePenetration(Vector3 a, Vector3 b, RigidBody3D box)
+    private static float LinePenetration(Vector3 a, Vector3 b, RigidBody3D box, float grow = 0f)
     {
-        Vector3 half = AnvilSize * 0.5f;
+        Vector3 half = AnvilSize * 0.5f + Vector3.One * grow;
         Transform3D inv = box.GlobalTransform.AffineInverse();
         float deepest = 0f;
         for (int i = 0; i <= 40; i++)

scripts/PhysicsArms.cs

@@ -27,8 +27,11 @@ public partial class PhysicsArms : Node
     private const float LeanSmoothRate = 6f;
     private const float WristOffset = 0.06f;
     private const float SoftIKFactor = 0.98f;
-    private const float PoleHandWeight = 0.75f;
+    private const float PoleHandWeight = 0.85f;
     private const float PoleSmoothRate = 12f;
+    private const float PoleMaxAngle = 1.92f;  // 110 deg either way from down/back/out
+    private const float PoleMaxSpeed = 6f;     // rad/s
+    public const float HandArmSlack = 0.03f;
     private const float ElbowRiseAllowance = 0.05f;
 
     public static float ForearmMaxForce => BodyMassStat * ForearmForcePerKg;
@@ -39,6 +42,10 @@ public partial class PhysicsArms : Node
     public PhysicsTorso Torso;
     public RigidBody3D HandLeft;
     public RigidBody3D HandRight;
+    // Hand ORIENTATION source for the elbow: the tracked controllers, not the physics palms
+    // (a palm fighting contact must not swing the elbow). Falls back to the hand body.
+    public Node3D OrientLeft;
+    public Node3D OrientRight;
 
     public bool Calibrated { get; private set; }
     public float UpperLen { get; private set; }
@@ -50,7 +57,8 @@ public partial class PhysicsArms : Node
     private readonly Vector3[] _shoulder = new Vector3[2];
     private readonly Vector3[] _elbowTarget = new Vector3[2];
     private readonly Vector3[] _wristTarget = new Vector3[2];
-    private readonly Vector3[] _lastPole = new Vector3[2];
+    private readonly float[] _poleAngle = new float[2];
+    private readonly Vector3[] _lastRef = new Vector3[2];
     private readonly RigidBody3D[] _held = new RigidBody3D[2];
     private Vector3 _torsoOffset;
     private Basis _torsoBasis = Basis.Identity;
@@ -75,6 +83,8 @@ public partial class PhysicsArms : Node
             Torso = GetNode<PhysicsTorso>("../PhysicsTorso");
             HandLeft = PhysicsHands.GetBody(GetNode<XRController3D>("../XROrigin3D/LeftHand"));
             HandRight = PhysicsHands.GetBody(GetNode<XRController3D>("../XROrigin3D/RightHand"));
+            OrientLeft = GetNode<XRController3D>("../XROrigin3D/LeftHand");
+            OrientRight = GetNode<XRController3D>("../XROrigin3D/RightHand");
         }
     }
 
@@ -94,8 +104,8 @@ public partial class PhysicsArms : Node
         _shoulder[0] = topCenter - _torsoBasis.X * ShoulderHalfWidth;
         _shoulder[1] = topCenter + _torsoBasis.X * ShoulderHalfWidth;
 
-        SolveArm(0, -_torsoBasis.X, HandLeft, dt);
-        SolveArm(1, _torsoBasis.X, HandRight, dt);
+        SolveArm(0, -_torsoBasis.X, HandLeft, OrientLeft, dt);
+        SolveArm(1, _torsoBasis.X, HandRight, OrientRight, dt);
         UpdateLean(dt);
 
         for (int side = 0; side < 2; side++)
@@ -135,6 +145,8 @@ public partial class PhysicsArms : Node
             ContinuousCd = true,
             CollisionLayer = 0b10000,  // layer 5 = player arms
             CollisionMask = 0b1,       // world + props only; own chest/hands/arms excluded
+            ContactMonitor = true,
+            MaxContactsReported = 4,
         };
         body.AddChild(new CollisionShape3D { Shape = new BoxShape3D { Size = size } });
         AddChild(body);
@@ -213,6 +225,25 @@ public partial class PhysicsArms : Node
         }
     }
 
+    // Stage 2b coupling: while an arm segment is in contact, the hand may lead the forearm's
+    // end by at most HandArmSlack — a blocked forearm holds the hand back (the hand ghost
+    // shows the controller). Free arms never limit the hand. PhysicsHands calls this with
+    // the controller target before chasing; returns true when the limit is active.
+    public bool ConstrainHand(int side, ref Transform3D target)
+    {
+        if (!Calibrated || _fore[side] == null)
+            return false;
+        if (_fore[side].GetContactCount() == 0 && _upper[side].GetContactCount() == 0)
+            return false;
+        Vector3 wristOffset = target.Basis * new Vector3(0f, 0f, WristOffset);
+        Vector3 forearmEnd = Wrist(side);
+        Vector3 lead = target.Origin + wristOffset - forearmEnd;
+        if (lead.Length() <= HandArmSlack)
+            return true;
+        target.Origin = forearmEnd + lead.Normalized() * HandArmSlack - wristOffset;
+        return true;
+    }
+
     // Torso lean toward overreaching hands, computed OPEN-LOOP from the head-derived nominal
     // chest pose — never from the body's own shoulders (that loop made the chest hunt:
     // lean moves shoulders → overreach changes → lean changes). Exact two-arm combination:
@@ -255,7 +286,7 @@ public partial class PhysicsArms : Node
     // "down/back/out" pole fills in where the hand axis says nothing (arm pointing straight
     // along the hand). The pole is smoothed by ROTATING it at a bounded rate around the arm
     // axis, so it can never pass through zero and flip.
-    private void SolveArm(int index, Vector3 side, RigidBody3D hand, float delta)
+    private void SolveArm(int index, Vector3 side, RigidBody3D hand, Node3D orient, float delta)
     {
         Vector3 shoulder = _shoulder[index];
         Vector3 rawTarget = hand != null ? WristPoint(hand) : shoulder + _torsoBasis * new Vector3(0f, -0.25f, -0.3f);
@@ -275,38 +306,39 @@ public partial class PhysicsArms : Node
         float radius = Mathf.Sqrt(Mathf.Max(UpperLen * UpperLen - along * along, 0f));
         Vector3 center = shoulder + dir * along;
 
-        Vector3 natural = Vector3.Down * 2f + _torsoBasis * Vector3.Back * 0.8f + side * 0.3f;
-        natural -= dir * natural.Dot(dir);
-        Vector3 pole = natural.LengthSquared() > 1e-8f ? natural.Normalized() * (1f - PoleHandWeight) : Vector3.Zero;
-        if (hand != null)
+        // Reference = torso-frame down/back/out projected off the arm axis. The elbow is
+        // stored as an ANGLE around the arm axis relative to it, clamped to ±110° and
+        // rate-limited — it can never swing through the inward/up side (the 180° flip).
+        Vector3 reference = Vector3.Down * 2f + _torsoBasis * Vector3.Back * 0.8f + side * 0.3f;
+        reference -= dir * reference.Dot(dir);
+        if (reference.LengthSquared() > 0.06f)
+            _lastRef[index] = reference.Normalized();
+        else
         {
-            Vector3 handForward = (hand.GlobalTransform.Basis * Vector3.Forward).Normalized();
+            // Arm pointing along the reference: keep the previous one, re-projected.
+            reference = _lastRef[index] - dir * _lastRef[index].Dot(dir);
+            reference = reference.LengthSquared() > 1e-8f ? reference.Normalized() : dir.Cross(_torsoBasis.X).Normalized();
+        }
+        Vector3 refN = reference.Normalized();
+        Vector3 refB = dir.Cross(refN);
+
+        float targetAngle = 0f;
+        Basis handBasis = orient != null ? orient.GlobalTransform.Basis : hand?.GlobalTransform.Basis ?? Basis.Identity;
+        if (orient != null || hand != null)
+        {
+            Vector3 handForward = (handBasis * Vector3.Forward).Normalized();
             Vector3 handElbow = wrist - handForward * ForeLen - center;
             handElbow -= dir * handElbow.Dot(dir);
             float confidence = Mathf.Clamp(handElbow.Length() / (0.5f * radius + 1e-4f), 0f, 1f);
             if (handElbow.LengthSquared() > 1e-8f)
-                pole += handElbow.Normalized() * (PoleHandWeight * confidence);
+                targetAngle = Mathf.Atan2(handElbow.Dot(refB), handElbow.Dot(refN)) * PoleHandWeight * confidence;
         }
+        targetAngle = Mathf.Clamp(targetAngle, -PoleMaxAngle, PoleMaxAngle);
+        float step = (targetAngle - _poleAngle[index]) * (1f - Mathf.Exp(-delta * PoleSmoothRate));
+        _poleAngle[index] += Mathf.Clamp(step, -PoleMaxSpeed * delta, PoleMaxSpeed * delta);
+        Vector3 pole = refN.Rotated(dir, _poleAngle[index]);
 
-        Vector3 last = _lastPole[index];
-        last -= dir * last.Dot(dir);
-        if (last.LengthSquared() < 1e-8f)
-            last = pole.LengthSquared() > 1e-8f ? pole : natural;
-        last = last.LengthSquared() > 1e-8f ? last.Normalized() : Vector3.Down;
-        if (pole.LengthSquared() > 1e-8f)
-        {
-            pole = pole.Normalized();
-            float angle = last.AngleTo(pole);
-            if (angle > 1e-5f)
-            {
-                Vector3 axis = last.Cross(pole);
-                axis = axis.LengthSquared() > 1e-10f ? axis.Normalized() : dir;
-                last = last.Rotated(axis, angle * (1f - Mathf.Exp(-delta * PoleSmoothRate)));
-            }
-        }
-        _lastPole[index] = last;
-
-        Vector3 elbow = center + CapElbowHeight(last, dir, center, radius, Mathf.Max(shoulder.Y, wrist.Y) + ElbowRiseAllowance) * radius;
+        Vector3 elbow = center + CapElbowHeight(pole, dir, center, radius, Mathf.Max(shoulder.Y, wrist.Y) + ElbowRiseAllowance) * radius;
         _elbowTarget[index] = elbow;
         _wristTarget[index] = elbow + (wrist - elbow).Normalized() * ForeLen;
     }

scripts/PhysicsHands.cs

@@ -15,6 +15,7 @@ public partial class PhysicsHands : Node
 
     private XRController3D _left;
     private XRController3D _right;
+    private PhysicsArms _arms;
     private readonly RigidBody3D[] _bodies = new RigidBody3D[2];
     private readonly MeshInstance3D[] _ghosts = new MeshInstance3D[2];
     private readonly float[] _stuckTimer = new float[2];
@@ -24,6 +25,7 @@ public partial class PhysicsHands : Node
         _instance = this;
         _left = GetNode<XRController3D>("../XROrigin3D/LeftHand");
         _right = GetNode<XRController3D>("../XROrigin3D/RightHand");
+        _arms = GetNodeOrNull<PhysicsArms>("../PhysicsArms");
         _bodies[0] = MakeHand("LeftHandBody", new Color(0.9f, 0.3f, 0.35f));
         _bodies[1] = MakeHand("RightHandBody", new Color(0.3f, 0.5f, 0.9f));
         _ghosts[0] = MakeGhost();
@@ -92,6 +94,8 @@ public partial class PhysicsHands : Node
             return;
         int hand = _left == controller ? 0 : 1;
         Vector3 target = controller.GlobalPosition;
+        Transform3D driveTarget = controller.GlobalTransform;
+        bool armHeld = _arms != null && _arms.ConstrainHand(hand, ref driveTarget);
 
         bool lagging = body.GlobalPosition.DistanceTo(target) > GhostLagDistance;
         if (_ghosts[hand] != null)
@@ -103,7 +107,9 @@ public partial class PhysicsHands : Node
 
         if (!PropGrabber.IsGrabbing(controller))
         {
-            if (body.GlobalPosition.DistanceTo(target) > StuckDistance)
+            // A hand held back by its own blocked arm is not stuck — snapping it into the
+            // obstacle would just loop.
+            if (body.GlobalPosition.DistanceTo(target) > StuckDistance && !armHeld)
                 _stuckTimer[hand] += delta;
             else
                 _stuckTimer[hand] = 0f;
@@ -123,7 +129,7 @@ public partial class PhysicsHands : Node
                 return;
             }
         }
-        Drive(body, controller.GlobalTransform, delta);
+        Drive(body, driveTarget, delta);
     }
 
     // The hand chase itself — public so headless spikes drive their stand-ins with the real code.