fix(ramp): skip RESET-action beforeRemove close on HeadlessHost (Cursor Bugbot)

Phase 9.5's chrome-strip commit added a beforeRemove navigation listener on
HeadlessHost that fires closeSession({ reason: 'user_dismissed' }) on every
beforeRemove event. Cursor Bugbot caught a high-severity bug: useTransakRouting
uses navigation.reset() to re-pin HEADLESS_HOST at the base of the stack when
moving to VerifyIdentity / BasicInfo / Checkout / KycWebview. The reset action
fires beforeRemove on the OLD HEADLESS_HOST instance before re-pinning the new
one, but the session is still in flight — closing it here prematurely fires
onClose({ reason: 'user_dismissed' }) and breaks the consumer's flow.

Resolution: inspect e.data.action.type inside the listener and short-circuit on
'RESET'. Legitimate user-dismissal paths (GO_BACK, POP) still close the session
synchronously. Other unmount cases (real stack reset that does NOT re-pin the
Host, hot reload) remain caught by useHeadlessSessionDismissal's unmount
cleanup, which uses isHeadlessHostStillInNavigator to differentiate.

Adds a HeadlessHost.test.tsx case 'does NOT close the session when beforeRemove
fires for a RESET action (stack rebuild guard)'. Updates the existing test
helper to pass a non-RESET action in the event arg so the listener's new
signature stays exercised.

Bug report: #30104 (review)

Author: saustrie-consensys

CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - Route swallowed `getUserLimits` infrastructure errors through `failSession` when a headless Ramp session is active, so headless consumers receive an `onError` callback instead of a silent hang (Phase 9.5 Fix A).
+- Skip the `beforeRemove` close path on `RESET` actions in the Ramp Headless Host so `useTransakRouting`'s stack rebuilds (re-pinning HEADLESS_HOST when routing to VerifyIdentity / BasicInfo / Checkout / KycWebview) no longer prematurely fire `onClose({ reason: 'user_dismissed' })` (Phase 9.5; Cursor Bugbot finding).
 
 ## [7.76.3]
 

app/components/UI/Ramp/Views/HeadlessHost/HeadlessHost.test.tsx

@@ -34,7 +34,18 @@ const mockUseContinueWithQuoteOptions = jest.fn();
 // Holds the most recent 'beforeRemove' listener registered against the
 // mocked navigation object. Tests fire it directly to exercise the
 // production beforeRemove path without spinning up a real navigator.
-let registeredBeforeRemoveListener: (() => void) | null = null;
+// The listener now reads `e.data.action.type` so it can ignore RESET
+// stack-rebuilds; tests pass an event arg accordingly.
+interface BeforeRemoveEvent {
+  data: { action: { type: string } };
+}
+let registeredBeforeRemoveListener: ((e?: BeforeRemoveEvent) => void) | null =
+  null;
+// Default event passed when a test wants to simulate a user back/swipe — any
+// non-RESET action type triggers the close path.
+const DEFAULT_GO_BACK_EVENT: BeforeRemoveEvent = {
+  data: { action: { type: 'GO_BACK' } },
+};
 
 jest.mock('@react-navigation/native', () => {
   const actual = jest.requireActual('@react-navigation/native');
@@ -164,7 +175,7 @@ describe('HeadlessHost', () => {
     __resetSessionRegistryForTests();
     registeredBeforeRemoveListener = null;
     mockAddListener.mockImplementation(
-      (eventName: string, listener: () => void) => {
+      (eventName: string, listener: (e?: BeforeRemoveEvent) => void) => {
         if (eventName === 'beforeRemove') {
           registeredBeforeRemoveListener = listener;
         }
@@ -455,7 +466,7 @@ describe('HeadlessHost', () => {
       expect(typeof registeredBeforeRemoveListener).toBe('function');
 
       // Fire the listener like React Navigation would on a back gesture.
-      registeredBeforeRemoveListener?.();
+      registeredBeforeRemoveListener?.(DEFAULT_GO_BACK_EVENT);
 
       expect(callbacks.onClose).toHaveBeenCalledTimes(1);
       expect(callbacks.onClose).toHaveBeenCalledWith({
@@ -464,6 +475,30 @@ describe('HeadlessHost', () => {
       expect(getSession(session.id)).toBeUndefined();
     });
 
+    it('does NOT close the session when beforeRemove fires for a RESET action (stack rebuild guard)', () => {
+      // Cursor Bugbot — useTransakRouting calls navigation.reset() to
+      // re-pin HEADLESS_HOST at the base when moving to VerifyIdentity /
+      // BasicInfo / Checkout / KycWebview. The reset fires beforeRemove on
+      // the OLD instance, but the session is still in flight; closing it
+      // here would prematurely fire onClose({ reason: 'user_dismissed' })
+      // and break the flow.
+      const quote = buildAggregatorQuote();
+      const session = seedSession(quote);
+      const callbacks = session.callbacks;
+      renderHost({ headlessSessionId: session.id });
+      expect(typeof registeredBeforeRemoveListener).toBe('function');
+
+      registeredBeforeRemoveListener?.({
+        data: { action: { type: 'RESET' } },
+      });
+
+      expect(callbacks.onClose).not.toHaveBeenCalled();
+      // The session is still live so useTransakRouting's reset can complete
+      // and re-pin the new HEADLESS_HOST without losing the consumer's
+      // callbacks.
+      expect(getSession(session.id)).toBeDefined();
+    });
+
     it('fires onClose({ reason: "user_dismissed" }) once when the host unmounts mid-flow without a terminal status', async () => {
       mockContinueWithQuote.mockImplementation(
         () => new Promise(() => undefined),
@@ -506,7 +541,7 @@ describe('HeadlessHost', () => {
       // beforeRemove fires too (React Navigation always fires it on screen
       // removal), then unmount cleanup runs. Both find the session gone and
       // no-op.
-      registeredBeforeRemoveListener?.();
+      registeredBeforeRemoveListener?.(DEFAULT_GO_BACK_EVENT);
       unmount();
 
       expect(callbacks.onClose).toHaveBeenCalledTimes(1);
@@ -526,7 +561,7 @@ describe('HeadlessHost', () => {
       expect(callbacks.onClose).toHaveBeenCalledTimes(1);
       expect(callbacks.onClose).toHaveBeenCalledWith({ reason: 'unknown' });
 
-      registeredBeforeRemoveListener?.();
+      registeredBeforeRemoveListener?.(DEFAULT_GO_BACK_EVENT);
       unmount();
 
       // Both follow-up paths re-read, see nothing, no-op.
@@ -546,7 +581,7 @@ describe('HeadlessHost', () => {
       });
 
       const { unmount } = renderHost({ headlessSessionId: session.id });
-      registeredBeforeRemoveListener?.();
+      registeredBeforeRemoveListener?.(DEFAULT_GO_BACK_EVENT);
       unmount();
 
       expect(callbacks.onClose).toHaveBeenCalledTimes(1);

app/components/UI/Ramp/Views/HeadlessHost/HeadlessHost.tsx

@@ -104,8 +104,22 @@ function HeadlessHost() {
   // are caught by `useHeadlessSessionDismissal`'s unmount cleanup above.
   // closeSession is idempotent: Phase 6 success and Phase 7 errors clear
   // the session before `beforeRemove` and turn this into a no-op.
+  //
+  // Stack-rebuild guard (Cursor Bugbot): `useTransakRouting` calls
+  // `navigation.reset()` to re-pin HEADLESS_HOST at the base of the stack
+  // when navigating to VerifyIdentity / BasicInfo / Checkout / KycWebview.
+  // The reset action fires `beforeRemove` on the OLD HEADLESS_HOST instance
+  // before re-pinning the new one, but the session is still in flight —
+  // closing it here would prematurely fire `onClose({ reason: 'user_dismissed' })`
+  // and break the flow. Skip the close when the action is a RESET; the
+  // legitimate unmount cases (stack reset that does NOT re-pin the Host,
+  // hot reload) are caught by `useHeadlessSessionDismissal`'s unmount path
+  // with `isHeadlessHostStillInNavigator`.
   useEffect(() => {
-    const unsubscribe = navigation.addListener('beforeRemove', () => {
+    const unsubscribe = navigation.addListener('beforeRemove', (e) => {
+      if (e.data.action.type === 'RESET') {
+        return;
+      }
       closeSession(headlessSessionId, { reason: 'user_dismissed' });
     });
     return unsubscribe;

app/components/UI/Ramp/headless/PLAN.md

@@ -671,6 +671,34 @@ UB2's existing swallow stays in place — the existing test at [useTransakRoutin
 
 The parallel swallow in [useDepositRouting.ts:137-180](../hooks/useDepositRouting.ts) is deliberately **not** fixed here — Deposit isn't a headless route, and the "ramps work is UB2-only" rule keeps us off the Deposit tree.
 
+#### Fix B — RESET-action guard in HeadlessHost's `beforeRemove` listener (Cursor Bugbot)
+
+The chrome-strip commit added a `beforeRemove` navigation listener on HeadlessHost so the synchronous `closeSession({ reason: 'user_dismissed' })` still fires when the user backs out (no more visible Cancel/Back button to wire). The original implementation fired the close on EVERY `beforeRemove` event.
+
+Cursor Bugbot flagged that `useTransakRouting` uses `navigation.reset()` to re-pin HEADLESS_HOST at the base of the stack whenever it routes to VerifyIdentity / BasicInfo / Checkout / KycWebview. The reset action fires `beforeRemove` on the OLD HEADLESS_HOST instance before re-pinning the new one — but the session is still in flight, so the close fires prematurely with `user_dismissed`, breaking the consumer's flow.
+
+Resolution at [HeadlessHost.tsx:107-118](../Views/HeadlessHost/HeadlessHost.tsx): inspect `e.data.action.type` inside the listener and skip the close on `'RESET'`:
+
+```ts
+useEffect(() => {
+  const unsubscribe = navigation.addListener('beforeRemove', (e) => {
+    if (e.data.action.type === 'RESET') {
+      return;
+    }
+    closeSession(headlessSessionId, { reason: 'user_dismissed' });
+  });
+  return unsubscribe;
+}, [navigation, headlessSessionId]);
+```
+
+The legitimate unmount paths (real stack reset that does NOT re-pin the Host, hot reload) stay correct because `useHeadlessSessionDismissal`'s unmount cleanup uses `isHeadlessHostStillInNavigator` to differentiate. The two layers are complementary: `beforeRemove` for synchronous user-driven dismissals (GO_BACK, POP), `useHeadlessSessionDismissal` for asynchronous unmount cleanup.
+
+A new test in [HeadlessHost.test.tsx](../Views/HeadlessHost/HeadlessHost.test.tsx) (`'does NOT close the session when beforeRemove fires for a RESET action (stack rebuild guard)'`) fires the listener with `{ data: { action: { type: 'RESET' } } }` and asserts the session stays live.
+
+#### Note on the original "Fix B" deferral
+
+The pasted-plan placeholder "Fix B (`getProviderBuyLimit` belt-and-braces pre-flight)" landed in the Phase 9 PR ([metamask-mobile#30103](https://github.com/MetaMask/metamask-mobile/pull/30103)) as `feat(ramp): pre-quote static bounds check + expose getProviderBuyLimit`, with a more comprehensive implementation than this PR originally drafted (UB2-parity skip on `amount <= 0`, conservative "all candidates reject" rule, `details.source` discriminator, plus a public `getProviderBuyLimit` re-export). Phase 9.5 doesn't duplicate it.
+
 ---
 
 ## Phase 10 — Implement deferred Phase 5b + playground polish