@agent-native/core 0.98.3 → 0.98.4

package/corpus/core/src/client/session-replay.ts

@@ -11,6 +11,12 @@ type QueuedReplayEvent = {
   type: number | null;
 };
 type ReplayStopFn = () => void;
+type ReplayResourceNode = {
+  tagName: string;
+  rel: string;
+  as: string;
+  type: string;
+};
 export type SessionReplayUrlMatcher =
   | string
   | RegExp
@@ -68,6 +74,20 @@ interface SessionReplayState {
   restoreCaptures: (() => void) | null;
   options: NormalizedSessionReplayOptions | null;
   lastAuthenticatedProperties: Record<string, unknown> | null;
+  /** Resource tag metadata used to classify later rrweb attribute mutations. */
+  resourceNodes: Map<number, ReplayResourceNode>;
+  /**
+   * Prevents a permanently misconfigured endpoint from causing an automatic
+   * 409 -> restart -> 409 loop. A successful upload resets the allowance, so
+   * a later, independent sequence conflict can still recover in-place.
+   */
+  automaticConflictRestartAttempted: boolean;
+  /**
+   * Cross-tab "who is recording this replayId" channel, open for the
+   * lifetime of an active recording. See `getOrCreateReplaySession` for why
+   * this exists (duplicated-tab guard against a shared `replayId`).
+   */
+  broadcastChannel: BroadcastChannel | null;
 }
 
 interface StoredReplaySession {
@@ -77,6 +97,27 @@ interface StoredReplaySession {
   sequence?: number;
 }
 
+/** Broadcast on `SESSION_REPLAY_BROADCAST_CHANNEL_NAME` by a tab resuming a
+ * stored replay session, to check whether another tab is already recording
+ * that same `replayId` (see the duplicated-tab guard in
+ * `getOrCreateReplaySession`'s doc comment). */
+interface ReplayClaimMessage {
+  type: "an-replay-claim";
+  replayId: string;
+  instanceNonce: string;
+}
+
+/** Reply from a tab that is actively recording the claimed `replayId`. */
+interface ReplayClaimTakenMessage {
+  type: "an-replay-claim-taken";
+  replayId: string;
+  /** Only the claimant with this nonce should yield the stored replay id.
+   * Optional while older recorder bundles can still be open during rollout. */
+  claimantNonce?: string;
+}
+
+type ReplayBroadcastMessage = ReplayClaimMessage | ReplayClaimTakenMessage;
+
 /** rrweb `sampling` shape (mousemove/scroll/media throttles, input strategy). */
 export type ReplayEventSampling = Record<string, unknown>;
 
@@ -107,6 +148,13 @@ export interface SessionReplayNetworkOptions {
   maxErrorBodyLength?: number;
 }
 
+export interface SessionReplayUploadRejectedDetails {
+  status: number;
+  restartAttempted: boolean;
+  restartSucceeded: boolean;
+  restartReason?: SessionReplayStartResult["reason"];
+}
+
 export interface SessionReplayOptions {
   enabled?: boolean;
   /** Rechecked immediately before rrweb starts to cancel deferred startup. */
@@ -157,6 +205,8 @@ export interface SessionReplayOptions {
    * disable, or an options object to override caps.
    */
   network?: boolean | SessionReplayNetworkOptions;
+  /** Rare recorder lifecycle signal; never includes replay content or URLs. */
+  onUploadRejected?: (details: SessionReplayUploadRejectedDetails) => void;
   extraProperties?:
     | Record<string, unknown>
     | (() => Record<string, unknown> | undefined);
@@ -209,6 +259,7 @@ interface NormalizedSessionReplayOptions {
   console: NormalizedCaptureOptions | null;
   /** Null disables network capture entirely. */
   network: NormalizedCaptureOptions | null;
+  onUploadRejected?: SessionReplayOptions["onUploadRejected"];
   extraProperties?: SessionReplayOptions["extraProperties"];
   shouldStart?: SessionReplayOptions["shouldStart"];
 }
@@ -266,6 +317,11 @@ const DEFAULT_MAX_EVENTS_PER_BATCH = 50;
 const DEFAULT_MAX_BATCH_BYTES = 256 * 1024;
 const MAX_KEEPALIVE_REPLAY_UPLOAD_BYTES = 60 * 1024;
 const RRWEB_FULL_SNAPSHOT_EVENT_TYPE = 2;
+/** Cross-tab channel name used by the duplicated-tab claim guard. */
+const SESSION_REPLAY_BROADCAST_CHANNEL_NAME = "agent-native-session-replay";
+/** How long a resuming tab waits for a "someone else already owns this
+ * replayId" reply before proceeding to record with the resumed id. */
+const SESSION_REPLAY_CLAIM_TIMEOUT_MS = 150;
 
 /** rrweb custom-event tag for captured console/window-error entries. */
 export const SESSION_REPLAY_CONSOLE_EVENT_TAG = "agent-native.console";
@@ -354,27 +410,64 @@ function getState(): SessionReplayState {
       restoreCaptures: null,
       options: null,
       lastAuthenticatedProperties: null,
+      resourceNodes: new Map(),
+      automaticConflictRestartAttempted: false,
+      broadcastChannel: null,
     };
   }
-  return g[SESSION_REPLAY_STATE_KEY]!;
+  const state = g[SESSION_REPLAY_STATE_KEY]!;
+  // Keep Vite HMR safe when an older recorder state survives a module reload.
+  state.resourceNodes ??= new Map();
+  return state;
 }
 
-function safeStorageGet(key: string): string | null {
+// The replay session record (replayId + sequence counter) lives in
+// `sessionStorage`, not `localStorage`: `localStorage` is shared by every
+// open tab of the origin, which would hand every tab the same `replayId` and
+// the same sequence counter. See the guard comment above
+// `getOrCreateReplaySession` for the corruption that causes.
+function safeSessionStorageGet(key: string): string | null {
   try {
-    return window.localStorage.getItem(key);
+    return window.sessionStorage.getItem(key);
   } catch {
     return null;
   }
 }
 
-function safeStorageSet(key: string, value: string): void {
+function safeSessionStorageSet(key: string, value: string): void {
+  try {
+    window.sessionStorage.setItem(key, value);
+  } catch {
+    // private browsing / storage disabled -- replay still works for this page
+  }
+}
+
+function safeSessionStorageRemove(key: string): void {
   try {
-    window.localStorage.setItem(key, value);
+    window.sessionStorage.removeItem(key);
   } catch {
     // private browsing / storage disabled -- replay still works for this page
   }
 }
 
+let legacyLocalStorageReplaySessionCleared = false;
+
+/**
+ * Best-effort, one-time removal of the pre-fix replay session record that
+ * used to live in `localStorage`. Never read from it -- adopting its
+ * `replayId` would recreate the exact shared-identity bug this file now
+ * avoids by using `sessionStorage` instead.
+ */
+function clearLegacyLocalStorageReplaySession(): void {
+  if (legacyLocalStorageReplaySessionCleared) return;
+  legacyLocalStorageReplaySessionCleared = true;
+  try {
+    window.localStorage.removeItem(SESSION_REPLAY_ID_STORAGE_KEY);
+  } catch {
+    // best-effort only -- a stray legacy record is harmless once ignored
+  }
+}
+
 function generateReplayId(): string {
   try {
     if (
@@ -390,7 +483,7 @@ function generateReplayId(): string {
 }
 
 function readStoredReplaySession(): StoredReplaySession | null {
-  const raw = safeStorageGet(SESSION_REPLAY_ID_STORAGE_KEY);
+  const raw = safeSessionStorageGet(SESSION_REPLAY_ID_STORAGE_KEY);
   if (!raw) return null;
   try {
     const parsed = JSON.parse(raw) as StoredReplaySession;
@@ -402,14 +495,47 @@ function readStoredReplaySession(): StoredReplaySession | null {
 }
 
 function writeStoredReplaySession(value: StoredReplaySession): void {
-  safeStorageSet(SESSION_REPLAY_ID_STORAGE_KEY, JSON.stringify(value));
+  safeSessionStorageSet(SESSION_REPLAY_ID_STORAGE_KEY, JSON.stringify(value));
 }
 
+function removeStoredReplaySession(replayId: string): void {
+  if (readStoredReplaySession()?.replayId !== replayId) return;
+  safeSessionStorageRemove(SESSION_REPLAY_ID_STORAGE_KEY);
+}
+
+/**
+ * Per-tab replay identity is deliberate -- do not "fix" this by reading or
+ * writing the session record through `localStorage` again.
+ *
+ * `sessionStorage` is scoped to a single tab (and survives reloads/
+ * navigations within that tab, which is exactly the lifetime a recording
+ * needs). `localStorage` is shared by every open tab of the origin. If this
+ * record lived there, two tabs open to the same app would read/write the
+ * *same* `replayId` and the *same* sequence counter, so rrweb in each tab
+ * would record independently but upload chunks under one shared identity.
+ * The two interleaved DOM mutation streams get merged into a single
+ * recording server-side: mutations reference the other tab's node ids
+ * (broken CSS), the viewport/meta events reflect whichever tab resized last
+ * (wrong or ultra-wide viewport), and lost mousemove batches from the
+ * "other" tab's chunks read as a frozen cursor or a fake inactivity gap. A
+ * chunk-sequence collision with a different checksum gets rejected
+ * server-side (409) rather than merged, so one tab's batches are silently
+ * dropped -- there is no way to reconstruct or repair this at playback time.
+ * Keep this per-tab. A tab *duplicated* mid-session still shares a
+ * `sessionStorage` snapshot, which is what the `BroadcastChannel` claim
+ * check in `startSessionReplayRecorder` guards against.
+ */
 function getOrCreateReplaySession(sessionId: string): {
   replayId: string;
   startedAtMs: number;
   sequence: number;
+  /** True when resuming a session found in this tab's `sessionStorage`
+   * (e.g. a reload), as opposed to minting a brand-new id. Only the resumed
+   * case needs the duplicated-tab claim check -- a fresh id can never
+   * collide with anything already recording. */
+  resumed: boolean;
 } {
+  clearLegacyLocalStorageReplaySession();
   const parsed = readStoredReplaySession();
   if (parsed?.sessionId === sessionId && parsed.replayId) {
     const startedAtMs =
@@ -424,12 +550,127 @@ function getOrCreateReplaySession(sessionId: string): {
       parsed.sequence >= 0
         ? Math.floor(parsed.sequence)
         : 0;
-    return { replayId: parsed.replayId, startedAtMs, sequence };
+    return { replayId: parsed.replayId, startedAtMs, sequence, resumed: true };
   }
   const replayId = generateReplayId();
   const startedAtMs = Date.now();
   writeStoredReplaySession({ sessionId, replayId, startedAtMs, sequence: 0 });
-  return { replayId, startedAtMs, sequence: 0 };
+  return { replayId, startedAtMs, sequence: 0, resumed: false };
+}
+
+/**
+ * Open the cross-tab claim channel used to detect a *duplicated* tab (a
+ * browser "duplicate tab" or same-origin `window.open` copies
+ * `sessionStorage`, so two tabs can legitimately start with the same
+ * resumed `replayId`). Returns `null` when `BroadcastChannel` is
+ * unavailable -- callers must treat that as "skip the guard", never as an
+ * error.
+ */
+function openReplayBroadcastChannel(): BroadcastChannel | null {
+  if (typeof BroadcastChannel === "undefined") return null;
+  try {
+    return new BroadcastChannel(SESSION_REPLAY_BROADCAST_CHANNEL_NAME);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Wires up the duplicated-tab claim channel for one recorder lifetime.
+ * `respond` keeps listening for the whole life of the channel (any tab may
+ * later claim the `replayId` this tab is actively recording); `probeClaim`
+ * is used once, only when resuming a stored session, to ask "is anyone else
+ * already recording this id?" and wait up to
+ * `SESSION_REPLAY_CLAIM_TIMEOUT_MS` for a reply.
+ */
+function createReplayClaimChannel(
+  state: SessionReplayState,
+  instanceNonce: string,
+): {
+  channel: BroadcastChannel | null;
+  probeClaim: (replayId: string) => Promise<boolean>;
+} {
+  const channel = openReplayBroadcastChannel();
+  if (!channel) {
+    return { channel: null, probeClaim: async () => false };
+  }
+  let pending: {
+    replayId: string;
+    resolve: (taken: boolean) => void;
+    timer: number;
+  } | null = null;
+  channel.onmessage = (event: MessageEvent) => {
+    const data = event?.data as ReplayBroadcastMessage | undefined | null;
+    if (!data || typeof data !== "object") return;
+    if (data.type === "an-replay-claim") {
+      if (data.instanceNonce === instanceNonce) return;
+      const ownsReplayId = state.active && state.replayId === data.replayId;
+      const winsSimultaneousClaim =
+        pending?.replayId === data.replayId &&
+        instanceNonce.localeCompare(data.instanceNonce) < 0;
+      if (!ownsReplayId && !winsSimultaneousClaim) {
+        // If both duplicated tabs start simultaneously, deterministically
+        // yield to the lower nonce rather than letting both probes time out
+        // and record under the copied replay id.
+        if (
+          pending?.replayId === data.replayId &&
+          data.instanceNonce.localeCompare(instanceNonce) < 0
+        ) {
+          window.clearTimeout(pending.timer);
+          const resolve = pending.resolve;
+          pending = null;
+          resolve(true);
+        }
+        return;
+      }
+      try {
+        const reply: ReplayClaimTakenMessage = {
+          type: "an-replay-claim-taken",
+          replayId: data.replayId,
+          claimantNonce: data.instanceNonce,
+        };
+        channel.postMessage(reply);
+      } catch {
+        // best-effort -- a lost reply just means the duplicate tab resumes
+        // recording under the shared id; later 409s still protect the
+        // stream from getting corrupted merges.
+      }
+      return;
+    }
+    if (data.type === "an-replay-claim-taken") {
+      if (
+        pending &&
+        data.replayId === pending.replayId &&
+        (!data.claimantNonce || data.claimantNonce === instanceNonce)
+      ) {
+        window.clearTimeout(pending.timer);
+        const resolve = pending.resolve;
+        pending = null;
+        resolve(true);
+      }
+    }
+  };
+  const probeClaim = (replayId: string): Promise<boolean> =>
+    new Promise((resolve) => {
+      const timer = window.setTimeout(() => {
+        pending = null;
+        resolve(false);
+      }, SESSION_REPLAY_CLAIM_TIMEOUT_MS);
+      pending = { replayId, resolve, timer };
+      try {
+        const claim: ReplayClaimMessage = {
+          type: "an-replay-claim",
+          replayId,
+          instanceNonce,
+        };
+        channel.postMessage(claim);
+      } catch {
+        window.clearTimeout(timer);
+        pending = null;
+        resolve(false);
+      }
+    });
+  return { channel, probeClaim };
 }
 
 function persistReplaySequence(
@@ -658,6 +899,7 @@ function normalizeOptions(
       options.network,
       DEFAULT_MAX_NETWORK_EVENTS,
     ),
+    onUploadRejected: options.onUploadRejected,
     extraProperties: options.extraProperties,
     shouldStart: options.shouldStart,
   };
@@ -732,8 +974,159 @@ function scrubReplayValue(
  * the scrub into the single serialization pass avoids a separate deep-clone of
  * every emitted event (FullSnapshots are large DOM trees) on the hot path.
  */
-function scrubReplayReplacer(key: string, value: unknown): unknown {
-  return typeof value === "string" ? scrubStringValue(key, value) : value;
+const REPLAY_RESOURCE_LINK_RELS = new Set([
+  "stylesheet",
+  "icon",
+  "apple-touch-icon",
+  "mask-icon",
+]);
+const REPLAY_RESOURCE_PRELOAD_TYPES = new Set([
+  "style",
+  "font",
+  "image",
+  "audio",
+  "video",
+  "track",
+]);
+const REPLAY_RESOURCE_TAGS = new Set([
+  "img",
+  "source",
+  "video",
+  "audio",
+  "track",
+  "input",
+  "link",
+]);
+const NO_REPLAY_RESOURCE_ATTRIBUTES = new Set<string>();
+const REPLAY_SRC_ATTRIBUTES = new Set(["src"]);
+const REPLAY_SRCSET_ATTRIBUTES = new Set(["src", "srcset"]);
+const REPLAY_VIDEO_ATTRIBUTES = new Set(["src", "poster"]);
+const REPLAY_HREF_ATTRIBUTES = new Set(["href"]);
+
+function replayAttributeString(
+  attributes: Record<string, unknown>,
+  key: string,
+): string {
+  return typeof attributes[key] === "string"
+    ? attributes[key].toLowerCase()
+    : "";
+}
+
+function updateReplayResourceNode(
+  current: ReplayResourceNode,
+  attributes: Record<string, unknown>,
+): ReplayResourceNode {
+  return {
+    tagName: current.tagName,
+    rel: Object.hasOwn(attributes, "rel")
+      ? replayAttributeString(attributes, "rel")
+      : current.rel,
+    as: Object.hasOwn(attributes, "as")
+      ? replayAttributeString(attributes, "as")
+      : current.as,
+    type: Object.hasOwn(attributes, "type")
+      ? replayAttributeString(attributes, "type")
+      : current.type,
+  };
+}
+
+function replayPreservedResourceAttributes(
+  node: ReplayResourceNode,
+): ReadonlySet<string> {
+  switch (node.tagName) {
+    case "img":
+    case "source":
+      return REPLAY_SRCSET_ATTRIBUTES;
+    case "video":
+      return REPLAY_VIDEO_ATTRIBUTES;
+    case "audio":
+    case "track":
+      return REPLAY_SRC_ATTRIBUTES;
+    case "input":
+      return node.type === "image"
+        ? REPLAY_SRC_ATTRIBUTES
+        : NO_REPLAY_RESOURCE_ATTRIBUTES;
+    case "link": {
+      const rels = node.rel.split(/\s+/);
+      const isLoadBearingResource =
+        rels.some((rel) => REPLAY_RESOURCE_LINK_RELS.has(rel)) ||
+        (rels.includes("preload") &&
+          REPLAY_RESOURCE_PRELOAD_TYPES.has(node.as));
+      return isLoadBearingResource
+        ? REPLAY_HREF_ATTRIBUTES
+        : NO_REPLAY_RESOURCE_ATTRIBUTES;
+    }
+    default:
+      return NO_REPLAY_RESOURCE_ATTRIBUTES;
+  }
+}
+
+/**
+ * Build a path-aware replay serializer without cloning the rrweb event.
+ *
+ * Privacy still wins for Meta/navigation URLs, executable/embed URLs, anchor
+ * hrefs, and custom console/network diagnostics. The narrow exception is
+ * load-bearing stylesheet, font, image, and media attributes: changing those
+ * signed URLs makes rrweb rebuild a page that never existed. JSON.stringify
+ * calls a replacer for an `attributes` object before its children, so the
+ * WeakMap lets the child callback recognize only that bag.
+ */
+function createReplayScrubReplacer(
+  resourceNodes: Map<number, ReplayResourceNode>,
+): (this: unknown, key: string, value: unknown) => unknown {
+  const preservedAttributes = new WeakMap<object, ReadonlySet<string>>();
+
+  return function replayScrubReplacer(
+    this: unknown,
+    key: string,
+    value: unknown,
+  ): unknown {
+    if (key === "attributes" && value && typeof value === "object") {
+      const attributes = value as Record<string, unknown>;
+      const holder =
+        this && typeof this === "object"
+          ? (this as Record<string, unknown>)
+          : undefined;
+      const tagName =
+        typeof holder?.tagName === "string" ? holder.tagName.toLowerCase() : "";
+      const nodeId =
+        typeof holder?.id === "number" && Number.isFinite(holder.id)
+          ? holder.id
+          : undefined;
+      let resourceNode: ReplayResourceNode | undefined;
+      if (tagName && REPLAY_RESOURCE_TAGS.has(tagName)) {
+        resourceNode = updateReplayResourceNode(
+          { tagName, rel: "", as: "", type: "" },
+          attributes,
+        );
+      } else if (nodeId !== undefined && !tagName) {
+        const current = resourceNodes.get(nodeId);
+        if (current) {
+          resourceNode = updateReplayResourceNode(current, attributes);
+        }
+      }
+      if (nodeId !== undefined && resourceNode) {
+        resourceNodes.set(nodeId, resourceNode);
+      }
+
+      const resourceKeys = resourceNode
+        ? replayPreservedResourceAttributes(resourceNode)
+        : NO_REPLAY_RESOURCE_ATTRIBUTES;
+
+      if (resourceKeys.size > 0) preservedAttributes.set(value, resourceKeys);
+      return value;
+    }
+
+    if (
+      typeof value === "string" &&
+      this &&
+      typeof this === "object" &&
+      preservedAttributes.get(this)?.has(key.toLowerCase())
+    ) {
+      return value;
+    }
+    return typeof value === "string" ? scrubStringValue(key, value) : value;
+  };
 }
 
 /**
@@ -741,9 +1134,13 @@ function scrubReplayReplacer(key: string, value: unknown): unknown {
  * directly on the queue and reused verbatim at flush, so each event is
  * stringified exactly once (was: deep-clone + size-stringify + flush-stringify).
  */
-function serializeReplayEvent(event: ReplayEvent): string {
+function serializeReplayEvent(
+  event: ReplayEvent,
+  resourceNodes: Map<number, ReplayResourceNode>,
+): string {
   try {
-    return JSON.stringify(event, scrubReplayReplacer);
+    if (event.type === 2) resourceNodes.clear();
+    return JSON.stringify(event, createReplayScrubReplacer(resourceNodes));
   } catch {
     return "";
   }
@@ -766,7 +1163,7 @@ function enqueueReplayEvent(
   event: ReplayEvent,
 ): void {
   if (!state.options) return;
-  const serialized = serializeReplayEvent(event);
+  const serialized = serializeReplayEvent(event, state.resourceNodes);
   if (!serialized) return;
   const estimatedBytes = serialized.length;
   if (
@@ -977,6 +1374,27 @@ function canUseReplayKeepalive(body: BodyInit): boolean {
   return replayUploadBodyBytes(body) <= MAX_KEEPALIVE_REPLAY_UPLOAD_BYTES;
 }
 
+/** Thrown by `sendReplayUpload` on a non-ok HTTP response, carrying the
+ * status so `flushSessionReplay` can tell a permanent client rejection
+ * (e.g. a 409 checksum conflict, which can never succeed on retry) apart
+ * from a transient failure worth retrying. */
+class ReplayUploadHttpError extends Error {
+  readonly status: number;
+  constructor(status: number) {
+    super(`Session replay upload failed with HTTP ${status}`);
+    this.name = "ReplayUploadHttpError";
+    this.status = status;
+  }
+}
+
+/** 4xx statuses where retrying the exact same batch can never succeed --
+ * e.g. a 409 chunk-sequence/checksum conflict, or a 400 the server will
+ * reject again. 408 (timeout) and 429 (rate limit) are excluded because a
+ * later retry can plausibly succeed. */
+function isDefinitiveReplayUploadClientError(status: number): boolean {
+  return status >= 400 && status < 500 && status !== 408 && status !== 429;
+}
+
 async function sendReplayUpload(
   options: NormalizedSessionReplayOptions,
   body: string,
@@ -992,9 +1410,7 @@ async function sendReplayUpload(
       headers: { "Content-Type": "text/plain;charset=UTF-8" },
     });
     if (!response.ok) {
-      throw new Error(
-        `Session replay upload failed with HTTP ${response.status}`,
-      );
+      throw new ReplayUploadHttpError(response.status);
     }
     return;
   }
@@ -1012,9 +1428,7 @@ async function sendReplayUpload(
     },
   });
   if (!response.ok) {
-    throw new Error(
-      `Session replay upload failed with HTTP ${response.status}`,
-    );
+    throw new ReplayUploadHttpError(response.status);
   }
 }
 
@@ -1120,6 +1534,7 @@ export async function flushSessionReplay(reason = "manual"): Promise<void> {
   state.flushing = true;
   let uploaded = false;
   let reservedSequence = false;
+  let definitiveClientErrorStatus: number | null = null;
   try {
     await sendReplayUpload(state.options, payload.body, {
       beforeKeepaliveUpload: shouldReserveSequenceBeforeKeepalive(reason)
@@ -1130,16 +1545,44 @@ export async function flushSessionReplay(reason = "manual"): Promise<void> {
         : undefined,
     });
     if (!reservedSequence) advanceReplaySequence(state, payload);
+    state.automaticConflictRestartAttempted = false;
     uploaded = true;
   } catch (error) {
     if (reservedSequence) rollbackReplaySequenceReservation(state, payload);
-    restoreReplayEvents(state, events);
+    // A definitive 4xx (e.g. a 409 chunk-sequence/checksum conflict) can
+    // never succeed by retrying the exact same batch -- requeuing it would
+    // just spin forever, blocking every later batch behind it (flushes are
+    // FIFO via `retryBatches`). Drop it and move on instead.
+    const isDefinitiveClientError =
+      error instanceof ReplayUploadHttpError &&
+      isDefinitiveReplayUploadClientError(error.status);
+    if (isDefinitiveClientError) {
+      // Continuing after a checksum/sequence conflict would reuse the same
+      // rejected sequence forever. More importantly, advancing past it would
+      // append mutations to a replay whose DOM stream may belong to another
+      // tab. End this recorder and clear its persisted identity so the next
+      // start creates a clean replay instead of producing corrupt playback.
+      state.queue = [];
+      state.queuedBytes = 0;
+      state.retryBatches = [];
+      removeStoredReplaySession(payload.replayId);
+      definitiveClientErrorStatus = error.status;
+    } else {
+      restoreReplayEvents(state, events);
+    }
     // Guard the recorder's own warning so console capture never records it
     // (a captured warning would enqueue an event and retrigger a flush).
     const previousInternal = replayCaptureInternal;
     replayCaptureInternal = true;
     try {
-      console.warn("[session-replay] upload failed", error);
+      if (isDefinitiveClientError) {
+        console.warn(
+          `[session-replay] dropping upload (HTTP ${(error as ReplayUploadHttpError).status})`,
+          error,
+        );
+      } else {
+        console.warn("[session-replay] upload failed", error);
+      }
     } finally {
       replayCaptureInternal = previousInternal;
     }
@@ -1149,6 +1592,101 @@ export async function flushSessionReplay(reason = "manual"): Promise<void> {
   if (uploaded && hasPendingReplayBatch(state)) {
     flushQueuedReplayIfNeeded(state);
   }
+  if (
+    definitiveClientErrorStatus !== null &&
+    state.replayId === payload.replayId
+  ) {
+    const rejectedOptions = state.options;
+    const shouldRestartAfterConflict =
+      definitiveClientErrorStatus === 409 &&
+      state.active &&
+      !isFinalFlushReason(reason) &&
+      !state.automaticConflictRestartAttempted;
+    if (shouldRestartAfterConflict) {
+      state.automaticConflictRestartAttempted = true;
+    }
+
+    await stopSessionReplay("upload-rejected");
+
+    // A 409 means this replay identity can no longer append safely (usually a
+    // duplicated tab that inherited sessionStorage, or an old shared identity
+    // still open during rollout). Do not leave a long-lived SPA tab silently
+    // unrecorded until its next page load: restart rrweb under a fresh per-tab
+    // id so it emits a new Meta + FullSnapshot stream. Limit this to one retry
+    // until an upload succeeds; other definitive 4xx responses usually reflect
+    // configuration/input errors and must not create a restart loop.
+    let restartResult: SessionReplayStartResult | null = null;
+    if (shouldRestartAfterConflict && rejectedOptions) {
+      restartResult = await restartSessionReplayAfterConflict(
+        state,
+        rejectedOptions,
+        payload.sessionId,
+      );
+    }
+
+    // Rare recovery-path telemetry lets Analytics owners quantify conflicts
+    // without recording the rejected replay id, URL, or any captured content.
+    try {
+      rejectedOptions?.onUploadRejected?.({
+        status: definitiveClientErrorStatus,
+        restartAttempted: shouldRestartAfterConflict,
+        restartSucceeded: restartResult?.started === true,
+        ...(restartResult?.reason
+          ? { restartReason: restartResult.reason }
+          : {}),
+      });
+    } catch {
+      // best-effort telemetry must never interfere with recording recovery
+    }
+  }
+}
+
+/**
+ * Restart a recorder whose replay identity was rejected without routing the
+ * already-normalized options back through the public start API.
+ *
+ * The original recording already passed whole-session sampling. Re-entering
+ * `startSessionReplay` here would ask `getOrCreateAnalyticsSessionId` again;
+ * if the analytics session rotated while the upload was in flight, recovery
+ * could be sampled out and leave a long-lived SPA tab silently unrecorded.
+ * Keeping the original session id and accepted sampling decision also lets us
+ * reuse the exact normalized console/network capture caps instead of relying
+ * on internal option shapes continuing to round-trip through the public API.
+ */
+async function restartSessionReplayAfterConflict(
+  state: SessionReplayState,
+  options: NormalizedSessionReplayOptions,
+  sessionId: string,
+): Promise<SessionReplayStartResult> {
+  if (options.shouldStart && !options.shouldStart()) {
+    return { started: false, reason: "disabled", sessionId, sampled: true };
+  }
+
+  const initialProperties = replayExtraProperties(options);
+  if (options.requireSignedInUser && !replayUserEmail(initialProperties)) {
+    return {
+      started: false,
+      reason: "missing-user-id",
+      sessionId,
+      sampled: true,
+    };
+  }
+  if (!isUrlRecordable(window.location.href, options)) {
+    return {
+      started: false,
+      reason: "url-blocked",
+      sessionId,
+      sampled: true,
+    };
+  }
+
+  return startSessionReplayRecorder(
+    state,
+    options,
+    sessionId,
+    true,
+    initialProperties,
+  );
 }
 
 function installUrlMonitor(state: SessionReplayState): void {
@@ -2043,7 +2581,34 @@ async function startSessionReplayRecorder(
     return { started: false, reason: "disabled", sessionId, sampled };
   }
 
-  const replaySession = getOrCreateReplaySession(sessionId);
+  let replaySession = getOrCreateReplaySession(sessionId);
+  const instanceNonce = generateReplayId();
+  const { channel: replayChannel, probeClaim } = createReplayClaimChannel(
+    state,
+    instanceNonce,
+  );
+  // Only a *resumed* id needs the duplicated-tab check -- a freshly minted
+  // id can never collide with a recorder that's already running, so this
+  // never adds startup latency for the common "new tab" case.
+  if (replaySession.resumed && replayChannel) {
+    const taken = await probeClaim(replaySession.replayId);
+    if (taken) {
+      const freshReplayId = generateReplayId();
+      const freshStartedAtMs = Date.now();
+      writeStoredReplaySession({
+        sessionId,
+        replayId: freshReplayId,
+        startedAtMs: freshStartedAtMs,
+        sequence: 0,
+      });
+      replaySession = {
+        replayId: freshReplayId,
+        startedAtMs: freshStartedAtMs,
+        sequence: 0,
+        resumed: false,
+      };
+    }
+  }
   state.options = normalized;
   state.replayId = replaySession.replayId;
   state.startedAtMs = replaySession.startedAtMs;
@@ -2051,7 +2616,9 @@ async function startSessionReplayRecorder(
   state.queue = [];
   state.queuedBytes = 0;
   state.retryBatches = [];
+  state.resourceNodes.clear();
   state.stopRecorder = null;
+  state.broadcastChannel = replayChannel;
   state.lastAuthenticatedProperties = replayUserEmail(initialProperties)
     ? { ...initialProperties }
     : null;
@@ -2096,6 +2663,12 @@ async function startSessionReplayRecorder(
       state.replayId = null;
       state.startedAtMs = null;
       state.lastAuthenticatedProperties = null;
+      try {
+        state.broadcastChannel?.close();
+      } catch {
+        // best-effort cleanup
+      }
+      state.broadcastChannel = null;
       return { started: false, reason: "record-failed", sessionId, sampled };
     }
     state.stopRecorder = stopRecorder;
@@ -2133,6 +2706,12 @@ async function startSessionReplayRecorder(
     state.replayId = null;
     state.startedAtMs = null;
     state.lastAuthenticatedProperties = null;
+    try {
+      state.broadcastChannel?.close();
+    } catch {
+      // best-effort cleanup
+    }
+    state.broadcastChannel = null;
     return { started: false, reason: "record-failed", sessionId, sampled };
   }
 }
@@ -2167,6 +2746,12 @@ export async function stopSessionReplay(reason = "manual"): Promise<void> {
   }
   state.restoreUrlMonitor?.();
   state.removeLifecycleListeners?.();
+  try {
+    state.broadcastChannel?.close();
+  } catch {
+    // best-effort cleanup
+  }
+  state.broadcastChannel = null;
   await flushSessionReplay(reason);
 }
 
@@ -2182,9 +2767,10 @@ export function isSessionReplayActive(): boolean {
 
 /**
  * The active session replay id when a recording is running, or the last one
- * persisted for this analytics session in `localStorage`. First-party error
- * capture uses this to tie each captured exception to the replay it happened
- * in, so triage can jump straight to `/sessions/<recordingId>`.
+ * persisted for this analytics session in this tab's `sessionStorage`.
+ * First-party error capture uses this to tie each captured exception to the
+ * replay it happened in, so triage can jump straight to
+ * `/sessions/<recordingId>`.
  */
 export function getSessionReplayId(): string | null {
   const state = getState();