fix(#648): grace window so a just-armed narrating spinner survives a spurious clear

viewer/openworlds/app.jsx

@@ -209,6 +209,15 @@ window.neutralizeMarkup = window.neutralizeMarkup || function neutralizeMarkup(r
 const PENDING_RECOVERY_MS = 180 * 1000;           // #399: later-beat stall window (worst-case DM turns run ~90–120s; was 90s/#342).
 const PENDING_RECOVERY_FIRST_MS = 4 * 60 * 1000;  // #348: first-beat (Act-opening) window — fits the multi-minute cold open.
 const PENDING_BACKSTOP_MS = 12 * 60 * 1000;       // …with the original hard backstop as a final net.
+// #648: a JUST-armed narrating turn is protected from a SPURIOUS same-tick clear (the immediate
+// post-armPending surface poll, a /chat cursor-reset re-reading the prior resolved turn's line as a
+// fresh resolution, or a transient campaignId flip tripping the per-run reset) for this long — so the
+// spinner can't be wiped milliseconds after submit, stranding the player with an enabled bar + no DM
+// feedback for the whole ~150s beat (the #648 report). Far below a real DM beat (~100–150s) → a
+// genuine resolution is never swallowed; above the 4s poll cycle → the one-shot post-arm clear can't
+// beat it. Once /events prose streams (`streaming`) the guard lifts, and the 12-min backstop bypasses
+// it entirely (it calls setPendingState(null) directly).
+const PENDING_ARM_GRACE_MS = 10 * 1000;
 // #348: the single source of truth for the recovery window, by turn position. Pure + exported
 // (window.__PENDING_TIMING__ below) so the timing contract is unit-testable without reaching into
 // the hook's internal beat counter. firstBeat ⇒ the longer cold-open window; else the snappy one.
@@ -365,7 +374,20 @@ function useLiveSession(state) {
     });
   }, []);
 
-  const clearPending = React.useCallback(() => { clearTimers(); setPendingState(null); }, [clearTimers, setPendingState]);
+  const clearPending = React.useCallback(() => {
+    // #648: keep a FRESHLY-armed, not-yet-streaming turn alive through a spurious same-tick clear
+    // (see PENDING_ARM_GRACE_MS). The real "Try again" retry path re-arms via armPending (which calls
+    // clearTimers itself), NOT clearPending, so this never blocks a legitimate re-arm; it only stops a
+    // poll/reset/flip from wiping the narrating spinner before the DM's first line could land. A real
+    // resolution arrives long past the grace (or after /events streamed), so it still clears normally.
+    const p = pendingRef.current;
+    if (p && !p.streaming && typeof p.since === "number"
+        && (Date.now() - p.since) < PENDING_ARM_GRACE_MS) {
+      return;
+    }
+    clearTimers();
+    setPendingState(null);
+  }, [clearTimers, setPendingState]);
 
   // #342 + #348: arm the narrating indicator + a recovery timeout. If a DM beat doesn't arrive within
   // the recovery window the turn is flagged `stuck` (the bar re-enables with a "try again" hint)
@@ -650,6 +672,7 @@ window.__PENDING_TIMING__ = {
   recoveryMs: PENDING_RECOVERY_MS,
   recoveryFirstMs: PENDING_RECOVERY_FIRST_MS,
   backstopMs: PENDING_BACKSTOP_MS,
+  armGraceMs: PENDING_ARM_GRACE_MS,  // #648: the just-armed-turn protection window
 };
 // #402: expose the live-tail bound for tests/devtools introspection (purely additive — the hook
 // closes over the consts directly; nothing in the running app reads these off window).

viewer/tests/test_live_narration_stream.py

@@ -241,6 +241,10 @@
   caps: () => sandbox.window.__LIVE_TAIL_CAPS__,
   beatCount: () => (reactHost.api().chatBeats || []).length,
   drain,
+  // #648: advance the fake clock (Date.now reads NOW) so a test can resolve a turn AFTER the
+  // armPending grace window — a real DM beat lands ~100–150s post-submit, far past the guard, so a
+  // same-tick resolve is unrealistic (and now intentionally a no-op for the freshly-armed spinner).
+  advance: (ms) => { NOW += ms || 0; },
 };
 
 // Each test's `script` is a sequence of statements ending in `return (<resultExpr>)`. The scripts
@@ -477,6 +481,9 @@ def test_resolved_beat_makes_next_turn_a_later_beat(self):
             # Turn 1: arm, then resolve it with a turn-END /chat DM line (bumps the internal beat count).
             "h.arm('open the scene');"
             "h.enqueue('/chat', { items: [{ role: 'dm', text: 'You stand at the gates of Baldur\\u2019s Gate.' }], next: 1 });"
+            # a real DM beat lands ~120s post-submit — advance past the #648 armPending grace so the
+            # turn-END line resolves the pending turn (a same-tick resolve is unrealistic + now guarded).
+            "h.advance(121000);"
             "await h.tick();"
             "var afterTurn1 = h.pending();"  # JS string; afterTurn1 should be null (turn resolved)
             # Turn 2: arm again — this pending must be a LATER beat (firstBeat:false).
@@ -906,6 +913,9 @@ def test_engine_logged_chat_reply_resolves_without_rendering_duplicate(self):
         out = self._run(
             "h.arm('ask the sergeant');"
             "h.enqueue('/chat', { items: [{ role: 'dm', text: 'The sergeant refuses to name the captain.', engine_logged: true }], next: 1 });"
+            # advance past the #648 armPending grace (a real beat is ~120s) so the engine-logged
+            # turn-END line resolves the pending turn.
+            "h.advance(121000);"
             "await h.tick();"
             "var afterChat = h.narrationTexts();"
             "var pendingAfterChat = h.pending();"

viewer/tests/test_recovery_timing.py

@@ -275,6 +275,9 @@ def test_clear_pending_resets_state_and_disarms_timers(self):
         out = self._run(
             "h.arm('do thing');"
             "var armed = h.pending();"
+            # advance past the #648 arm-grace so this exercises a GENUINE clear (a real resolution
+            # lands long after submit); the same-tick protection is covered by the #648 test below.
+            "h.advance(h.constants().armGraceMs + 1000);"
             "h.clear();"
             "var cleared = h.pending();"
             # advancing past every window after a manual clear must NOT resurrect a stuck flag —
@@ -286,3 +289,28 @@ def test_clear_pending_resets_state_and_disarms_timers(self):
         self.assertTrue(out["armed_present"])
         self.assertTrue(out["cleared_null"])
         self.assertTrue(out["no_resurrect"], "cleared timers must not fire after clearPending (clean #344 retry re-arm)")
+
+    # --- #648: a freshly-armed narrating turn survives a SPURIOUS same-tick clear -------------
+    def test_armpending_survives_a_same_tick_clear_then_resolves(self):
+        """#648 (the move-sink → pending-arm contract): after an Enter-submitted Do, a clearPending
+        can fire milliseconds later — the immediate post-armPending surface poll, a /chat cursor-reset
+        re-reading the prior resolved turn's line as a fresh resolution, or a transient campaignId
+        flip tripping the per-run reset. That MUST NOT wipe the just-armed narrating spinner (the
+        adversarial's '[MAJOR] no spinner, buttons enabled, no DM for 3+ min until I clicked
+        Continue'). The guard is bounded: a REAL resolution (~100–150s later, past the grace) still
+        clears the turn, so the spinner is never stuck on."""
+        out = self._run(
+            "h.arm('Stand down. That child is with me.');"
+            "var armed = !!h.pending();"
+            "h.clear();"                                     # the spurious same-tick clear (must be a no-op)
+            "var p = h.pending();"
+            "var survived = !!p;"
+            "var narrating = !!(p && !p.stuck);"
+            "h.advance(h.constants().armGraceMs + 1000);"    # the real DM beat lands well past the grace
+            "h.clear();"                                     # genuine resolution → clears
+            "({ armed: armed, survives: survived, narrating: narrating, resolves_later: h.pending() === null })"
+        )
+        self.assertTrue(out["armed"], "armPending should arm a narrating turn")
+        self.assertTrue(out["survives"], "#648: a same-tick clear must NOT wipe the just-armed spinner")
+        self.assertTrue(out["narrating"], "the protected turn stays in the narrating (not stuck) state")
+        self.assertTrue(out["resolves_later"], "the protected turn still resolves on the real (post-grace) clear")