@scalebun/react-native 1.10.3 → 1.10.5

package/lib/module/debug/redaction.js

@@ -10,29 +10,80 @@
 
 const REDACTED = '[REDACTED]';
 
+// ─── Safety limits (SB-25 / SB-27) ───────────────────────────────────────────
+// The PII scanner runs synchronously on the JS thread inside the app's own
+// fetch()/XHR call. Left unbounded it is both a ReDoS vector (a large body of
+// alphanumeric text can make regex matching cost seconds — an Android ANR) and
+// a payload-amplification / exfiltration channel (one warning object per match).
+// These bounds keep every scan linear and its output small.
+
+/** Never scan more than this many characters — truncate before matching. */
+const MAX_SCAN_INPUT_CHARS = 16 * 1024;
+/** Abandon a scan once it has spent this long on the JS thread. */
+const SCAN_TIME_BUDGET_MS = 10;
+/** Never emit more than this many PII warnings for a single event. */
+const MAX_PII_WARNINGS = 20;
+/** Never pattern-scrub a string value longer than this (bounded work). */
+const MAX_STRING_SCRUB_CHARS = 64 * 1024;
+
 /** Headers that must always be redacted (case-insensitive) */
 const SENSITIVE_HEADERS = new Set(['authorization', 'cookie', 'set-cookie', 'x-api-key', 'x-auth-token', 'proxy-authorization']);
 
-/** PII detection patterns */
+/**
+ * PII detection patterns.
+ *
+ * SB-25: patterns must be free of catastrophic backtracking. The email pattern
+ * uses non-overlapping character classes with bounded quantifiers so it cannot
+ * backtrack quadratically on adversarial input like `'a'.repeat(N) + '@' + …`.
+ * All quantifiers here are bounded; combined with the input cap above this keeps
+ * matching linear in input size.
+ */
 const PII_PATTERNS = [{
   name: 'email',
-  pattern: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g
+  pattern: /[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9-]{1,63}(?:\.[A-Za-z0-9-]{1,63}){0,8}\.[A-Za-z]{2,24}/g
 }, {
   name: 'phone',
-  pattern: /(?:\+?\d{1,3}[-.\s]?)?\(?\d{2,4}\)?[-.\s]?\d{3,4}[-.\s]?\d{3,4}/g
+  pattern: /\+?\d{1,3}[-.\s]?\(?\d{2,4}\)?[-.\s]?\d{3,4}[-.\s]?\d{3,4}/g
 }, {
   name: 'ssn',
   pattern: /\b\d{3}-\d{2}-\d{4}\b/g
 }, {
   name: 'credit_card',
   pattern: /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/g
+}, {
+  name: 'iban',
+  pattern: /\b[A-Z]{2}\d{2}[A-Z0-9]{10,30}\b/g
+}, {
+  name: 'jwt',
+  pattern: /\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\b/g
 }, {
   name: 'ip_address',
   pattern: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g
 }];
 
+/**
+ * Value patterns used to scrub secrets out of raw string bodies (SB-02).
+ * These are applied to string values (including parsed-out JSON string leaves
+ * and non-JSON bodies) where a denylisted key name is not available. All are
+ * bounded / anchored to avoid backtracking.
+ */
+const VALUE_SCRUB_PATTERNS = [{
+  name: 'jwt',
+  pattern: /eyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}/g
+}, {
+  name: 'email',
+  pattern: /[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9-]{1,63}(?:\.[A-Za-z0-9-]{1,63}){0,8}\.[A-Za-z]{2,24}/g
+}, {
+  name: 'iban',
+  pattern: /\b[A-Z]{2}\d{2}[A-Z0-9]{10,30}\b/g
+}, {
+  name: 'credit_card',
+  pattern: /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{2,7}\b/g,
+  luhn: true
+}];
+
 /** Keys in request/response bodies that likely contain sensitive data */
-const SENSITIVE_BODY_KEYS = new Set(['password', 'passwd', 'secret', 'token', 'access_token', 'refresh_token', 'api_key', 'apiKey', 'private_key', 'privateKey', 'credit_card', 'creditCard', 'ccNumber', 'cvv', 'ssn', 'social_security']);
+const SENSITIVE_BODY_KEYS = new Set(['password', 'passwd', 'secret', 'token', 'access_token', 'refresh_token', 'id_token', 'api_key', 'apiKey', 'private_key', 'privateKey', 'credit_card', 'creditCard', 'ccnumber', 'cardnumber', 'card_number', 'pan', 'cvv', 'cvc', 'ssn', 'social_security', 'nationalid', 'national_id', 'iban', 'otp', 'pin', 'totp', 'mfa', 'mnemonic', 'seed']);
 
 // ─── Header Redaction ───────────────────────────────────────────────────────
 
@@ -59,9 +110,68 @@ export function redactHeaders(headers) {
 
 // ─── Body Redaction ─────────────────────────────────────────────────────────
 
+/** Normalize a key for denylist comparison: lowercase, strip separators. */
+function _normalizeKey(key) {
+  return key.toLowerCase().replace(/[_\-\s]/g, '');
+}
+
+/** Normalized denylist so `access_token`, `accessToken` and `Access-Token` all match. */
+const NORMALIZED_SENSITIVE_KEYS = new Set(Array.from(SENSITIVE_BODY_KEYS, _normalizeKey));
+function _isSensitiveKey(key) {
+  return NORMALIZED_SENSITIVE_KEYS.has(_normalizeKey(key));
+}
+
+/** Passes the Luhn checksum — used to avoid over-redacting random 16-digit ids. */
+function _luhnValid(digits) {
+  const s = digits.replace(/[^\d]/g, '');
+  if (s.length < 12 || s.length > 19) return false;
+  let sum = 0;
+  let alt = false;
+  for (let i = s.length - 1; i >= 0; i--) {
+    let d = s.charCodeAt(i) - 48;
+    if (alt) {
+      d *= 2;
+      if (d > 9) d -= 9;
+    }
+    sum += d;
+    alt = !alt;
+  }
+  return sum % 10 === 0;
+}
+
+/**
+ * Scrub structured secrets (JWT, email, IBAN, Luhn-valid card) out of a raw
+ * string value where no denylisted key name is available (SB-02). Bounded work:
+ * the string is capped and every pattern is anchored/bounded.
+ */
+function _scrubSecretsInString(value) {
+  if (value.length > MAX_STRING_SCRUB_CHARS) {
+    value = value.slice(0, MAX_STRING_SCRUB_CHARS);
+  }
+  let out = value;
+  try {
+    for (const {
+      pattern,
+      luhn
+    } of VALUE_SCRUB_PATTERNS) {
+      pattern.lastIndex = 0;
+      out = out.replace(pattern, m => luhn && !_luhnValid(m) ? m : REDACTED);
+    }
+  } catch {
+    // Never throw — return whatever scrubbing produced so far.
+  }
+  return out;
+}
+
 /**
  * Deep-redact sensitive keys in a body object. Returns a new object.
  * Handles nested objects and arrays. Never throws.
+ *
+ * SB-02: string bodies (what JSON.stringify produces — i.e. essentially every
+ * React Native network body) are no longer passed through untouched. If a string
+ * parses as JSON it is deep-redacted and re-serialized; otherwise structured
+ * secrets in the string are scrubbed. This closes the "6 of 9 seeded secrets
+ * survived" leak while leaving non-sensitive metadata intact.
  */
 export function redactBody(body, maxDepth = 10) {
   try {
@@ -74,9 +184,7 @@ function _redactValue(value, depth, maxDepth) {
   if (depth > maxDepth) return '[MAX_DEPTH]';
   if (value === null || value === undefined) return value;
   if (typeof value === 'string') {
-    // Don't deeply redact strings at the value level here,
-    // PII scanning is a separate concern
-    return value;
+    return _redactString(value, depth, maxDepth);
   }
   if (Array.isArray(value)) {
     return value.map(item => _redactValue(item, depth + 1, maxDepth));
@@ -84,7 +192,7 @@ function _redactValue(value, depth, maxDepth) {
   if (typeof value === 'object') {
     const result = {};
     for (const [key, val] of Object.entries(value)) {
-      if (SENSITIVE_BODY_KEYS.has(key) || SENSITIVE_BODY_KEYS.has(key.toLowerCase())) {
+      if (_isSensitiveKey(key)) {
         result[key] = REDACTED;
       } else {
         result[key] = _redactValue(val, depth + 1, maxDepth);
@@ -95,66 +203,145 @@ function _redactValue(value, depth, maxDepth) {
   return value;
 }
 
+/**
+ * Redact a string value. If it looks like a JSON object/array, parse it, redact
+ * by key, and re-serialize so a serialized body such as
+ * `{"password":"...","otp":"..."}` is scrubbed. Otherwise scrub structured
+ * secrets out of the raw text.
+ */
+function _redactString(value, depth, maxDepth) {
+  const trimmed = value.trimStart();
+  if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+    try {
+      const parsed = JSON.parse(value);
+      if (parsed !== null && typeof parsed === 'object') {
+        const redacted = _redactValue(parsed, depth + 1, maxDepth);
+        return JSON.stringify(redacted);
+      }
+    } catch {
+      // Not valid JSON — fall through to pattern scrubbing.
+    }
+  }
+  return _scrubSecretsInString(value);
+}
+
 // ─── PII Scanning ───────────────────────────────────────────────────────────
 
 /**
- * Scan a string for PII patterns. Returns list of warnings.
- * Never throws.
+ * Bounded scan context shared across one logical scan (SB-25 / SB-27). Enforces
+ * a wall-clock budget and a warning cap while accumulating per-type counts so the
+ * final output can report `{ email: 5000 }` instead of 5000 fragment objects.
  */
-export function scanForPII(text, location = 'unknown') {
-  const warnings = [];
+
+function _newScanContext() {
+  return {
+    warnings: [],
+    byType: {},
+    deadline: Date.now() + SCAN_TIME_BUDGET_MS,
+    truncated: false,
+    total: 0
+  };
+}
+function _pushWarning(ctx, type, rawMatch, location) {
+  ctx.total += 1;
+  ctx.byType[type] = (ctx.byType[type] ?? 0) + 1;
+  if (ctx.warnings.length < MAX_PII_WARNINGS) {
+    ctx.warnings.push({
+      type,
+      match: _maskPII(rawMatch),
+      location
+    });
+  } else {
+    ctx.truncated = true;
+  }
+}
+
+/**
+ * Finalize a scan: append a single summary entry carrying per-type counts when
+ * anything was dropped, so consumers see the full magnitude without the SDK
+ * shipping every matched fragment (SB-27).
+ */
+function _finalizeScan(ctx) {
+  if (ctx.truncated) {
+    ctx.warnings.push({
+      type: '_summary',
+      match: `truncated: ${ctx.total} matches`,
+      location: `counts:${JSON.stringify(ctx.byType)}`
+    });
+  }
+  return ctx.warnings;
+}
+function _scanTextInto(text, location, ctx) {
+  // SB-25: cap the input before any regex runs, so matching cost is bounded
+  // regardless of the (attacker-controlled) body size.
+  const input = text.length > MAX_SCAN_INPUT_CHARS ? text.slice(0, MAX_SCAN_INPUT_CHARS) : text;
   try {
     for (const {
       name,
       pattern
     } of PII_PATTERNS) {
-      // Reset regex state
       pattern.lastIndex = 0;
-      let match = pattern.exec(text);
+      let match = pattern.exec(input);
       while (match) {
-        warnings.push({
-          type: name,
-          match: _maskPII(match[0]),
-          location
-        });
-        match = pattern.exec(text);
+        _pushWarning(ctx, name, match[0], location);
+        // SB-25: abandon the scan if it has exceeded its time budget.
+        if (Date.now() > ctx.deadline) {
+          ctx.truncated = true;
+          return;
+        }
+        if (pattern.lastIndex === match.index) pattern.lastIndex++; // guard zero-width
+        match = pattern.exec(input);
       }
     }
   } catch {
-    // Never throw — return whatever we found so far
+    // Never throw — keep whatever was found so far.
   }
-  return warnings;
 }
 
 /**
- * Scan an object deeply for PII. Returns list of warnings.
+ * Scan a string for PII patterns. Returns a bounded list of warnings.
+ * Never throws.
+ */
+export function scanForPII(text, location = 'unknown') {
+  const ctx = _newScanContext();
+  _scanTextInto(text, location, ctx);
+  return _finalizeScan(ctx);
+}
+
+/**
+ * Scan an object deeply for PII. Returns a bounded list of warnings.
  * Never throws.
  */
 export function scanObjectForPII(obj, basePath = '', maxDepth = 10) {
-  const warnings = [];
+  const ctx = _newScanContext();
   try {
-    _scanObject(obj, basePath, 0, maxDepth, warnings);
+    _scanObjectInto(obj, basePath, 0, maxDepth, ctx);
   } catch {
     // Never throw
   }
-  return warnings;
+  return _finalizeScan(ctx);
 }
-function _scanObject(value, path, depth, maxDepth, warnings) {
+function _scanObjectInto(value, path, depth, maxDepth, ctx) {
   if (depth > maxDepth || value === null || value === undefined) return;
+  if (ctx.truncated || Date.now() > ctx.deadline) {
+    ctx.truncated = true;
+    return;
+  }
   if (typeof value === 'string') {
-    const found = scanForPII(value, path);
-    warnings.push(...found);
+    _scanTextInto(value, path, ctx);
     return;
   }
   if (Array.isArray(value)) {
-    value.forEach((item, i) => {
-      _scanObject(item, `${path}[${i}]`, depth + 1, maxDepth, warnings);
-    });
+    for (let i = 0; i < value.length; i++) {
+      if (ctx.truncated) return;
+      _scanObjectInto(value[i], `${path}[${i}]`, depth + 1, maxDepth, ctx);
+    }
     return;
   }
   if (typeof value === 'object') {
     for (const [key, val] of Object.entries(value)) {
-      _scanObject(val, path ? `${path}.${key}` : key, depth + 1, maxDepth, warnings);
+      if (ctx.truncated) return;
+      _scanObjectInto(val, path ? `${path}.${key}` : key, depth + 1, maxDepth, ctx);
     }
   }
 }
@@ -196,20 +383,19 @@ export function redactUrl(url) {
  * Apply full redaction pipeline to a network event.
  */
 export function redactNetworkEvent(event) {
-  const piiWarnings = [];
-
-  // Scan URL for PII
+  // One bounded context for the whole event so the aggregate warning count and
+  // scan time stay capped across url + request + response (SB-25 / SB-27).
+  const ctx = _newScanContext();
   if (event.url) {
-    piiWarnings.push(...scanForPII(event.url, 'url'));
+    _scanTextInto(event.url, 'url', ctx);
   }
-
-  // Scan bodies for PII
   if (event.requestBody) {
-    piiWarnings.push(...scanObjectForPII(event.requestBody, 'requestBody'));
+    _scanObjectInto(event.requestBody, 'requestBody', 0, 10, ctx);
   }
   if (event.responseBody) {
-    piiWarnings.push(...scanObjectForPII(event.responseBody, 'responseBody'));
+    _scanObjectInto(event.responseBody, 'responseBody', 0, 10, ctx);
   }
+  const piiWarnings = _finalizeScan(ctx);
   return {
     url: event.url ? redactUrl(event.url) : '',
     method: event.method ?? 'GET',

package/lib/module/features/journey/ScaleBunDebugRoot.js

@@ -575,7 +575,15 @@ export function ScaleBunDebugRoot({
               });
             }
           } catch {/* no-throw */}
-        }, 200);
+          // 600ms, was 200ms. The race this defer exists for happens on the FIRST tap of a
+          // mount: native isn't confirmed yet, JS emitted at 200ms, then the first native
+          // event crossed the bridge at ~300-400ms — recording the same tap TWICE, with the
+          // JS copy missing normalizedX/Y whenever the async root-view measure hadn't
+          // resolved (an interaction the heatmap cannot place). QA hit exactly this pair.
+          // The wider defer lets the first native event cancel the JS emission instead; on
+          // devices with no native tracker at all it merely delays a background emission,
+          // which nothing user-visible waits on.
+        }, 600);
       }
       touchStartRef.current = null;
     } catch {/* no-throw */}

package/lib/module/features/navigation/AutoScreenDetector.js

@@ -36,12 +36,22 @@ export class AutoScreenDetector {
   _manualScreen = null;
   _manualScreenTs = 0;
   _autoScreen = null;
+  /** `name#key` of the last auto-detected screen VISIT — see _extractActiveVisit. */
+  _autoVisitSig = null;
   _navigationRef = null;
   _navListenerRemover = null;
   _navListenerWired = false;
   _heuristicTimer = null;
   _started = false;
   _lastEmittedScreen = null;
+  _lastEmittedTs = 0;
+  /**
+   * Cross-source emit dedup window — see _emitScreenChange. Long enough to absorb the manual
+   * beacon and the navRef listener both reporting the SAME transition (they land within the
+   * 30ms nav debounce plus a render), short enough that a genuine re-visit of the same route
+   * a moment later is a new screen view rather than silence.
+   */
+  static EMIT_DEDUP_WINDOW_MS = 800;
   _navDebounceTimer = null;
   /** Whether the React Navigation exports were actually replaced — see _autoHookReactNavigation. */
   _autoHookInstalled = false;
@@ -100,6 +110,7 @@ export class AutoScreenDetector {
       if (this.isManualScreenActive()) return;
       if (name !== this._autoScreen) {
         this._autoScreen = name;
+        this._autoVisitSig = name; // native lifecycle carries no route key — name-only visit
         this._emitScreenChange(name, 'heuristic');
       }
     } catch {/* no-throw */}
@@ -162,10 +173,13 @@ export class AutoScreenDetector {
               try {
                 const state = typeof container.getRootState === 'function' ? container.getRootState() : null;
                 if (state) {
-                  const screen = this._extractActiveRoute(state);
-                  if (screen && screen !== this._autoScreen) {
-                    this._autoScreen = screen;
-                    this._emitScreenChange(screen, 'navRef');
+                  // Compared by name#key so a re-VISIT of the same route
+                  // (new key) is recorded — name-only comparison swallowed it.
+                  const visit = this._extractActiveVisit(state);
+                  if (visit && this._visitSig(visit) !== this._autoVisitSig) {
+                    this._autoScreen = visit.name;
+                    this._autoVisitSig = this._visitSig(visit);
+                    this._emitScreenChange(visit.name, 'navRef');
                   }
                 }
               } catch {/* no-throw */}
@@ -179,10 +193,11 @@ export class AutoScreenDetector {
       if (typeof container.getRootState === 'function') {
         const state = container.getRootState();
         if (state) {
-          const screen = this._extractActiveRoute(state);
-          if (screen) {
-            this._autoScreen = screen;
-            this._emitScreenChange(screen, 'navRef');
+          const visit = this._extractActiveVisit(state);
+          if (visit) {
+            this._autoScreen = visit.name;
+            this._autoVisitSig = this._visitSig(visit);
+            this._emitScreenChange(visit.name, 'navRef');
           }
         }
       }
@@ -218,10 +233,14 @@ export class AutoScreenDetector {
         if (navContainer) {
           const state = typeof navContainer.getRootState === 'function' ? navContainer.getRootState() : null;
           if (state) {
-            const screen = this._extractActiveRoute(state);
-            if (screen && screen !== this._autoScreen) {
-              this._autoScreen = screen;
-              this._emitScreenChange(screen, 'heuristic');
+            // name#key comparison: a re-opened route (same name, fresh key) seen
+            // across poll ticks is a new visit even when every intermediate screen
+            // fell between polls — the case a name-only diff could never see.
+            const visit = this._extractActiveVisit(state);
+            if (visit && this._visitSig(visit) !== this._autoVisitSig) {
+              this._autoScreen = visit.name;
+              this._autoVisitSig = this._visitSig(visit);
+              this._emitScreenChange(visit.name, 'heuristic');
             }
           }
         }
@@ -261,6 +280,22 @@ export class AutoScreenDetector {
    * Handles nested navigators by walking to the deepest active route.
    */
   _extractActiveRoute(state) {
+    return this._extractActiveVisit(state)?.name ?? null;
+  }
+
+  /**
+   * Extract the active route's name AND its React Navigation route `key`.
+   *
+   * The key is what makes re-VISITS detectable. Comparing names alone collapses two
+   * different visits to the same route into one screen view: leave Details, open Details
+   * again, and `name === _autoScreen` swallowed the second visit entirely (QA: "opened the
+   * same route again and no screen event was recorded"). React Navigation mints a fresh
+   * `key` for every pushed route instance, so a re-push of the same name is a NEW key —
+   * name+key comparison records each visit while a mere re-render of the same instance
+   * (same key) still emits nothing. States without keys degrade to name-only, i.e. the
+   * old behaviour, never worse.
+   */
+  _extractActiveVisit(state) {
     try {
       if (!state?.routes || typeof state.index !== 'number') return null;
       const activeRoute = state.routes[state.index];
@@ -268,15 +303,25 @@ export class AutoScreenDetector {
 
       // If this route has nested state, recurse to find the deepest active route
       if (activeRoute.state?.routes && typeof activeRoute.state.index === 'number') {
-        const nested = this._extractActiveRoute(activeRoute.state);
+        const nested = this._extractActiveVisit(activeRoute.state);
         if (nested) return nested;
       }
-      return activeRoute.name || null;
+      if (!activeRoute.name) return null;
+      const rawKey = activeRoute.key;
+      return {
+        name: activeRoute.name,
+        key: typeof rawKey === 'string' ? rawKey : null
+      };
     } catch {
       return null;
     }
   }
 
+  /** `name#key` signature of one screen VISIT — what the auto paths dedup on. */
+  _visitSig(visit) {
+    return visit.key ? `${visit.name}#${visit.key}` : visit.name;
+  }
+
   // ─── Lifecycle ──────────────────────────────────────────────────────
 
   /** Start auto-detection (idempotent) */
@@ -466,9 +511,16 @@ export class AutoScreenDetector {
 
   _emitScreenChange(name, source) {
     try {
-      // Deduplicate: don't emit if the screen is the same as last emitted
-      if (name === this._lastEmittedScreen) return;
+      // Cross-source dedup, TIME-BOUNDED. This used to drop any name equal to the last
+      // emitted, forever — so re-entering a route whose departure was never observed
+      // (heuristic poll missed the intermediate screen, or the user re-pushed the same
+      // route) was swallowed on EVERY path, manual beacons included (QA: "opened the
+      // same route again, no screen event"). Same name within the window is still one
+      // transition double-reported by two sources; same name after it is a new visit.
+      const emitNow = Date.now();
+      if (name === this._lastEmittedScreen && emitNow - this._lastEmittedTs < AutoScreenDetector.EMIT_DEDUP_WINDOW_MS) return;
       this._lastEmittedScreen = name;
+      this._lastEmittedTs = emitNow;
       for (const cb of this._listeners) {
         try {
           cb(name, source);

package/lib/module/features/session/BackendSessionAdapter.js

@@ -93,6 +93,13 @@ export class BackendSessionAdapter {
   // the flush timer retries, so nothing is lost to a start/child race. The durable native
   // outbox path has its own ordering; this guards only the JS in-memory fallback.
   _startedSessionIds = new Set();
+  // §11 offline-start recovery: INGESTION_START payloads whose POST failed (e.g. the app
+  // launched with no connectivity). Without this, a failed START was logged and forgotten —
+  // the row-ready gate never opened, every child lane re-buffered forever, and the session
+  // stayed stuck until an app restart even after the network returned. Each flush tick
+  // re-attempts these until acked (network errors keep retrying; permanent 4xx gives up).
+  _pendingStartPayloads = new Map();
+  _startRetryInFlight = false;
   pendingFrames = [];
   pendingEvents = [];
   pendingNetworkRequests = [];
@@ -228,11 +235,20 @@ export class BackendSessionAdapter {
         }
       };
       __DEV__ && logger.debug(`[BackendSessionAdapter] POST session start: ${session.sessionId}`);
-      return this._post(startEndpoint, payload);
-    }).then(() => {
-      // §11: row now exists — release the child-lane flush gate for this id.
-      this._startedSessionIds.add(session.sessionId);
-      __DEV__ && logger.info(`[ScaleBun Replay] backend session upload success`);
+      return this._post(startEndpoint, payload).then(() => {
+        // §11: row now exists — release the child-lane flush gate for this id.
+        this._startedSessionIds.add(session.sessionId);
+        this._pendingStartPayloads.delete(session.sessionId);
+        __DEV__ && logger.info(`[ScaleBun Replay] backend session upload success`);
+      }, err => {
+        // Offline-start recovery: keep the payload; the flush timer re-attempts it
+        // until the row is acked. A permanent 4xx (rejected key) is not retried —
+        // the same payload can never succeed.
+        if (!BackendSessionAdapter._isPermanentHttpError(err)) {
+          this._pendingStartPayloads.set(session.sessionId, payload);
+        }
+        logger.info(`[ScaleBun Replay] backend session upload failure`);
+      });
     }).catch(() => logger.info(`[ScaleBun Replay] backend session upload failure`));
   }
   sendSessionEnd(session) {
@@ -327,10 +343,22 @@ export class BackendSessionAdapter {
           environment: m?.buildType
         }
       };
-      await this._post(startEndpoint, payload);
+      try {
+        await this._post(startEndpoint, payload);
+      } catch (err) {
+        // Offline-start recovery: keep the payload for the flush-tick retry loop.
+        // Without this a session that started with no connectivity NEVER opened its
+        // row-ready gate — frames/events re-buffered for the life of the process and
+        // only an app restart recovered it, even after the network came back.
+        if (!BackendSessionAdapter._isPermanentHttpError(err)) {
+          this._pendingStartPayloads.set(session.sessionId, payload);
+        }
+        throw err;
+      }
       // §11: row exists. When recording adopts this analytics id (one-row merge),
       // this also releases the recording child-lane gate (_sessionRowReady).
       this._startedSessionIds.add(session.sessionId);
+      this._pendingStartPayloads.delete(session.sessionId);
       // Row is confirmed — replay any events buffered while START was in flight.
       // The pre-ack flush at the top of this method is gated off until now, so
       // this is what actually drains the pre-ready buffer (no premature 404).
@@ -341,6 +369,42 @@ export class BackendSessionAdapter {
     }
   }
 
+  /**
+   * Re-attempt any INGESTION_START whose POST failed (offline app launch). Runs on every
+   * flush tick of BOTH lanes — cheap no-op when the map is empty, single-flight guarded.
+   * On ack: opens the row-ready gate and drains whichever lane the id belongs to, which is
+   * exactly what un-sticks a replay that started offline once connectivity returns.
+   */
+  _retryPendingStarts() {
+    if (this.destroyed || this._startRetryInFlight || this._pendingStartPayloads.size === 0) return;
+    const entry = this._pendingStartPayloads.entries().next().value;
+    if (!entry) return;
+    const [sessionId, payload] = entry;
+    // A stale pending start for a session that already ended AND is not the open analytics
+    // session would create a row nothing will ever finalize — drop it instead.
+    const stillRelevant = sessionId === this.currentSessionId || sessionId === this._analyticsSessionId;
+    if (!stillRelevant) {
+      this._pendingStartPayloads.delete(sessionId);
+      return;
+    }
+    this._startRetryInFlight = true;
+    const startEndpoint = this.config.clientKey ? ENDPOINTS.INGESTION_START : '/replay/sessions';
+    this._post(startEndpoint, payload).then(() => {
+      this._startedSessionIds.add(sessionId);
+      this._pendingStartPayloads.delete(sessionId);
+      __DEV__ && logger.info(`[ScaleBun Replay] deferred session start delivered: ${sessionId}`);
+      if (sessionId === this._analyticsSessionId) {
+        this._flushAnalyticsEvents().catch(() => {});
+      }
+    }).catch(err => {
+      if (BackendSessionAdapter._isPermanentHttpError(err)) {
+        this._pendingStartPayloads.delete(sessionId); // will never succeed — stop retrying
+      }
+    }).finally(() => {
+      this._startRetryInFlight = false;
+    });
+  }
+
   /**
    * Enqueue a user track() event. Buffers (bounded, drop-oldest) when the
    * analytics session is not yet open; flushes at >=20 once it is.
@@ -488,6 +552,7 @@ export class BackendSessionAdapter {
   _startAnalyticsFlushTimer() {
     this._stopAnalyticsFlushTimer();
     this.analyticsFlushTimer = setInterval(() => {
+      this._retryPendingStarts();
       this._flushAnalyticsEvents().catch(() => {});
     }, this.config.flushIntervalMs);
   }
@@ -734,6 +799,7 @@ export class BackendSessionAdapter {
     this._analyticsSessionId = null;
     this._pendingFinalizeId = null;
     this._startedSessionIds.clear();
+    this._pendingStartPayloads.clear();
   }
 
   // ─── Internal: Flush ────────────────────────────────────────────────
@@ -1360,6 +1426,7 @@ export class BackendSessionAdapter {
   _startFlushTimer() {
     this._stopFlushTimer();
     this.flushTimer = setInterval(() => {
+      this._retryPendingStarts();
       this._flushFrames().catch(() => {});
       this._flushEvents().catch(() => {});
       this._flushNetwork().catch(() => {});