feat(shared,clerk-js): Add better logs for pending session state

Sessions in the `pending` state are treated as signed out by the JS SDK
(`isSignedIn` returns false, `useAuth` reports the user signed out) while
remaining session tasks are completed. Previously this happened silently,
forcing developers to debug "signed in but treated as signed out" with no
console hint. iOS and Android SDKs already emit a console message in this
state via SessionStatusLogger; this brings the JS SDK to parity.

Adds `warnPendingSessionStatus` in @clerk/shared and a single call site in
`Clerk.updateClient`, gated on `session?.status === 'pending'`. Dedupes via
`logger.warnOnce` keyed by the message string (session id + task key), so a
new pending session or a task transition surface a fresh log line.

MOBILE-428

Author: chriscanin

.changeset/warn_pending_session_status.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': patch
+'@clerk/clerk-js': patch
+---
+
+Add a console warning when a session is in the `pending` state. The SDK treats pending sessions as signed out (`isSignedIn` returns `false`, `useAuth` reports signed out) while remaining session tasks are completed, which previously gave no feedback to developers. This brings the JS SDK in line with the equivalent logger on iOS and Android.

packages/clerk-js/src/core/clerk.ts

@@ -34,6 +34,7 @@ import {
   getTaskEndpoint,
   navigateIfTaskExists,
   warnMissingPendingTaskHandlers,
+  warnPendingSessionStatus,
 } from '@clerk/shared/internal/clerk-js/sessionTasks';
 import { warnings } from '@clerk/shared/internal/clerk-js/warnings';
 import { windowNavigate } from '@clerk/shared/internal/clerk-js/windowNavigate';
@@ -2892,6 +2893,10 @@ export class Clerk implements ClerkInterface {
       eventBus.emit(events.TokenUpdate, { token: this.session?.lastActiveToken });
     }
 
+    if (this.session?.status === 'pending') {
+      warnPendingSessionStatus(this.session);
+    }
+
     if (!options?.__internal_dangerouslySkipEmit) {
       this.#emit();
     }

packages/shared/src/internal/clerk-js/__tests__/sessionTasks.test.ts

@@ -0,0 +1,77 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { warnPendingSessionStatus } from '../sessionTasks';
+
+describe('warnPendingSessionStatus', () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  it('does not warn when status is active', () => {
+    warnPendingSessionStatus({ id: 'sess_active', status: 'active', currentTask: undefined as any });
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it('warns when status is pending and includes the session id', () => {
+    warnPendingSessionStatus({
+      id: 'sess_pending_1',
+      status: 'pending',
+      currentTask: { key: 'choose-organization' },
+    });
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0][0]).toContain('sess_pending_1');
+    expect(warnSpy.mock.calls[0][0]).toContain('pending');
+  });
+
+  it('includes the current task key in the message', () => {
+    warnPendingSessionStatus({
+      id: 'sess_pending_2',
+      status: 'pending',
+      currentTask: { key: 'choose-organization' },
+    });
+    expect(warnSpy.mock.calls[0][0]).toContain('choose-organization');
+  });
+
+  it('omits the tasks suffix when no current task is present', () => {
+    warnPendingSessionStatus({
+      id: 'sess_pending_3',
+      status: 'pending',
+      currentTask: undefined as any,
+    });
+    expect(warnSpy.mock.calls[0][0]).not.toContain('Remaining session tasks');
+  });
+
+  it('dedupes identical messages across calls', () => {
+    warnPendingSessionStatus({
+      id: 'sess_pending_dedupe',
+      status: 'pending',
+      currentTask: { key: 'choose-organization' },
+    });
+    warnPendingSessionStatus({
+      id: 'sess_pending_dedupe',
+      status: 'pending',
+      currentTask: { key: 'choose-organization' },
+    });
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('logs again when the task key changes within the same session', () => {
+    warnPendingSessionStatus({
+      id: 'sess_pending_task_change',
+      status: 'pending',
+      currentTask: { key: 'choose-organization' },
+    });
+    warnPendingSessionStatus({
+      id: 'sess_pending_task_change',
+      status: 'pending',
+      currentTask: { key: 'setup-mfa' },
+    });
+    expect(warnSpy).toHaveBeenCalledTimes(2);
+  });
+});

packages/shared/src/internal/clerk-js/sessionTasks.ts

@@ -69,3 +69,27 @@ export function warnMissingPendingTaskHandlers(options: Record<string, unknown>)
     `Clerk: Session has pending tasks but no handling is configured. To handle pending tasks, provide either "taskUrls" for navigation to custom URLs or "navigate" for programmatic navigation. Without these options, users may get stuck on incomplete flows.`,
   );
 }
+
+/**
+ * Warns when a session is in the `pending` state. Mirrors the behavior of
+ * `SessionStatusLogger` on iOS / Android so developers across platforms get the
+ * same heads-up that the SDK is treating their signed-in user as signed out
+ * until the remaining session task is resolved.
+ *
+ * Dedupe is per-session/per-task: a new pending session or a task transition
+ * within the same session both surface a fresh log line.
+ */
+export function warnPendingSessionStatus(session: Pick<SessionResource, 'id' | 'status' | 'currentTask'>) {
+  if (session.status !== 'pending') {
+    return;
+  }
+
+  const taskKey = session.currentTask?.key;
+  const tasksDescription = taskKey ? ` Remaining session tasks: [${taskKey}].` : '';
+
+  logger.warnOnce(
+    `Clerk: Session ${session.id} is currently pending. ` +
+      `\`isSignedIn\` will return false and \`useAuth\` will report the user as signed out ` +
+      `until the remaining session tasks are completed.${tasksDescription}`,
+  );
+}