From 07331df68ba2e50b8a4ddcaca6b10afba45908b6 Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 04:41:12 +0530
Subject: [PATCH 01/29] feat(connect): add account-backed referral points

---
 apps/marketing/src/pages/privacy-policy.astro |   18 +-
 apps/mobile/src/Stack.tsx                     |    8 +
 .../src/features/cloud/managedRelayState.ts   |   58 +
 .../settings/SettingsReferralsRouteScreen.tsx |  216 ++
 .../features/settings/SettingsRouteScreen.tsx |    8 +
 .../components/settings-sheet-targets.ts      |    3 +-
 apps/web/src/cloud/managedRelayState.ts       |   52 +
 apps/web/src/cloud/referralLinks.test.ts      |   11 +
 apps/web/src/cloud/referralLinks.ts           |   15 +
 .../clerk/ReferralsUserProfilePage.tsx        |  194 ++
 .../clerk/T3ConnectSidebarSignIn.tsx          |   10 +-
 .../cloud/ReferralClaimCoordinator.tsx        |  115 ++
 apps/web/src/routes/__root.tsx                |    2 +
 docs/README.md                                |    1 +
 docs/internals/t3-connect.md                  |   16 +
 docs/user/referrals.md                        |   17 +
 infra/relay/README.md                         |    2 +
 .../migration.sql                             |   23 +
 .../snapshot.json                             | 1812 +++++++++++++++++
 infra/relay/src/http/Api.ts                   |   18 +
 infra/relay/src/persistence/schema.ts         |   37 +
 .../src/referrals/ReferralProgram.test.ts     |  223 ++
 infra/relay/src/referrals/ReferralProgram.ts  |  340 ++++
 infra/relay/src/worker.ts                     |    2 +
 .../src/connection/resolver.test.ts           |    2 +
 .../src/relay/discovery.test.ts               |    4 +
 .../client-runtime/src/relay/managedRelay.ts  |   42 +
 .../src/relay/managedRelayState.test.ts       |   47 +
 .../src/relay/managedRelayState.ts            |   46 +-
 packages/contracts/src/relay.ts               |   43 +
 packages/shared/package.json                  |    4 +
 packages/shared/src/referral.test.ts          |   16 +
 packages/shared/src/referral.ts               |   13 +
 33 files changed, 3409 insertions(+), 9 deletions(-)
 create mode 100644 apps/mobile/src/features/settings/SettingsReferralsRouteScreen.tsx
 create mode 100644 apps/web/src/cloud/referralLinks.test.ts
 create mode 100644 apps/web/src/cloud/referralLinks.ts
 create mode 100644 apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
 create mode 100644 apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
 create mode 100644 docs/user/referrals.md
 create mode 100644 infra/relay/migrations/postgres/20260826230249_complete_logan/migration.sql
 create mode 100644 infra/relay/migrations/postgres/20260826230249_complete_logan/snapshot.json
 create mode 100644 infra/relay/src/referrals/ReferralProgram.test.ts
 create mode 100644 infra/relay/src/referrals/ReferralProgram.ts
 create mode 100644 packages/shared/src/referral.test.ts
 create mode 100644 packages/shared/src/referral.ts

diff --git a/apps/marketing/src/pages/privacy-policy.astro b/apps/marketing/src/pages/privacy-policy.astro
index b85bc0b12b44..697f820ec2b7 100644
--- a/apps/marketing/src/pages/privacy-policy.astro
+++ b/apps/marketing/src/pages/privacy-policy.astro
@@ -75,6 +75,11 @@ const sections = [
               credential hashes, connection status, app and operating-system versions, and
               notification preferences.
             </li>
+            <li>
+              <strong>Referral information.</strong> If you use the referral program, we process
+              referral codes, account-to-account referral attribution, qualification status, and
+              point-ledger entries.
+            </li>
             <li>
               <strong>Agent activity and notifications.</strong> If you enable notifications or Live
               Activities, we process push tokens and limited activity information needed to provide
@@ -151,6 +156,7 @@ const sections = [
           <ul>
             <li>To establish and verify your identity and authenticate your account;</li>
             <li>To link and protect devices and environments and deliver optional notifications;</li>
+            <li>To operate the referral program and maintain account point balances;</li>
             <li>To process and fulfill requests you make through the Services;</li>
             <li>To provide customer service and respond to support requests and feedback;</li>
             <li>To communicate with you about the Services and your relationship with us;</li>
@@ -339,12 +345,12 @@ const sections = [
 
           <h3>Retention and Deletion</h3>
           <p>
-            We retain account, environment-link, device-registration, notification, and security
-            information while your account or the relevant feature is active and for as long as
-            reasonably necessary to provide the Services, protect them from abuse, comply with law,
-            and resolve disputes. Operational diagnostic traces are configured to expire after 30
-            days. Some records may remain longer in backups or where retention is required for
-            security, fraud prevention, or legal compliance.
+            We retain account, environment-link, device-registration, notification, referral, and
+            security information while your account or the relevant feature is active and for as
+            long as reasonably necessary to provide the Services, protect them from abuse, comply
+            with law, and resolve disputes. Operational diagnostic traces are configured to expire
+            after 30 days. Some records may remain longer in backups or where retention is required
+            for security, fraud prevention, or legal compliance.
           </p>
           <p>
             To request deletion of your T3 account and associated T3 Connect data, email{" "}<a
diff --git a/apps/mobile/src/Stack.tsx b/apps/mobile/src/Stack.tsx
index 7cffbf62b0d7..7a3b8bcc6f04 100644
--- a/apps/mobile/src/Stack.tsx
+++ b/apps/mobile/src/Stack.tsx
@@ -56,6 +56,7 @@ import { SettingsAuthRouteScreen } from "./features/settings/SettingsAuthRouteSc
 import { SettingsEnvironmentsRouteScreen } from "./features/settings/SettingsEnvironmentsRouteScreen";
 import { SettingsLegalRouteScreen } from "./features/settings/SettingsLegalRouteScreen";
 import { SettingsProjectGroupingRouteScreen } from "./features/settings/SettingsProjectGroupingRouteScreen";
+import { SettingsReferralsRouteScreen } from "./features/settings/SettingsReferralsRouteScreen";
 import { UsageRouteScreen } from "./features/usage/UsageRouteScreen";
 import { SettingsRouteScreen } from "./features/settings/SettingsRouteScreen";
 import { ShowcaseCaptureCoordinator } from "./features/showcase/ShowcaseCaptureCoordinator";
@@ -198,6 +199,13 @@ const SettingsContentStack = createNativeStackNavigator({
         title: "Usage",
       },
     }),
+    SettingsReferrals: createNativeStackScreen({
+      screen: SettingsReferralsRouteScreen,
+      linking: "referrals",
+      options: {
+        title: "Referrals",
+      },
+    }),
   },
 });
 
diff --git a/apps/mobile/src/features/cloud/managedRelayState.ts b/apps/mobile/src/features/cloud/managedRelayState.ts
index eec1e3410e6e..b017893a52eb 100644
--- a/apps/mobile/src/features/cloud/managedRelayState.ts
+++ b/apps/mobile/src/features/cloud/managedRelayState.ts
@@ -1,5 +1,6 @@
 import { useAtomValue } from "@effect/atom-react";
 import {
+  claimManagedRelayReferral,
   createManagedRelayQueryManager,
   managedRelaySessionAtom,
   readManagedRelaySnapshotState,
@@ -7,7 +8,12 @@ import {
 import type {
   RelayClientEnvironmentRecord,
   RelayEnvironmentStatusResponse,
+  RelayReferralSummary,
 } from "@t3tools/contracts/relay";
+import {
+  createAtomCommandScheduler,
+  createRuntimeCommand,
+} from "@t3tools/client-runtime/state/runtime";
 import { AsyncResult, Atom } from "effect/unstable/reactivity";
 import { useCallback, useEffect } from "react";
 
@@ -22,6 +28,18 @@ export const managedRelayQueryManager = createManagedRelayQueryManager(managedRe
     cloudDebugLog(`query:${event.operation}:${event.stage}:${event.phase}`, { ...event }),
 });
 
+const managedRelayMutationScheduler = createAtomCommandScheduler();
+
+export const claimManagedRelayReferralCommand = createRuntimeCommand(managedRelayAtomRuntime, {
+  label: "mobile:managed-relay:claim-referral",
+  scheduler: managedRelayMutationScheduler,
+  concurrency: {
+    mode: "serial",
+    key: (input: { readonly accountId: string; readonly referralCode: string }) => input.accountId,
+  },
+  execute: (input, registry) => claimManagedRelayReferral(registry, input),
+});
+
 const EMPTY_ENVIRONMENTS_ATOM = Atom.make(
   AsyncResult.success<ReadonlyArray<RelayClientEnvironmentRecord>>([]),
 ).pipe(Atom.keepAlive, Atom.withLabel("managed-relay:mobile:environments:null"));
@@ -30,6 +48,10 @@ const EMPTY_ENVIRONMENT_STATUS_ATOM = Atom.make(
   AsyncResult.initial<RelayEnvironmentStatusResponse, never>(false),
 ).pipe(Atom.keepAlive, Atom.withLabel("managed-relay:mobile:environment-status:null"));
 
+const EMPTY_REFERRAL_SUMMARY_ATOM = Atom.make(
+  AsyncResult.initial<RelayReferralSummary, never>(false),
+).pipe(Atom.keepAlive, Atom.withLabel("managed-relay:mobile:referrals:null"));
+
 export function useManagedRelayEnvironments() {
   const session = useAtomValue(managedRelaySessionAtom);
   const accountId = session?.accountId ?? null;
@@ -92,9 +114,45 @@ export function useManagedRelayEnvironmentStatus(environment: RelayClientEnviron
   };
 }
 
+export function useManagedRelayReferralSummary() {
+  const session = useAtomValue(managedRelaySessionAtom);
+  const accountId = session?.accountId ?? null;
+  const atom = accountId
+    ? managedRelayQueryManager.referralSummaryAtom(accountId)
+    : EMPTY_REFERRAL_SUMMARY_ATOM;
+  const result = useAtomValue(atom);
+  const snapshot = readManagedRelaySnapshotState(result);
+  useEffect(() => {
+    if (snapshot.error) {
+      console.error("[t3-cloud] Relay referral summary failed", {
+        message: snapshot.error,
+        traceId: snapshot.errorTraceId,
+      });
+    }
+  }, [snapshot.error, snapshot.errorTraceId]);
+  const refresh = useCallback(() => {
+    if (accountId) {
+      managedRelayQueryManager.refreshReferralSummary(appAtomRegistry, accountId);
+    }
+  }, [accountId]);
+
+  return {
+    ...snapshot,
+    accountId,
+    refresh,
+  };
+}
+
 export function refreshManagedRelayEnvironments(): void {
   const session = appAtomRegistry.get(managedRelaySessionAtom);
   if (session) {
     managedRelayQueryManager.refreshEnvironments(appAtomRegistry, session.accountId);
   }
 }
+
+export function refreshManagedRelayReferralSummary(): void {
+  const session = appAtomRegistry.get(managedRelaySessionAtom);
+  if (session) {
+    managedRelayQueryManager.refreshReferralSummary(appAtomRegistry, session.accountId);
+  }
+}
diff --git a/apps/mobile/src/features/settings/SettingsReferralsRouteScreen.tsx b/apps/mobile/src/features/settings/SettingsReferralsRouteScreen.tsx
new file mode 100644
index 000000000000..596c0b85ecfa
--- /dev/null
+++ b/apps/mobile/src/features/settings/SettingsReferralsRouteScreen.tsx
@@ -0,0 +1,216 @@
+import { useAuth } from "@clerk/expo";
+import {
+  isAtomCommandInterrupted,
+  squashAtomCommandFailure,
+} from "@t3tools/client-runtime/state/runtime";
+import type { RelayReferralClaimResult } from "@t3tools/contracts/relay";
+import { DEFAULT_HOSTED_APP_URL } from "@t3tools/shared/connectAuth";
+import { buildReferralLink, normalizeReferralCode } from "@t3tools/shared/referral";
+import { useState } from "react";
+import { ActivityIndicator, Alert, ScrollView, Share, TextInput, View } from "react-native";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+
+import { AppText as Text } from "../../components/AppText";
+import { CopyTextButton } from "../../components/CopyTextButton";
+import { useThemeColor } from "../../lib/useThemeColor";
+import { useAtomCommand } from "../../state/use-atom-command";
+import {
+  claimManagedRelayReferralCommand,
+  useManagedRelayReferralSummary,
+} from "../cloud/managedRelayState";
+import { ConnectionSheetButton } from "../connection/ConnectionSheetButton";
+
+function showClaimResult(result: RelayReferralClaimResult): void {
+  switch (result) {
+    case "claimed":
+      Alert.alert(
+        "Referral applied",
+        "Your referrer will receive 67 points after you link your first environment.",
+      );
+      return;
+    case "already_claimed":
+      Alert.alert("Referral already claimed", "This account already has a referral attached.");
+      return;
+    case "invalid_code":
+      Alert.alert("Invalid referral code", "Check the code and try again.");
+      return;
+    case "self_referral":
+      Alert.alert("Referral not applied", "You cannot use your own referral code.");
+      return;
+    case "ineligible":
+      Alert.alert(
+        "Referral not applied",
+        "Referral codes must be claimed before linking an environment.",
+      );
+  }
+}
+
+export function SettingsReferralsRouteScreen() {
+  const { isSignedIn } = useAuth({ treatPendingAsSignedOut: false });
+  const insets = useSafeAreaInsets();
+  const summaryState = useManagedRelayReferralSummary();
+  const claimReferral = useAtomCommand(claimManagedRelayReferralCommand, {
+    reportFailure: false,
+  });
+  const [referralCode, setReferralCode] = useState("");
+  const [isClaiming, setIsClaiming] = useState(false);
+  const iconColor = useThemeColor("--color-icon");
+  const iconSuccess = useThemeColor("--color-success");
+  const inputPlaceholder = useThemeColor("--color-foreground-muted");
+  const summary = summaryState.data;
+  const referralLink = summary
+    ? buildReferralLink(DEFAULT_HOSTED_APP_URL, summary.referralCode)
+    : "";
+
+  const submitReferralCode = async () => {
+    const accountId = summaryState.accountId;
+    const normalized = normalizeReferralCode(referralCode);
+    if (!accountId || !normalized || isClaiming) {
+      if (!normalized) Alert.alert("Invalid referral code", "Enter the 16-character code.");
+      return;
+    }
+
+    setIsClaiming(true);
+    const result = await claimReferral({ accountId, referralCode: normalized });
+    setIsClaiming(false);
+    if (result._tag === "Success") {
+      setReferralCode("");
+      showClaimResult(result.value.result);
+      summaryState.refresh();
+      return;
+    }
+    if (isAtomCommandInterrupted(result)) return;
+    const cause = squashAtomCommandFailure(result);
+    Alert.alert(
+      "Could not claim referral code",
+      cause instanceof Error ? cause.message : "Try again.",
+    );
+  };
+
+  if (!isSignedIn) {
+    return (
+      <View className="flex-1 items-center justify-center bg-sheet px-8">
+        <Text className="text-center text-base text-foreground-muted">
+          Sign in to your T3 account to view referral points.
+        </Text>
+      </View>
+    );
+  }
+
+  return (
+    <View collapsable={false} className="flex-1 bg-sheet">
+      <ScrollView
+        contentInsetAdjustmentBehavior="automatic"
+        showsVerticalScrollIndicator={false}
+        className="flex-1"
+        contentContainerClassName="gap-5 px-5 pt-4"
+        contentContainerStyle={{ paddingBottom: Math.max(insets.bottom, 18) + 18 }}
+      >
+        <Text className="px-1 text-sm leading-5 text-foreground-muted">
+          Earn 67 points when someone you invite links their first T3 Code environment. Points stay
+          with your T3 account on every device.
+        </Text>
+
+        {summaryState.error ? (
+          <View className="gap-3 rounded-[24px] border border-danger-border bg-card p-5">
+            <Text className="font-t3-bold text-danger-foreground">Could not load referrals</Text>
+            <Text className="text-sm text-foreground-muted">{summaryState.error}</Text>
+            <ConnectionSheetButton
+              compact
+              icon="arrow.clockwise"
+              label="Try again"
+              onPress={summaryState.refresh}
+            />
+          </View>
+        ) : summary === null ? (
+          <View className="items-center justify-center py-16">
+            <ActivityIndicator />
+          </View>
+        ) : (
+          <>
+            <View className="flex-row gap-3">
+              <View className="flex-1 rounded-[24px] bg-card p-4">
+                <Text className="text-sm text-foreground-muted">Points</Text>
+                <Text className="mt-1 text-3xl font-t3-bold text-foreground">{summary.points}</Text>
+              </View>
+              <View className="flex-1 rounded-[24px] bg-card p-4">
+                <Text className="text-sm text-foreground-muted">Referrals</Text>
+                <Text className="mt-1 text-3xl font-t3-bold text-foreground">
+                  {summary.qualifiedReferrals}
+                </Text>
+                {summary.pendingReferrals > 0 ? (
+                  <Text className="mt-1 text-xs text-foreground-muted">
+                    {summary.pendingReferrals} pending
+                  </Text>
+                ) : null}
+              </View>
+            </View>
+
+            <View className="gap-4 rounded-[24px] bg-card p-5">
+              <View className="gap-1">
+                <Text className="text-lg font-t3-bold text-foreground">Invite someone</Text>
+                <Text className="text-sm leading-5 text-foreground-muted">
+                  They must claim your code before linking their first environment.
+                </Text>
+              </View>
+              <View className="flex-row items-center gap-3 rounded-[16px] border border-input-border bg-input px-4 py-3">
+                <Text className="min-w-0 flex-1 text-sm text-foreground" numberOfLines={1}>
+                  {summary.referralCode}
+                </Text>
+                <CopyTextButton
+                  accessibilityLabel="Copy referral code"
+                  text={summary.referralCode}
+                  tintColor={iconColor}
+                  copiedTintColor={iconSuccess}
+                />
+              </View>
+              <ConnectionSheetButton
+                icon="arrow.up.right"
+                label="Share referral link"
+                tone="primary"
+                onPress={() => {
+                  void Share.share({
+                    message: `Join me on T3 Code. Claim referral code ${summary.referralCode}: ${referralLink}`,
+                    url: referralLink,
+                  });
+                }}
+              />
+            </View>
+
+            {!summary.hasClaimedReferral ? (
+              <View className="gap-4 rounded-[24px] bg-card p-5">
+                <View className="gap-1">
+                  <Text className="text-lg font-t3-bold text-foreground">
+                    Have a referral code?
+                  </Text>
+                  <Text className="text-sm leading-5 text-foreground-muted">
+                    Apply it before linking your first environment.
+                  </Text>
+                </View>
+                <TextInput
+                  autoCapitalize="characters"
+                  autoCorrect={false}
+                  editable={!isClaiming}
+                  maxLength={19}
+                  placeholder="ABCD1234EFAB5678"
+                  placeholderTextColor={inputPlaceholder}
+                  value={referralCode}
+                  onChangeText={setReferralCode}
+                  onSubmitEditing={() => void submitReferralCode()}
+                  className="rounded-[16px] border border-input-border bg-input px-4 py-3.5 text-base text-foreground"
+                />
+                <ConnectionSheetButton
+                  icon="checkmark"
+                  label={isClaiming ? "Applying..." : "Apply code"}
+                  disabled={isClaiming}
+                  tone="primary"
+                  onPress={() => void submitReferralCode()}
+                />
+              </View>
+            ) : null}
+          </>
+        )}
+      </ScrollView>
+    </View>
+  );
+}
diff --git a/apps/mobile/src/features/settings/SettingsRouteScreen.tsx b/apps/mobile/src/features/settings/SettingsRouteScreen.tsx
index b0e851b59d88..e59ce494a266 100644
--- a/apps/mobile/src/features/settings/SettingsRouteScreen.tsx
+++ b/apps/mobile/src/features/settings/SettingsRouteScreen.tsx
@@ -458,6 +458,14 @@ function ConfiguredSettingsRouteScreen() {
               value={accountLabel}
               onPress={openAccount}
             />
+            {isSignedIn ? (
+              <SettingsRow
+                icon="link"
+                label="Referrals"
+                value="67 points each"
+                target="SettingsReferrals"
+              />
+            ) : null}
           </SettingsSection>
           <Text className="px-2 text-sm text-foreground-muted">
             T3 Code works locally without signing in. Cloud features are optional.
diff --git a/apps/mobile/src/features/settings/components/settings-sheet-targets.ts b/apps/mobile/src/features/settings/components/settings-sheet-targets.ts
index 7189fdc2ebe5..2645fe46c21a 100644
--- a/apps/mobile/src/features/settings/components/settings-sheet-targets.ts
+++ b/apps/mobile/src/features/settings/components/settings-sheet-targets.ts
@@ -4,6 +4,7 @@ export type SettingsSheetTarget =
   | "SettingsAppearance"
   | "SettingsProjectGrouping"
   | "SettingsClientStorage"
-  | "SettingsUsage";
+  | "SettingsUsage"
+  | "SettingsReferrals";
 
 export type SettingsLegalDocumentTarget = "SettingsLegal";
diff --git a/apps/web/src/cloud/managedRelayState.ts b/apps/web/src/cloud/managedRelayState.ts
index 9a56bde88514..e68cc3ac4a6d 100644
--- a/apps/web/src/cloud/managedRelayState.ts
+++ b/apps/web/src/cloud/managedRelayState.ts
@@ -1,6 +1,7 @@
 import { useAtomValue } from "@effect/atom-react";
 import {
   createManagedRelayQueryManager,
+  claimManagedRelayReferral,
   deregisterManagedRelayEnvironment,
   ManagedRelay,
   managedRelaySessionAtom,
@@ -13,6 +14,7 @@ import {
 import type {
   RelayClientDeviceRecord,
   RelayClientEnvironmentRecord,
+  RelayReferralSummary,
 } from "@t3tools/contracts/relay";
 import type { EnvironmentId } from "@t3tools/contracts";
 import * as Context from "effect/Context";
@@ -51,6 +53,16 @@ export const deregisterManagedRelayEnvironmentCommand = createRuntimeCommand(
   },
 );
 
+export const claimManagedRelayReferralCommand = createRuntimeCommand(managedRelayAtomRuntime, {
+  label: "web:managed-relay:claim-referral",
+  scheduler: managedRelayMutationScheduler,
+  concurrency: {
+    mode: "serial",
+    key: (input: { readonly accountId: string; readonly referralCode: string }) => input.accountId,
+  },
+  execute: (input, registry) => claimManagedRelayReferral(registry, input),
+});
+
 const EMPTY_ENVIRONMENTS_ATOM = Atom.make(
   AsyncResult.success<ReadonlyArray<RelayClientEnvironmentRecord>>([]),
 ).pipe(Atom.keepAlive, Atom.withLabel("managed-relay:web:environments:null"));
@@ -59,6 +71,10 @@ const EMPTY_DEVICES_ATOM = Atom.make(
   AsyncResult.success<ReadonlyArray<RelayClientDeviceRecord>>([]),
 ).pipe(Atom.keepAlive, Atom.withLabel("managed-relay:web:devices:null"));
 
+const EMPTY_REFERRAL_SUMMARY_ATOM = Atom.make(
+  AsyncResult.initial<RelayReferralSummary, never>(false),
+).pipe(Atom.keepAlive, Atom.withLabel("managed-relay:web:referrals:null"));
+
 export function useManagedRelayEnvironments() {
   const session = useAtomValue(managedRelaySessionAtom);
   const accountId = session?.accountId ?? null;
@@ -115,9 +131,45 @@ export function useManagedRelayDevices() {
   };
 }
 
+export function useManagedRelayReferralSummary() {
+  const session = useAtomValue(managedRelaySessionAtom);
+  const accountId = session?.accountId ?? null;
+  const atom = accountId
+    ? managedRelayQueryManager.referralSummaryAtom(accountId)
+    : EMPTY_REFERRAL_SUMMARY_ATOM;
+  const result = useAtomValue(atom);
+  const snapshot = readManagedRelaySnapshotState(result);
+  useEffect(() => {
+    if (snapshot.error) {
+      console.error("[t3-cloud] Relay referral summary failed", {
+        message: snapshot.error,
+        traceId: snapshot.errorTraceId,
+      });
+    }
+  }, [snapshot.error, snapshot.errorTraceId]);
+  const refresh = useCallback(() => {
+    if (accountId) {
+      managedRelayQueryManager.refreshReferralSummary(appAtomRegistry, accountId);
+    }
+  }, [accountId]);
+
+  return {
+    ...snapshot,
+    accountId,
+    refresh,
+  };
+}
+
 export function refreshManagedRelayEnvironments(): void {
   const session = appAtomRegistry.get(managedRelaySessionAtom);
   if (session) {
     managedRelayQueryManager.refreshEnvironments(appAtomRegistry, session.accountId);
   }
 }
+
+export function refreshManagedRelayReferralSummary(): void {
+  const session = appAtomRegistry.get(managedRelaySessionAtom);
+  if (session) {
+    managedRelayQueryManager.refreshReferralSummary(appAtomRegistry, session.accountId);
+  }
+}
diff --git a/apps/web/src/cloud/referralLinks.test.ts b/apps/web/src/cloud/referralLinks.test.ts
new file mode 100644
index 000000000000..e10a54b59f82
--- /dev/null
+++ b/apps/web/src/cloud/referralLinks.test.ts
@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { referralCodeFromUrl, urlWithoutReferralCode } from "./referralLinks";
+
+describe("referralLinks", () => {
+  it("reads and removes only the referral parameter", () => {
+    const url = new URL("https://app.t3.codes/?channel=nightly&ref=abcd1234efab5678#thread");
+    expect(referralCodeFromUrl(url)).toBe("ABCD1234EFAB5678");
+    expect(urlWithoutReferralCode(url)).toBe("/?channel=nightly#thread");
+  });
+});
diff --git a/apps/web/src/cloud/referralLinks.ts b/apps/web/src/cloud/referralLinks.ts
new file mode 100644
index 000000000000..42aa223935b5
--- /dev/null
+++ b/apps/web/src/cloud/referralLinks.ts
@@ -0,0 +1,15 @@
+import { buildReferralLink, normalizeReferralCode } from "@t3tools/shared/referral";
+
+export const PENDING_REFERRAL_CODE_STORAGE_KEY = "t3code.pending-referral-code";
+
+export function referralCodeFromUrl(url: URL): string | null {
+  return normalizeReferralCode(url.searchParams.get("ref") ?? "");
+}
+
+export function urlWithoutReferralCode(url: URL): string {
+  const next = new URL(url);
+  next.searchParams.delete("ref");
+  return `${next.pathname}${next.search}${next.hash}`;
+}
+
+export { buildReferralLink, normalizeReferralCode };
diff --git a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
new file mode 100644
index 000000000000..3d3d8ddcbb36
--- /dev/null
+++ b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
@@ -0,0 +1,194 @@
+import {
+  isAtomCommandInterrupted,
+  squashAtomCommandFailure,
+} from "@t3tools/client-runtime/state/runtime";
+import type { RelayReferralClaimResult } from "@t3tools/contracts/relay";
+import { CopyIcon, GiftIcon, TicketCheckIcon } from "lucide-react";
+import { useMemo, useState } from "react";
+
+import {
+  claimManagedRelayReferralCommand,
+  useManagedRelayReferralSummary,
+} from "../../cloud/managedRelayState";
+import { buildReferralLink, normalizeReferralCode } from "../../cloud/referralLinks";
+import { configuredHostedAppUrl } from "../../hostedPairing";
+import { useAtomCommand } from "../../state/use-atom-command";
+import { Button } from "../ui/button";
+import { Input } from "../ui/input";
+import { Skeleton } from "../ui/skeleton";
+import { toastManager } from "../ui/toast";
+import { ClerkUserProfilePage, ClerkUserProfileRefreshButton } from "./ClerkUserProfilePage";
+
+function claimResultMessage(result: RelayReferralClaimResult): {
+  readonly type: "success" | "warning" | "info";
+  readonly title: string;
+  readonly description?: string;
+} {
+  switch (result) {
+    case "claimed":
+      return {
+        type: "success",
+        title: "Referral applied",
+        description: "Your referrer will receive 67 points after you link your first environment.",
+      };
+    case "already_claimed":
+      return { type: "info", title: "This account already claimed a referral" };
+    case "invalid_code":
+      return { type: "warning", title: "This referral code is not valid" };
+    case "self_referral":
+      return { type: "warning", title: "You cannot use your own referral code" };
+    case "ineligible":
+      return {
+        type: "info",
+        title: "Referral code not applied",
+        description: "Referral codes must be claimed before linking an environment.",
+      };
+  }
+}
+
+export function ReferralsUserProfilePage() {
+  const summaryState = useManagedRelayReferralSummary();
+  const claimReferral = useAtomCommand(claimManagedRelayReferralCommand, {
+    reportFailure: false,
+  });
+  const [referralCode, setReferralCode] = useState("");
+  const [isClaiming, setIsClaiming] = useState(false);
+  const summary = summaryState.data;
+  const referralLink = useMemo(
+    () => (summary ? buildReferralLink(configuredHostedAppUrl(), summary.referralCode) : null),
+    [summary],
+  );
+
+  const copyInviteLink = async () => {
+    if (!referralLink || !navigator.clipboard?.writeText) return;
+    await navigator.clipboard.writeText(referralLink);
+    toastManager.add({ type: "success", title: "Referral link copied" });
+  };
+
+  const submitReferralCode = async () => {
+    const accountId = summaryState.accountId;
+    const normalized = normalizeReferralCode(referralCode);
+    if (!accountId || !normalized || isClaiming) {
+      if (!normalized) {
+        toastManager.add({ type: "warning", title: "Enter a valid 16-character referral code" });
+      }
+      return;
+    }
+
+    setIsClaiming(true);
+    const result = await claimReferral({ accountId, referralCode: normalized });
+    setIsClaiming(false);
+    if (result._tag === "Success") {
+      const message = claimResultMessage(result.value.result);
+      toastManager.add(message);
+      setReferralCode("");
+      summaryState.refresh();
+      return;
+    }
+    if (isAtomCommandInterrupted(result)) return;
+    const cause = squashAtomCommandFailure(result);
+    toastManager.add({
+      type: "error",
+      title: "Could not claim referral code",
+      description: cause instanceof Error ? cause.message : "Try again.",
+    });
+  };
+
+  const isInitialLoad =
+    !summaryState.accountId || (summaryState.data === null && !summaryState.error);
+
+  return (
+    <ClerkUserProfilePage
+      title="Referrals"
+      description="Earn 67 points when someone you invite links their first T3 Code environment. Your points follow your T3 account across devices."
+      action={
+        <ClerkUserProfileRefreshButton
+          disabled={isClaiming}
+          isPending={summaryState.isPending}
+          onClick={summaryState.refresh}
+        />
+      }
+    >
+      {summaryState.error ? (
+        <div className="mb-4 border-t border-destructive/35 py-3 text-[0.8125rem]" role="alert">
+          <p className="font-medium text-destructive-foreground">Could not load referral points</p>
+          <p className="mt-1 text-xs text-muted-foreground">{summaryState.error}</p>
+        </div>
+      ) : null}
+
+      {isInitialLoad ? (
+        <div className="grid gap-3 border-t py-5 sm:grid-cols-3" aria-label="Loading referrals">
+          <Skeleton className="h-24 rounded-xl" />
+          <Skeleton className="h-24 rounded-xl" />
+          <Skeleton className="h-24 rounded-xl" />
+        </div>
+      ) : summary ? (
+        <div className="space-y-6 border-t py-5">
+          <div className="grid gap-3 sm:grid-cols-3">
+            <div className="rounded-xl border bg-muted/24 p-4">
+              <p className="text-xs font-medium text-muted-foreground">Points</p>
+              <p className="mt-1 text-3xl font-semibold tracking-tight">{summary.points}</p>
+            </div>
+            <div className="rounded-xl border bg-muted/24 p-4">
+              <p className="text-xs font-medium text-muted-foreground">Successful referrals</p>
+              <p className="mt-1 text-3xl font-semibold tracking-tight">
+                {summary.qualifiedReferrals}
+              </p>
+            </div>
+            <div className="rounded-xl border bg-muted/24 p-4">
+              <p className="text-xs font-medium text-muted-foreground">Pending</p>
+              <p className="mt-1 text-3xl font-semibold tracking-tight">
+                {summary.pendingReferrals}
+              </p>
+            </div>
+          </div>
+
+          <section>
+            <div className="flex items-center gap-2">
+              <GiftIcon className="size-4 text-muted-foreground" aria-hidden="true" />
+              <h3 className="text-sm font-semibold">Invite someone</h3>
+            </div>
+            <p className="mt-1 text-xs leading-5 text-muted-foreground">
+              They must claim the code before linking their first environment.
+            </p>
+            <div className="mt-3 flex gap-2">
+              <Input nativeInput readOnly value={referralLink ?? ""} aria-label="Referral link" />
+              <Button size="sm" variant="outline" onClick={() => void copyInviteLink()}>
+                <CopyIcon className="size-3.5" aria-hidden="true" />
+                Copy
+              </Button>
+            </div>
+            <p className="mt-2 font-mono text-xs text-muted-foreground">
+              Code: {summary.referralCode}
+            </p>
+          </section>
+
+          {!summary.hasClaimedReferral ? (
+            <section className="rounded-xl border bg-muted/16 p-4">
+              <div className="flex items-center gap-2">
+                <TicketCheckIcon className="size-4 text-muted-foreground" aria-hidden="true" />
+                <h3 className="text-sm font-semibold">Have a referral code?</h3>
+              </div>
+              <div className="mt-3 flex gap-2">
+                <Input
+                  nativeInput
+                  value={referralCode}
+                  placeholder="ABCD1234EFAB5678"
+                  aria-label="Referral code"
+                  disabled={isClaiming}
+                  onChange={(event) => setReferralCode(event.currentTarget.value)}
+                  onKeyDown={(event) => {
+                    if (event.key === "Enter") void submitReferralCode();
+                  }}
+                />
+                <Button size="sm" disabled={isClaiming} onClick={() => void submitReferralCode()}>
+                  {isClaiming ? "Applying..." : "Apply"}
+                </Button>
+              </div>
+            </section>
+          ) : null}
+        </div>
+      ) : null}
+    </ClerkUserProfilePage>
+  );
+}
diff --git a/apps/web/src/components/clerk/T3ConnectSidebarSignIn.tsx b/apps/web/src/components/clerk/T3ConnectSidebarSignIn.tsx
index 9dfd8dce13b1..245cf7b1a04d 100644
--- a/apps/web/src/components/clerk/T3ConnectSidebarSignIn.tsx
+++ b/apps/web/src/components/clerk/T3ConnectSidebarSignIn.tsx
@@ -1,9 +1,10 @@
 import { UserButton, useAuth } from "@clerk/react";
-import { LogInIcon, ServerIcon, SmartphoneIcon } from "lucide-react";
+import { GiftIcon, LogInIcon, ServerIcon, SmartphoneIcon } from "lucide-react";
 
 import { hasCloudPublicConfig } from "../../cloud/publicConfig";
 import { SidebarMenu, SidebarMenuButton, SidebarMenuItem } from "../ui/sidebar";
 import { MobileClientsUserProfilePage } from "./MobileClientsUserProfilePage";
+import { ReferralsUserProfilePage } from "./ReferralsUserProfilePage";
 import { T3ConnectUserProfilePage } from "./T3ConnectUserProfilePage";
 import { useT3ConnectAuthPrompt } from "./useT3ConnectAuthPrompt";
 
@@ -47,6 +48,13 @@ function ConfiguredT3ConnectSidebarAvatar() {
       >
         <T3ConnectUserProfilePage />
       </UserButton.UserProfilePage>
+      <UserButton.UserProfilePage
+        label="Referrals"
+        labelIcon={<GiftIcon className="size-4" />}
+        url="referrals"
+      >
+        <ReferralsUserProfilePage />
+      </UserButton.UserProfilePage>
     </UserButton>
   );
 }
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
new file mode 100644
index 000000000000..bb208dbe92a9
--- /dev/null
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
@@ -0,0 +1,115 @@
+import { useAuth } from "@clerk/react";
+import {
+  isAtomCommandInterrupted,
+  squashAtomCommandFailure,
+} from "@t3tools/client-runtime/state/runtime";
+import type { RelayReferralClaimResult } from "@t3tools/contracts/relay";
+import { useEffect, useRef } from "react";
+
+import {
+  claimManagedRelayReferralCommand,
+  refreshManagedRelayReferralSummary,
+} from "../../cloud/managedRelayState";
+import { hasCloudPublicConfig } from "../../cloud/publicConfig";
+import {
+  PENDING_REFERRAL_CODE_STORAGE_KEY,
+  referralCodeFromUrl,
+  urlWithoutReferralCode,
+} from "../../cloud/referralLinks";
+import { useAtomCommand } from "../../state/use-atom-command";
+import { toastManager } from "../ui/toast";
+
+function clearPendingReferralCode(): void {
+  try {
+    window.localStorage.removeItem(PENDING_REFERRAL_CODE_STORAGE_KEY);
+  } catch {
+    // The referral query parameter still gets removed when storage is unavailable.
+  }
+}
+
+function readPendingReferralCode(): string | null {
+  try {
+    return window.localStorage.getItem(PENDING_REFERRAL_CODE_STORAGE_KEY);
+  } catch {
+    return null;
+  }
+}
+
+function captureReferralCode(): void {
+  const url = new URL(window.location.href);
+  const referralCode = referralCodeFromUrl(url);
+  if (!referralCode) return;
+  try {
+    window.localStorage.setItem(PENDING_REFERRAL_CODE_STORAGE_KEY, referralCode);
+  } catch {
+    return;
+  }
+  window.history.replaceState(window.history.state, "", urlWithoutReferralCode(url));
+}
+
+function showClaimResult(result: RelayReferralClaimResult): void {
+  switch (result) {
+    case "claimed":
+      toastManager.add({
+        type: "success",
+        title: "Referral applied",
+        description: "Your referrer will receive 67 points after you link your first environment.",
+      });
+      return;
+    case "already_claimed":
+      return;
+    case "invalid_code":
+      toastManager.add({ type: "warning", title: "This referral code is not valid" });
+      return;
+    case "self_referral":
+      toastManager.add({ type: "warning", title: "You cannot use your own referral code" });
+      return;
+    case "ineligible":
+      toastManager.add({
+        type: "info",
+        title: "Referral code not applied",
+        description: "Referral codes must be claimed before linking an environment.",
+      });
+  }
+}
+
+export function ReferralClaimCoordinator() {
+  if (!hasCloudPublicConfig()) return null;
+  return <ConfiguredReferralClaimCoordinator />;
+}
+
+function ConfiguredReferralClaimCoordinator() {
+  const { isLoaded, isSignedIn, userId } = useAuth({ treatPendingAsSignedOut: false });
+  const claimReferral = useAtomCommand(claimManagedRelayReferralCommand, {
+    reportFailure: false,
+  });
+  const attemptedClaimRef = useRef<string | null>(null);
+
+  useEffect(() => {
+    captureReferralCode();
+  }, []);
+
+  useEffect(() => {
+    if (!isLoaded || !isSignedIn || !userId) return;
+    const referralCode = readPendingReferralCode();
+    if (!referralCode) return;
+    const attemptKey = `${userId}:${referralCode}`;
+    if (attemptedClaimRef.current === attemptKey) return;
+    attemptedClaimRef.current = attemptKey;
+
+    void (async () => {
+      const result = await claimReferral({ accountId: userId, referralCode });
+      if (result._tag === "Success") {
+        clearPendingReferralCode();
+        refreshManagedRelayReferralSummary();
+        showClaimResult(result.value.result);
+        return;
+      }
+      if (isAtomCommandInterrupted(result)) return;
+      const cause = squashAtomCommandFailure(result);
+      console.error("[t3-cloud] Could not claim captured referral code", { cause });
+    })();
+  }, [claimReferral, isLoaded, isSignedIn, userId]);
+
+  return null;
+}
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index 7c715dff9e95..d4d6dbcf33ba 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -17,6 +17,7 @@ import { CommandPalette } from "../components/CommandPalette";
 import { ConfirmDialogHost } from "../components/ConfirmDialogHost";
 import { ConnectOnboardingDialog } from "../components/cloud/ConnectOnboardingDialog";
 import { RelayClientInstallDialog } from "../components/cloud/RelayClientInstallDialog";
+import { ReferralClaimCoordinator } from "../components/cloud/ReferralClaimCoordinator";
 import { SshPasswordPromptDialog } from "../components/desktop/SshPasswordPromptDialog";
 import { ProviderUpdateLaunchNotification } from "../components/ProviderUpdateLaunchNotification";
 import { SlowRpcRequestToastCoordinator } from "../components/SlowRpcRequestToastCoordinator";
@@ -137,6 +138,7 @@ function RootRouteView() {
         <FontAppearanceSync />
         {primaryEnvironmentAuthenticated ? <AuthenticatedTracingBootstrap /> : null}
         <RelayClientInstallDialog />
+        <ReferralClaimCoordinator />
         <ConnectOnboardingDialog />
         <SshPasswordPromptDialog />
         <ConfirmDialogHost />
diff --git a/docs/README.md b/docs/README.md
index 622d81064387..572af89fe856 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -7,6 +7,7 @@
 - [Keyboard shortcuts](./user/keybindings.md)
 - [Organizing threads](./user/thread-sidebar.md)
 - [Review usage](./user/usage.md)
+- [Referral points](./user/referrals.md)
 - [Customize a project icon](./user/project-settings.md)
 - [Mobile appearance](./user/mobile-appearance.md)
 - [Remote access](./user/remote-access.md)
diff --git a/docs/internals/t3-connect.md b/docs/internals/t3-connect.md
index 6f796123e98b..93c5eb2a5517 100644
--- a/docs/internals/t3-connect.md
+++ b/docs/internals/t3-connect.md
@@ -255,6 +255,22 @@ Desktop renders the same web bundle, so it has them too. The waitlist enrollment
 private beta was removed when Connect went GA; sign-up is open unless a Clerk restriction below is
 enabled.
 
+## Referral Points
+
+Referral points are account state owned by the hosted relay. `relay_referral_accounts` maps each
+Clerk user ID to one random referral code and records an optional referrer. The append-only
+`relay_referral_point_entries` table is the balance ledger; summaries derive the balance by summing
+the ledger instead of trusting a mutable counter.
+
+A signed-in user can claim one code only before their account has an environment link. The claim is
+pending until `linkEnvironment` succeeds for that account. The link handler then qualifies the
+referral and appends one 67-point ledger entry for the referrer. A unique index on referrer, reason,
+and referred user makes retries idempotent.
+
+Web and desktop expose referrals in the Clerk account menu. A hosted `?ref=` link is captured before
+sign-in and claimed after Clerk supplies the account session. Mobile exposes the same relay-backed
+summary under Settings and shares hosted links, so every client reads the same account balance.
+
 ## Restricting Sign-ups: Known-User Allowlist
 
 For a closed deployment where all permitted users are known in advance, restrict sign-up to
diff --git a/docs/user/referrals.md b/docs/user/referrals.md
new file mode 100644
index 000000000000..33b01651298f
--- /dev/null
+++ b/docs/user/referrals.md
@@ -0,0 +1,17 @@
+# Referral points
+
+T3 Code referral points belong to your T3 account. Sign in with the same account to see the same
+balance on web, desktop, or mobile, even when you use a different machine.
+
+Open your account menu and choose **Referrals** to find your referral link and code. On mobile, open
+**Settings → Account → Referrals**.
+
+You earn 67 points when someone:
+
+1. Opens your referral link or enters your code while signed in.
+2. Claims the referral before linking any T3 Code environment to their account.
+3. Links their first environment.
+
+A referral appears as pending after the code is claimed. It becomes successful and adds 67 points
+when the referred account links its first environment. A code can be claimed only once per account,
+and you cannot claim your own code.
diff --git a/infra/relay/README.md b/infra/relay/README.md
index 0085c9c5b6b7..a1a465b1ff73 100644
--- a/infra/relay/README.md
+++ b/infra/relay/README.md
@@ -20,6 +20,7 @@ The relay currently owns:
 - Provisioning and tracking managed environment endpoints.
 - Issuing short-lived credentials used to connect clients to linked environments.
 - Listing linked environments and registered mobile devices for an account.
+- Tracking account referral codes, qualification, and the referral-point ledger.
 - Registering mobile notification preferences and APNs tokens.
 - Receiving published agent activity and delivering notifications or Live Activity updates.
 - Persisting relay state and exposing relay-specific traces for diagnostics.
@@ -38,6 +39,7 @@ credential, or authorization behavior.
   provisioning, and connection flows.
 - [`src/agentActivity`](./src/agentActivity) contains mobile device registration, activity state,
   APNs delivery, and queue processing.
+- [`src/referrals`](./src/referrals) contains referral claiming, qualification, and balance logic.
 - [`src/auth`](./src/auth) contains relay token and DPoP proof handling.
 - [`src/persistence/schema.ts`](./src/persistence/schema.ts) defines persisted relay state. Keep
   schema and migration changes together.
diff --git a/infra/relay/migrations/postgres/20260826230249_complete_logan/migration.sql b/infra/relay/migrations/postgres/20260826230249_complete_logan/migration.sql
new file mode 100644
index 000000000000..d7003997805d
--- /dev/null
+++ b/infra/relay/migrations/postgres/20260826230249_complete_logan/migration.sql
@@ -0,0 +1,23 @@
+CREATE TABLE "relay_referral_accounts" (
+	"user_id" varchar(191) PRIMARY KEY,
+	"referral_code" varchar(16) NOT NULL,
+	"referrer_user_id" varchar(191),
+	"referred_at" varchar(64),
+	"qualified_at" varchar(64),
+	"created_at" varchar(64) NOT NULL,
+	"updated_at" varchar(64) NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "relay_referral_point_entries" (
+	"id" varchar(36) PRIMARY KEY,
+	"user_id" varchar(191) NOT NULL,
+	"points" integer NOT NULL,
+	"reason" varchar(32) NOT NULL,
+	"referred_user_id" varchar(191) NOT NULL,
+	"created_at" varchar(64) NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX "idx_relay_referral_accounts_code" ON "relay_referral_accounts" ("referral_code");--> statement-breakpoint
+CREATE INDEX "idx_relay_referral_accounts_referrer" ON "relay_referral_accounts" ("referrer_user_id","qualified_at");--> statement-breakpoint
+CREATE INDEX "idx_relay_referral_point_entries_user" ON "relay_referral_point_entries" ("user_id","created_at");--> statement-breakpoint
+CREATE UNIQUE INDEX "idx_relay_referral_point_entries_award" ON "relay_referral_point_entries" ("user_id","reason","referred_user_id");
\ No newline at end of file
diff --git a/infra/relay/migrations/postgres/20260826230249_complete_logan/snapshot.json b/infra/relay/migrations/postgres/20260826230249_complete_logan/snapshot.json
new file mode 100644
index 000000000000..a688ee0f0c3c
--- /dev/null
+++ b/infra/relay/migrations/postgres/20260826230249_complete_logan/snapshot.json
@@ -0,0 +1,1812 @@
+{
+  "version": "8",
+  "dialect": "postgres",
+  "id": "a3c85f32-9315-46ec-acce-8ccb82c0edea",
+  "prevIds": ["2374caff-40bf-423c-9255-55e76dddbc2a"],
+  "ddl": [
+    {
+      "isRlsEnabled": false,
+      "name": "relay_agent_activity_rows",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "isRlsEnabled": false,
+      "name": "relay_delivery_attempts",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "isRlsEnabled": false,
+      "name": "relay_dpop_proofs",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "isRlsEnabled": false,
+      "name": "relay_environment_credentials",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "isRlsEnabled": false,
+      "name": "relay_environment_links",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "isRlsEnabled": false,
+      "name": "relay_live_activities",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "isRlsEnabled": false,
+      "name": "relay_managed_endpoint_allocations",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "isRlsEnabled": false,
+      "name": "relay_managed_tunnel_limits",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "isRlsEnabled": false,
+      "name": "relay_mobile_devices",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "isRlsEnabled": false,
+      "name": "relay_referral_accounts",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "isRlsEnabled": false,
+      "name": "relay_referral_point_entries",
+      "entityType": "tables",
+      "schema": "public"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "environment_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_agent_activity_rows"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "environment_public_key",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_agent_activity_rows"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "thread_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_agent_activity_rows"
+    },
+    {
+      "type": "jsonb",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "state_json",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_agent_activity_rows"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "updated_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_agent_activity_rows"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_agent_activity_rows"
+    },
+    {
+      "type": "varchar(36)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "varchar(255)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "user_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "environment_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "thread_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "varchar(255)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "device_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "kind",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "source_job_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "varchar(16)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "token_suffix",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "integer",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "apns_status",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "apns_reason",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "varchar(128)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "apns_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "transport_error",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "type": "varchar(128)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "thumbprint",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_dpop_proofs"
+    },
+    {
+      "type": "varchar(255)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "jti",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_dpop_proofs"
+    },
+    {
+      "type": "integer",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "iat",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_dpop_proofs"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "expires_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_dpop_proofs"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_dpop_proofs"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "credential_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_credentials"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "environment_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_credentials"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "environment_public_key",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_credentials"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "credential_hash",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_credentials"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "revoked_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_credentials"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_credentials"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "updated_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_credentials"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "user_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "environment_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": "'T3 Environment'",
+      "generated": null,
+      "identity": null,
+      "name": "environment_label",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "environment_public_key",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "endpoint_http_base_url",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "endpoint_ws_base_url",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "varchar(32)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "endpoint_provider_kind",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "boolean",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": "true",
+      "generated": null,
+      "identity": null,
+      "name": "notifications_enabled",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "boolean",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": "true",
+      "generated": null,
+      "identity": null,
+      "name": "live_activities_enabled",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "boolean",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": "false",
+      "generated": null,
+      "identity": null,
+      "name": "managed_tunnels_enabled",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_by_device_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "revoked_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "updated_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "type": "varchar(255)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "user_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "type": "varchar(255)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "device_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "activity_push_token",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "remote_start_queued_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "remote_started_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "ended_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "type": "jsonb",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "last_aggregate_json",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "last_live_activity_delivery_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "updated_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "user_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "environment_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "hostname",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "tunnel_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "tunnel_name",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "dns_record_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "ready_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "updated_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "user_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_tunnel_limits"
+    },
+    {
+      "type": "integer",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "max_tunnels",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_tunnel_limits"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_tunnel_limits"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "updated_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_managed_tunnel_limits"
+    },
+    {
+      "type": "varchar(255)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "user_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "varchar(255)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "device_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": "'iOS device'",
+      "generated": null,
+      "identity": null,
+      "name": "label",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "varchar(16)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "platform",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "integer",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "ios_major_version",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "app_version",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "varchar(255)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "bundle_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "varchar(16)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "aps_environment",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "push_token",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "text",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "push_to_start_token",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "jsonb",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "preferences_json",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "updated_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "user_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_accounts"
+    },
+    {
+      "type": "varchar(16)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "referral_code",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_accounts"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "referrer_user_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_accounts"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "referred_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_accounts"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": false,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "qualified_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_accounts"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_accounts"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "updated_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_accounts"
+    },
+    {
+      "type": "varchar(36)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_point_entries"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "user_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_point_entries"
+    },
+    {
+      "type": "integer",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "points",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_point_entries"
+    },
+    {
+      "type": "varchar(32)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "reason",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_point_entries"
+    },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "referred_user_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_point_entries"
+    },
+    {
+      "type": "varchar(64)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "created_at",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_point_entries"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "updated_at",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": false,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_agent_activity_rows_updated",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_agent_activity_rows"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "environment_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "thread_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "created_at",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": false,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_delivery_attempts_environment",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "source_job_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": true,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_delivery_attempts_source_job",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_delivery_attempts"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "expires_at",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": false,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_dpop_proofs_expires_at",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_dpop_proofs"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "credential_hash",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": true,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_environment_credentials_hash",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_environment_credentials"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "environment_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "revoked_at",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": false,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_environment_credentials_environment",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_environment_credentials"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "environment_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "environment_public_key",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "revoked_at",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": false,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_environment_credentials_environment_key",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_environment_credentials"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "environment_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "revoked_at",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": false,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_environment_links_environment",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "activity_push_token",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": true,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_live_activities_activity_push_token",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "hostname",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": true,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_managed_endpoint_allocations_hostname",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "tunnel_name",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": true,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_managed_endpoint_allocations_tunnel_name",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "push_token",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": true,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_mobile_devices_push_token",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "push_to_start_token",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": true,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_mobile_devices_push_to_start_token",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "referral_code",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": true,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_referral_accounts_code",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_referral_accounts"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "referrer_user_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "qualified_at",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": false,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_referral_accounts_referrer",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_referral_accounts"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "user_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "created_at",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": false,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_referral_point_entries_user",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_referral_point_entries"
+    },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "user_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "reason",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "referred_user_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": true,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_referral_point_entries_award",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_referral_point_entries"
+    },
+    {
+      "columns": ["environment_id", "environment_public_key", "thread_id"],
+      "nameExplicit": false,
+      "name": "relay_agent_activity_rows_pkey",
+      "entityType": "pks",
+      "schema": "public",
+      "table": "relay_agent_activity_rows"
+    },
+    {
+      "columns": ["thumbprint", "jti"],
+      "nameExplicit": false,
+      "name": "relay_dpop_proofs_pkey",
+      "entityType": "pks",
+      "schema": "public",
+      "table": "relay_dpop_proofs"
+    },
+    {
+      "columns": ["user_id", "environment_id"],
+      "nameExplicit": false,
+      "name": "relay_environment_links_pkey",
+      "entityType": "pks",
+      "schema": "public",
+      "table": "relay_environment_links"
+    },
+    {
+      "columns": ["user_id", "device_id"],
+      "nameExplicit": false,
+      "name": "relay_live_activities_pkey",
+      "entityType": "pks",
+      "schema": "public",
+      "table": "relay_live_activities"
+    },
+    {
+      "columns": ["user_id", "environment_id"],
+      "nameExplicit": false,
+      "name": "relay_managed_endpoint_allocations_pkey",
+      "entityType": "pks",
+      "schema": "public",
+      "table": "relay_managed_endpoint_allocations"
+    },
+    {
+      "columns": ["user_id", "device_id"],
+      "nameExplicit": false,
+      "name": "relay_mobile_devices_pkey",
+      "entityType": "pks",
+      "schema": "public",
+      "table": "relay_mobile_devices"
+    },
+    {
+      "columns": ["id"],
+      "nameExplicit": false,
+      "name": "relay_delivery_attempts_pkey",
+      "schema": "public",
+      "table": "relay_delivery_attempts",
+      "entityType": "pks"
+    },
+    {
+      "columns": ["credential_id"],
+      "nameExplicit": false,
+      "name": "relay_environment_credentials_pkey",
+      "schema": "public",
+      "table": "relay_environment_credentials",
+      "entityType": "pks"
+    },
+    {
+      "columns": ["user_id"],
+      "nameExplicit": false,
+      "name": "relay_managed_tunnel_limits_pkey",
+      "schema": "public",
+      "table": "relay_managed_tunnel_limits",
+      "entityType": "pks"
+    },
+    {
+      "columns": ["user_id"],
+      "nameExplicit": false,
+      "name": "relay_referral_accounts_pkey",
+      "schema": "public",
+      "table": "relay_referral_accounts",
+      "entityType": "pks"
+    },
+    {
+      "columns": ["id"],
+      "nameExplicit": false,
+      "name": "relay_referral_point_entries_pkey",
+      "schema": "public",
+      "table": "relay_referral_point_entries",
+      "entityType": "pks"
+    }
+  ],
+  "renames": []
+}
diff --git a/infra/relay/src/http/Api.ts b/infra/relay/src/http/Api.ts
index 50bcff665a9b..b2f396d3002f 100644
--- a/infra/relay/src/http/Api.ts
+++ b/infra/relay/src/http/Api.ts
@@ -67,6 +67,7 @@ import * as ManagedEndpointProvider from "../environments/ManagedEndpointProvide
 import * as ManagedEndpointAllocations from "../environments/ManagedEndpointAllocations.ts";
 import * as EnvironmentPublishSignatures from "../environments/EnvironmentPublishSignatures.ts";
 import * as MobileRegistrations from "../agentActivity/MobileRegistrations.ts";
+import * as ReferralProgram from "../referrals/ReferralProgram.ts";
 import { withSpanAttributes } from "../observability.ts";
 import * as RelayDb from "../db.ts";
 
@@ -532,6 +533,7 @@ export const clientApi = HttpApiBuilder.group(
     const links = yield* EnvironmentLinks.EnvironmentLinks;
     const managedEndpointProvider = yield* ManagedEndpointProvider.ManagedEndpointProvider;
     const devices = yield* Devices.Devices;
+    const referrals = yield* ReferralProgram.ReferralProgram;
     return handlers
       .handle(
         "listEnvironments",
@@ -548,6 +550,20 @@ export const clientApi = HttpApiBuilder.group(
           return { devices: yield* devices.listForUser({ userId }) };
         }, mapRelayCommonApiErrors("not_authorized")),
       )
+      .handle(
+        "getReferralSummary",
+        Effect.fn("relay.api.client.getReferralSummary")(function* () {
+          const { userId } = yield* RelayClientPrincipal;
+          return yield* referrals.getSummary({ userId });
+        }, mapRelayCommonApiErrors("not_authorized")),
+      )
+      .handle(
+        "claimReferral",
+        Effect.fn("relay.api.client.claimReferral")(function* ({ payload }) {
+          const { userId } = yield* RelayClientPrincipal;
+          return yield* referrals.claim({ userId, referralCode: payload.referralCode });
+        }, mapRelayCommonApiErrors("not_authorized")),
+      )
       .handle(
         "linkEnvironment",
         Effect.fn("relay.api.client.linkEnvironment")(
@@ -556,6 +572,7 @@ export const clientApi = HttpApiBuilder.group(
             yield* appendRelayCredentialResponseHeaders;
             const { userId } = yield* RelayClientPrincipal;
             const result = yield* linker.link({ userId, request: payload });
+            yield* referrals.qualify({ userId });
             return {
               ok: true,
               cloudUserId: userId,
@@ -1025,6 +1042,7 @@ const RelayCommonPersistenceError = Schema.Union([
   AgentActivityRows.AgentActivityRowListPersistenceError,
   LiveActivities.LiveActivityDeliveryMarkPersistenceError,
   DeliveryAttempts.DeliveryAttemptRecordPersistenceError,
+  ReferralProgram.ReferralProgramPersistenceError,
 ]);
 type RelayCommonPersistenceError = typeof RelayCommonPersistenceError.Type;
 const isRelayCommonPersistenceError = Schema.is(RelayCommonPersistenceError);
diff --git a/infra/relay/src/persistence/schema.ts b/infra/relay/src/persistence/schema.ts
index 61b72f2df868..a75627633253 100644
--- a/infra/relay/src/persistence/schema.ts
+++ b/infra/relay/src/persistence/schema.ts
@@ -110,6 +110,43 @@ export const relayManagedTunnelLimits = pgTable("relay_managed_tunnel_limits", {
   updatedAt: varchar("updated_at", { length: 64 }).notNull(),
 });
 
+export const relayReferralAccounts = pgTable(
+  "relay_referral_accounts",
+  {
+    userId: varchar("user_id", { length: 191 }).primaryKey(),
+    referralCode: varchar("referral_code", { length: 16 }).notNull(),
+    referrerUserId: varchar("referrer_user_id", { length: 191 }),
+    referredAt: varchar("referred_at", { length: 64 }),
+    qualifiedAt: varchar("qualified_at", { length: 64 }),
+    createdAt: varchar("created_at", { length: 64 }).notNull(),
+    updatedAt: varchar("updated_at", { length: 64 }).notNull(),
+  },
+  (table) => [
+    uniqueIndex("idx_relay_referral_accounts_code").on(table.referralCode),
+    index("idx_relay_referral_accounts_referrer").on(table.referrerUserId, table.qualifiedAt),
+  ],
+);
+
+export const relayReferralPointEntries = pgTable(
+  "relay_referral_point_entries",
+  {
+    id: varchar("id", { length: 36 }).primaryKey(),
+    userId: varchar("user_id", { length: 191 }).notNull(),
+    points: integer("points").notNull(),
+    reason: varchar("reason", { length: 32 }).notNull().$type<"qualified_referral">(),
+    referredUserId: varchar("referred_user_id", { length: 191 }).notNull(),
+    createdAt: varchar("created_at", { length: 64 }).notNull(),
+  },
+  (table) => [
+    index("idx_relay_referral_point_entries_user").on(table.userId, table.createdAt),
+    uniqueIndex("idx_relay_referral_point_entries_award").on(
+      table.userId,
+      table.reason,
+      table.referredUserId,
+    ),
+  ],
+);
+
 export const relayEnvironmentCredentials = pgTable(
   "relay_environment_credentials",
   {
diff --git a/infra/relay/src/referrals/ReferralProgram.test.ts b/infra/relay/src/referrals/ReferralProgram.test.ts
new file mode 100644
index 000000000000..5511b4e633e2
--- /dev/null
+++ b/infra/relay/src/referrals/ReferralProgram.test.ts
@@ -0,0 +1,223 @@
+import { describe, expect, it } from "@effect/vitest";
+import { PgDialect } from "drizzle-orm/pg-core";
+import * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+
+import * as RelayDb from "../db.ts";
+import {
+  relayEnvironmentLinks,
+  relayReferralAccounts,
+  relayReferralPointEntries,
+} from "../persistence/schema.ts";
+import * as ReferralProgram from "./ReferralProgram.ts";
+
+type ReferralAccount = typeof relayReferralAccounts.$inferSelect;
+type ReferralPointEntry = typeof relayReferralPointEntries.$inferSelect;
+
+interface FakeReferralState {
+  readonly accounts: Map<string, ReferralAccount>;
+  readonly environmentUsers: Set<string>;
+  readonly pointEntries: Array<ReferralPointEntry>;
+}
+
+const hasSelection = (selection: unknown, key: string): boolean =>
+  typeof selection === "object" && selection !== null && key in selection;
+
+function sqlQuery(condition: unknown) {
+  return new PgDialect().sqlToQuery(condition as never);
+}
+
+function makeFakeDb(state: FakeReferralState) {
+  return {
+    select: (selection?: unknown) => ({
+      from: (table: unknown) => {
+        if (table === relayReferralPointEntries) {
+          return {
+            where: (condition: unknown) => {
+              const userId = String(sqlQuery(condition).params[0]);
+              const points = state.pointEntries
+                .filter((entry) => entry.userId === userId)
+                .reduce((sum, entry) => sum + entry.points, 0);
+              return Effect.succeed([{ points }]);
+            },
+          };
+        }
+
+        if (table === relayEnvironmentLinks) {
+          return {
+            where: (condition: unknown) => ({
+              limit: () => {
+                const userId = String(sqlQuery(condition).params[0]);
+                return Effect.succeed(
+                  state.environmentUsers.has(userId) ? [{ environmentId: "environment-1" }] : [],
+                );
+              },
+            }),
+          };
+        }
+
+        expect(table).toBe(relayReferralAccounts);
+        return {
+          where: (condition: unknown) => {
+            const query = sqlQuery(condition);
+            const value = String(query.params[0]);
+
+            if (hasSelection(selection, "referrals")) {
+              const wantsQualified = query.sql.includes('"qualified_at" is not null');
+              const referrals = [...state.accounts.values()].filter(
+                (account) =>
+                  account.referrerUserId === value &&
+                  (wantsQualified ? account.qualifiedAt !== null : account.qualifiedAt === null),
+              ).length;
+              return Effect.succeed([{ referrals }]);
+            }
+
+            const account = hasSelection(selection, "userId")
+              ? [...state.accounts.values()].find((row) => row.referralCode === value)
+              : state.accounts.get(value);
+            return {
+              limit: () => Effect.succeed(account ? [account] : []),
+            };
+          },
+        };
+      },
+    }),
+    insert: (table: unknown) => ({
+      values: (value: ReferralAccount | ReferralPointEntry) => ({
+        onConflictDoNothing: () => ({
+          returning: () => {
+            if (table === relayReferralAccounts) {
+              const account = value as ReferralAccount;
+              const conflict =
+                state.accounts.has(account.userId) ||
+                [...state.accounts.values()].some(
+                  (existing) => existing.referralCode === account.referralCode,
+                );
+              if (conflict) return Effect.succeed([]);
+              state.accounts.set(account.userId, account);
+              return Effect.succeed([account]);
+            }
+
+            expect(table).toBe(relayReferralPointEntries);
+            const entry = value as ReferralPointEntry;
+            const conflict = state.pointEntries.some(
+              (existing) =>
+                existing.userId === entry.userId &&
+                existing.reason === entry.reason &&
+                existing.referredUserId === entry.referredUserId,
+            );
+            if (conflict) return Effect.succeed([]);
+            state.pointEntries.push(entry);
+            return Effect.succeed([{ id: entry.id }]);
+          },
+        }),
+      }),
+    }),
+    update: (table: unknown) => {
+      expect(table).toBe(relayReferralAccounts);
+      return {
+        set: (values: Partial<ReferralAccount>) => ({
+          where: (condition: unknown) => {
+            const userId = String(sqlQuery(condition).params[0]);
+            const account = state.accounts.get(userId);
+
+            if (values.referrerUserId !== undefined) {
+              return {
+                returning: () => {
+                  if (!account || account.referrerUserId !== null) return Effect.succeed([]);
+                  state.accounts.set(userId, { ...account, ...values });
+                  return Effect.succeed([{ userId }]);
+                },
+              };
+            }
+
+            if (account) state.accounts.set(userId, { ...account, ...values });
+            return Effect.void;
+          },
+        }),
+      };
+    },
+  } as unknown as RelayDb.RelayDb["Service"];
+}
+
+function makeTestLayer(state: FakeReferralState) {
+  let randomByte = 0;
+  const crypto = Crypto.make({
+    randomBytes: (size) => {
+      randomByte += 1;
+      return new Uint8Array(size).fill(randomByte);
+    },
+    digest: (_algorithm, data) => Effect.succeed(data),
+  });
+  const db = makeFakeDb(state);
+  return ReferralProgram.layer.pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        Layer.succeed(RelayDb.RelayDb, db),
+        Layer.succeed(
+          RelayDb.RelayTransactions,
+          RelayDb.RelayTransactions.of({ withTransaction: (effect) => effect }),
+        ),
+        Layer.succeed(Crypto.Crypto, crypto),
+      ),
+    ),
+  );
+}
+
+function makeState(): FakeReferralState {
+  return {
+    accounts: new Map(),
+    environmentUsers: new Set(),
+    pointEntries: [],
+  };
+}
+
+describe("ReferralProgram", () => {
+  it.effect("awards 67 account points once when the referred account links", () => {
+    const state = makeState();
+    return Effect.gen(function* () {
+      const referrals = yield* ReferralProgram.ReferralProgram;
+      const referrer = yield* referrals.getSummary({ userId: "referrer" });
+      const claim = yield* referrals.claim({
+        userId: "referred",
+        referralCode: referrer.referralCode.toLowerCase(),
+      });
+
+      expect(claim.result).toBe("claimed");
+      expect((yield* referrals.getSummary({ userId: "referrer" })).pendingReferrals).toBe(1);
+      expect(yield* referrals.qualify({ userId: "referred" })).toBe(true);
+      expect(yield* referrals.qualify({ userId: "referred" })).toBe(false);
+
+      expect(yield* referrals.getSummary({ userId: "referrer" })).toMatchObject({
+        points: 67,
+        awardPoints: 67,
+        qualifiedReferrals: 1,
+        pendingReferrals: 0,
+      });
+      expect(state.pointEntries).toHaveLength(1);
+    }).pipe(Effect.provide(makeTestLayer(state)));
+  });
+
+  it.effect("rejects self-referrals and accounts that already linked an environment", () => {
+    const state = makeState();
+    state.environmentUsers.add("linked-user");
+    return Effect.gen(function* () {
+      const referrals = yield* ReferralProgram.ReferralProgram;
+      const referrer = yield* referrals.getSummary({ userId: "referrer" });
+
+      expect(
+        (yield* referrals.claim({
+          userId: "referrer",
+          referralCode: referrer.referralCode,
+        })).result,
+      ).toBe("self_referral");
+      expect(
+        (yield* referrals.claim({
+          userId: "linked-user",
+          referralCode: referrer.referralCode,
+        })).result,
+      ).toBe("ineligible");
+    }).pipe(Effect.provide(makeTestLayer(state)));
+  });
+});
diff --git a/infra/relay/src/referrals/ReferralProgram.ts b/infra/relay/src/referrals/ReferralProgram.ts
new file mode 100644
index 000000000000..77eb3c532f0e
--- /dev/null
+++ b/infra/relay/src/referrals/ReferralProgram.ts
@@ -0,0 +1,340 @@
+import type {
+  RelayReferralClaimResponse,
+  RelayReferralClaimResult,
+  RelayReferralSummary,
+} from "@t3tools/contracts/relay";
+import { normalizeReferralCode } from "@t3tools/shared/referral";
+import { and, count, eq, isNotNull, isNull, sql } from "drizzle-orm";
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+
+import * as RelayDb from "../db.ts";
+import {
+  relayEnvironmentLinks,
+  relayReferralAccounts,
+  relayReferralPointEntries,
+} from "../persistence/schema.ts";
+
+export const REFERRAL_AWARD_POINTS = 67;
+
+type ReferralAccountRecord = typeof relayReferralAccounts.$inferSelect;
+
+export class ReferralProgramPersistenceError extends Schema.TaggedErrorClass<ReferralProgramPersistenceError>()(
+  "ReferralProgramPersistenceError",
+  {
+    operation: Schema.Literals([
+      "create-account",
+      "load-account",
+      "load-summary",
+      "claim-referral",
+      "qualify-referral",
+    ]),
+    userId: Schema.String,
+    cause: Schema.optionalKey(Schema.Defect()),
+  },
+) {
+  override get message(): string {
+    return `Referral program persistence failed during '${this.operation}' for user '${this.userId}'`;
+  }
+}
+
+export class ReferralProgram extends Context.Service<
+  ReferralProgram,
+  {
+    readonly getSummary: (input: {
+      readonly userId: string;
+    }) => Effect.Effect<RelayReferralSummary, ReferralProgramPersistenceError>;
+    readonly claim: (input: {
+      readonly userId: string;
+      readonly referralCode: string;
+    }) => Effect.Effect<RelayReferralClaimResponse, ReferralProgramPersistenceError>;
+    readonly qualify: (input: {
+      readonly userId: string;
+    }) => Effect.Effect<boolean, ReferralProgramPersistenceError>;
+  }
+>()("t3code-relay/referrals/ReferralProgram") {}
+
+function referralCodeFromUuid(uuid: string): string {
+  return uuid.replaceAll("-", "").slice(0, 16).toUpperCase();
+}
+
+export const make = Effect.gen(function* () {
+  const crypto = yield* Crypto.Crypto;
+  const db = yield* RelayDb.RelayDb;
+  const transactions = yield* RelayDb.RelayTransactions;
+
+  const loadAccount = Effect.fn("relay.referrals.load_account")(function* (userId: string) {
+    const rows = yield* db
+      .select()
+      .from(relayReferralAccounts)
+      .where(eq(relayReferralAccounts.userId, userId))
+      .limit(1)
+      .pipe(
+        Effect.mapError(
+          (cause) =>
+            new ReferralProgramPersistenceError({
+              operation: "load-account",
+              userId,
+              cause,
+            }),
+        ),
+      );
+    return rows[0] ?? null;
+  });
+
+  const ensureAccount = Effect.fn("relay.referrals.ensure_account")(function* (
+    userId: string,
+  ): Effect.fn.Return<ReferralAccountRecord, ReferralProgramPersistenceError> {
+    const existing = yield* loadAccount(userId);
+    if (existing) return existing;
+
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+      const now = DateTime.formatIso(yield* DateTime.now);
+      const referralCode = referralCodeFromUuid(
+        yield* crypto.randomUUIDv4.pipe(
+          Effect.mapError(
+            (cause) =>
+              new ReferralProgramPersistenceError({
+                operation: "create-account",
+                userId,
+                cause,
+              }),
+          ),
+        ),
+      );
+      const inserted = yield* db
+        .insert(relayReferralAccounts)
+        .values({
+          userId,
+          referralCode,
+          referrerUserId: null,
+          referredAt: null,
+          qualifiedAt: null,
+          createdAt: now,
+          updatedAt: now,
+        })
+        .onConflictDoNothing()
+        .returning()
+        .pipe(
+          Effect.mapError(
+            (cause) =>
+              new ReferralProgramPersistenceError({
+                operation: "create-account",
+                userId,
+                cause,
+              }),
+          ),
+        );
+      if (inserted[0]) return inserted[0];
+
+      const raced = yield* loadAccount(userId);
+      if (raced) return raced;
+    }
+
+    return yield* new ReferralProgramPersistenceError({
+      operation: "create-account",
+      userId,
+    });
+  });
+
+  const getSummary = Effect.fn("relay.referrals.get_summary")(function* (input: {
+    readonly userId: string;
+  }) {
+    const account = yield* ensureAccount(input.userId);
+    const [pointRows, qualifiedRows, pendingRows] = yield* Effect.all(
+      [
+        db
+          .select({
+            points: sql<number>`coalesce(sum(${relayReferralPointEntries.points}), 0)`.mapWith(
+              Number,
+            ),
+          })
+          .from(relayReferralPointEntries)
+          .where(eq(relayReferralPointEntries.userId, input.userId)),
+        db
+          .select({ referrals: count() })
+          .from(relayReferralAccounts)
+          .where(
+            and(
+              eq(relayReferralAccounts.referrerUserId, input.userId),
+              isNotNull(relayReferralAccounts.qualifiedAt),
+            ),
+          ),
+        db
+          .select({ referrals: count() })
+          .from(relayReferralAccounts)
+          .where(
+            and(
+              eq(relayReferralAccounts.referrerUserId, input.userId),
+              isNull(relayReferralAccounts.qualifiedAt),
+            ),
+          ),
+      ],
+      { concurrency: "unbounded" },
+    ).pipe(
+      Effect.mapError(
+        (cause) =>
+          new ReferralProgramPersistenceError({
+            operation: "load-summary",
+            userId: input.userId,
+            cause,
+          }),
+      ),
+    );
+
+    return {
+      points: pointRows[0]?.points ?? 0,
+      referralCode: account.referralCode,
+      awardPoints: REFERRAL_AWARD_POINTS,
+      qualifiedReferrals: qualifiedRows[0]?.referrals ?? 0,
+      pendingReferrals: pendingRows[0]?.referrals ?? 0,
+      hasClaimedReferral: account.referrerUserId !== null,
+    } satisfies RelayReferralSummary;
+  });
+
+  const claim = Effect.fn("relay.referrals.claim")(function* (input: {
+    readonly userId: string;
+    readonly referralCode: string;
+  }) {
+    const account = yield* ensureAccount(input.userId);
+    let result: RelayReferralClaimResult;
+
+    if (account.referrerUserId !== null) {
+      result = "already_claimed";
+    } else {
+      const code = normalizeReferralCode(input.referralCode);
+      const referrerRows = yield* db
+        .select({ userId: relayReferralAccounts.userId })
+        .from(relayReferralAccounts)
+        .where(eq(relayReferralAccounts.referralCode, code ?? ""))
+        .limit(1)
+        .pipe(
+          Effect.mapError(
+            (cause) =>
+              new ReferralProgramPersistenceError({
+                operation: "claim-referral",
+                userId: input.userId,
+                cause,
+              }),
+          ),
+        );
+      const referrerUserId = referrerRows[0]?.userId;
+
+      if (!referrerUserId) {
+        result = "invalid_code";
+      } else if (referrerUserId === input.userId) {
+        result = "self_referral";
+      } else {
+        const environmentRows = yield* db
+          .select({ environmentId: relayEnvironmentLinks.environmentId })
+          .from(relayEnvironmentLinks)
+          .where(eq(relayEnvironmentLinks.userId, input.userId))
+          .limit(1)
+          .pipe(
+            Effect.mapError(
+              (cause) =>
+                new ReferralProgramPersistenceError({
+                  operation: "claim-referral",
+                  userId: input.userId,
+                  cause,
+                }),
+            ),
+          );
+
+        if (environmentRows.length > 0) {
+          result = "ineligible";
+        } else {
+          const now = DateTime.formatIso(yield* DateTime.now);
+          const claimed = yield* db
+            .update(relayReferralAccounts)
+            .set({ referrerUserId, referredAt: now, updatedAt: now })
+            .where(
+              and(
+                eq(relayReferralAccounts.userId, input.userId),
+                isNull(relayReferralAccounts.referrerUserId),
+              ),
+            )
+            .returning({ userId: relayReferralAccounts.userId })
+            .pipe(
+              Effect.mapError(
+                (cause) =>
+                  new ReferralProgramPersistenceError({
+                    operation: "claim-referral",
+                    userId: input.userId,
+                    cause,
+                  }),
+              ),
+            );
+          result = claimed.length > 0 ? "claimed" : "already_claimed";
+        }
+      }
+    }
+
+    return {
+      result,
+      summary: yield* getSummary({ userId: input.userId }),
+    } satisfies RelayReferralClaimResponse;
+  });
+
+  const qualify = Effect.fn("relay.referrals.qualify")(function* (input: {
+    readonly userId: string;
+  }) {
+    const account = yield* loadAccount(input.userId);
+    if (!account?.referrerUserId || account.qualifiedAt !== null) return false;
+    const referrerUserId = account.referrerUserId;
+
+    const entryId = yield* crypto.randomUUIDv4.pipe(
+      Effect.mapError(
+        (cause) =>
+          new ReferralProgramPersistenceError({
+            operation: "qualify-referral",
+            userId: input.userId,
+            cause,
+          }),
+      ),
+    );
+    return yield* transactions
+      .withTransaction(
+        Effect.gen(function* () {
+          const now = DateTime.formatIso(yield* DateTime.now);
+          const inserted = yield* db
+            .insert(relayReferralPointEntries)
+            .values({
+              id: entryId,
+              userId: referrerUserId,
+              points: REFERRAL_AWARD_POINTS,
+              reason: "qualified_referral",
+              referredUserId: input.userId,
+              createdAt: now,
+            })
+            .onConflictDoNothing()
+            .returning({ id: relayReferralPointEntries.id });
+          if (inserted.length === 0) return false;
+
+          yield* db
+            .update(relayReferralAccounts)
+            .set({ qualifiedAt: now, updatedAt: now })
+            .where(eq(relayReferralAccounts.userId, input.userId));
+          return true;
+        }),
+      )
+      .pipe(
+        Effect.mapError(
+          (cause) =>
+            new ReferralProgramPersistenceError({
+              operation: "qualify-referral",
+              userId: input.userId,
+              cause,
+            }),
+        ),
+      );
+  });
+
+  return ReferralProgram.of({ getSummary, claim, qualify });
+});
+
+export const layer = Layer.effect(ReferralProgram, make);
diff --git a/infra/relay/src/worker.ts b/infra/relay/src/worker.ts
index 77dfd845c5bc..2504595f7b54 100644
--- a/infra/relay/src/worker.ts
+++ b/infra/relay/src/worker.ts
@@ -57,6 +57,7 @@ import * as EnvironmentPublishSignatures from "./environments/EnvironmentPublish
 import * as ManagedEndpointProvider from "./environments/ManagedEndpointProvider.ts";
 import * as ManagedTunnelLimits from "./environments/ManagedTunnelLimits.ts";
 import * as MobileRegistrations from "./agentActivity/MobileRegistrations.ts";
+import * as ReferralProgram from "./referrals/ReferralProgram.ts";
 
 const webcryptoLayer = Layer.succeed(
   Crypto.Crypto,
@@ -217,6 +218,7 @@ export const ApiLive = Api.make(
           EnvironmentLinks.layer,
           ManagedEndpointAllocations.layer,
           ManagedTunnelLimits.layer,
+          ReferralProgram.layer,
         ),
       ),
       Layer.provideMerge(LiveActivities.layer),
diff --git a/packages/client-runtime/src/connection/resolver.test.ts b/packages/client-runtime/src/connection/resolver.test.ts
index d71c0f9602bf..01ee28cecf74 100644
--- a/packages/client-runtime/src/connection/resolver.test.ts
+++ b/packages/client-runtime/src/connection/resolver.test.ts
@@ -76,6 +76,8 @@ function relayClient(
     relayUrl: "https://relay.example.test",
     listEnvironments: () => unsupported("listEnvironments"),
     listDevices: () => unsupported("listDevices"),
+    getReferralSummary: () => unsupported("getReferralSummary"),
+    claimReferral: () => unsupported("claimReferral"),
     createEnvironmentLinkChallenge: () => unsupported("createEnvironmentLinkChallenge"),
     linkEnvironment: () => unsupported("linkEnvironment"),
     unlinkEnvironment: () => unsupported("unlinkEnvironment"),
diff --git a/packages/client-runtime/src/relay/discovery.test.ts b/packages/client-runtime/src/relay/discovery.test.ts
index 8cb963000bd3..94196cd6982c 100644
--- a/packages/client-runtime/src/relay/discovery.test.ts
+++ b/packages/client-runtime/src/relay/discovery.test.ts
@@ -105,6 +105,8 @@ const makeHarness = Effect.fn("RelayDiscoveryTest.makeHarness")(function* () {
         Effect.flatMap((requests) => Deferred.await(requests.get(environmentId)!)),
       ),
     listDevices: () => Effect.die("unused"),
+    getReferralSummary: () => Effect.die("unused"),
+    claimReferral: () => Effect.die("unused"),
     createEnvironmentLinkChallenge: () => Effect.die("unused"),
     linkEnvironment: () => Effect.die("unused"),
     unlinkEnvironment: () => Effect.die("unused"),
@@ -267,6 +269,8 @@ describe("RelayEnvironmentDiscovery", () => {
           ),
         getEnvironmentStatus: () => Effect.die("unused"),
         listDevices: () => Effect.die("unused"),
+        getReferralSummary: () => Effect.die("unused"),
+        claimReferral: () => Effect.die("unused"),
         createEnvironmentLinkChallenge: () => Effect.die("unused"),
         linkEnvironment: () => Effect.die("unused"),
         unlinkEnvironment: () => Effect.die("unused"),
diff --git a/packages/client-runtime/src/relay/managedRelay.ts b/packages/client-runtime/src/relay/managedRelay.ts
index 06769a4372f1..10d19dd9e328 100644
--- a/packages/client-runtime/src/relay/managedRelay.ts
+++ b/packages/client-runtime/src/relay/managedRelay.ts
@@ -22,6 +22,8 @@ import {
   RelayMobileRegistrationScope,
   type RelayOkResponse,
   type RelayPublicClientId,
+  type RelayReferralClaimResponse,
+  type RelayReferralSummary,
   RelayRegisterDeviceEndpoint,
   RelayAgentActivitySnapshotEndpoint,
   RelayRegisterLiveActivityEndpoint,
@@ -86,6 +88,8 @@ export const ManagedRelayRequestAction = Schema.Literals([
   "exchange relay DPoP access token",
   "list relay-managed environments",
   "list relay client devices",
+  "read referral points",
+  "claim referral code",
   "create relay environment link challenge",
   "link relay environment",
   "unlink relay environment",
@@ -102,6 +106,8 @@ export const ManagedRelayRequestActivity = Schema.Literals([
   "Relay DPoP access token exchange",
   "Relay environment listing",
   "Relay client device listing",
+  "Relay referral summary",
+  "Relay referral claim",
   "Relay environment link challenge",
   "Relay environment linking",
   "Relay environment unlinking",
@@ -259,6 +265,13 @@ export class ManagedRelayClient extends Context.Service<
     readonly listDevices: (input: {
       readonly clerkToken: string;
     }) => Effect.Effect<ReadonlyArray<RelayClientDeviceRecord>, ManagedRelayClientError>;
+    readonly getReferralSummary: (input: {
+      readonly clerkToken: string;
+    }) => Effect.Effect<RelayReferralSummary, ManagedRelayClientError>;
+    readonly claimReferral: (input: {
+      readonly clerkToken: string;
+      readonly referralCode: string;
+    }) => Effect.Effect<RelayReferralClaimResponse, ManagedRelayClientError>;
     readonly createEnvironmentLinkChallenge: (input: {
       readonly clerkToken: string;
       readonly payload: RelayEnvironmentLinkChallengeRequest;
@@ -407,6 +420,8 @@ function disabledManagedRelayClient(relayUrl: string): ManagedRelayClient["Servi
     relayUrl,
     listEnvironments: unavailable("clientRuntime.managedRelay.listEnvironments"),
     listDevices: unavailable("clientRuntime.managedRelay.listDevices"),
+    getReferralSummary: unavailable("clientRuntime.managedRelay.getReferralSummary"),
+    claimReferral: unavailable("clientRuntime.managedRelay.claimReferral"),
     createEnvironmentLinkChallenge: unavailable(
       "clientRuntime.managedRelay.createEnvironmentLinkChallenge",
     ),
@@ -721,6 +736,33 @@ export const make = Effect.fn("ManagedRelayClient.make")(function* (
       Effect.withSpan("clientRuntime.managedRelay.listDevices"),
       withRelayClientTracing,
     ),
+    getReferralSummary: Effect.fnUntraced(
+      function* (input) {
+        return yield* client.client
+          .getReferralSummary({ headers: bearerHeaders(input.clerkToken) })
+          .pipe(
+            Effect.mapError(relayRequestError("read referral points")),
+            timeoutRelayRequest("Relay referral summary"),
+          );
+      },
+      Effect.withSpan("clientRuntime.managedRelay.getReferralSummary"),
+      withRelayClientTracing,
+    ),
+    claimReferral: Effect.fnUntraced(
+      function* (input) {
+        return yield* client.client
+          .claimReferral({
+            headers: bearerHeaders(input.clerkToken),
+            payload: { referralCode: input.referralCode },
+          })
+          .pipe(
+            Effect.mapError(relayRequestError("claim referral code")),
+            timeoutRelayRequest("Relay referral claim"),
+          );
+      },
+      Effect.withSpan("clientRuntime.managedRelay.claimReferral"),
+      withRelayClientTracing,
+    ),
     createEnvironmentLinkChallenge: Effect.fnUntraced(
       function* (input) {
         return yield* client.client
diff --git a/packages/client-runtime/src/relay/managedRelayState.test.ts b/packages/client-runtime/src/relay/managedRelayState.test.ts
index 00ac733762fe..bb670a0bfbd4 100644
--- a/packages/client-runtime/src/relay/managedRelayState.test.ts
+++ b/packages/client-runtime/src/relay/managedRelayState.test.ts
@@ -14,6 +14,7 @@ import { afterEach, vi } from "vite-plus/test";
 
 import * as ManagedRelay from "./managedRelay.ts";
 import {
+  claimManagedRelayReferral,
   createManagedRelayQueryManager,
   createManagedRelaySession,
   deregisterManagedRelayEnvironment,
@@ -58,6 +59,15 @@ const device = {
   updatedAt: "2026-06-01T00:00:00.000Z",
 } satisfies RelayClientDeviceRecord;
 
+const referralSummary = {
+  points: 67,
+  referralCode: "ABCD1234EFAB5678",
+  awardPoints: 67,
+  qualifiedReferrals: 1,
+  pendingReferrals: 0,
+  hasClaimedReferral: false,
+} as const;
+
 function resetRegistry() {
   registry.dispose();
   registry = AtomRegistry.make();
@@ -68,6 +78,8 @@ function createClient(overrides?: Partial<ManagedRelay.ManagedRelayClient["Servi
     relayUrl: "https://relay.example.test",
     listEnvironments: () => Effect.succeed([environment]),
     listDevices: () => Effect.succeed([device]),
+    getReferralSummary: () => Effect.die("unused"),
+    claimReferral: () => Effect.die("unused"),
     createEnvironmentLinkChallenge: () => Effect.die("unused"),
     linkEnvironment: () => Effect.die("unused"),
     unlinkEnvironment: () => Effect.die("unused"),
@@ -146,6 +158,28 @@ describe("createManagedRelayQueryManager", () => {
     }),
   );
 
+  it.effect("claims a referral through the current account session", () =>
+    Effect.gen(function* () {
+      const claimReferral = vi.fn(() =>
+        Effect.succeed({ result: "claimed" as const, summary: referralSummary }),
+      );
+      setSession();
+
+      expect(
+        yield* claimManagedRelayReferral(registry, {
+          accountId: "account-1",
+          referralCode: referralSummary.referralCode,
+        }).pipe(
+          Effect.provideService(ManagedRelay.ManagedRelayClient, createClient({ claimReferral })),
+        ),
+      ).toEqual({ result: "claimed", summary: referralSummary });
+      expect(claimReferral).toHaveBeenCalledWith({
+        clerkToken: "clerk-token",
+        referralCode: referralSummary.referralCode,
+      });
+    }),
+  );
+
   it.effect("rejects deregistration after the account changes", () =>
     Effect.gen(function* () {
       const unlinkEnvironment = vi.fn(() => Effect.succeed({ ok: true }));
@@ -349,6 +383,19 @@ describe("createManagedRelayQueryManager", () => {
     });
   });
 
+  it("loads referral points through the current account session", async () => {
+    const getReferralSummary = vi.fn(() => Effect.succeed(referralSummary));
+    const manager = createManager({ getReferralSummary });
+    setSession();
+    const atom = manager.referralSummaryAtom("account-1");
+
+    registry.get(atom);
+    await vi.waitFor(() => {
+      expect(readManagedRelaySnapshotState(registry.get(atom)).data).toEqual(referralSummary);
+    });
+    expect(getReferralSummary).toHaveBeenCalledWith({ clerkToken: "clerk-token" });
+  });
+
   it("reports token and relay request phases for environment status queries", async () => {
     const onQueryEvent = vi.fn();
     const manager = createManager(undefined, onQueryEvent);
diff --git a/packages/client-runtime/src/relay/managedRelayState.ts b/packages/client-runtime/src/relay/managedRelayState.ts
index 1a3a22efb204..a653df808a64 100644
--- a/packages/client-runtime/src/relay/managedRelayState.ts
+++ b/packages/client-runtime/src/relay/managedRelayState.ts
@@ -47,7 +47,7 @@ export interface ManagedRelaySnapshotState<A> {
 }
 
 export interface ManagedRelayQueryEvent {
-  readonly operation: "environments" | "devices" | "environment-status";
+  readonly operation: "environments" | "devices" | "referrals" | "environment-status";
   readonly stage: "clerk-token" | "relay-request" | "validation";
   readonly phase: "start" | "success" | "failure";
   readonly accountId: string;
@@ -237,6 +237,23 @@ export const deregisterManagedRelayEnvironment = Effect.fn(
   yield* relay.unlinkEnvironment({ clerkToken, environmentId: input.environmentId });
 });
 
+export const claimManagedRelayReferral = Effect.fn(
+  "clientRuntime.managedRelaySession.claimReferral",
+)(function* (
+  registry: AtomRegistry.AtomRegistry,
+  input: { readonly accountId: string; readonly referralCode: string },
+) {
+  const session = registry.get(managedRelaySessionAtom);
+  if (!session || session.accountId !== input.accountId) {
+    return yield* new ManagedRelaySessionError({
+      message: "Sign in to T3 Connect before claiming a referral code.",
+    });
+  }
+  const clerkToken = yield* readSessionClerkToken(session);
+  const relay = yield* ManagedRelay.ManagedRelayClient;
+  return yield* relay.claimReferral({ clerkToken, referralCode: input.referralCode });
+});
+
 function requireClerkToken(
   get: Atom.AtomContext,
   accountId: string,
@@ -407,6 +424,29 @@ export function createManagedRelayQueryManager(
       ),
   );
 
+  const referralSummaryAtom = Atom.family((accountId: string) =>
+    runtime
+      .atom((get) =>
+        Effect.gen(function* () {
+          const base = { operation: "referrals" as const, accountId };
+          const clerkToken = yield* observe(
+            { ...base, stage: "clerk-token" },
+            requireClerkToken(get, accountId),
+          );
+          const relay = yield* ManagedRelay.ManagedRelayClient;
+          return yield* observe(
+            { ...base, stage: "relay-request" },
+            relay.getReferralSummary({ clerkToken }),
+          );
+        }),
+      )
+      .pipe(
+        Atom.swr({ staleTime, revalidateOnMount: true }),
+        Atom.setIdleTTL(idleTtl),
+        Atom.withLabel(`managed-relay:referrals:${accountId}`),
+      ),
+  );
+
   const environmentStatusAtom = Atom.family((key: string) => {
     const { accountId, environment } = parseStatusKey(key);
     return runtime
@@ -446,6 +486,7 @@ export function createManagedRelayQueryManager(
   return {
     environmentsAtom,
     devicesAtom,
+    referralSummaryAtom: (accountId: string) => referralSummaryAtom(accountId),
     environmentStatusAtom: (input: {
       readonly accountId: string;
       readonly environment: RelayClientEnvironmentRecord;
@@ -456,6 +497,9 @@ export function createManagedRelayQueryManager(
     refreshDevices(registry: AtomRegistry.AtomRegistry, accountId: string): void {
       registry.refresh(devicesAtom(accountId));
     },
+    refreshReferralSummary(registry: AtomRegistry.AtomRegistry, accountId: string): void {
+      registry.refresh(referralSummaryAtom(accountId));
+    },
     refreshEnvironmentStatus(
       registry: AtomRegistry.AtomRegistry,
       input: {
diff --git a/packages/contracts/src/relay.ts b/packages/contracts/src/relay.ts
index 52f7d7d43550..a36f0809229b 100644
--- a/packages/contracts/src/relay.ts
+++ b/packages/contracts/src/relay.ts
@@ -631,6 +631,38 @@ export const RelayListEnvironmentsResponse = Schema.Struct({
 });
 export type RelayListEnvironmentsResponse = typeof RelayListEnvironmentsResponse.Type;
 
+const RelayNonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+
+export const RelayReferralSummary = Schema.Struct({
+  points: RelayNonNegativeInt,
+  referralCode: TrimmedNonEmptyString,
+  awardPoints: Schema.Int.check(Schema.isGreaterThan(0)),
+  qualifiedReferrals: RelayNonNegativeInt,
+  pendingReferrals: RelayNonNegativeInt,
+  hasClaimedReferral: Schema.Boolean,
+});
+export type RelayReferralSummary = typeof RelayReferralSummary.Type;
+
+export const RelayReferralClaimRequest = Schema.Struct({
+  referralCode: TrimmedNonEmptyString,
+});
+export type RelayReferralClaimRequest = typeof RelayReferralClaimRequest.Type;
+
+export const RelayReferralClaimResult = Schema.Literals([
+  "claimed",
+  "already_claimed",
+  "invalid_code",
+  "self_referral",
+  "ineligible",
+]);
+export type RelayReferralClaimResult = typeof RelayReferralClaimResult.Type;
+
+export const RelayReferralClaimResponse = Schema.Struct({
+  result: RelayReferralClaimResult,
+  summary: RelayReferralSummary,
+});
+export type RelayReferralClaimResponse = typeof RelayReferralClaimResponse.Type;
+
 export const RelayEnvironmentConnectRequest = Schema.Struct({
   deviceId: Schema.optional(
     TrimmedNonEmptyString.annotate({
@@ -958,6 +990,17 @@ export const RelayClientGroup = HttpApiGroup.make("client")
       success: RelayListDevicesResponse,
       error: RelayAuthAndInternalErrors,
     }).annotate(OpenApi.Summary, "List registered mobile devices"),
+    HttpApiEndpoint.get("getReferralSummary", "/v1/client/referrals", {
+      headers: RelayBearerRequestHeaders,
+      success: RelayReferralSummary,
+      error: RelayAuthAndInternalErrors,
+    }).annotate(OpenApi.Summary, "Read the signed-in account's referral points"),
+    HttpApiEndpoint.post("claimReferral", "/v1/client/referrals/claim", {
+      headers: RelayBearerRequestHeaders,
+      payload: RelayReferralClaimRequest,
+      success: RelayReferralClaimResponse,
+      error: RelayAuthAndInternalErrors,
+    }).annotate(OpenApi.Summary, "Claim a referral code"),
     HttpApiEndpoint.post("linkEnvironment", "/v1/client/environment-links", {
       headers: RelayBearerRequestHeaders,
       payload: RelayEnvironmentLinkRequest,
diff --git a/packages/shared/package.json b/packages/shared/package.json
index eeaa5f59e087..ee5c8b705d40 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -159,6 +159,10 @@
       "types": "./src/connectAuth.ts",
       "import": "./src/connectAuth.ts"
     },
+    "./referral": {
+      "types": "./src/referral.ts",
+      "import": "./src/referral.ts"
+    },
     "./path": {
       "types": "./src/path.ts",
       "import": "./src/path.ts"
diff --git a/packages/shared/src/referral.test.ts b/packages/shared/src/referral.test.ts
new file mode 100644
index 000000000000..5e6e15cfc0da
--- /dev/null
+++ b/packages/shared/src/referral.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { buildReferralLink, normalizeReferralCode } from "./referral.js";
+
+describe("referral", () => {
+  it("normalizes referral codes shared with separators", () => {
+    expect(normalizeReferralCode(" abcd-1234-efab-5678 ")).toBe("ABCD1234EFAB5678");
+    expect(normalizeReferralCode("not-a-code")).toBeNull();
+  });
+
+  it("builds a hosted referral link", () => {
+    expect(buildReferralLink("https://app.t3.codes", "ABCD1234EFAB5678")).toBe(
+      "https://app.t3.codes/?ref=ABCD1234EFAB5678",
+    );
+  });
+});
diff --git a/packages/shared/src/referral.ts b/packages/shared/src/referral.ts
new file mode 100644
index 000000000000..2e11e5b3c0e0
--- /dev/null
+++ b/packages/shared/src/referral.ts
@@ -0,0 +1,13 @@
+export const REFERRAL_CODE_LENGTH = 16;
+const REFERRAL_CODE_PATTERN = new RegExp(`^[A-F0-9]{${REFERRAL_CODE_LENGTH}}$`, "u");
+
+export function normalizeReferralCode(value: string): string | null {
+  const code = value.trim().replaceAll("-", "").toUpperCase();
+  return REFERRAL_CODE_PATTERN.test(code) ? code : null;
+}
+
+export function buildReferralLink(hostedAppUrl: string, referralCode: string): string {
+  const url = new URL("/", hostedAppUrl);
+  url.searchParams.set("ref", referralCode);
+  return url.toString();
+}

From de48db3c58361fb5ac9b349635ff92474347e900 Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 04:57:46 +0530
Subject: [PATCH 02/29] fix(connect): make referral awards race-safe

---
 .../clerk/ReferralsUserProfilePage.tsx        |  40 ++--
 .../cloud/ReferralClaimCoordinator.tsx        |  37 ++--
 infra/relay/src/http/Api.ts                   |  10 +-
 .../src/referrals/ReferralProgram.test.ts     |  38 +++-
 infra/relay/src/referrals/ReferralProgram.ts  | 186 ++++++++++--------
 5 files changed, 201 insertions(+), 110 deletions(-)

diff --git a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
index 3d3d8ddcbb36..6c03324d30dd 100644
--- a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
+++ b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
@@ -3,7 +3,7 @@ import {
   squashAtomCommandFailure,
 } from "@t3tools/client-runtime/state/runtime";
 import type { RelayReferralClaimResult } from "@t3tools/contracts/relay";
-import { CopyIcon, GiftIcon, TicketCheckIcon } from "lucide-react";
+import { CheckIcon, CopyIcon, GiftIcon, TicketCheckIcon } from "lucide-react";
 import { useMemo, useState } from "react";
 
 import {
@@ -12,6 +12,7 @@ import {
 } from "../../cloud/managedRelayState";
 import { buildReferralLink, normalizeReferralCode } from "../../cloud/referralLinks";
 import { configuredHostedAppUrl } from "../../hostedPairing";
+import { useCopyToClipboard } from "../../hooks/useCopyToClipboard";
 import { useAtomCommand } from "../../state/use-atom-command";
 import { Button } from "../ui/button";
 import { Input } from "../ui/input";
@@ -53,18 +54,22 @@ export function ReferralsUserProfilePage() {
   });
   const [referralCode, setReferralCode] = useState("");
   const [isClaiming, setIsClaiming] = useState(false);
+  const { copyToClipboard, isCopied } = useCopyToClipboard({
+    target: "referral link",
+    onCopy: () => toastManager.add({ type: "success", title: "Referral link copied" }),
+    onError: (error) =>
+      toastManager.add({
+        type: "error",
+        title: "Could not copy referral link",
+        description: error.message,
+      }),
+  });
   const summary = summaryState.data;
   const referralLink = useMemo(
     () => (summary ? buildReferralLink(configuredHostedAppUrl(), summary.referralCode) : null),
     [summary],
   );
 
-  const copyInviteLink = async () => {
-    if (!referralLink || !navigator.clipboard?.writeText) return;
-    await navigator.clipboard.writeText(referralLink);
-    toastManager.add({ type: "success", title: "Referral link copied" });
-  };
-
   const submitReferralCode = async () => {
     const accountId = summaryState.accountId;
     const normalized = normalizeReferralCode(referralCode);
@@ -117,7 +122,11 @@ export function ReferralsUserProfilePage() {
       ) : null}
 
       {isInitialLoad ? (
-        <div className="grid gap-3 border-t py-5 sm:grid-cols-3" aria-label="Loading referrals">
+        <div
+          className="grid gap-3 border-t py-5 sm:grid-cols-3"
+          aria-label="Loading referrals"
+          role="status"
+        >
           <Skeleton className="h-24 rounded-xl" />
           <Skeleton className="h-24 rounded-xl" />
           <Skeleton className="h-24 rounded-xl" />
@@ -153,9 +162,18 @@ export function ReferralsUserProfilePage() {
             </p>
             <div className="mt-3 flex gap-2">
               <Input nativeInput readOnly value={referralLink ?? ""} aria-label="Referral link" />
-              <Button size="sm" variant="outline" onClick={() => void copyInviteLink()}>
-                <CopyIcon className="size-3.5" aria-hidden="true" />
-                Copy
+              <Button
+                size="sm"
+                variant="outline"
+                disabled={!referralLink}
+                onClick={() => copyToClipboard(referralLink ?? "")}
+              >
+                {isCopied ? (
+                  <CheckIcon className="size-3.5" aria-hidden="true" />
+                ) : (
+                  <CopyIcon className="size-3.5" aria-hidden="true" />
+                )}
+                {isCopied ? "Copied" : "Copy"}
               </Button>
             </div>
             <p className="mt-2 font-mono text-xs text-muted-foreground">
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
index bb208dbe92a9..88fa314bb3b5 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
@@ -1,4 +1,6 @@
 import { useAuth } from "@clerk/react";
+import { useAtomValue } from "@effect/atom-react";
+import { managedRelaySessionAtom } from "@t3tools/client-runtime/relay";
 import {
   isAtomCommandInterrupted,
   squashAtomCommandFailure,
@@ -83,33 +85,40 @@ function ConfiguredReferralClaimCoordinator() {
   const claimReferral = useAtomCommand(claimManagedRelayReferralCommand, {
     reportFailure: false,
   });
-  const attemptedClaimRef = useRef<string | null>(null);
+  const relayAccountId = useAtomValue(managedRelaySessionAtom)?.accountId ?? null;
+  const activeClaimRef = useRef<string | null>(null);
+  const completedClaimRef = useRef<string | null>(null);
 
   useEffect(() => {
     captureReferralCode();
   }, []);
 
   useEffect(() => {
-    if (!isLoaded || !isSignedIn || !userId) return;
+    if (!isLoaded || !isSignedIn || !userId || relayAccountId !== userId) return;
     const referralCode = readPendingReferralCode();
     if (!referralCode) return;
     const attemptKey = `${userId}:${referralCode}`;
-    if (attemptedClaimRef.current === attemptKey) return;
-    attemptedClaimRef.current = attemptKey;
+    if (activeClaimRef.current === attemptKey || completedClaimRef.current === attemptKey) return;
+    activeClaimRef.current = attemptKey;
 
     void (async () => {
-      const result = await claimReferral({ accountId: userId, referralCode });
-      if (result._tag === "Success") {
-        clearPendingReferralCode();
-        refreshManagedRelayReferralSummary();
-        showClaimResult(result.value.result);
-        return;
+      try {
+        const result = await claimReferral({ accountId: userId, referralCode });
+        if (result._tag === "Success") {
+          completedClaimRef.current = attemptKey;
+          clearPendingReferralCode();
+          refreshManagedRelayReferralSummary();
+          showClaimResult(result.value.result);
+          return;
+        }
+        if (isAtomCommandInterrupted(result)) return;
+        const cause = squashAtomCommandFailure(result);
+        console.error("[t3-cloud] Could not claim captured referral code", { cause });
+      } finally {
+        if (activeClaimRef.current === attemptKey) activeClaimRef.current = null;
       }
-      if (isAtomCommandInterrupted(result)) return;
-      const cause = squashAtomCommandFailure(result);
-      console.error("[t3-cloud] Could not claim captured referral code", { cause });
     })();
-  }, [claimReferral, isLoaded, isSignedIn, userId]);
+  }, [claimReferral, isLoaded, isSignedIn, relayAccountId, userId]);
 
   return null;
 }
diff --git a/infra/relay/src/http/Api.ts b/infra/relay/src/http/Api.ts
index b2f396d3002f..21b4b77f0f8c 100644
--- a/infra/relay/src/http/Api.ts
+++ b/infra/relay/src/http/Api.ts
@@ -572,7 +572,15 @@ export const clientApi = HttpApiBuilder.group(
             yield* appendRelayCredentialResponseHeaders;
             const { userId } = yield* RelayClientPrincipal;
             const result = yield* linker.link({ userId, request: payload });
-            yield* referrals.qualify({ userId });
+            yield* referrals.qualify({ userId }).pipe(
+              Effect.tapError((error) =>
+                Effect.logWarning("referral qualification after environment link failed", {
+                  errorTag: error._tag,
+                  operation: error.operation,
+                }),
+              ),
+              Effect.ignore,
+            );
             return {
               ok: true,
               cloudUserId: userId,
diff --git a/infra/relay/src/referrals/ReferralProgram.test.ts b/infra/relay/src/referrals/ReferralProgram.test.ts
index 5511b4e633e2..e38ba7236e1a 100644
--- a/infra/relay/src/referrals/ReferralProgram.test.ts
+++ b/infra/relay/src/referrals/ReferralProgram.test.ts
@@ -17,8 +17,10 @@ type ReferralPointEntry = typeof relayReferralPointEntries.$inferSelect;
 
 interface FakeReferralState {
   readonly accounts: Map<string, ReferralAccount>;
+  readonly claimUpdateSql: Array<string>;
   readonly environmentUsers: Set<string>;
   readonly pointEntries: Array<ReferralPointEntry>;
+  beforeClaimUpdate?: () => void;
 }
 
 const hasSelection = (selection: unknown, key: string): boolean =>
@@ -119,13 +121,20 @@ function makeFakeDb(state: FakeReferralState) {
       return {
         set: (values: Partial<ReferralAccount>) => ({
           where: (condition: unknown) => {
-            const userId = String(sqlQuery(condition).params[0]);
+            const query = sqlQuery(condition);
+            const userId = String(query.params[0]);
             const account = state.accounts.get(userId);
 
             if (values.referrerUserId !== undefined) {
+              state.claimUpdateSql.push(query.sql);
               return {
                 returning: () => {
-                  if (!account || account.referrerUserId !== null) return Effect.succeed([]);
+                  const eligible =
+                    account !== undefined &&
+                    account.referrerUserId === null &&
+                    !state.environmentUsers.has(userId);
+                  state.beforeClaimUpdate?.();
+                  if (!eligible || !account) return Effect.succeed([]);
                   state.accounts.set(userId, { ...account, ...values });
                   return Effect.succeed([{ userId }]);
                 },
@@ -168,6 +177,7 @@ function makeTestLayer(state: FakeReferralState) {
 function makeState(): FakeReferralState {
   return {
     accounts: new Map(),
+    claimUpdateSql: [],
     environmentUsers: new Set(),
     pointEntries: [],
   };
@@ -186,6 +196,7 @@ describe("ReferralProgram", () => {
 
       expect(claim.result).toBe("claimed");
       expect((yield* referrals.getSummary({ userId: "referrer" })).pendingReferrals).toBe(1);
+      state.environmentUsers.add("referred");
       expect(yield* referrals.qualify({ userId: "referred" })).toBe(true);
       expect(yield* referrals.qualify({ userId: "referred" })).toBe(false);
 
@@ -220,4 +231,27 @@ describe("ReferralProgram", () => {
       ).toBe("ineligible");
     }).pipe(Effect.provide(makeTestLayer(state)));
   });
+
+  it.effect("awards a referral when the first link commits during the claim write", () => {
+    const state = makeState();
+    return Effect.gen(function* () {
+      const referrals = yield* ReferralProgram.ReferralProgram;
+      const referrer = yield* referrals.getSummary({ userId: "referrer" });
+      state.beforeClaimUpdate = () => state.environmentUsers.add("referred");
+
+      expect(
+        (yield* referrals.claim({
+          userId: "referred",
+          referralCode: referrer.referralCode,
+        })).result,
+      ).toBe("claimed");
+      expect(state.claimUpdateSql[0]).toContain("not exists");
+      expect(state.claimUpdateSql[0]).toContain('from "relay_environment_links"');
+      expect(yield* referrals.getSummary({ userId: "referrer" })).toMatchObject({
+        points: 67,
+        qualifiedReferrals: 1,
+        pendingReferrals: 0,
+      });
+    }).pipe(Effect.provide(makeTestLayer(state)));
+  });
 });
diff --git a/infra/relay/src/referrals/ReferralProgram.ts b/infra/relay/src/referrals/ReferralProgram.ts
index 77eb3c532f0e..00340c9fef90 100644
--- a/infra/relay/src/referrals/ReferralProgram.ts
+++ b/infra/relay/src/referrals/ReferralProgram.ts
@@ -196,93 +196,33 @@ export const make = Effect.gen(function* () {
     } satisfies RelayReferralSummary;
   });
 
-  const claim = Effect.fn("relay.referrals.claim")(function* (input: {
-    readonly userId: string;
-    readonly referralCode: string;
-  }) {
-    const account = yield* ensureAccount(input.userId);
-    let result: RelayReferralClaimResult;
-
-    if (account.referrerUserId !== null) {
-      result = "already_claimed";
-    } else {
-      const code = normalizeReferralCode(input.referralCode);
-      const referrerRows = yield* db
-        .select({ userId: relayReferralAccounts.userId })
-        .from(relayReferralAccounts)
-        .where(eq(relayReferralAccounts.referralCode, code ?? ""))
-        .limit(1)
-        .pipe(
-          Effect.mapError(
-            (cause) =>
-              new ReferralProgramPersistenceError({
-                operation: "claim-referral",
-                userId: input.userId,
-                cause,
-              }),
-          ),
-        );
-      const referrerUserId = referrerRows[0]?.userId;
-
-      if (!referrerUserId) {
-        result = "invalid_code";
-      } else if (referrerUserId === input.userId) {
-        result = "self_referral";
-      } else {
-        const environmentRows = yield* db
-          .select({ environmentId: relayEnvironmentLinks.environmentId })
-          .from(relayEnvironmentLinks)
-          .where(eq(relayEnvironmentLinks.userId, input.userId))
-          .limit(1)
-          .pipe(
-            Effect.mapError(
-              (cause) =>
-                new ReferralProgramPersistenceError({
-                  operation: "claim-referral",
-                  userId: input.userId,
-                  cause,
-                }),
-            ),
-          );
-
-        if (environmentRows.length > 0) {
-          result = "ineligible";
-        } else {
-          const now = DateTime.formatIso(yield* DateTime.now);
-          const claimed = yield* db
-            .update(relayReferralAccounts)
-            .set({ referrerUserId, referredAt: now, updatedAt: now })
-            .where(
-              and(
-                eq(relayReferralAccounts.userId, input.userId),
-                isNull(relayReferralAccounts.referrerUserId),
-              ),
-            )
-            .returning({ userId: relayReferralAccounts.userId })
-            .pipe(
-              Effect.mapError(
-                (cause) =>
-                  new ReferralProgramPersistenceError({
-                    operation: "claim-referral",
-                    userId: input.userId,
-                    cause,
-                  }),
-              ),
-            );
-          result = claimed.length > 0 ? "claimed" : "already_claimed";
-        }
-      }
-    }
-
-    return {
-      result,
-      summary: yield* getSummary({ userId: input.userId }),
-    } satisfies RelayReferralClaimResponse;
+  const hasEnvironmentLink = Effect.fn("relay.referrals.has_environment_link")(function* (
+    userId: string,
+    operation: "claim-referral" | "qualify-referral",
+  ) {
+    const rows = yield* db
+      .select({ environmentId: relayEnvironmentLinks.environmentId })
+      .from(relayEnvironmentLinks)
+      .where(eq(relayEnvironmentLinks.userId, userId))
+      .limit(1)
+      .pipe(
+        Effect.mapError(
+          (cause) =>
+            new ReferralProgramPersistenceError({
+              operation,
+              userId,
+              cause,
+            }),
+        ),
+      );
+    return rows.length > 0;
   });
 
   const qualify = Effect.fn("relay.referrals.qualify")(function* (input: {
     readonly userId: string;
   }) {
+    if (!(yield* hasEnvironmentLink(input.userId, "qualify-referral"))) return false;
+
     const account = yield* loadAccount(input.userId);
     if (!account?.referrerUserId || account.qualifiedAt !== null) return false;
     const referrerUserId = account.referrerUserId;
@@ -334,6 +274,88 @@ export const make = Effect.gen(function* () {
       );
   });
 
+  const claim = Effect.fn("relay.referrals.claim")(function* (input: {
+    readonly userId: string;
+    readonly referralCode: string;
+  }) {
+    const account = yield* ensureAccount(input.userId);
+    let result: RelayReferralClaimResult;
+
+    if (account.referrerUserId !== null) {
+      result = "already_claimed";
+    } else {
+      const code = normalizeReferralCode(input.referralCode);
+      const referrerRows = yield* db
+        .select({ userId: relayReferralAccounts.userId })
+        .from(relayReferralAccounts)
+        .where(eq(relayReferralAccounts.referralCode, code ?? ""))
+        .limit(1)
+        .pipe(
+          Effect.mapError(
+            (cause) =>
+              new ReferralProgramPersistenceError({
+                operation: "claim-referral",
+                userId: input.userId,
+                cause,
+              }),
+          ),
+        );
+      const referrerUserId = referrerRows[0]?.userId;
+
+      if (!referrerUserId) {
+        result = "invalid_code";
+      } else if (referrerUserId === input.userId) {
+        result = "self_referral";
+      } else {
+        const now = DateTime.formatIso(yield* DateTime.now);
+        const claimed = yield* db
+          .update(relayReferralAccounts)
+          .set({ referrerUserId, referredAt: now, updatedAt: now })
+          .where(
+            and(
+              eq(relayReferralAccounts.userId, input.userId),
+              isNull(relayReferralAccounts.referrerUserId),
+              sql`not exists (
+                select 1 from ${relayEnvironmentLinks}
+                where ${relayEnvironmentLinks.userId} = ${input.userId}
+              )`,
+            ),
+          )
+          .returning({ userId: relayReferralAccounts.userId })
+          .pipe(
+            Effect.mapError(
+              (cause) =>
+                new ReferralProgramPersistenceError({
+                  operation: "claim-referral",
+                  userId: input.userId,
+                  cause,
+                }),
+            ),
+          );
+
+        if (claimed.length > 0) {
+          result = "claimed";
+        } else {
+          const current = yield* loadAccount(input.userId);
+          result = current?.referrerUserId
+            ? "already_claimed"
+            : (yield* hasEnvironmentLink(input.userId, "claim-referral"))
+              ? "ineligible"
+              : "already_claimed";
+        }
+      }
+    }
+
+    if (result === "claimed" || result === "already_claimed") {
+      yield* qualify({ userId: input.userId });
+    }
+
+    return {
+      result,
+      summary: yield* getSummary({ userId: input.userId }),
+    } satisfies RelayReferralClaimResponse;
+  });
+
   return ReferralProgram.of({ getSummary, claim, qualify });
 });
 

From 6966a8ab6f3e201efaacf098ba858e7c9d0f1523 Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 05:02:07 +0530
Subject: [PATCH 03/29] fix(web): align referral form controls

---
 .../src/components/clerk/ReferralsUserProfilePage.tsx    | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
index 6c03324d30dd..5f29997a6ab0 100644
--- a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
+++ b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
@@ -161,7 +161,13 @@ export function ReferralsUserProfilePage() {
               They must claim the code before linking their first environment.
             </p>
             <div className="mt-3 flex gap-2">
-              <Input nativeInput readOnly value={referralLink ?? ""} aria-label="Referral link" />
+              <Input
+                nativeInput
+                readOnly
+                size="sm"
+                value={referralLink ?? ""}
+                aria-label="Referral link"
+              />
               <Button
                 size="sm"
                 variant="outline"
@@ -190,6 +196,7 @@ export function ReferralsUserProfilePage() {
               <div className="mt-3 flex gap-2">
                 <Input
                   nativeInput
+                  size="sm"
                   value={referralCode}
                   placeholder="ABCD1234EFAB5678"
                   aria-label="Referral code"

From 3a5668285b0f76759644996b3ee507b77472ae82 Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 05:15:11 +0530
Subject: [PATCH 04/29] fix(connect): make referral claims atomic

---
 .../src/referrals/ReferralProgram.test.ts     |  42 ++++-
 infra/relay/src/referrals/ReferralProgram.ts  | 152 ++++++++++--------
 2 files changed, 124 insertions(+), 70 deletions(-)

diff --git a/infra/relay/src/referrals/ReferralProgram.test.ts b/infra/relay/src/referrals/ReferralProgram.test.ts
index e38ba7236e1a..bdb5b0c166ae 100644
--- a/infra/relay/src/referrals/ReferralProgram.test.ts
+++ b/infra/relay/src/referrals/ReferralProgram.test.ts
@@ -21,6 +21,7 @@ interface FakeReferralState {
   readonly environmentUsers: Set<string>;
   readonly pointEntries: Array<ReferralPointEntry>;
   beforeClaimUpdate?: () => void;
+  pointInsertFailure?: Error;
 }
 
 const hasSelection = (selection: unknown, key: string): boolean =>
@@ -102,6 +103,7 @@ function makeFakeDb(state: FakeReferralState) {
             }
 
             expect(table).toBe(relayReferralPointEntries);
+            if (state.pointInsertFailure) return Effect.fail(state.pointInsertFailure);
             const entry = value as ReferralPointEntry;
             const conflict = state.pointEntries.some(
               (existing) =>
@@ -166,7 +168,24 @@ function makeTestLayer(state: FakeReferralState) {
         Layer.succeed(RelayDb.RelayDb, db),
         Layer.succeed(
           RelayDb.RelayTransactions,
-          RelayDb.RelayTransactions.of({ withTransaction: (effect) => effect }),
+          RelayDb.RelayTransactions.of({
+            withTransaction: (effect) =>
+              Effect.suspend(() => {
+                const accounts = new Map(state.accounts);
+                const pointEntries = [...state.pointEntries];
+                return effect.pipe(
+                  Effect.tapError(() =>
+                    Effect.sync(() => {
+                      state.accounts.clear();
+                      for (const [userId, account] of accounts) {
+                        state.accounts.set(userId, account);
+                      }
+                      state.pointEntries.splice(0, state.pointEntries.length, ...pointEntries);
+                    }),
+                  ),
+                );
+              }),
+          }),
         ),
         Layer.succeed(Crypto.Crypto, crypto),
       ),
@@ -254,4 +273,25 @@ describe("ReferralProgram", () => {
       });
     }).pipe(Effect.provide(makeTestLayer(state)));
   });
+
+  it.effect("rolls back the claim when its immediate point award cannot be persisted", () => {
+    const state = makeState();
+    state.pointInsertFailure = new Error("point insert failed");
+    return Effect.gen(function* () {
+      const referrals = yield* ReferralProgram.ReferralProgram;
+      const referrer = yield* referrals.getSummary({ userId: "referrer" });
+      state.beforeClaimUpdate = () => state.environmentUsers.add("referred");
+
+      const error = yield* Effect.flip(
+        referrals.claim({
+          userId: "referred",
+          referralCode: referrer.referralCode,
+        }),
+      );
+
+      expect(error._tag).toBe("ReferralProgramPersistenceError");
+      expect(state.accounts.get("referred")?.referrerUserId).toBeNull();
+      expect(state.pointEntries).toHaveLength(0);
+    }).pipe(Effect.provide(makeTestLayer(state)));
+  });
 });
diff --git a/infra/relay/src/referrals/ReferralProgram.ts b/infra/relay/src/referrals/ReferralProgram.ts
index 00340c9fef90..cb444c2c9d22 100644
--- a/infra/relay/src/referrals/ReferralProgram.ts
+++ b/infra/relay/src/referrals/ReferralProgram.ts
@@ -218,16 +218,51 @@ export const make = Effect.gen(function* () {
     return rows.length > 0;
   });
 
+  const qualifyInCurrentTransaction = Effect.fn("relay.referrals.qualify_in_current_transaction")(
+    function* (input: { readonly userId: string }) {
+      if (!(yield* hasEnvironmentLink(input.userId, "qualify-referral"))) return false;
+
+      const account = yield* loadAccount(input.userId);
+      if (!account?.referrerUserId || account.qualifiedAt !== null) return false;
+      const referrerUserId = account.referrerUserId;
+
+      const entryId = yield* crypto.randomUUIDv4.pipe(
+        Effect.mapError(
+          (cause) =>
+            new ReferralProgramPersistenceError({
+              operation: "qualify-referral",
+              userId: input.userId,
+              cause,
+            }),
+        ),
+      );
+      const now = DateTime.formatIso(yield* DateTime.now);
+      const inserted = yield* db
+        .insert(relayReferralPointEntries)
+        .values({
+          id: entryId,
+          userId: referrerUserId,
+          points: REFERRAL_AWARD_POINTS,
+          reason: "qualified_referral",
+          referredUserId: input.userId,
+          createdAt: now,
+        })
+        .onConflictDoNothing()
+        .returning({ id: relayReferralPointEntries.id });
+      if (inserted.length === 0) return false;
+
+      yield* db
+        .update(relayReferralAccounts)
+        .set({ qualifiedAt: now, updatedAt: now })
+        .where(eq(relayReferralAccounts.userId, input.userId));
+      return true;
+    },
+  );
+
   const qualify = Effect.fn("relay.referrals.qualify")(function* (input: {
     readonly userId: string;
   }) {
-    if (!(yield* hasEnvironmentLink(input.userId, "qualify-referral"))) return false;
-
-    const account = yield* loadAccount(input.userId);
-    if (!account?.referrerUserId || account.qualifiedAt !== null) return false;
-    const referrerUserId = account.referrerUserId;
-
-    const entryId = yield* crypto.randomUUIDv4.pipe(
+    return yield* transactions.withTransaction(qualifyInCurrentTransaction(input)).pipe(
       Effect.mapError(
         (cause) =>
           new ReferralProgramPersistenceError({
@@ -237,41 +272,6 @@ export const make = Effect.gen(function* () {
           }),
       ),
     );
-    return yield* transactions
-      .withTransaction(
-        Effect.gen(function* () {
-          const now = DateTime.formatIso(yield* DateTime.now);
-          const inserted = yield* db
-            .insert(relayReferralPointEntries)
-            .values({
-              id: entryId,
-              userId: referrerUserId,
-              points: REFERRAL_AWARD_POINTS,
-              reason: "qualified_referral",
-              referredUserId: input.userId,
-              createdAt: now,
-            })
-            .onConflictDoNothing()
-            .returning({ id: relayReferralPointEntries.id });
-          if (inserted.length === 0) return false;
-
-          yield* db
-            .update(relayReferralAccounts)
-            .set({ qualifiedAt: now, updatedAt: now })
-            .where(eq(relayReferralAccounts.userId, input.userId));
-          return true;
-        }),
-      )
-      .pipe(
-        Effect.mapError(
-          (cause) =>
-            new ReferralProgramPersistenceError({
-              operation: "qualify-referral",
-              userId: input.userId,
-              cause,
-            }),
-        ),
-      );
   });
 
   const claim = Effect.fn("relay.referrals.claim")(function* (input: {
@@ -307,21 +307,38 @@ export const make = Effect.gen(function* () {
       } else if (referrerUserId === input.userId) {
         result = "self_referral";
       } else {
-        const now = DateTime.formatIso(yield* DateTime.now);
-        const claimed = yield* db
-          .update(relayReferralAccounts)
-          .set({ referrerUserId, referredAt: now, updatedAt: now })
-          .where(
-            and(
-              eq(relayReferralAccounts.userId, input.userId),
-              isNull(relayReferralAccounts.referrerUserId),
-              sql`not exists (
-                select 1 from ${relayEnvironmentLinks}
-                where ${relayEnvironmentLinks.userId} = ${input.userId}
-              )`,
-            ),
+        result = yield* transactions
+          .withTransaction(
+            Effect.gen(function* () {
+              const now = DateTime.formatIso(yield* DateTime.now);
+              const claimed = yield* db
+                .update(relayReferralAccounts)
+                .set({ referrerUserId, referredAt: now, updatedAt: now })
+                .where(
+                  and(
+                    eq(relayReferralAccounts.userId, input.userId),
+                    isNull(relayReferralAccounts.referrerUserId),
+                    sql`not exists (
+                      select 1 from ${relayEnvironmentLinks}
+                      where ${relayEnvironmentLinks.userId} = ${input.userId}
+                    )`,
+                  ),
+                )
+                .returning({ userId: relayReferralAccounts.userId });
+
+              if (claimed.length > 0) {
+                yield* qualifyInCurrentTransaction({ userId: input.userId });
+                return "claimed" as const;
+              }
+
+              const current = yield* loadAccount(input.userId);
+              return current?.referrerUserId
+                ? ("already_claimed" as const)
+                : (yield* hasEnvironmentLink(input.userId, "claim-referral"))
+                  ? ("ineligible" as const)
+                  : ("already_claimed" as const);
+            }),
           )
-          .returning({ userId: relayReferralAccounts.userId })
           .pipe(
             Effect.mapError(
               (cause) =>
@@ -332,22 +349,19 @@ export const make = Effect.gen(function* () {
                 }),
             ),
           );
-
-        if (claimed.length > 0) {
-          result = "claimed";
-        } else {
-          const current = yield* loadAccount(input.userId);
-          result = current?.referrerUserId
-            ? "already_claimed"
-            : (yield* hasEnvironmentLink(input.userId, "claim-referral"))
-              ? "ineligible"
-              : "already_claimed";
-        }
       }
     }
 
-    if (result === "claimed" || result === "already_claimed") {
-      yield* qualify({ userId: input.userId });
+    if (result === "already_claimed") {
+      yield* qualify({ userId: input.userId }).pipe(
+        Effect.tapError((error) =>
+          Effect.logWarning("referral qualification after repeated claim failed", {
+            errorTag: error._tag,
+            operation: error.operation,
+          }),
+        ),
+        Effect.ignore,
+      );
     }
 
     return {

From 552cdc99a0a54cb1211a599bf3a89c13cfad6ea7 Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 05:19:39 +0530
Subject: [PATCH 05/29] fix(connect): preserve referral persistence errors

---
 .../src/referrals/ReferralProgram.test.ts     |  6 +-
 infra/relay/src/referrals/ReferralProgram.ts  | 56 +++++++++++++------
 2 files changed, 45 insertions(+), 17 deletions(-)

diff --git a/infra/relay/src/referrals/ReferralProgram.test.ts b/infra/relay/src/referrals/ReferralProgram.test.ts
index bdb5b0c166ae..e9bf73ed4efd 100644
--- a/infra/relay/src/referrals/ReferralProgram.test.ts
+++ b/infra/relay/src/referrals/ReferralProgram.test.ts
@@ -289,7 +289,11 @@ describe("ReferralProgram", () => {
         }),
       );
 
-      expect(error._tag).toBe("ReferralProgramPersistenceError");
+      expect(error).toMatchObject({
+        _tag: "ReferralProgramPersistenceError",
+        operation: "qualify-referral",
+        cause: state.pointInsertFailure,
+      });
       expect(state.accounts.get("referred")?.referrerUserId).toBeNull();
       expect(state.pointEntries).toHaveLength(0);
     }).pipe(Effect.provide(makeTestLayer(state)));
diff --git a/infra/relay/src/referrals/ReferralProgram.ts b/infra/relay/src/referrals/ReferralProgram.ts
index cb444c2c9d22..45502ee109f1 100644
--- a/infra/relay/src/referrals/ReferralProgram.ts
+++ b/infra/relay/src/referrals/ReferralProgram.ts
@@ -42,6 +42,8 @@ export class ReferralProgramPersistenceError extends Schema.TaggedErrorClass<Ref
   }
 }
 
+const isReferralProgramPersistenceError = Schema.is(ReferralProgramPersistenceError);
+
 export class ReferralProgram extends Context.Service<
   ReferralProgram,
   {
@@ -248,13 +250,33 @@ export const make = Effect.gen(function* () {
           createdAt: now,
         })
         .onConflictDoNothing()
-        .returning({ id: relayReferralPointEntries.id });
+        .returning({ id: relayReferralPointEntries.id })
+        .pipe(
+          Effect.mapError(
+            (cause) =>
+              new ReferralProgramPersistenceError({
+                operation: "qualify-referral",
+                userId: input.userId,
+                cause,
+              }),
+          ),
+        );
       if (inserted.length === 0) return false;
 
       yield* db
         .update(relayReferralAccounts)
         .set({ qualifiedAt: now, updatedAt: now })
-        .where(eq(relayReferralAccounts.userId, input.userId));
+        .where(eq(relayReferralAccounts.userId, input.userId))
+        .pipe(
+          Effect.mapError(
+            (cause) =>
+              new ReferralProgramPersistenceError({
+                operation: "qualify-referral",
+                userId: input.userId,
+                cause,
+              }),
+          ),
+        );
       return true;
     },
   );
@@ -263,13 +285,14 @@ export const make = Effect.gen(function* () {
     readonly userId: string;
   }) {
     return yield* transactions.withTransaction(qualifyInCurrentTransaction(input)).pipe(
-      Effect.mapError(
-        (cause) =>
-          new ReferralProgramPersistenceError({
-            operation: "qualify-referral",
-            userId: input.userId,
-            cause,
-          }),
+      Effect.mapError((cause) =>
+        isReferralProgramPersistenceError(cause)
+          ? cause
+          : new ReferralProgramPersistenceError({
+              operation: "qualify-referral",
+              userId: input.userId,
+              cause,
+            }),
       ),
     );
   });
@@ -340,13 +363,14 @@ export const make = Effect.gen(function* () {
             }),
           )
           .pipe(
-            Effect.mapError(
-              (cause) =>
-                new ReferralProgramPersistenceError({
-                  operation: "claim-referral",
-                  userId: input.userId,
-                  cause,
-                }),
+            Effect.mapError((cause) =>
+              isReferralProgramPersistenceError(cause)
+                ? cause
+                : new ReferralProgramPersistenceError({
+                    operation: "claim-referral",
+                    userId: input.userId,
+                    cause,
+                  }),
             ),
           );
       }

From 3d30a793a1112d0a85fc849a553ffc70691c1bfe Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 05:27:47 +0530
Subject: [PATCH 06/29] fix(connect): keep referral awards recoverable

---
 .../src/referrals/ReferralProgram.test.ts     | 28 +++++--
 infra/relay/src/referrals/ReferralProgram.ts  | 75 +++++++++----------
 2 files changed, 55 insertions(+), 48 deletions(-)

diff --git a/infra/relay/src/referrals/ReferralProgram.test.ts b/infra/relay/src/referrals/ReferralProgram.test.ts
index e9bf73ed4efd..b3c5a852d2e8 100644
--- a/infra/relay/src/referrals/ReferralProgram.test.ts
+++ b/infra/relay/src/referrals/ReferralProgram.test.ts
@@ -274,7 +274,7 @@ describe("ReferralProgram", () => {
     }).pipe(Effect.provide(makeTestLayer(state)));
   });
 
-  it.effect("rolls back the claim when its immediate point award cannot be persisted", () => {
+  it.effect("keeps a claim recoverable when its immediate point award cannot be persisted", () => {
     const state = makeState();
     state.pointInsertFailure = new Error("point insert failed");
     return Effect.gen(function* () {
@@ -282,20 +282,34 @@ describe("ReferralProgram", () => {
       const referrer = yield* referrals.getSummary({ userId: "referrer" });
       state.beforeClaimUpdate = () => state.environmentUsers.add("referred");
 
-      const error = yield* Effect.flip(
-        referrals.claim({
+      expect(
+        (yield* referrals.claim({
           userId: "referred",
           referralCode: referrer.referralCode,
-        }),
-      );
+        })).result,
+      ).toBe("claimed");
+      expect(state.accounts.get("referred")?.referrerUserId).toBe("referrer");
+      expect(state.pointEntries).toHaveLength(0);
 
+      const error = yield* Effect.flip(referrals.qualify({ userId: "referred" }));
       expect(error).toMatchObject({
         _tag: "ReferralProgramPersistenceError",
         operation: "qualify-referral",
         cause: state.pointInsertFailure,
       });
-      expect(state.accounts.get("referred")?.referrerUserId).toBeNull();
-      expect(state.pointEntries).toHaveLength(0);
+
+      delete state.pointInsertFailure;
+      expect(
+        (yield* referrals.claim({
+          userId: "referred",
+          referralCode: referrer.referralCode,
+        })).result,
+      ).toBe("already_claimed");
+      expect(yield* referrals.getSummary({ userId: "referrer" })).toMatchObject({
+        points: 67,
+        qualifiedReferrals: 1,
+        pendingReferrals: 0,
+      });
     }).pipe(Effect.provide(makeTestLayer(state)));
   });
 });
diff --git a/infra/relay/src/referrals/ReferralProgram.ts b/infra/relay/src/referrals/ReferralProgram.ts
index 45502ee109f1..22396dc0e5d3 100644
--- a/infra/relay/src/referrals/ReferralProgram.ts
+++ b/infra/relay/src/referrals/ReferralProgram.ts
@@ -330,56 +330,49 @@ export const make = Effect.gen(function* () {
       } else if (referrerUserId === input.userId) {
         result = "self_referral";
       } else {
-        result = yield* transactions
-          .withTransaction(
-            Effect.gen(function* () {
-              const now = DateTime.formatIso(yield* DateTime.now);
-              const claimed = yield* db
-                .update(relayReferralAccounts)
-                .set({ referrerUserId, referredAt: now, updatedAt: now })
-                .where(
-                  and(
-                    eq(relayReferralAccounts.userId, input.userId),
-                    isNull(relayReferralAccounts.referrerUserId),
-                    sql`not exists (
-                      select 1 from ${relayEnvironmentLinks}
-                      where ${relayEnvironmentLinks.userId} = ${input.userId}
-                    )`,
-                  ),
-                )
-                .returning({ userId: relayReferralAccounts.userId });
-
-              if (claimed.length > 0) {
-                yield* qualifyInCurrentTransaction({ userId: input.userId });
-                return "claimed" as const;
-              }
-
-              const current = yield* loadAccount(input.userId);
-              return current?.referrerUserId
-                ? ("already_claimed" as const)
-                : (yield* hasEnvironmentLink(input.userId, "claim-referral"))
-                  ? ("ineligible" as const)
-                  : ("already_claimed" as const);
-            }),
+        const now = DateTime.formatIso(yield* DateTime.now);
+        const claimed = yield* db
+          .update(relayReferralAccounts)
+          .set({ referrerUserId, referredAt: now, updatedAt: now })
+          .where(
+            and(
+              eq(relayReferralAccounts.userId, input.userId),
+              isNull(relayReferralAccounts.referrerUserId),
+              sql`not exists (
+                select 1 from ${relayEnvironmentLinks}
+                where ${relayEnvironmentLinks.userId} = ${input.userId}
+              )`,
+            ),
           )
+          .returning({ userId: relayReferralAccounts.userId })
           .pipe(
-            Effect.mapError((cause) =>
-              isReferralProgramPersistenceError(cause)
-                ? cause
-                : new ReferralProgramPersistenceError({
-                    operation: "claim-referral",
-                    userId: input.userId,
-                    cause,
-                  }),
+            Effect.mapError(
+              (cause) =>
+                new ReferralProgramPersistenceError({
+                  operation: "claim-referral",
+                  userId: input.userId,
+                  cause,
+                }),
             ),
           );
+
+        if (claimed.length > 0) {
+          result = "claimed";
+        } else {
+          const current = yield* loadAccount(input.userId);
+          result = current?.referrerUserId
+            ? "already_claimed"
+            : (yield* hasEnvironmentLink(input.userId, "claim-referral"))
+              ? "ineligible"
+              : "already_claimed";
+        }
       }
     }
 
-    if (result === "already_claimed") {
+    if (result === "claimed" || result === "already_claimed") {
       yield* qualify({ userId: input.userId }).pipe(
         Effect.tapError((error) =>
-          Effect.logWarning("referral qualification after repeated claim failed", {
+          Effect.logWarning("referral qualification after claim failed", {
             errorTag: error._tag,
             operation: error.operation,
           }),

From 56320a503ed571965ac5ca55e5fee463bc6e6e0f Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 10:33:11 +0530
Subject: [PATCH 07/29] fix(referrals): finish cross-platform sharing flow

---
 .../settings/SettingsReferralsRouteScreen.tsx | 325 ++++++++++++------
 .../clerk/ReferralsUserProfilePage.tsx        | 228 ++++++++----
 .../clerk/useT3ConnectAuthPrompt.tsx          |   5 +-
 .../cloud/ReferralClaimCoordinator.tsx        |  34 +-
 docs/user/referrals.md                        |   4 +
 packages/shared/src/referral.test.ts          |  23 +-
 packages/shared/src/referral.ts               |  13 +-
 7 files changed, 452 insertions(+), 180 deletions(-)

diff --git a/apps/mobile/src/features/settings/SettingsReferralsRouteScreen.tsx b/apps/mobile/src/features/settings/SettingsReferralsRouteScreen.tsx
index 596c0b85ecfa..527de2345638 100644
--- a/apps/mobile/src/features/settings/SettingsReferralsRouteScreen.tsx
+++ b/apps/mobile/src/features/settings/SettingsReferralsRouteScreen.tsx
@@ -1,24 +1,42 @@
 import { useAuth } from "@clerk/expo";
+import { useNavigation } from "@react-navigation/native";
 import {
   isAtomCommandInterrupted,
   squashAtomCommandFailure,
 } from "@t3tools/client-runtime/state/runtime";
 import type { RelayReferralClaimResult } from "@t3tools/contracts/relay";
 import { DEFAULT_HOSTED_APP_URL } from "@t3tools/shared/connectAuth";
-import { buildReferralLink, normalizeReferralCode } from "@t3tools/shared/referral";
+import {
+  buildReferralLink,
+  buildReferralShareMessage,
+  normalizeReferralCode,
+  REFERRAL_SHARE_TITLE,
+} from "@t3tools/shared/referral";
+import type { ComponentProps } from "react";
 import { useState } from "react";
-import { ActivityIndicator, Alert, ScrollView, Share, TextInput, View } from "react-native";
+import {
+  ActivityIndicator,
+  Alert,
+  Platform,
+  Pressable,
+  ScrollView,
+  Share,
+  View,
+} from "react-native";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 
-import { AppText as Text } from "../../components/AppText";
+import { AndroidScreenHeader } from "../../components/AndroidScreenHeader";
+import { AppText as Text, AppTextInput as TextInput } from "../../components/AppText";
+import { SymbolView } from "../../components/AppSymbol";
 import { CopyTextButton } from "../../components/CopyTextButton";
 import { useThemeColor } from "../../lib/useThemeColor";
+import { NativeStackScreenOptions } from "../../native/StackHeader";
 import { useAtomCommand } from "../../state/use-atom-command";
 import {
   claimManagedRelayReferralCommand,
   useManagedRelayReferralSummary,
 } from "../cloud/managedRelayState";
-import { ConnectionSheetButton } from "../connection/ConnectionSheetButton";
+import { SettingsSection } from "./components/SettingsSection";
 
 function showClaimResult(result: RelayReferralClaimResult): void {
   switch (result) {
@@ -45,8 +63,71 @@ function showClaimResult(result: RelayReferralClaimResult): void {
   }
 }
 
+function ReferralMetric(props: {
+  readonly label: string;
+  readonly value: number;
+  readonly divided?: boolean;
+}) {
+  return (
+    <View
+      className={
+        props.divided ? "flex-1 border-l border-border-subtle px-4 py-4" : "flex-1 px-4 py-4"
+      }
+    >
+      <Text className="text-xs text-foreground-muted">{props.label}</Text>
+      <Text className="mt-0.5 text-2xl font-t3-bold tabular-nums text-foreground">
+        {props.value}
+      </Text>
+    </View>
+  );
+}
+
+function ReferralActionRow(props: {
+  readonly icon: ComponentProps<typeof SymbolView>["name"];
+  readonly label: string;
+  readonly detail: string;
+  readonly disabled?: boolean;
+  readonly onPress: () => void;
+}) {
+  const iconColor = useThemeColor("--color-icon");
+  const chevronColor = useThemeColor("--color-chevron");
+
+  return (
+    <Pressable
+      accessibilityLabel={props.label}
+      accessibilityRole="button"
+      accessibilityState={{ disabled: props.disabled ?? false }}
+      className="flex-row items-center gap-4 border-t border-border-subtle p-4 disabled:opacity-50"
+      disabled={props.disabled}
+      onPress={props.onPress}
+    >
+      <SymbolView
+        name={props.icon}
+        size={22}
+        tintColor={iconColor}
+        type="monochrome"
+        weight="regular"
+      />
+      <View className="min-w-0 flex-1 gap-0.5">
+        <Text className="text-lg text-foreground">{props.label}</Text>
+        <Text className="text-sm text-foreground-muted" numberOfLines={1}>
+          {props.detail}
+        </Text>
+      </View>
+      <SymbolView
+        name="chevron.right"
+        size={16}
+        tintColor={chevronColor}
+        type="monochrome"
+        weight="semibold"
+      />
+    </Pressable>
+  );
+}
+
 export function SettingsReferralsRouteScreen() {
   const { isSignedIn } = useAuth({ treatPendingAsSignedOut: false });
+  const navigation = useNavigation();
   const insets = useSafeAreaInsets();
   const summaryState = useManagedRelayReferralSummary();
   const claimReferral = useAtomCommand(claimManagedRelayReferralCommand, {
@@ -56,7 +137,7 @@ export function SettingsReferralsRouteScreen() {
   const [isClaiming, setIsClaiming] = useState(false);
   const iconColor = useThemeColor("--color-icon");
   const iconSuccess = useThemeColor("--color-success");
-  const inputPlaceholder = useThemeColor("--color-foreground-muted");
+  const primaryForeground = useThemeColor("--color-primary-foreground");
   const summary = summaryState.data;
   const referralLink = summary
     ? buildReferralLink(DEFAULT_HOSTED_APP_URL, summary.referralCode)
@@ -87,125 +168,169 @@ export function SettingsReferralsRouteScreen() {
     );
   };
 
+  const shareReferral = () => {
+    if (!referralLink) return;
+    void Share.share(
+      {
+        title: REFERRAL_SHARE_TITLE,
+        message: buildReferralShareMessage(referralLink),
+      },
+      {
+        dialogTitle: "Share referral link",
+        subject: REFERRAL_SHARE_TITLE,
+      },
+    );
+  };
+
   if (!isSignedIn) {
     return (
-      <View className="flex-1 items-center justify-center bg-sheet px-8">
-        <Text className="text-center text-base text-foreground-muted">
-          Sign in to your T3 account to view referral points.
-        </Text>
+      <View className="flex-1 bg-sheet">
+        {Platform.OS === "android" ? (
+          <>
+            <NativeStackScreenOptions options={{ headerShown: false }} />
+            <AndroidScreenHeader title="Referrals" onBack={() => navigation.goBack()} />
+          </>
+        ) : null}
+        <View className="flex-1 items-center justify-center px-8">
+          <Text className="text-center text-base text-foreground-muted">
+            Sign in to your T3 account to view referral points.
+          </Text>
+        </View>
       </View>
     );
   }
 
   return (
     <View collapsable={false} className="flex-1 bg-sheet">
+      {Platform.OS === "android" ? (
+        <>
+          <NativeStackScreenOptions options={{ headerShown: false }} />
+          <AndroidScreenHeader title="Referrals" onBack={() => navigation.goBack()} />
+        </>
+      ) : null}
       <ScrollView
         contentInsetAdjustmentBehavior="automatic"
         showsVerticalScrollIndicator={false}
         className="flex-1"
-        contentContainerClassName="gap-5 px-5 pt-4"
+        contentContainerClassName="gap-6 px-5 pt-4"
         contentContainerStyle={{ paddingBottom: Math.max(insets.bottom, 18) + 18 }}
       >
-        <Text className="px-1 text-sm leading-5 text-foreground-muted">
-          Earn 67 points when someone you invite links their first T3 Code environment. Points stay
-          with your T3 account on every device.
-        </Text>
-
         {summaryState.error ? (
-          <View className="gap-3 rounded-[24px] border border-danger-border bg-card p-5">
-            <Text className="font-t3-bold text-danger-foreground">Could not load referrals</Text>
-            <Text className="text-sm text-foreground-muted">{summaryState.error}</Text>
-            <ConnectionSheetButton
-              compact
-              icon="arrow.clockwise"
-              label="Try again"
-              onPress={summaryState.refresh}
-            />
-          </View>
+          <SettingsSection card title="Referral points">
+            <View className="gap-3 p-4">
+              <Text className="text-base text-danger-foreground">
+                Could not load referral points
+              </Text>
+              <Text className="text-sm text-foreground-muted">{summaryState.error}</Text>
+              <Pressable
+                accessibilityRole="button"
+                className="self-start rounded-full bg-secondary px-4 py-2.5 active:opacity-60"
+                onPress={summaryState.refresh}
+              >
+                <Text className="font-t3-medium text-secondary-foreground">Try again</Text>
+              </Pressable>
+            </View>
+          </SettingsSection>
         ) : summary === null ? (
-          <View className="items-center justify-center py-16">
-            <ActivityIndicator />
-          </View>
+          <SettingsSection card title="Your referrals">
+            <View className="items-center justify-center py-12">
+              <ActivityIndicator />
+            </View>
+          </SettingsSection>
         ) : (
           <>
-            <View className="flex-row gap-3">
-              <View className="flex-1 rounded-[24px] bg-card p-4">
-                <Text className="text-sm text-foreground-muted">Points</Text>
-                <Text className="mt-1 text-3xl font-t3-bold text-foreground">{summary.points}</Text>
-              </View>
-              <View className="flex-1 rounded-[24px] bg-card p-4">
-                <Text className="text-sm text-foreground-muted">Referrals</Text>
-                <Text className="mt-1 text-3xl font-t3-bold text-foreground">
-                  {summary.qualifiedReferrals}
-                </Text>
-                {summary.pendingReferrals > 0 ? (
-                  <Text className="mt-1 text-xs text-foreground-muted">
-                    {summary.pendingReferrals} pending
-                  </Text>
-                ) : null}
-              </View>
+            <View className="gap-3">
+              <SettingsSection card title="Your referrals">
+                <View className="flex-row">
+                  <ReferralMetric label="Points" value={summary.points} />
+                  <ReferralMetric divided label="Successful" value={summary.qualifiedReferrals} />
+                  <ReferralMetric divided label="Pending" value={summary.pendingReferrals} />
+                </View>
+              </SettingsSection>
+              <Text className="px-2 text-sm leading-normal text-foreground-muted">
+                Points belong to your T3 account, so this balance is the same on web, desktop, and
+                mobile.
+              </Text>
             </View>
 
-            <View className="gap-4 rounded-[24px] bg-card p-5">
-              <View className="gap-1">
-                <Text className="text-lg font-t3-bold text-foreground">Invite someone</Text>
-                <Text className="text-sm leading-5 text-foreground-muted">
-                  They must claim your code before linking their first environment.
-                </Text>
-              </View>
-              <View className="flex-row items-center gap-3 rounded-[16px] border border-input-border bg-input px-4 py-3">
-                <Text className="min-w-0 flex-1 text-sm text-foreground" numberOfLines={1}>
-                  {summary.referralCode}
-                </Text>
-                <CopyTextButton
-                  accessibilityLabel="Copy referral code"
-                  text={summary.referralCode}
-                  tintColor={iconColor}
-                  copiedTintColor={iconSuccess}
+            <View className="gap-3">
+              <SettingsSection card title="Invite someone">
+                <View className="flex-row items-center gap-4 p-4">
+                  <SymbolView
+                    name="link"
+                    size={22}
+                    tintColor={iconColor}
+                    type="monochrome"
+                    weight="regular"
+                  />
+                  <View className="min-w-0 flex-1 gap-0.5">
+                    <Text className="text-lg text-foreground">Referral code</Text>
+                    <Text
+                      selectable
+                      className="font-mono text-sm tracking-[0.5px] text-foreground-muted"
+                      numberOfLines={1}
+                    >
+                      {summary.referralCode}
+                    </Text>
+                  </View>
+                  <CopyTextButton
+                    accessibilityLabel="Copy referral code"
+                    text={summary.referralCode}
+                    tintColor={iconColor}
+                    copiedTintColor={iconSuccess}
+                  />
+                </View>
+                <ReferralActionRow
+                  icon="arrow.up.right"
+                  label="Share referral link"
+                  detail={referralLink}
+                  disabled={!referralLink}
+                  onPress={shareReferral}
                 />
-              </View>
-              <ConnectionSheetButton
-                icon="arrow.up.right"
-                label="Share referral link"
-                tone="primary"
-                onPress={() => {
-                  void Share.share({
-                    message: `Join me on T3 Code. Claim referral code ${summary.referralCode}: ${referralLink}`,
-                    url: referralLink,
-                  });
-                }}
-              />
+              </SettingsSection>
+              <Text className="px-2 text-sm leading-normal text-foreground-muted">
+                Your friend must claim the link before linking their first environment. You receive
+                67 points after that environment connects.
+              </Text>
             </View>
 
             {!summary.hasClaimedReferral ? (
-              <View className="gap-4 rounded-[24px] bg-card p-5">
-                <View className="gap-1">
-                  <Text className="text-lg font-t3-bold text-foreground">
-                    Have a referral code?
-                  </Text>
-                  <Text className="text-sm leading-5 text-foreground-muted">
-                    Apply it before linking your first environment.
-                  </Text>
-                </View>
-                <TextInput
-                  autoCapitalize="characters"
-                  autoCorrect={false}
-                  editable={!isClaiming}
-                  maxLength={19}
-                  placeholder="ABCD1234EFAB5678"
-                  placeholderTextColor={inputPlaceholder}
-                  value={referralCode}
-                  onChangeText={setReferralCode}
-                  onSubmitEditing={() => void submitReferralCode()}
-                  className="rounded-[16px] border border-input-border bg-input px-4 py-3.5 text-base text-foreground"
-                />
-                <ConnectionSheetButton
-                  icon="checkmark"
-                  label={isClaiming ? "Applying..." : "Apply code"}
-                  disabled={isClaiming}
-                  tone="primary"
-                  onPress={() => void submitReferralCode()}
-                />
+              <View className="gap-3">
+                <SettingsSection card title="Use a referral code">
+                  <View className="gap-3 p-4">
+                    <TextInput
+                      accessibilityLabel="Referral code"
+                      autoCapitalize="characters"
+                      autoCorrect={false}
+                      editable={!isClaiming}
+                      maxLength={19}
+                      placeholder="ABCD1234EFAB5678"
+                      returnKeyType="done"
+                      value={referralCode}
+                      onChangeText={setReferralCode}
+                      onSubmitEditing={() => void submitReferralCode()}
+                    />
+                    <Pressable
+                      accessibilityLabel={
+                        isClaiming ? "Applying referral code" : "Apply referral code"
+                      }
+                      accessibilityRole="button"
+                      accessibilityState={{ disabled: isClaiming }}
+                      className="min-h-[46px] items-center justify-center rounded-[14px] bg-primary px-4 active:opacity-70 disabled:opacity-50"
+                      disabled={isClaiming}
+                      onPress={() => void submitReferralCode()}
+                    >
+                      {isClaiming ? (
+                        <ActivityIndicator color={primaryForeground} />
+                      ) : (
+                        <Text className="font-t3-medium text-primary-foreground">Apply code</Text>
+                      )}
+                    </Pressable>
+                  </View>
+                </SettingsSection>
+                <Text className="px-2 text-sm leading-normal text-foreground-muted">
+                  Apply a code before you link your first T3 Code environment.
+                </Text>
               </View>
             ) : null}
           </>
diff --git a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
index 5f29997a6ab0..6fe24dff9296 100644
--- a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
+++ b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
@@ -3,8 +3,9 @@ import {
   squashAtomCommandFailure,
 } from "@t3tools/client-runtime/state/runtime";
 import type { RelayReferralClaimResult } from "@t3tools/contracts/relay";
-import { CheckIcon, CopyIcon, GiftIcon, TicketCheckIcon } from "lucide-react";
-import { useMemo, useState } from "react";
+import { REFERRAL_SHARE_TEXT, REFERRAL_SHARE_TITLE } from "@t3tools/shared/referral";
+import { CheckIcon, CopyIcon, GiftIcon, LinkIcon, Share2Icon, TicketCheckIcon } from "lucide-react";
+import { type ReactNode, useMemo, useState } from "react";
 
 import {
   claimManagedRelayReferralCommand,
@@ -47,6 +48,46 @@ function claimResultMessage(result: RelayReferralClaimResult): {
   }
 }
 
+function ReferralMetric(props: { readonly label: string; readonly value: number }) {
+  return (
+    <div className="min-w-0 px-3 py-4 first:pl-0 last:pr-0 sm:px-5">
+      <dt className="text-[0.6875rem] leading-4 font-medium text-muted-foreground">
+        {props.label}
+      </dt>
+      <dd className="mt-0.5 text-[1.625rem] leading-8 font-semibold tracking-tight tabular-nums">
+        {props.value}
+      </dd>
+    </div>
+  );
+}
+
+function ReferralSectionHeading({
+  icon,
+  title,
+  description,
+}: {
+  readonly icon: ReactNode;
+  readonly title: string;
+  readonly description: string;
+}) {
+  return (
+    <div className="flex items-start gap-3">
+      <div
+        aria-hidden="true"
+        className="flex size-8 shrink-0 items-center justify-center rounded-lg border bg-muted/32 text-muted-foreground"
+      >
+        {icon}
+      </div>
+      <div className="min-w-0 pt-0.5">
+        <h3 className="text-sm font-semibold">{title}</h3>
+        <p className="mt-0.5 max-w-[30rem] text-xs leading-5 text-muted-foreground">
+          {description}
+        </p>
+      </div>
+    </div>
+  );
+}
+
 export function ReferralsUserProfilePage() {
   const summaryState = useManagedRelayReferralSummary();
   const claimReferral = useAtomCommand(claimManagedRelayReferralCommand, {
@@ -54,7 +95,7 @@ export function ReferralsUserProfilePage() {
   });
   const [referralCode, setReferralCode] = useState("");
   const [isClaiming, setIsClaiming] = useState(false);
-  const { copyToClipboard, isCopied } = useCopyToClipboard({
+  const { copyToClipboard: copyReferralLink, isCopied: isLinkCopied } = useCopyToClipboard({
     target: "referral link",
     onCopy: () => toastManager.add({ type: "success", title: "Referral link copied" }),
     onError: (error) =>
@@ -64,11 +105,22 @@ export function ReferralsUserProfilePage() {
         description: error.message,
       }),
   });
+  const { copyToClipboard: copyReferralCode, isCopied: isCodeCopied } = useCopyToClipboard({
+    target: "referral code",
+    onCopy: () => toastManager.add({ type: "success", title: "Referral code copied" }),
+    onError: (error) =>
+      toastManager.add({
+        type: "error",
+        title: "Could not copy referral code",
+        description: error.message,
+      }),
+  });
   const summary = summaryState.data;
   const referralLink = useMemo(
     () => (summary ? buildReferralLink(configuredHostedAppUrl(), summary.referralCode) : null),
     [summary],
   );
+  const canShare = typeof navigator !== "undefined" && typeof navigator.share === "function";
 
   const submitReferralCode = async () => {
     const accountId = summaryState.accountId;
@@ -99,13 +151,36 @@ export function ReferralsUserProfilePage() {
     });
   };
 
+  const shareReferral = async () => {
+    if (!referralLink) return;
+    if (!canShare) {
+      await copyReferralLink(referralLink);
+      return;
+    }
+
+    try {
+      await navigator.share({
+        title: REFERRAL_SHARE_TITLE,
+        text: REFERRAL_SHARE_TEXT,
+        url: referralLink,
+      });
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") return;
+      toastManager.add({
+        type: "error",
+        title: "Could not share referral link",
+        description: error instanceof Error ? error.message : "Try copying the link instead.",
+      });
+    }
+  };
+
   const isInitialLoad =
     !summaryState.accountId || (summaryState.data === null && !summaryState.error);
 
   return (
     <ClerkUserProfilePage
       title="Referrals"
-      description="Earn 67 points when someone you invite links their first T3 Code environment. Your points follow your T3 account across devices."
+      description="Earn 67 points when a friend claims your link before connecting their first environment. Your balance follows your T3 account."
       action={
         <ClerkUserProfileRefreshButton
           disabled={isClaiming}
@@ -123,77 +198,91 @@ export function ReferralsUserProfilePage() {
 
       {isInitialLoad ? (
         <div
-          className="grid gap-3 border-t py-5 sm:grid-cols-3"
+          className="grid grid-cols-3 divide-x border-y"
           aria-label="Loading referrals"
           role="status"
         >
-          <Skeleton className="h-24 rounded-xl" />
-          <Skeleton className="h-24 rounded-xl" />
-          <Skeleton className="h-24 rounded-xl" />
+          <div className="py-5 pr-4">
+            <Skeleton className="h-11 rounded-lg" />
+          </div>
+          <div className="px-4 py-5">
+            <Skeleton className="h-11 rounded-lg" />
+          </div>
+          <div className="py-5 pl-4">
+            <Skeleton className="h-11 rounded-lg" />
+          </div>
         </div>
       ) : summary ? (
-        <div className="space-y-6 border-t py-5">
-          <div className="grid gap-3 sm:grid-cols-3">
-            <div className="rounded-xl border bg-muted/24 p-4">
-              <p className="text-xs font-medium text-muted-foreground">Points</p>
-              <p className="mt-1 text-3xl font-semibold tracking-tight">{summary.points}</p>
-            </div>
-            <div className="rounded-xl border bg-muted/24 p-4">
-              <p className="text-xs font-medium text-muted-foreground">Successful referrals</p>
-              <p className="mt-1 text-3xl font-semibold tracking-tight">
-                {summary.qualifiedReferrals}
-              </p>
-            </div>
-            <div className="rounded-xl border bg-muted/24 p-4">
-              <p className="text-xs font-medium text-muted-foreground">Pending</p>
-              <p className="mt-1 text-3xl font-semibold tracking-tight">
-                {summary.pendingReferrals}
-              </p>
-            </div>
-          </div>
+        <div className="border-t">
+          <dl className="grid grid-cols-3 divide-x border-b">
+            <ReferralMetric label="Points" value={summary.points} />
+            <ReferralMetric label="Successful" value={summary.qualifiedReferrals} />
+            <ReferralMetric label="Pending" value={summary.pendingReferrals} />
+          </dl>
 
-          <section>
-            <div className="flex items-center gap-2">
-              <GiftIcon className="size-4 text-muted-foreground" aria-hidden="true" />
-              <h3 className="text-sm font-semibold">Invite someone</h3>
-            </div>
-            <p className="mt-1 text-xs leading-5 text-muted-foreground">
-              They must claim the code before linking their first environment.
-            </p>
-            <div className="mt-3 flex gap-2">
-              <Input
-                nativeInput
-                readOnly
-                size="sm"
-                value={referralLink ?? ""}
-                aria-label="Referral link"
-              />
-              <Button
-                size="sm"
-                variant="outline"
-                disabled={!referralLink}
-                onClick={() => copyToClipboard(referralLink ?? "")}
-              >
-                {isCopied ? (
-                  <CheckIcon className="size-3.5" aria-hidden="true" />
-                ) : (
-                  <CopyIcon className="size-3.5" aria-hidden="true" />
-                )}
-                {isCopied ? "Copied" : "Copy"}
-              </Button>
+          <section className="border-b py-5">
+            <ReferralSectionHeading
+              icon={<GiftIcon className="size-4" />}
+              title="Invite someone"
+              description="They need to claim your link before linking their first T3 Code environment."
+            />
+            <div className="mt-4 space-y-2 sm:ml-11">
+              <div className="flex flex-col gap-2 sm:flex-row">
+                <div className="min-w-0 flex-1 rounded-lg border bg-muted/24 px-3 py-2.5">
+                  <div className="flex items-center gap-1.5 text-[0.6875rem] font-medium text-muted-foreground">
+                    <LinkIcon className="size-3" aria-hidden="true" />
+                    Referral link
+                  </div>
+                  <p className="mt-0.5 truncate text-xs">{referralLink}</p>
+                </div>
+                <Button
+                  size="sm"
+                  variant="outline"
+                  className="shrink-0"
+                  disabled={!referralLink}
+                  onClick={() => void shareReferral()}
+                >
+                  {canShare ? (
+                    <Share2Icon className="size-3.5" aria-hidden="true" />
+                  ) : isLinkCopied ? (
+                    <CheckIcon className="size-3.5" aria-hidden="true" />
+                  ) : (
+                    <CopyIcon className="size-3.5" aria-hidden="true" />
+                  )}
+                  {canShare ? "Share" : isLinkCopied ? "Copied" : "Copy link"}
+                </Button>
+              </div>
+              <div className="flex items-center justify-between gap-3 px-1 py-1">
+                <div className="min-w-0">
+                  <span className="text-[0.6875rem] font-medium text-muted-foreground">
+                    Referral code
+                  </span>
+                  <code className="ml-2 text-xs tracking-[0.04em]">{summary.referralCode}</code>
+                </div>
+                <Button
+                  size="icon-xs"
+                  variant="ghost-muted"
+                  aria-label={isCodeCopied ? "Referral code copied" : "Copy referral code"}
+                  onClick={() => copyReferralCode(summary.referralCode)}
+                >
+                  {isCodeCopied ? (
+                    <CheckIcon className="size-3.5" aria-hidden="true" />
+                  ) : (
+                    <CopyIcon className="size-3.5" aria-hidden="true" />
+                  )}
+                </Button>
+              </div>
             </div>
-            <p className="mt-2 font-mono text-xs text-muted-foreground">
-              Code: {summary.referralCode}
-            </p>
           </section>
 
           {!summary.hasClaimedReferral ? (
-            <section className="rounded-xl border bg-muted/16 p-4">
-              <div className="flex items-center gap-2">
-                <TicketCheckIcon className="size-4 text-muted-foreground" aria-hidden="true" />
-                <h3 className="text-sm font-semibold">Have a referral code?</h3>
-              </div>
-              <div className="mt-3 flex gap-2">
+            <section className="py-5">
+              <ReferralSectionHeading
+                icon={<TicketCheckIcon className="size-4" />}
+                title="Use a referral code"
+                description="Apply it before linking your first environment."
+              />
+              <div className="mt-4 flex flex-col gap-2 sm:ml-11 sm:flex-row">
                 <Input
                   nativeInput
                   size="sm"
@@ -206,8 +295,13 @@ export function ReferralsUserProfilePage() {
                     if (event.key === "Enter") void submitReferralCode();
                   }}
                 />
-                <Button size="sm" disabled={isClaiming} onClick={() => void submitReferralCode()}>
-                  {isClaiming ? "Applying..." : "Apply"}
+                <Button
+                  size="sm"
+                  className="shrink-0"
+                  disabled={isClaiming}
+                  onClick={() => void submitReferralCode()}
+                >
+                  {isClaiming ? "Applying..." : "Apply code"}
                 </Button>
               </div>
             </section>
diff --git a/apps/web/src/components/clerk/useT3ConnectAuthPrompt.tsx b/apps/web/src/components/clerk/useT3ConnectAuthPrompt.tsx
index 859a122ffe4b..c05b6fe687de 100644
--- a/apps/web/src/components/clerk/useT3ConnectAuthPrompt.tsx
+++ b/apps/web/src/components/clerk/useT3ConnectAuthPrompt.tsx
@@ -1,12 +1,13 @@
 import { useClerk } from "@clerk/react";
+import { useCallback } from "react";
 
 import { isElectron } from "../../env";
 import { resolveClerkSignInProps } from "./authRedirect";
 
 export function useT3ConnectAuthPrompt() {
   const clerk = useClerk();
-  const openAuthPrompt = () => {
+  const openAuthPrompt = useCallback(() => {
     clerk.openSignIn(resolveClerkSignInProps(window.location.href, isElectron));
-  };
+  }, [clerk]);
   return { authPrompt: null, openAuthPrompt };
 }
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
index 88fa314bb3b5..c8258c517204 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
@@ -6,7 +6,7 @@ import {
   squashAtomCommandFailure,
 } from "@t3tools/client-runtime/state/runtime";
 import type { RelayReferralClaimResult } from "@t3tools/contracts/relay";
-import { useEffect, useRef } from "react";
+import { useEffect, useRef, useState } from "react";
 
 import {
   claimManagedRelayReferralCommand,
@@ -19,6 +19,7 @@ import {
   urlWithoutReferralCode,
 } from "../../cloud/referralLinks";
 import { useAtomCommand } from "../../state/use-atom-command";
+import { useT3ConnectAuthPrompt } from "../clerk/useT3ConnectAuthPrompt";
 import { toastManager } from "../ui/toast";
 
 function clearPendingReferralCode(): void {
@@ -37,16 +38,17 @@ function readPendingReferralCode(): string | null {
   }
 }
 
-function captureReferralCode(): void {
+function captureReferralCode(): string | null {
   const url = new URL(window.location.href);
   const referralCode = referralCodeFromUrl(url);
-  if (!referralCode) return;
+  if (!referralCode) return null;
   try {
     window.localStorage.setItem(PENDING_REFERRAL_CODE_STORAGE_KEY, referralCode);
   } catch {
-    return;
+    // Keep the code in component state for this tab when storage is unavailable.
   }
   window.history.replaceState(window.history.state, "", urlWithoutReferralCode(url));
+  return referralCode;
 }
 
 function showClaimResult(result: RelayReferralClaimResult): void {
@@ -86,16 +88,31 @@ function ConfiguredReferralClaimCoordinator() {
     reportFailure: false,
   });
   const relayAccountId = useAtomValue(managedRelaySessionAtom)?.accountId ?? null;
+  const { authPrompt, openAuthPrompt } = useT3ConnectAuthPrompt();
+  const [pendingReferralCode, setPendingReferralCode] = useState<string | null>(null);
   const activeClaimRef = useRef<string | null>(null);
   const completedClaimRef = useRef<string | null>(null);
+  const promptedSignInRef = useRef<string | null>(null);
 
   useEffect(() => {
-    captureReferralCode();
+    setPendingReferralCode(captureReferralCode() ?? readPendingReferralCode());
   }, []);
 
+  useEffect(() => {
+    if (!isLoaded || isSignedIn || !pendingReferralCode) return;
+    if (promptedSignInRef.current === pendingReferralCode) return;
+    promptedSignInRef.current = pendingReferralCode;
+    toastManager.add({
+      type: "info",
+      title: "Referral link ready",
+      description: "Sign in to claim it before linking your first environment.",
+    });
+    openAuthPrompt();
+  }, [isLoaded, isSignedIn, openAuthPrompt, pendingReferralCode]);
+
   useEffect(() => {
     if (!isLoaded || !isSignedIn || !userId || relayAccountId !== userId) return;
-    const referralCode = readPendingReferralCode();
+    const referralCode = pendingReferralCode ?? readPendingReferralCode();
     if (!referralCode) return;
     const attemptKey = `${userId}:${referralCode}`;
     if (activeClaimRef.current === attemptKey || completedClaimRef.current === attemptKey) return;
@@ -107,6 +124,7 @@ function ConfiguredReferralClaimCoordinator() {
         if (result._tag === "Success") {
           completedClaimRef.current = attemptKey;
           clearPendingReferralCode();
+          setPendingReferralCode(null);
           refreshManagedRelayReferralSummary();
           showClaimResult(result.value.result);
           return;
@@ -118,7 +136,7 @@ function ConfiguredReferralClaimCoordinator() {
         if (activeClaimRef.current === attemptKey) activeClaimRef.current = null;
       }
     })();
-  }, [claimReferral, isLoaded, isSignedIn, relayAccountId, userId]);
+  }, [claimReferral, isLoaded, isSignedIn, pendingReferralCode, relayAccountId, userId]);
 
-  return null;
+  return authPrompt;
 }
diff --git a/docs/user/referrals.md b/docs/user/referrals.md
index 33b01651298f..29df3b3384db 100644
--- a/docs/user/referrals.md
+++ b/docs/user/referrals.md
@@ -6,6 +6,10 @@ balance on web, desktop, or mobile, even when you use a different machine.
 Open your account menu and choose **Referrals** to find your referral link and code. On mobile, open
 **Settings → Account → Referrals**.
 
+Referral links open the hosted T3 Code app. If the recipient is signed out, T3 Code saves the code
+and opens sign-in. It claims the referral after that account signs in. The shared message states
+that the referrer receives the 67 points; it does not promise points to the recipient.
+
 You earn 67 points when someone:
 
 1. Opens your referral link or enters your code while signed in.
diff --git a/packages/shared/src/referral.test.ts b/packages/shared/src/referral.test.ts
index 5e6e15cfc0da..f92f5cc6c8c9 100644
--- a/packages/shared/src/referral.test.ts
+++ b/packages/shared/src/referral.test.ts
@@ -1,6 +1,12 @@
 import { describe, expect, it } from "vite-plus/test";
 
-import { buildReferralLink, normalizeReferralCode } from "./referral.js";
+import {
+  buildReferralLink,
+  buildReferralShareMessage,
+  normalizeReferralCode,
+  REFERRAL_SHARE_TEXT,
+  REFERRAL_SHARE_TITLE,
+} from "./referral.js";
 
 describe("referral", () => {
   it("normalizes referral codes shared with separators", () => {
@@ -9,8 +15,21 @@ describe("referral", () => {
   });
 
   it("builds a hosted referral link", () => {
-    expect(buildReferralLink("https://app.t3.codes", "ABCD1234EFAB5678")).toBe(
+    expect(buildReferralLink("https://app.t3.codes/somewhere", "abcd-1234-efab-5678")).toBe(
       "https://app.t3.codes/?ref=ABCD1234EFAB5678",
     );
   });
+
+  it("rejects malformed referral links before they can be shared", () => {
+    expect(() => buildReferralLink("https://app.t3.codes", "not-a-code")).toThrow(
+      "valid 16-character referral code",
+    );
+  });
+
+  it("builds accurate cross-platform share copy", () => {
+    const link = "https://app.t3.codes/?ref=ABCD1234EFAB5678";
+    expect(REFERRAL_SHARE_TITLE).toBe("T3 Code referral");
+    expect(buildReferralShareMessage(link)).toBe(`${REFERRAL_SHARE_TEXT}\n${link}`);
+    expect(buildReferralShareMessage(link)).toContain("I get 67 points");
+  });
 });
diff --git a/packages/shared/src/referral.ts b/packages/shared/src/referral.ts
index 2e11e5b3c0e0..61d859f2d9f7 100644
--- a/packages/shared/src/referral.ts
+++ b/packages/shared/src/referral.ts
@@ -1,5 +1,8 @@
 export const REFERRAL_CODE_LENGTH = 16;
 const REFERRAL_CODE_PATTERN = new RegExp(`^[A-F0-9]{${REFERRAL_CODE_LENGTH}}$`, "u");
+export const REFERRAL_SHARE_TITLE = "T3 Code referral";
+export const REFERRAL_SHARE_TEXT =
+  "Try T3 Code with my referral. If you claim it before linking your first environment, I get 67 points.";
 
 export function normalizeReferralCode(value: string): string | null {
   const code = value.trim().replaceAll("-", "").toUpperCase();
@@ -7,7 +10,15 @@ export function normalizeReferralCode(value: string): string | null {
 }
 
 export function buildReferralLink(hostedAppUrl: string, referralCode: string): string {
+  const normalized = normalizeReferralCode(referralCode);
+  if (!normalized) {
+    throw new Error("Referral links require a valid 16-character referral code.");
+  }
   const url = new URL("/", hostedAppUrl);
-  url.searchParams.set("ref", referralCode);
+  url.searchParams.set("ref", normalized);
   return url.toString();
 }
+
+export function buildReferralShareMessage(referralLink: string): string {
+  return `${REFERRAL_SHARE_TEXT}\n${referralLink}`;
+}

From 5b0294728c7f528f8087a70ba83b34a0f96bc28a Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 10:39:18 +0530
Subject: [PATCH 08/29] fix(web): align referral profile controls

---
 .../components/clerk/ClerkUserProfilePage.tsx  | 18 ++++++++++++------
 .../clerk/ReferralsUserProfilePage.tsx         | 15 +++++++--------
 2 files changed, 19 insertions(+), 14 deletions(-)

diff --git a/apps/web/src/components/clerk/ClerkUserProfilePage.tsx b/apps/web/src/components/clerk/ClerkUserProfilePage.tsx
index 00f20e53fbe1..6732a67dfe51 100644
--- a/apps/web/src/components/clerk/ClerkUserProfilePage.tsx
+++ b/apps/web/src/components/clerk/ClerkUserProfilePage.tsx
@@ -61,6 +61,17 @@ export function ClerkUserProfileRefreshButton({
   );
 }
 
+export function ClerkUserProfileIcon({ children }: { readonly children: ReactNode }) {
+  return (
+    <div
+      aria-hidden="true"
+      className="flex size-8 shrink-0 items-center justify-center rounded-lg border bg-muted/32 text-muted-foreground"
+    >
+      {children}
+    </div>
+  );
+}
+
 export function ClerkUserProfileRow({
   children,
   className,
@@ -73,12 +84,7 @@ export function ClerkUserProfileRow({
   return (
     <li className={cn("border-t py-4 first:border-t-0", className)}>
       <div className="flex items-start gap-3">
-        <div
-          aria-hidden="true"
-          className="flex size-8 shrink-0 items-center justify-center rounded-lg border bg-muted/32 text-muted-foreground"
-        >
-          {icon}
-        </div>
+        <ClerkUserProfileIcon>{icon}</ClerkUserProfileIcon>
         <div className="min-w-0 flex-1">{children}</div>
       </div>
     </li>
diff --git a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
index 6fe24dff9296..04f0af59e67c 100644
--- a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
+++ b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
@@ -19,7 +19,11 @@ import { Button } from "../ui/button";
 import { Input } from "../ui/input";
 import { Skeleton } from "../ui/skeleton";
 import { toastManager } from "../ui/toast";
-import { ClerkUserProfilePage, ClerkUserProfileRefreshButton } from "./ClerkUserProfilePage";
+import {
+  ClerkUserProfileIcon,
+  ClerkUserProfilePage,
+  ClerkUserProfileRefreshButton,
+} from "./ClerkUserProfilePage";
 
 function claimResultMessage(result: RelayReferralClaimResult): {
   readonly type: "success" | "warning" | "info";
@@ -72,12 +76,7 @@ function ReferralSectionHeading({
 }) {
   return (
     <div className="flex items-start gap-3">
-      <div
-        aria-hidden="true"
-        className="flex size-8 shrink-0 items-center justify-center rounded-lg border bg-muted/32 text-muted-foreground"
-      >
-        {icon}
-      </div>
+      <ClerkUserProfileIcon>{icon}</ClerkUserProfileIcon>
       <div className="min-w-0 pt-0.5">
         <h3 className="text-sm font-semibold">{title}</h3>
         <p className="mt-0.5 max-w-[30rem] text-xs leading-5 text-muted-foreground">
@@ -227,7 +226,7 @@ export function ReferralsUserProfilePage() {
               description="They need to claim your link before linking their first T3 Code environment."
             />
             <div className="mt-4 space-y-2 sm:ml-11">
-              <div className="flex flex-col gap-2 sm:flex-row">
+              <div className="flex flex-col gap-2 sm:flex-row sm:items-center">
                 <div className="min-w-0 flex-1 rounded-lg border bg-muted/24 px-3 py-2.5">
                   <div className="flex items-center gap-1.5 text-[0.6875rem] font-medium text-muted-foreground">
                     <LinkIcon className="size-3" aria-hidden="true" />

From 9142846e0042d841adb38726d220fa50be01a272 Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 11:04:20 +0530
Subject: [PATCH 09/29] fix(web): preserve referrals when storage fails

---
 apps/web/src/cloud/referralLinks.test.ts      | 21 ++++++++++++++++-
 apps/web/src/cloud/referralLinks.ts           | 16 +++++++++++++
 .../cloud/ReferralClaimCoordinator.tsx        | 23 +++++++++++--------
 3 files changed, 50 insertions(+), 10 deletions(-)

diff --git a/apps/web/src/cloud/referralLinks.test.ts b/apps/web/src/cloud/referralLinks.test.ts
index e10a54b59f82..dfbe57cc6e4e 100644
--- a/apps/web/src/cloud/referralLinks.test.ts
+++ b/apps/web/src/cloud/referralLinks.test.ts
@@ -1,6 +1,10 @@
 import { describe, expect, it } from "vite-plus/test";
 
-import { referralCodeFromUrl, urlWithoutReferralCode } from "./referralLinks";
+import {
+  captureReferralCodeFromUrl,
+  referralCodeFromUrl,
+  urlWithoutReferralCode,
+} from "./referralLinks";
 
 describe("referralLinks", () => {
   it("reads and removes only the referral parameter", () => {
@@ -8,4 +12,19 @@ describe("referralLinks", () => {
     expect(referralCodeFromUrl(url)).toBe("ABCD1234EFAB5678");
     expect(urlWithoutReferralCode(url)).toBe("/?channel=nightly#thread");
   });
+
+  it("only cleans the URL after the referral code is persisted", () => {
+    const url = new URL("https://app.t3.codes/?ref=abcd1234efab5678#thread");
+
+    expect(
+      captureReferralCodeFromUrl(url, () => {
+        throw new Error("storage unavailable");
+      }),
+    ).toEqual({ referralCode: "ABCD1234EFAB5678", cleanedUrl: null });
+
+    expect(captureReferralCodeFromUrl(url, () => undefined)).toEqual({
+      referralCode: "ABCD1234EFAB5678",
+      cleanedUrl: "/#thread",
+    });
+  });
 });
diff --git a/apps/web/src/cloud/referralLinks.ts b/apps/web/src/cloud/referralLinks.ts
index 42aa223935b5..2e274c9f1aca 100644
--- a/apps/web/src/cloud/referralLinks.ts
+++ b/apps/web/src/cloud/referralLinks.ts
@@ -12,4 +12,20 @@ export function urlWithoutReferralCode(url: URL): string {
   return `${next.pathname}${next.search}${next.hash}`;
 }
 
+export function captureReferralCodeFromUrl(
+  url: URL,
+  persist: (referralCode: string) => void,
+): { referralCode: string; cleanedUrl: string | null } | null {
+  const referralCode = referralCodeFromUrl(url);
+  if (!referralCode) return null;
+
+  try {
+    persist(referralCode);
+  } catch {
+    return { referralCode, cleanedUrl: null };
+  }
+
+  return { referralCode, cleanedUrl: urlWithoutReferralCode(url) };
+}
+
 export { buildReferralLink, normalizeReferralCode };
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
index c8258c517204..a66c1f94c3bc 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
@@ -14,6 +14,7 @@ import {
 } from "../../cloud/managedRelayState";
 import { hasCloudPublicConfig } from "../../cloud/publicConfig";
 import {
+  captureReferralCodeFromUrl,
   PENDING_REFERRAL_CODE_STORAGE_KEY,
   referralCodeFromUrl,
   urlWithoutReferralCode,
@@ -25,9 +26,7 @@ import { toastManager } from "../ui/toast";
 function clearPendingReferralCode(): void {
   try {
     window.localStorage.removeItem(PENDING_REFERRAL_CODE_STORAGE_KEY);
-  } catch {
-    // The referral query parameter still gets removed when storage is unavailable.
-  }
+  } catch {}
 }
 
 function readPendingReferralCode(): string | null {
@@ -40,15 +39,20 @@ function readPendingReferralCode(): string | null {
 
 function captureReferralCode(): string | null {
   const url = new URL(window.location.href);
-  const referralCode = referralCodeFromUrl(url);
-  if (!referralCode) return null;
-  try {
+  const captured = captureReferralCodeFromUrl(url, (referralCode) => {
     window.localStorage.setItem(PENDING_REFERRAL_CODE_STORAGE_KEY, referralCode);
-  } catch {
-    // Keep the code in component state for this tab when storage is unavailable.
+  });
+  if (!captured) return null;
+  if (captured.cleanedUrl) {
+    window.history.replaceState(window.history.state, "", captured.cleanedUrl);
   }
+  return captured.referralCode;
+}
+
+function clearReferralCodeFromUrl(): void {
+  const url = new URL(window.location.href);
+  if (!referralCodeFromUrl(url)) return;
   window.history.replaceState(window.history.state, "", urlWithoutReferralCode(url));
-  return referralCode;
 }
 
 function showClaimResult(result: RelayReferralClaimResult): void {
@@ -124,6 +128,7 @@ function ConfiguredReferralClaimCoordinator() {
         if (result._tag === "Success") {
           completedClaimRef.current = attemptKey;
           clearPendingReferralCode();
+          clearReferralCodeFromUrl();
           setPendingReferralCode(null);
           refreshManagedRelayReferralSummary();
           showClaimResult(result.value.result);

From 7faa241f1275e8862262755a4f53d5885ce36ae2 Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 11:14:44 +0530
Subject: [PATCH 10/29] fix(web): retry automatic referral claims

---
 .../ReferralClaimCoordinator.logic.test.ts    | 39 +++++++++++++++++++
 .../cloud/ReferralClaimCoordinator.logic.ts   | 26 +++++++++++++
 .../cloud/ReferralClaimCoordinator.tsx        | 31 ++++++++++++---
 3 files changed, 90 insertions(+), 6 deletions(-)
 create mode 100644 apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts
 create mode 100644 apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts

diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts
new file mode 100644
index 000000000000..0c009a5dd68a
--- /dev/null
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { claimReferralWithRetry } from "./ReferralClaimCoordinator.logic";
+
+describe("claimReferralWithRetry", () => {
+  it("retries transient failures with bounded backoff", async () => {
+    const results = ["failure", "failure", "success"] as const;
+    const delays: number[] = [];
+    let attempts = 0;
+
+    const result = await claimReferralWithRetry({
+      claim: async () => results[attempts++] ?? "failure",
+      shouldRetry: (claimResult) => claimResult === "failure",
+      wait: async (delay) => {
+        delays.push(delay);
+      },
+    });
+
+    expect(result).toBe("success");
+    expect(attempts).toBe(3);
+    expect(delays).toEqual([250, 1_000]);
+  });
+
+  it("stops after three retries", async () => {
+    let attempts = 0;
+
+    const result = await claimReferralWithRetry({
+      claim: async () => {
+        attempts += 1;
+        return "failure";
+      },
+      shouldRetry: () => true,
+      wait: async () => undefined,
+    });
+
+    expect(result).toBe("failure");
+    expect(attempts).toBe(4);
+  });
+});
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts
new file mode 100644
index 000000000000..d76af70e9b49
--- /dev/null
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts
@@ -0,0 +1,26 @@
+const REFERRAL_CLAIM_RETRY_DELAYS_MS = [250, 1_000, 3_000] as const;
+
+function waitForRetry(delay: number): Promise<void> {
+  return new Promise((resolve) => globalThis.setTimeout(resolve, delay));
+}
+
+export async function claimReferralWithRetry<Result>({
+  claim,
+  shouldRetry,
+  wait = waitForRetry,
+}: {
+  readonly claim: () => Promise<Result>;
+  readonly shouldRetry: (result: Result) => boolean;
+  readonly wait?: (delay: number) => Promise<void>;
+}): Promise<Result> {
+  let failedAttempts = 0;
+  while (true) {
+    const result = await claim();
+    if (!shouldRetry(result)) return result;
+
+    const retryDelay = REFERRAL_CLAIM_RETRY_DELAYS_MS[failedAttempts];
+    if (retryDelay === undefined) return result;
+    failedAttempts += 1;
+    await wait(retryDelay);
+  }
+}
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
index a66c1f94c3bc..673d18d2e313 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
@@ -22,6 +22,7 @@ import {
 import { useAtomCommand } from "../../state/use-atom-command";
 import { useT3ConnectAuthPrompt } from "../clerk/useT3ConnectAuthPrompt";
 import { toastManager } from "../ui/toast";
+import { claimReferralWithRetry } from "./ReferralClaimCoordinator.logic";
 
 function clearPendingReferralCode(): void {
   try {
@@ -119,12 +120,18 @@ function ConfiguredReferralClaimCoordinator() {
     const referralCode = pendingReferralCode ?? readPendingReferralCode();
     if (!referralCode) return;
     const attemptKey = `${userId}:${referralCode}`;
-    if (activeClaimRef.current === attemptKey || completedClaimRef.current === attemptKey) return;
-    activeClaimRef.current = attemptKey;
 
-    void (async () => {
+    const runClaim = async () => {
+      if (activeClaimRef.current === attemptKey || completedClaimRef.current === attemptKey) return;
+      activeClaimRef.current = attemptKey;
       try {
-        const result = await claimReferral({ accountId: userId, referralCode });
+        const result = await claimReferralWithRetry({
+          claim: () => claimReferral({ accountId: userId, referralCode }),
+          shouldRetry: (claimResult) =>
+            activeClaimRef.current === attemptKey &&
+            claimResult._tag !== "Success" &&
+            !isAtomCommandInterrupted(claimResult),
+        });
         if (result._tag === "Success") {
           completedClaimRef.current = attemptKey;
           clearPendingReferralCode();
@@ -134,13 +141,25 @@ function ConfiguredReferralClaimCoordinator() {
           showClaimResult(result.value.result);
           return;
         }
-        if (isAtomCommandInterrupted(result)) return;
+        if (activeClaimRef.current !== attemptKey || isAtomCommandInterrupted(result)) return;
         const cause = squashAtomCommandFailure(result);
         console.error("[t3-cloud] Could not claim captured referral code", { cause });
+        toastManager.add({
+          type: "error",
+          title: "Referral still pending",
+          description: "Retry before linking an environment so your referrer can receive points.",
+          timeout: 0,
+          actionProps: {
+            children: "Retry",
+            onClick: () => void runClaim(),
+          },
+        });
       } finally {
         if (activeClaimRef.current === attemptKey) activeClaimRef.current = null;
       }
-    })();
+    };
+
+    void runClaim();
   }, [claimReferral, isLoaded, isSignedIn, pendingReferralCode, relayAccountId, userId]);
 
   return authPrompt;

From e25c1302102e75478c2aee33d2d62f246aaa001d Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 11:24:32 +0530
Subject: [PATCH 11/29] fix(web): keep referral sign-in user initiated

---
 .../cloud/ReferralClaimCoordinator.logic.test.ts  | 15 ++++++++++++++-
 .../cloud/ReferralClaimCoordinator.logic.ts       | 10 ++++++++++
 .../components/cloud/ReferralClaimCoordinator.tsx | 13 ++++++++++---
 3 files changed, 34 insertions(+), 4 deletions(-)

diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts
index 0c009a5dd68a..92a83c868456 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts
@@ -1,6 +1,19 @@
 import { describe, expect, it } from "vite-plus/test";
 
-import { claimReferralWithRetry } from "./ReferralClaimCoordinator.logic";
+import { claimReferralWithRetry, referralClaimLoadState } from "./ReferralClaimCoordinator.logic";
+
+describe("referralClaimLoadState", () => {
+  it("only prompts sign-in for a referral captured on the current load", () => {
+    expect(referralClaimLoadState("FROM_URL", "FROM_STORAGE")).toEqual({
+      referralCode: "FROM_URL",
+      shouldPromptSignIn: true,
+    });
+    expect(referralClaimLoadState(null, "FROM_STORAGE")).toEqual({
+      referralCode: "FROM_STORAGE",
+      shouldPromptSignIn: false,
+    });
+  });
+});
 
 describe("claimReferralWithRetry", () => {
   it("retries transient failures with bounded backoff", async () => {
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts
index d76af70e9b49..ee437a6b88ef 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts
@@ -4,6 +4,16 @@ function waitForRetry(delay: number): Promise<void> {
   return new Promise((resolve) => globalThis.setTimeout(resolve, delay));
 }
 
+export function referralClaimLoadState(
+  capturedCode: string | null,
+  storedCode: string | null,
+): { referralCode: string | null; shouldPromptSignIn: boolean } {
+  return {
+    referralCode: capturedCode ?? storedCode,
+    shouldPromptSignIn: capturedCode !== null,
+  };
+}
+
 export async function claimReferralWithRetry<Result>({
   claim,
   shouldRetry,
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
index 673d18d2e313..4d1d8c6c9256 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
@@ -22,7 +22,7 @@ import {
 import { useAtomCommand } from "../../state/use-atom-command";
 import { useT3ConnectAuthPrompt } from "../clerk/useT3ConnectAuthPrompt";
 import { toastManager } from "../ui/toast";
-import { claimReferralWithRetry } from "./ReferralClaimCoordinator.logic";
+import { claimReferralWithRetry, referralClaimLoadState } from "./ReferralClaimCoordinator.logic";
 
 function clearPendingReferralCode(): void {
   try {
@@ -98,13 +98,20 @@ function ConfiguredReferralClaimCoordinator() {
   const activeClaimRef = useRef<string | null>(null);
   const completedClaimRef = useRef<string | null>(null);
   const promptedSignInRef = useRef<string | null>(null);
+  const shouldPromptSignInRef = useRef(false);
 
   useEffect(() => {
-    setPendingReferralCode(captureReferralCode() ?? readPendingReferralCode());
+    const capturedCode = captureReferralCode();
+    const initial = referralClaimLoadState(
+      capturedCode,
+      capturedCode ? null : readPendingReferralCode(),
+    );
+    shouldPromptSignInRef.current = initial.shouldPromptSignIn;
+    setPendingReferralCode(initial.referralCode);
   }, []);
 
   useEffect(() => {
-    if (!isLoaded || isSignedIn || !pendingReferralCode) return;
+    if (!isLoaded || isSignedIn || !pendingReferralCode || !shouldPromptSignInRef.current) return;
     if (promptedSignInRef.current === pendingReferralCode) return;
     promptedSignInRef.current = pendingReferralCode;
     toastManager.add({

From 37c4b4bedc80b6cb195c8be82bcaf6a59d089bb6 Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 11:39:56 +0530
Subject: [PATCH 12/29] fix(referrals): recover failed awards and share links

---
 apps/web/src/cloud/referralLinks.test.ts      | 12 +++++
 apps/web/src/cloud/referralLinks.ts           | 15 +++++-
 .../clerk/ReferralsUserProfilePage.tsx        | 13 +++--
 infra/relay/src/http/Api.ts                   |  1 +
 .../src/referrals/ReferralProgram.test.ts     | 28 +++++++---
 infra/relay/src/referrals/ReferralProgram.ts  | 53 ++++++++++++++++++-
 infra/relay/src/worker.ts                     |  7 ++-
 7 files changed, 113 insertions(+), 16 deletions(-)

diff --git a/apps/web/src/cloud/referralLinks.test.ts b/apps/web/src/cloud/referralLinks.test.ts
index dfbe57cc6e4e..99f7d080ec74 100644
--- a/apps/web/src/cloud/referralLinks.test.ts
+++ b/apps/web/src/cloud/referralLinks.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vite-plus/test";
 
 import {
+  buildReferralShareData,
   captureReferralCodeFromUrl,
   referralCodeFromUrl,
   urlWithoutReferralCode,
@@ -27,4 +28,15 @@ describe("referralLinks", () => {
       cleanedUrl: "/#thread",
     });
   });
+
+  it("embeds the claim URL in web share text even when a share target drops the url field", () => {
+    const referralLink = "https://app.t3.codes/?ref=ABCD1234EFAB5678";
+    const shareData = buildReferralShareData(referralLink);
+
+    expect(shareData).toMatchObject({
+      title: "T3 Code referral",
+      url: referralLink,
+    });
+    expect(shareData.text).toContain(referralLink);
+  });
 });
diff --git a/apps/web/src/cloud/referralLinks.ts b/apps/web/src/cloud/referralLinks.ts
index 2e274c9f1aca..db7cc5266d10 100644
--- a/apps/web/src/cloud/referralLinks.ts
+++ b/apps/web/src/cloud/referralLinks.ts
@@ -1,4 +1,9 @@
-import { buildReferralLink, normalizeReferralCode } from "@t3tools/shared/referral";
+import {
+  buildReferralLink,
+  buildReferralShareMessage,
+  normalizeReferralCode,
+  REFERRAL_SHARE_TITLE,
+} from "@t3tools/shared/referral";
 
 export const PENDING_REFERRAL_CODE_STORAGE_KEY = "t3code.pending-referral-code";
 
@@ -28,4 +33,12 @@ export function captureReferralCodeFromUrl(
   return { referralCode, cleanedUrl: urlWithoutReferralCode(url) };
 }
 
+export function buildReferralShareData(referralLink: string) {
+  return {
+    title: REFERRAL_SHARE_TITLE,
+    text: buildReferralShareMessage(referralLink),
+    url: referralLink,
+  };
+}
+
 export { buildReferralLink, normalizeReferralCode };
diff --git a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
index 04f0af59e67c..699e64547a0a 100644
--- a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
+++ b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
@@ -3,7 +3,6 @@ import {
   squashAtomCommandFailure,
 } from "@t3tools/client-runtime/state/runtime";
 import type { RelayReferralClaimResult } from "@t3tools/contracts/relay";
-import { REFERRAL_SHARE_TEXT, REFERRAL_SHARE_TITLE } from "@t3tools/shared/referral";
 import { CheckIcon, CopyIcon, GiftIcon, LinkIcon, Share2Icon, TicketCheckIcon } from "lucide-react";
 import { type ReactNode, useMemo, useState } from "react";
 
@@ -11,7 +10,11 @@ import {
   claimManagedRelayReferralCommand,
   useManagedRelayReferralSummary,
 } from "../../cloud/managedRelayState";
-import { buildReferralLink, normalizeReferralCode } from "../../cloud/referralLinks";
+import {
+  buildReferralLink,
+  buildReferralShareData,
+  normalizeReferralCode,
+} from "../../cloud/referralLinks";
 import { configuredHostedAppUrl } from "../../hostedPairing";
 import { useCopyToClipboard } from "../../hooks/useCopyToClipboard";
 import { useAtomCommand } from "../../state/use-atom-command";
@@ -158,11 +161,7 @@ export function ReferralsUserProfilePage() {
     }
 
     try {
-      await navigator.share({
-        title: REFERRAL_SHARE_TITLE,
-        text: REFERRAL_SHARE_TEXT,
-        url: referralLink,
-      });
+      await navigator.share(buildReferralShareData(referralLink));
     } catch (error) {
       if (error instanceof Error && error.name === "AbortError") return;
       toastManager.add({
diff --git a/infra/relay/src/http/Api.ts b/infra/relay/src/http/Api.ts
index 21b4b77f0f8c..4c134df39435 100644
--- a/infra/relay/src/http/Api.ts
+++ b/infra/relay/src/http/Api.ts
@@ -554,6 +554,7 @@ export const clientApi = HttpApiBuilder.group(
         "getReferralSummary",
         Effect.fn("relay.api.client.getReferralSummary")(function* () {
           const { userId } = yield* RelayClientPrincipal;
+          yield* referrals.recoverPendingAwards({ referrerUserId: userId });
           return yield* referrals.getSummary({ userId });
         }, mapRelayCommonApiErrors("not_authorized")),
       )
diff --git a/infra/relay/src/referrals/ReferralProgram.test.ts b/infra/relay/src/referrals/ReferralProgram.test.ts
index b3c5a852d2e8..e8079303a6ef 100644
--- a/infra/relay/src/referrals/ReferralProgram.test.ts
+++ b/infra/relay/src/referrals/ReferralProgram.test.ts
@@ -76,6 +76,25 @@ function makeFakeDb(state: FakeReferralState) {
               return Effect.succeed([{ referrals }]);
             }
 
+            if (
+              hasSelection(selection, "userId") &&
+              query.sql.includes('"qualified_at" is null') &&
+              query.sql.includes('from "relay_environment_links"')
+            ) {
+              const referrerUserId = query.sql.includes('"referrer_user_id" =') ? value : null;
+              return Effect.succeed(
+                [...state.accounts.values()]
+                  .filter(
+                    (row) =>
+                      row.referrerUserId !== null &&
+                      row.qualifiedAt === null &&
+                      state.environmentUsers.has(row.userId) &&
+                      (referrerUserId === null || row.referrerUserId === referrerUserId),
+                  )
+                  .map((row) => ({ userId: row.userId })),
+              );
+            }
+
             const account = hasSelection(selection, "userId")
               ? [...state.accounts.values()].find((row) => row.referralCode === value)
               : state.accounts.get(value);
@@ -299,12 +318,9 @@ describe("ReferralProgram", () => {
       });
 
       delete state.pointInsertFailure;
-      expect(
-        (yield* referrals.claim({
-          userId: "referred",
-          referralCode: referrer.referralCode,
-        })).result,
-      ).toBe("already_claimed");
+      expect(yield* referrals.recoverPendingAwards({ referrerUserId: "someone-else" })).toBe(0);
+      expect(yield* referrals.recoverPendingAwards({ referrerUserId: "referrer" })).toBe(1);
+      expect(yield* referrals.recoverPendingAwards()).toBe(0);
       expect(yield* referrals.getSummary({ userId: "referrer" })).toMatchObject({
         points: 67,
         qualifiedReferrals: 1,
diff --git a/infra/relay/src/referrals/ReferralProgram.ts b/infra/relay/src/referrals/ReferralProgram.ts
index 22396dc0e5d3..cbd3f95b00fe 100644
--- a/infra/relay/src/referrals/ReferralProgram.ts
+++ b/infra/relay/src/referrals/ReferralProgram.ts
@@ -32,6 +32,7 @@ export class ReferralProgramPersistenceError extends Schema.TaggedErrorClass<Ref
       "load-summary",
       "claim-referral",
       "qualify-referral",
+      "recover-referrals",
     ]),
     userId: Schema.String,
     cause: Schema.optionalKey(Schema.Defect()),
@@ -57,6 +58,9 @@ export class ReferralProgram extends Context.Service<
     readonly qualify: (input: {
       readonly userId: string;
     }) => Effect.Effect<boolean, ReferralProgramPersistenceError>;
+    readonly recoverPendingAwards: (input?: {
+      readonly referrerUserId?: string;
+    }) => Effect.Effect<number, ReferralProgramPersistenceError>;
   }
 >()("t3code-relay/referrals/ReferralProgram") {}
 
@@ -297,6 +301,53 @@ export const make = Effect.gen(function* () {
     );
   });
 
+  const recoverPendingAwards = Effect.fn("relay.referrals.recover_pending_awards")(
+    function* (input?: { readonly referrerUserId?: string }) {
+      const pending = yield* db
+        .select({ userId: relayReferralAccounts.userId })
+        .from(relayReferralAccounts)
+        .where(
+          and(
+            isNotNull(relayReferralAccounts.referrerUserId),
+            isNull(relayReferralAccounts.qualifiedAt),
+            input?.referrerUserId
+              ? eq(relayReferralAccounts.referrerUserId, input.referrerUserId)
+              : undefined,
+            sql`exists (
+            select 1 from ${relayEnvironmentLinks}
+            where ${relayEnvironmentLinks.userId} = ${relayReferralAccounts.userId}
+          )`,
+          ),
+        )
+        .pipe(
+          Effect.mapError(
+            (cause) =>
+              new ReferralProgramPersistenceError({
+                operation: "recover-referrals",
+                userId: "system",
+                cause,
+              }),
+          ),
+        );
+      const recovered = yield* Effect.forEach(
+        pending,
+        ({ userId }) =>
+          qualify({ userId }).pipe(
+            Effect.tapError((error) =>
+              Effect.logWarning("pending referral award recovery failed", {
+                errorTag: error._tag,
+                operation: error.operation,
+                userId,
+              }),
+            ),
+            Effect.orElseSucceed(() => false),
+          ),
+        { concurrency: 4 },
+      );
+      return recovered.filter(Boolean).length;
+    },
+  );
+
   const claim = Effect.fn("relay.referrals.claim")(function* (input: {
     readonly userId: string;
     readonly referralCode: string;
@@ -387,7 +438,7 @@ export const make = Effect.gen(function* () {
     } satisfies RelayReferralClaimResponse;
   });
 
-  return ReferralProgram.of({ getSummary, claim, qualify });
+  return ReferralProgram.of({ getSummary, claim, qualify, recoverPendingAwards });
 });
 
 export const layer = Layer.effect(ReferralProgram, make);
diff --git a/infra/relay/src/worker.ts b/infra/relay/src/worker.ts
index 2504595f7b54..cb0b028840a9 100644
--- a/infra/relay/src/worker.ts
+++ b/infra/relay/src/worker.ts
@@ -276,7 +276,12 @@ export const ApiLive = Api.make(
             ),
           ),
         ),
-        Effect.withSpan("relay.cron.prune_expired_state"),
+        Effect.andThen(
+          ReferralProgram.ReferralProgram.pipe(
+            Effect.flatMap((referrals) => referrals.recoverPendingAwards()),
+          ),
+        ),
+        Effect.withSpan("relay.cron.maintenance"),
         Effect.provide(runtimeLayer),
       ),
     );

From 88385e42f90dce5f74aee174bd389f4139a44d8f Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 11:46:43 +0530
Subject: [PATCH 13/29] fix(web): align referral retry controls

---
 .../clerk/ReferralsUserProfilePage.tsx        |  4 ++++
 .../cloud/ReferralClaimCoordinator.tsx        | 23 +++++++++++--------
 2 files changed, 17 insertions(+), 10 deletions(-)

diff --git a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
index 699e64547a0a..5dc9b12b1980 100644
--- a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
+++ b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
@@ -282,8 +282,12 @@ export function ReferralsUserProfilePage() {
               />
               <div className="mt-4 flex flex-col gap-2 sm:ml-11 sm:flex-row">
                 <Input
+                  autoCapitalize="none"
+                  autoComplete="off"
+                  autoCorrect="off"
                   nativeInput
                   size="sm"
+                  spellCheck={false}
                   value={referralCode}
                   placeholder="ABCD1234EFAB5678"
                   aria-label="Referral code"
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
index 4d1d8c6c9256..e737c26615f9 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
@@ -22,6 +22,7 @@ import {
 import { useAtomCommand } from "../../state/use-atom-command";
 import { useT3ConnectAuthPrompt } from "../clerk/useT3ConnectAuthPrompt";
 import { toastManager } from "../ui/toast";
+import { stackedThreadToast } from "../ui/toastHelpers";
 import { claimReferralWithRetry, referralClaimLoadState } from "./ReferralClaimCoordinator.logic";
 
 function clearPendingReferralCode(): void {
@@ -151,16 +152,18 @@ function ConfiguredReferralClaimCoordinator() {
         if (activeClaimRef.current !== attemptKey || isAtomCommandInterrupted(result)) return;
         const cause = squashAtomCommandFailure(result);
         console.error("[t3-cloud] Could not claim captured referral code", { cause });
-        toastManager.add({
-          type: "error",
-          title: "Referral still pending",
-          description: "Retry before linking an environment so your referrer can receive points.",
-          timeout: 0,
-          actionProps: {
-            children: "Retry",
-            onClick: () => void runClaim(),
-          },
-        });
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Referral still pending",
+            description: "Retry before linking an environment so your referrer can receive points.",
+            timeout: 0,
+            actionProps: {
+              children: "Retry",
+              onClick: () => void runClaim(),
+            },
+          }),
+        );
       } finally {
         if (activeClaimRef.current === attemptKey) activeClaimRef.current = null;
       }

From 910d8f36d67a6893dd774f52e377239a8ced6781 Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 11:47:10 +0530
Subject: [PATCH 14/29] fix(web): match referral code input hints

---
 apps/web/src/components/clerk/ReferralsUserProfilePage.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
index 5dc9b12b1980..12b5d14c14c9 100644
--- a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
+++ b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
@@ -282,7 +282,7 @@ export function ReferralsUserProfilePage() {
               />
               <div className="mt-4 flex flex-col gap-2 sm:ml-11 sm:flex-row">
                 <Input
-                  autoCapitalize="none"
+                  autoCapitalize="characters"
                   autoComplete="off"
                   autoCorrect="off"
                   nativeInput

From 7d2f67a8c4dab43a20fb95eaf47e6d5c7210da37 Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 11:51:37 +0530
Subject: [PATCH 15/29] fix(web): match referral button typography

---
 apps/web/src/components/clerk/ReferralsUserProfilePage.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
index 12b5d14c14c9..6b1f5ef4c497 100644
--- a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
+++ b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
@@ -236,7 +236,7 @@ export function ReferralsUserProfilePage() {
                 <Button
                   size="sm"
                   variant="outline"
-                  className="shrink-0"
+                  className="shrink-0 text-[0.8125rem]"
                   disabled={!referralLink}
                   onClick={() => void shareReferral()}
                 >
@@ -299,7 +299,7 @@ export function ReferralsUserProfilePage() {
                 />
                 <Button
                   size="sm"
-                  className="shrink-0"
+                  className="shrink-0 text-[0.8125rem]"
                   disabled={isClaiming}
                   onClick={() => void submitReferralCode()}
                 >

From a88c6c27613f116cc645989b4af74b36bfc8c065 Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 12:04:06 +0530
Subject: [PATCH 16/29] fix(connect): keep referral summaries available

---
 infra/relay/src/http/Api.test.ts | 54 ++++++++++++++++++++++++++++++++
 infra/relay/src/http/Api.ts      | 32 +++++++++++++++++--
 2 files changed, 84 insertions(+), 2 deletions(-)

diff --git a/infra/relay/src/http/Api.test.ts b/infra/relay/src/http/Api.test.ts
index daf756a2b7cc..ad0d0b14fbe8 100644
--- a/infra/relay/src/http/Api.test.ts
+++ b/infra/relay/src/http/Api.test.ts
@@ -18,7 +18,9 @@ import { EnvironmentId } from "@t3tools/contracts";
 import { RelayEnvironmentAuth } from "@t3tools/contracts/relay";
 
 import {
+  REFERRAL_SUMMARY_RECOVERY_BUDGET_MS,
   RELAY_REQUEST_DEADLINE_MS,
+  loadReferralSummary,
   relayCors,
   relayDocsRedirectRoute,
   relayEnvironmentAuthLayer,
@@ -34,6 +36,7 @@ import * as RelayDb from "../db.ts";
 import * as EnvironmentCredentials from "../environments/EnvironmentCredentials.ts";
 import * as EnvironmentLinks from "../environments/EnvironmentLinks.ts";
 import * as ManagedEndpointProvider from "../environments/ManagedEndpointProvider.ts";
+import * as ReferralProgram from "../referrals/ReferralProgram.ts";
 
 vi.mock("@clerk/backend", () => ({
   createClerkClient: vi.fn(),
@@ -59,6 +62,57 @@ const relaySettings: RelayConfiguration.RelayConfiguration["Service"] = {
   managedEndpointNamespace: undefined,
 };
 
+const referralSummary = {
+  points: 67,
+  referralCode: "ABCDEF0123456789",
+  awardPoints: 67,
+  qualifiedReferrals: 1,
+  pendingReferrals: 0,
+  hasClaimedReferral: false,
+} as const;
+
+function referralService(
+  recoverPendingAwards: ReferralProgram.ReferralProgram["Service"]["recoverPendingAwards"],
+) {
+  return ReferralProgram.ReferralProgram.of({
+    getSummary: () => Effect.succeed(referralSummary),
+    claim: () => Effect.die("unused claim"),
+    qualify: () => Effect.die("unused qualify"),
+    recoverPendingAwards,
+  });
+}
+
+describe("relay referral summary", () => {
+  it.effect("returns the summary when pending award recovery fails", () => {
+    const failure = new ReferralProgram.ReferralProgramPersistenceError({
+      operation: "recover-referrals",
+      userId: "system",
+      cause: new Error("database unavailable"),
+    });
+    return Effect.gen(function* () {
+      expect(yield* loadReferralSummary("referrer")).toEqual(referralSummary);
+    }).pipe(
+      Effect.provideService(
+        ReferralProgram.ReferralProgram,
+        referralService(() => Effect.fail(failure)),
+      ),
+    );
+  });
+
+  it.effect("bounds pending award recovery before returning the summary", () =>
+    Effect.gen(function* () {
+      const fiber = yield* loadReferralSummary("referrer").pipe(Effect.forkChild);
+      yield* TestClock.adjust(Duration.millis(REFERRAL_SUMMARY_RECOVERY_BUDGET_MS));
+      expect(yield* Fiber.join(fiber)).toEqual(referralSummary);
+    }).pipe(
+      Effect.provideService(
+        ReferralProgram.ReferralProgram,
+        referralService(() => Effect.never),
+      ),
+    ),
+  );
+});
+
 describe("relay client authentication", () => {
   it.effect("preserves the existing Clerk session JWT path", () =>
     Effect.gen(function* () {
diff --git a/infra/relay/src/http/Api.ts b/infra/relay/src/http/Api.ts
index 4c134df39435..c2c1c491250b 100644
--- a/infra/relay/src/http/Api.ts
+++ b/infra/relay/src/http/Api.ts
@@ -166,6 +166,7 @@ export const relayDocsRedirectRoute = HttpRouter.add(
 // contains the exact child span that stalled, and the response still carries
 // the traceparent back to the client.
 export const RELAY_REQUEST_DEADLINE_MS = 9_000;
+export const REFERRAL_SUMMARY_RECOVERY_BUDGET_MS = 500;
 
 const relayRequestDeadline = <E, R>(
   httpEffect: Effect.Effect<
@@ -404,6 +405,34 @@ export const healthApi = HttpApiBuilder.group(
   }),
 );
 
+export const loadReferralSummary = Effect.fn("relay.api.client.loadReferralSummary")(function* (
+  userId: string,
+) {
+  const referrals = yield* ReferralProgram.ReferralProgram;
+  yield* referrals.recoverPendingAwards({ referrerUserId: userId }).pipe(
+    Effect.tapError((error) =>
+      Effect.logWarning("pending referral award recovery before summary failed", {
+        errorTag: error._tag,
+        operation: error.operation,
+        userId,
+      }),
+    ),
+    Effect.timeoutOption(Duration.millis(REFERRAL_SUMMARY_RECOVERY_BUDGET_MS)),
+    Effect.tap(
+      Option.match({
+        onNone: () =>
+          Effect.logWarning("pending referral award recovery before summary timed out", {
+            budgetMs: REFERRAL_SUMMARY_RECOVERY_BUDGET_MS,
+            userId,
+          }),
+        onSome: () => Effect.void,
+      }),
+    ),
+    Effect.ignore,
+  );
+  return yield* referrals.getSummary({ userId });
+});
+
 export const revokeEnvironmentLinkRecord = Effect.fn(
   "relay.api.client.revokeEnvironmentLinkRecord",
 )(function* (input: {
@@ -554,8 +583,7 @@ export const clientApi = HttpApiBuilder.group(
         "getReferralSummary",
         Effect.fn("relay.api.client.getReferralSummary")(function* () {
           const { userId } = yield* RelayClientPrincipal;
-          yield* referrals.recoverPendingAwards({ referrerUserId: userId });
-          return yield* referrals.getSummary({ userId });
+          return yield* loadReferralSummary(userId);
         }, mapRelayCommonApiErrors("not_authorized")),
       )
       .handle(

From 27567ede93634fa514e0bc88c0aa66f8e3d89edc Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 18:45:30 +0530
Subject: [PATCH 17/29] fix(web): soften referral profile surfaces

---
 .../components/clerk/ClerkUserProfilePage.tsx |   4 +-
 .../clerk/ReferralsUserProfilePage.tsx        | 214 +++++++++---------
 2 files changed, 114 insertions(+), 104 deletions(-)

diff --git a/apps/web/src/components/clerk/ClerkUserProfilePage.tsx b/apps/web/src/components/clerk/ClerkUserProfilePage.tsx
index 6732a67dfe51..1967c4da0268 100644
--- a/apps/web/src/components/clerk/ClerkUserProfilePage.tsx
+++ b/apps/web/src/components/clerk/ClerkUserProfilePage.tsx
@@ -50,7 +50,7 @@ export function ClerkUserProfileRefreshButton({
   return (
     <Button
       size="sm"
-      variant="outline"
+      variant="secondary"
       className={cn("text-[0.8125rem]", className)}
       disabled={disabled || isPending}
       onClick={onClick}
@@ -65,7 +65,7 @@ export function ClerkUserProfileIcon({ children }: { readonly children: ReactNod
   return (
     <div
       aria-hidden="true"
-      className="flex size-8 shrink-0 items-center justify-center rounded-lg border bg-muted/32 text-muted-foreground"
+      className="flex size-8 shrink-0 items-center justify-center rounded-lg bg-muted/55 text-muted-foreground"
     >
       {children}
     </div>
diff --git a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
index 6b1f5ef4c497..3a84dc193cf0 100644
--- a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
+++ b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
@@ -19,6 +19,7 @@ import { configuredHostedAppUrl } from "../../hostedPairing";
 import { useCopyToClipboard } from "../../hooks/useCopyToClipboard";
 import { useAtomCommand } from "../../state/use-atom-command";
 import { Button } from "../ui/button";
+import { Card, CardContent } from "../ui/card";
 import { Input } from "../ui/input";
 import { Skeleton } from "../ui/skeleton";
 import { toastManager } from "../ui/toast";
@@ -57,11 +58,11 @@ function claimResultMessage(result: RelayReferralClaimResult): {
 
 function ReferralMetric(props: { readonly label: string; readonly value: number }) {
   return (
-    <div className="min-w-0 px-3 py-4 first:pl-0 last:pr-0 sm:px-5">
+    <div className="min-w-0 rounded-lg px-3 py-3 sm:px-4">
       <dt className="text-[0.6875rem] leading-4 font-medium text-muted-foreground">
         {props.label}
       </dt>
-      <dd className="mt-0.5 text-[1.625rem] leading-8 font-semibold tracking-tight tabular-nums">
+      <dd className="mt-0.5 text-2xl leading-8 font-semibold tracking-tight tabular-nums">
         {props.value}
       </dd>
     </div>
@@ -188,125 +189,134 @@ export function ReferralsUserProfilePage() {
       }
     >
       {summaryState.error ? (
-        <div className="mb-4 border-t border-destructive/35 py-3 text-[0.8125rem]" role="alert">
+        <div className="mb-3 rounded-lg bg-destructive/8 px-3 py-2.5 text-[0.8125rem]" role="alert">
           <p className="font-medium text-destructive-foreground">Could not load referral points</p>
           <p className="mt-1 text-xs text-muted-foreground">{summaryState.error}</p>
         </div>
       ) : null}
 
       {isInitialLoad ? (
-        <div
-          className="grid grid-cols-3 divide-x border-y"
+        <Card
+          className="rounded-xl border-border/40 bg-muted/20 p-2 shadow-none before:hidden"
           aria-label="Loading referrals"
           role="status"
         >
-          <div className="py-5 pr-4">
-            <Skeleton className="h-11 rounded-lg" />
-          </div>
-          <div className="px-4 py-5">
-            <Skeleton className="h-11 rounded-lg" />
-          </div>
-          <div className="py-5 pl-4">
-            <Skeleton className="h-11 rounded-lg" />
+          <div className="grid grid-cols-3 gap-1.5">
+            <div className="p-2">
+              <Skeleton className="h-11 rounded-lg" />
+            </div>
+            <div className="p-2">
+              <Skeleton className="h-11 rounded-lg" />
+            </div>
+            <div className="p-2">
+              <Skeleton className="h-11 rounded-lg" />
+            </div>
           </div>
-        </div>
+        </Card>
       ) : summary ? (
-        <div className="border-t">
-          <dl className="grid grid-cols-3 divide-x border-b">
-            <ReferralMetric label="Points" value={summary.points} />
-            <ReferralMetric label="Successful" value={summary.qualifiedReferrals} />
-            <ReferralMetric label="Pending" value={summary.pendingReferrals} />
-          </dl>
+        <div className="space-y-3">
+          <Card className="rounded-xl border-border/40 bg-muted/20 p-2 shadow-none before:hidden">
+            <dl className="grid grid-cols-3 gap-1.5">
+              <ReferralMetric label="Points" value={summary.points} />
+              <ReferralMetric label="Successful" value={summary.qualifiedReferrals} />
+              <ReferralMetric label="Pending" value={summary.pendingReferrals} />
+            </dl>
+          </Card>
 
-          <section className="border-b py-5">
-            <ReferralSectionHeading
-              icon={<GiftIcon className="size-4" />}
-              title="Invite someone"
-              description="They need to claim your link before linking their first T3 Code environment."
-            />
-            <div className="mt-4 space-y-2 sm:ml-11">
-              <div className="flex flex-col gap-2 sm:flex-row sm:items-center">
-                <div className="min-w-0 flex-1 rounded-lg border bg-muted/24 px-3 py-2.5">
-                  <div className="flex items-center gap-1.5 text-[0.6875rem] font-medium text-muted-foreground">
-                    <LinkIcon className="size-3" aria-hidden="true" />
-                    Referral link
+          <Card className="rounded-xl border-border/40 bg-card/60 shadow-none before:hidden">
+            <CardContent className="p-4 sm:p-5">
+              <ReferralSectionHeading
+                icon={<GiftIcon className="size-4" />}
+                title="Invite someone"
+                description="They need to claim your link before linking their first T3 Code environment."
+              />
+              <div className="mt-4 space-y-2 sm:ml-11">
+                <div className="flex flex-col gap-2 sm:flex-row sm:items-center">
+                  <div className="min-w-0 flex-1 rounded-lg bg-muted/40 px-3 py-2.5">
+                    <div className="flex items-center gap-1.5 text-[0.6875rem] font-medium text-muted-foreground">
+                      <LinkIcon className="size-3" aria-hidden="true" />
+                      Referral link
+                    </div>
+                    <p className="mt-0.5 truncate text-xs">{referralLink}</p>
                   </div>
-                  <p className="mt-0.5 truncate text-xs">{referralLink}</p>
+                  <Button
+                    size="sm"
+                    variant="secondary"
+                    className="shrink-0 text-[0.8125rem]"
+                    disabled={!referralLink}
+                    onClick={() => void shareReferral()}
+                  >
+                    {canShare ? (
+                      <Share2Icon className="size-3.5" aria-hidden="true" />
+                    ) : isLinkCopied ? (
+                      <CheckIcon className="size-3.5" aria-hidden="true" />
+                    ) : (
+                      <CopyIcon className="size-3.5" aria-hidden="true" />
+                    )}
+                    {canShare ? "Share" : isLinkCopied ? "Copied" : "Copy link"}
+                  </Button>
                 </div>
-                <Button
-                  size="sm"
-                  variant="outline"
-                  className="shrink-0 text-[0.8125rem]"
-                  disabled={!referralLink}
-                  onClick={() => void shareReferral()}
-                >
-                  {canShare ? (
-                    <Share2Icon className="size-3.5" aria-hidden="true" />
-                  ) : isLinkCopied ? (
-                    <CheckIcon className="size-3.5" aria-hidden="true" />
-                  ) : (
-                    <CopyIcon className="size-3.5" aria-hidden="true" />
-                  )}
-                  {canShare ? "Share" : isLinkCopied ? "Copied" : "Copy link"}
-                </Button>
-              </div>
-              <div className="flex items-center justify-between gap-3 px-1 py-1">
-                <div className="min-w-0">
-                  <span className="text-[0.6875rem] font-medium text-muted-foreground">
-                    Referral code
-                  </span>
-                  <code className="ml-2 text-xs tracking-[0.04em]">{summary.referralCode}</code>
+                <div className="flex items-center justify-between gap-3 px-1 py-1">
+                  <div className="min-w-0">
+                    <span className="text-[0.6875rem] font-medium text-muted-foreground">
+                      Referral code
+                    </span>
+                    <code className="ml-2 text-xs tracking-[0.04em]">{summary.referralCode}</code>
+                  </div>
+                  <Button
+                    size="icon-xs"
+                    variant="ghost-muted"
+                    aria-label={isCodeCopied ? "Referral code copied" : "Copy referral code"}
+                    onClick={() => copyReferralCode(summary.referralCode)}
+                  >
+                    {isCodeCopied ? (
+                      <CheckIcon className="size-3.5" aria-hidden="true" />
+                    ) : (
+                      <CopyIcon className="size-3.5" aria-hidden="true" />
+                    )}
+                  </Button>
                 </div>
-                <Button
-                  size="icon-xs"
-                  variant="ghost-muted"
-                  aria-label={isCodeCopied ? "Referral code copied" : "Copy referral code"}
-                  onClick={() => copyReferralCode(summary.referralCode)}
-                >
-                  {isCodeCopied ? (
-                    <CheckIcon className="size-3.5" aria-hidden="true" />
-                  ) : (
-                    <CopyIcon className="size-3.5" aria-hidden="true" />
-                  )}
-                </Button>
               </div>
-            </div>
-          </section>
+            </CardContent>
+          </Card>
 
           {!summary.hasClaimedReferral ? (
-            <section className="py-5">
-              <ReferralSectionHeading
-                icon={<TicketCheckIcon className="size-4" />}
-                title="Use a referral code"
-                description="Apply it before linking your first environment."
-              />
-              <div className="mt-4 flex flex-col gap-2 sm:ml-11 sm:flex-row">
-                <Input
-                  autoCapitalize="characters"
-                  autoComplete="off"
-                  autoCorrect="off"
-                  nativeInput
-                  size="sm"
-                  spellCheck={false}
-                  value={referralCode}
-                  placeholder="ABCD1234EFAB5678"
-                  aria-label="Referral code"
-                  disabled={isClaiming}
-                  onChange={(event) => setReferralCode(event.currentTarget.value)}
-                  onKeyDown={(event) => {
-                    if (event.key === "Enter") void submitReferralCode();
-                  }}
+            <Card className="rounded-xl border-border/40 bg-card/60 shadow-none before:hidden">
+              <CardContent className="p-4 sm:p-5">
+                <ReferralSectionHeading
+                  icon={<TicketCheckIcon className="size-4" />}
+                  title="Use a referral code"
+                  description="Apply it before linking your first environment."
                 />
-                <Button
-                  size="sm"
-                  className="shrink-0 text-[0.8125rem]"
-                  disabled={isClaiming}
-                  onClick={() => void submitReferralCode()}
-                >
-                  {isClaiming ? "Applying..." : "Apply code"}
-                </Button>
-              </div>
-            </section>
+                <div className="mt-4 flex flex-col gap-2 sm:ml-11 sm:flex-row">
+                  <Input
+                    autoCapitalize="characters"
+                    autoComplete="off"
+                    autoCorrect="off"
+                    className="border-border/45 bg-muted/28 shadow-none before:hidden dark:bg-muted/28"
+                    nativeInput
+                    size="sm"
+                    spellCheck={false}
+                    value={referralCode}
+                    placeholder="ABCD1234EFAB5678"
+                    aria-label="Referral code"
+                    disabled={isClaiming}
+                    onChange={(event) => setReferralCode(event.currentTarget.value)}
+                    onKeyDown={(event) => {
+                      if (event.key === "Enter") void submitReferralCode();
+                    }}
+                  />
+                  <Button
+                    size="sm"
+                    className="shrink-0 text-[0.8125rem]"
+                    disabled={isClaiming}
+                    onClick={() => void submitReferralCode()}
+                  >
+                    {isClaiming ? "Applying..." : "Apply code"}
+                  </Button>
+                </div>
+              </CardContent>
+            </Card>
           ) : null}
         </div>
       ) : null}

From 530afbc1b4d4e3b5cf3de34044f3b71f661e4479 Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 18:53:48 +0530
Subject: [PATCH 18/29] fix(web): ignore stale referral claims

---
 .../ReferralClaimCoordinator.logic.test.ts    | 18 +++++++++++++++++-
 .../cloud/ReferralClaimCoordinator.logic.ts   |  8 ++++++++
 .../cloud/ReferralClaimCoordinator.tsx        | 19 ++++++++++++++++---
 3 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts
index 92a83c868456..58169b5e345a 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts
@@ -1,6 +1,10 @@
 import { describe, expect, it } from "vite-plus/test";
 
-import { claimReferralWithRetry, referralClaimLoadState } from "./ReferralClaimCoordinator.logic";
+import {
+  claimReferralWithRetry,
+  isCurrentReferralClaimAttempt,
+  referralClaimLoadState,
+} from "./ReferralClaimCoordinator.logic";
 
 describe("referralClaimLoadState", () => {
   it("only prompts sign-in for a referral captured on the current load", () => {
@@ -50,3 +54,15 @@ describe("claimReferralWithRetry", () => {
     expect(attempts).toBe(4);
   });
 });
+
+describe("isCurrentReferralClaimAttempt", () => {
+  it("rejects a result after the account changes or the effect is cancelled", () => {
+    const accountAAttempt = "account-a:ABCD1234EFAB5678";
+
+    expect(isCurrentReferralClaimAttempt(false, accountAAttempt, accountAAttempt)).toBe(true);
+    expect(
+      isCurrentReferralClaimAttempt(false, "account-b:ABCD1234EFAB5678", accountAAttempt),
+    ).toBe(false);
+    expect(isCurrentReferralClaimAttempt(true, accountAAttempt, accountAAttempt)).toBe(false);
+  });
+});
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts
index ee437a6b88ef..7d6d3c196e04 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts
@@ -14,6 +14,14 @@ export function referralClaimLoadState(
   };
 }
 
+export function isCurrentReferralClaimAttempt(
+  isCancelled: boolean,
+  activeAttemptKey: string | null,
+  attemptKey: string,
+): boolean {
+  return !isCancelled && activeAttemptKey === attemptKey;
+}
+
 export async function claimReferralWithRetry<Result>({
   claim,
   shouldRetry,
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
index e737c26615f9..9e105bd0d475 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
@@ -23,7 +23,11 @@ import { useAtomCommand } from "../../state/use-atom-command";
 import { useT3ConnectAuthPrompt } from "../clerk/useT3ConnectAuthPrompt";
 import { toastManager } from "../ui/toast";
 import { stackedThreadToast } from "../ui/toastHelpers";
-import { claimReferralWithRetry, referralClaimLoadState } from "./ReferralClaimCoordinator.logic";
+import {
+  claimReferralWithRetry,
+  isCurrentReferralClaimAttempt,
+  referralClaimLoadState,
+} from "./ReferralClaimCoordinator.logic";
 
 function clearPendingReferralCode(): void {
   try {
@@ -128,19 +132,24 @@ function ConfiguredReferralClaimCoordinator() {
     const referralCode = pendingReferralCode ?? readPendingReferralCode();
     if (!referralCode) return;
     const attemptKey = `${userId}:${referralCode}`;
+    let isCancelled = false;
+    const isCurrentAttempt = () =>
+      isCurrentReferralClaimAttempt(isCancelled, activeClaimRef.current, attemptKey);
 
     const runClaim = async () => {
+      if (isCancelled) return;
       if (activeClaimRef.current === attemptKey || completedClaimRef.current === attemptKey) return;
       activeClaimRef.current = attemptKey;
       try {
         const result = await claimReferralWithRetry({
           claim: () => claimReferral({ accountId: userId, referralCode }),
           shouldRetry: (claimResult) =>
-            activeClaimRef.current === attemptKey &&
+            isCurrentAttempt() &&
             claimResult._tag !== "Success" &&
             !isAtomCommandInterrupted(claimResult),
         });
         if (result._tag === "Success") {
+          if (!isCurrentAttempt()) return;
           completedClaimRef.current = attemptKey;
           clearPendingReferralCode();
           clearReferralCodeFromUrl();
@@ -149,7 +158,7 @@ function ConfiguredReferralClaimCoordinator() {
           showClaimResult(result.value.result);
           return;
         }
-        if (activeClaimRef.current !== attemptKey || isAtomCommandInterrupted(result)) return;
+        if (!isCurrentAttempt() || isAtomCommandInterrupted(result)) return;
         const cause = squashAtomCommandFailure(result);
         console.error("[t3-cloud] Could not claim captured referral code", { cause });
         toastManager.add(
@@ -170,6 +179,10 @@ function ConfiguredReferralClaimCoordinator() {
     };
 
     void runClaim();
+    return () => {
+      isCancelled = true;
+      if (activeClaimRef.current === attemptKey) activeClaimRef.current = null;
+    };
   }, [claimReferral, isLoaded, isSignedIn, pendingReferralCode, relayAccountId, userId]);
 
   return authPrompt;

From aabdc59466eac230ceae71f56a3a60762035b995 Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 18:58:32 +0530
Subject: [PATCH 19/29] refactor(web): align referral profile primitives

---
 .../components/clerk/ClerkUserProfilePage.tsx | 15 ++++++++--
 .../clerk/ReferralsUserProfilePage.tsx        | 17 ++++-------
 apps/web/src/components/ui/card.tsx           | 28 +++++++++++++++----
 3 files changed, 41 insertions(+), 19 deletions(-)

diff --git a/apps/web/src/components/clerk/ClerkUserProfilePage.tsx b/apps/web/src/components/clerk/ClerkUserProfilePage.tsx
index 1967c4da0268..764ebbcb4e34 100644
--- a/apps/web/src/components/clerk/ClerkUserProfilePage.tsx
+++ b/apps/web/src/components/clerk/ClerkUserProfilePage.tsx
@@ -50,7 +50,7 @@ export function ClerkUserProfileRefreshButton({
   return (
     <Button
       size="sm"
-      variant="secondary"
+      variant="outline"
       className={cn("text-[0.8125rem]", className)}
       disabled={disabled || isPending}
       onClick={onClick}
@@ -61,11 +61,20 @@ export function ClerkUserProfileRefreshButton({
   );
 }
 
-export function ClerkUserProfileIcon({ children }: { readonly children: ReactNode }) {
+export function ClerkUserProfileIcon({
+  children,
+  className,
+}: {
+  readonly children: ReactNode;
+  readonly className?: string;
+}) {
   return (
     <div
       aria-hidden="true"
-      className="flex size-8 shrink-0 items-center justify-center rounded-lg bg-muted/55 text-muted-foreground"
+      className={cn(
+        "flex size-8 shrink-0 items-center justify-center rounded-lg border bg-muted/32 text-muted-foreground",
+        className,
+      )}
     >
       {children}
     </div>
diff --git a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
index 3a84dc193cf0..a3efe07af54a 100644
--- a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
+++ b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
@@ -80,7 +80,7 @@ function ReferralSectionHeading({
 }) {
   return (
     <div className="flex items-start gap-3">
-      <ClerkUserProfileIcon>{icon}</ClerkUserProfileIcon>
+      <ClerkUserProfileIcon className="border-0 bg-muted/55">{icon}</ClerkUserProfileIcon>
       <div className="min-w-0 pt-0.5">
         <h3 className="text-sm font-semibold">{title}</h3>
         <p className="mt-0.5 max-w-[30rem] text-xs leading-5 text-muted-foreground">
@@ -196,11 +196,7 @@ export function ReferralsUserProfilePage() {
       ) : null}
 
       {isInitialLoad ? (
-        <Card
-          className="rounded-xl border-border/40 bg-muted/20 p-2 shadow-none before:hidden"
-          aria-label="Loading referrals"
-          role="status"
-        >
+        <Card variant="muted" className="p-2" aria-label="Loading referrals" role="status">
           <div className="grid grid-cols-3 gap-1.5">
             <div className="p-2">
               <Skeleton className="h-11 rounded-lg" />
@@ -215,7 +211,7 @@ export function ReferralsUserProfilePage() {
         </Card>
       ) : summary ? (
         <div className="space-y-3">
-          <Card className="rounded-xl border-border/40 bg-muted/20 p-2 shadow-none before:hidden">
+          <Card variant="muted" className="p-2">
             <dl className="grid grid-cols-3 gap-1.5">
               <ReferralMetric label="Points" value={summary.points} />
               <ReferralMetric label="Successful" value={summary.qualifiedReferrals} />
@@ -223,7 +219,7 @@ export function ReferralsUserProfilePage() {
             </dl>
           </Card>
 
-          <Card className="rounded-xl border-border/40 bg-card/60 shadow-none before:hidden">
+          <Card variant="muted">
             <CardContent className="p-4 sm:p-5">
               <ReferralSectionHeading
                 icon={<GiftIcon className="size-4" />}
@@ -241,7 +237,7 @@ export function ReferralsUserProfilePage() {
                   </div>
                   <Button
                     size="sm"
-                    variant="secondary"
+                    variant="outline"
                     className="shrink-0 text-[0.8125rem]"
                     disabled={!referralLink}
                     onClick={() => void shareReferral()}
@@ -281,7 +277,7 @@ export function ReferralsUserProfilePage() {
           </Card>
 
           {!summary.hasClaimedReferral ? (
-            <Card className="rounded-xl border-border/40 bg-card/60 shadow-none before:hidden">
+            <Card variant="muted">
               <CardContent className="p-4 sm:p-5">
                 <ReferralSectionHeading
                   icon={<TicketCheckIcon className="size-4" />}
@@ -293,7 +289,6 @@ export function ReferralsUserProfilePage() {
                     autoCapitalize="characters"
                     autoComplete="off"
                     autoCorrect="off"
-                    className="border-border/45 bg-muted/28 shadow-none before:hidden dark:bg-muted/28"
                     nativeInput
                     size="sm"
                     spellCheck={false}
diff --git a/apps/web/src/components/ui/card.tsx b/apps/web/src/components/ui/card.tsx
index f1428d13d909..79a6334f1ccf 100644
--- a/apps/web/src/components/ui/card.tsx
+++ b/apps/web/src/components/ui/card.tsx
@@ -2,15 +2,32 @@
 
 import { mergeProps } from "@base-ui/react/merge-props";
 import { useRender } from "@base-ui/react/use-render";
+import { cva, type VariantProps } from "class-variance-authority";
 
 import { cn } from "~/lib/utils";
 
-function Card({ className, render, ...props }: useRender.ComponentProps<"div">) {
+const cardVariants = cva(
+  "relative flex flex-col rounded-2xl border bg-card not-dark:bg-clip-padding text-card-foreground shadow-xs/5 before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-2xl)-1px)] before:shadow-[0_1px_--theme(--color-black/4%)] dark:before:shadow-[0_-1px_--theme(--color-white/6%)]",
+  {
+    defaultVariants: {
+      variant: "default",
+    },
+    variants: {
+      variant: {
+        default: null,
+        muted: "rounded-xl border-border/40 bg-muted/20 shadow-none before:hidden",
+      },
+    },
+  },
+);
+
+type CardProps = useRender.ComponentProps<"div"> & {
+  variant?: VariantProps<typeof cardVariants>["variant"];
+};
+
+function Card({ className, render, variant, ...props }: CardProps) {
   const defaultProps = {
-    className: cn(
-      "relative flex flex-col rounded-2xl border bg-card not-dark:bg-clip-padding text-card-foreground shadow-xs/5 before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-2xl)-1px)] before:shadow-[0_1px_--theme(--color-black/4%)] dark:before:shadow-[0_-1px_--theme(--color-white/6%)]",
-      className,
-    ),
+    className: cn(cardVariants({ variant }), className),
     "data-slot": "card",
   };
 
@@ -181,6 +198,7 @@ function CardFooter({ className, render, ...props }: useRender.ComponentProps<"d
 
 export {
   Card,
+  cardVariants,
   CardFrame,
   CardFrameHeader,
   CardFrameTitle,

From ab14475c2b240c6c4c2d4f51e6fd0f92c346df37 Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 19:18:04 +0530
Subject: [PATCH 20/29] fix(relay): use full referral code entropy

---
 .../src/referrals/ReferralProgram.test.ts     | 14 +++++++++++
 infra/relay/src/referrals/ReferralProgram.ts  | 24 ++++++++-----------
 2 files changed, 24 insertions(+), 14 deletions(-)

diff --git a/infra/relay/src/referrals/ReferralProgram.test.ts b/infra/relay/src/referrals/ReferralProgram.test.ts
index e8079303a6ef..f3d84f8b466a 100644
--- a/infra/relay/src/referrals/ReferralProgram.test.ts
+++ b/infra/relay/src/referrals/ReferralProgram.test.ts
@@ -222,6 +222,20 @@ function makeState(): FakeReferralState {
 }
 
 describe("ReferralProgram", () => {
+  it.effect("uses all 64 random bits in generated referral codes", () => {
+    const state = makeState();
+    return Effect.gen(function* () {
+      const referrals = yield* ReferralProgram.ReferralProgram;
+
+      expect((yield* referrals.getSummary({ userId: "first" })).referralCode).toBe(
+        "0101010101010101",
+      );
+      expect((yield* referrals.getSummary({ userId: "second" })).referralCode).toBe(
+        "0202020202020202",
+      );
+    }).pipe(Effect.provide(makeTestLayer(state)));
+  });
+
   it.effect("awards 67 account points once when the referred account links", () => {
     const state = makeState();
     return Effect.gen(function* () {
diff --git a/infra/relay/src/referrals/ReferralProgram.ts b/infra/relay/src/referrals/ReferralProgram.ts
index cbd3f95b00fe..83a77b9dd425 100644
--- a/infra/relay/src/referrals/ReferralProgram.ts
+++ b/infra/relay/src/referrals/ReferralProgram.ts
@@ -8,6 +8,7 @@ import { and, count, eq, isNotNull, isNull, sql } from "drizzle-orm";
 import * as Context from "effect/Context";
 import * as Crypto from "effect/Crypto";
 import * as DateTime from "effect/DateTime";
+import * as Encoding from "effect/Encoding";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Schema from "effect/Schema";
@@ -64,10 +65,6 @@ export class ReferralProgram extends Context.Service<
   }
 >()("t3code-relay/referrals/ReferralProgram") {}
 
-function referralCodeFromUuid(uuid: string): string {
-  return uuid.replaceAll("-", "").slice(0, 16).toUpperCase();
-}
-
 export const make = Effect.gen(function* () {
   const crypto = yield* Crypto.Crypto;
   const db = yield* RelayDb.RelayDb;
@@ -100,16 +97,15 @@ export const make = Effect.gen(function* () {
 
     for (let attempt = 0; attempt < 5; attempt += 1) {
       const now = DateTime.formatIso(yield* DateTime.now);
-      const referralCode = referralCodeFromUuid(
-        yield* crypto.randomUUIDv4.pipe(
-          Effect.mapError(
-            (cause) =>
-              new ReferralProgramPersistenceError({
-                operation: "create-account",
-                userId,
-                cause,
-              }),
-          ),
+      const referralCode = yield* crypto.randomBytes(8).pipe(
+        Effect.map((bytes) => Encoding.encodeHex(bytes).toUpperCase()),
+        Effect.mapError(
+          (cause) =>
+            new ReferralProgramPersistenceError({
+              operation: "create-account",
+              userId,
+              cause,
+            }),
         ),
       );
       const inserted = yield* db

From 45877632d0e945b1899a417f2553a32f0bd9f0fc Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 19:32:40 +0530
Subject: [PATCH 21/29] fix(web): isolate referral claim attempts

---
 .../cloud/ReferralClaimCoordinator.logic.test.ts  | 12 ++++++++++--
 .../cloud/ReferralClaimCoordinator.logic.ts       | 10 +++++++---
 .../components/cloud/ReferralClaimCoordinator.tsx | 15 +++++++++------
 3 files changed, 26 insertions(+), 11 deletions(-)

diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts
index 58169b5e345a..a6d5d3333a6a 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts
@@ -57,12 +57,20 @@ describe("claimReferralWithRetry", () => {
 
 describe("isCurrentReferralClaimAttempt", () => {
   it("rejects a result after the account changes or the effect is cancelled", () => {
-    const accountAAttempt = "account-a:ABCD1234EFAB5678";
+    const accountAAttempt = { key: "account-a:ABCD1234EFAB5678" };
 
     expect(isCurrentReferralClaimAttempt(false, accountAAttempt, accountAAttempt)).toBe(true);
     expect(
-      isCurrentReferralClaimAttempt(false, "account-b:ABCD1234EFAB5678", accountAAttempt),
+      isCurrentReferralClaimAttempt(false, { key: "account-b:ABCD1234EFAB5678" }, accountAAttempt),
     ).toBe(false);
     expect(isCurrentReferralClaimAttempt(true, accountAAttempt, accountAAttempt)).toBe(false);
   });
+
+  it("rejects a stale result when a same-key successor is active", () => {
+    const staleAttempt = { key: "account-a:ABCD1234EFAB5678" };
+    const successorAttempt = { key: "account-a:ABCD1234EFAB5678" };
+
+    expect(isCurrentReferralClaimAttempt(false, successorAttempt, staleAttempt)).toBe(false);
+    expect(isCurrentReferralClaimAttempt(false, successorAttempt, successorAttempt)).toBe(true);
+  });
 });
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts
index 7d6d3c196e04..7d4a4adb67c5 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts
@@ -1,5 +1,9 @@
 const REFERRAL_CLAIM_RETRY_DELAYS_MS = [250, 1_000, 3_000] as const;
 
+export interface ReferralClaimAttempt {
+  readonly key: string;
+}
+
 function waitForRetry(delay: number): Promise<void> {
   return new Promise((resolve) => globalThis.setTimeout(resolve, delay));
 }
@@ -16,10 +20,10 @@ export function referralClaimLoadState(
 
 export function isCurrentReferralClaimAttempt(
   isCancelled: boolean,
-  activeAttemptKey: string | null,
-  attemptKey: string,
+  activeAttempt: ReferralClaimAttempt | null,
+  attempt: ReferralClaimAttempt,
 ): boolean {
-  return !isCancelled && activeAttemptKey === attemptKey;
+  return !isCancelled && activeAttempt === attempt;
 }
 
 export async function claimReferralWithRetry<Result>({
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
index 9e105bd0d475..19a822116bbf 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
@@ -26,6 +26,7 @@ import { stackedThreadToast } from "../ui/toastHelpers";
 import {
   claimReferralWithRetry,
   isCurrentReferralClaimAttempt,
+  type ReferralClaimAttempt,
   referralClaimLoadState,
 } from "./ReferralClaimCoordinator.logic";
 
@@ -100,7 +101,7 @@ function ConfiguredReferralClaimCoordinator() {
   const relayAccountId = useAtomValue(managedRelaySessionAtom)?.accountId ?? null;
   const { authPrompt, openAuthPrompt } = useT3ConnectAuthPrompt();
   const [pendingReferralCode, setPendingReferralCode] = useState<string | null>(null);
-  const activeClaimRef = useRef<string | null>(null);
+  const activeClaimRef = useRef<ReferralClaimAttempt | null>(null);
   const completedClaimRef = useRef<string | null>(null);
   const promptedSignInRef = useRef<string | null>(null);
   const shouldPromptSignInRef = useRef(false);
@@ -132,14 +133,16 @@ function ConfiguredReferralClaimCoordinator() {
     const referralCode = pendingReferralCode ?? readPendingReferralCode();
     if (!referralCode) return;
     const attemptKey = `${userId}:${referralCode}`;
+    const attempt = { key: attemptKey };
     let isCancelled = false;
     const isCurrentAttempt = () =>
-      isCurrentReferralClaimAttempt(isCancelled, activeClaimRef.current, attemptKey);
+      isCurrentReferralClaimAttempt(isCancelled, activeClaimRef.current, attempt);
 
     const runClaim = async () => {
       if (isCancelled) return;
-      if (activeClaimRef.current === attemptKey || completedClaimRef.current === attemptKey) return;
-      activeClaimRef.current = attemptKey;
+      if (activeClaimRef.current?.key === attemptKey || completedClaimRef.current === attemptKey)
+        return;
+      activeClaimRef.current = attempt;
       try {
         const result = await claimReferralWithRetry({
           claim: () => claimReferral({ accountId: userId, referralCode }),
@@ -174,14 +177,14 @@ function ConfiguredReferralClaimCoordinator() {
           }),
         );
       } finally {
-        if (activeClaimRef.current === attemptKey) activeClaimRef.current = null;
+        if (activeClaimRef.current === attempt) activeClaimRef.current = null;
       }
     };
 
     void runClaim();
     return () => {
       isCancelled = true;
-      if (activeClaimRef.current === attemptKey) activeClaimRef.current = null;
+      if (activeClaimRef.current === attempt) activeClaimRef.current = null;
     };
   }, [claimReferral, isLoaded, isSignedIn, pendingReferralCode, relayAccountId, userId]);
 

From 2076e9a382492add486854d2190bc01afaddefd0 Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 19:42:07 +0530
Subject: [PATCH 22/29] fix(web): capture referral links before auth

---
 apps/web/src/cloud/referralLinks.test.ts      |  8 +++
 apps/web/src/cloud/referralLinks.ts           |  9 +++
 .../cloud/ReferralClaimCoordinator.tsx        | 19 ++++---
 apps/web/src/routes/__root.tsx                | 57 ++++++++++---------
 4 files changed, 60 insertions(+), 33 deletions(-)

diff --git a/apps/web/src/cloud/referralLinks.test.ts b/apps/web/src/cloud/referralLinks.test.ts
index 99f7d080ec74..56d8c8afa9d3 100644
--- a/apps/web/src/cloud/referralLinks.test.ts
+++ b/apps/web/src/cloud/referralLinks.test.ts
@@ -4,6 +4,7 @@ import {
   buildReferralShareData,
   captureReferralCodeFromUrl,
   referralCodeFromUrl,
+  urlWithoutMatchingReferralCode,
   urlWithoutReferralCode,
 } from "./referralLinks";
 
@@ -29,6 +30,13 @@ describe("referralLinks", () => {
     });
   });
 
+  it("does not clear a newer referral from the current URL", () => {
+    const currentUrl = new URL("https://app.t3.codes/?ref=BBBBBBBBBBBBBBBB#thread");
+
+    expect(urlWithoutMatchingReferralCode(currentUrl, "AAAAAAAAAAAAAAAA")).toBeNull();
+    expect(urlWithoutMatchingReferralCode(currentUrl, "bbbbbbbbbbbbbbbb")).toBe("/#thread");
+  });
+
   it("embeds the claim URL in web share text even when a share target drops the url field", () => {
     const referralLink = "https://app.t3.codes/?ref=ABCD1234EFAB5678";
     const shareData = buildReferralShareData(referralLink);
diff --git a/apps/web/src/cloud/referralLinks.ts b/apps/web/src/cloud/referralLinks.ts
index db7cc5266d10..ecd9b47292ad 100644
--- a/apps/web/src/cloud/referralLinks.ts
+++ b/apps/web/src/cloud/referralLinks.ts
@@ -17,6 +17,15 @@ export function urlWithoutReferralCode(url: URL): string {
   return `${next.pathname}${next.search}${next.hash}`;
 }
 
+export function urlWithoutMatchingReferralCode(
+  url: URL,
+  expectedReferralCode: string,
+): string | null {
+  const expected = normalizeReferralCode(expectedReferralCode);
+  if (!expected || referralCodeFromUrl(url) !== expected) return null;
+  return urlWithoutReferralCode(url);
+}
+
 export function captureReferralCodeFromUrl(
   url: URL,
   persist: (referralCode: string) => void,
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
index 19a822116bbf..fd5d26bfa595 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
@@ -6,6 +6,7 @@ import {
   squashAtomCommandFailure,
 } from "@t3tools/client-runtime/state/runtime";
 import type { RelayReferralClaimResult } from "@t3tools/contracts/relay";
+import { useLocation } from "@tanstack/react-router";
 import { useEffect, useRef, useState } from "react";
 
 import {
@@ -16,8 +17,7 @@ import { hasCloudPublicConfig } from "../../cloud/publicConfig";
 import {
   captureReferralCodeFromUrl,
   PENDING_REFERRAL_CODE_STORAGE_KEY,
-  referralCodeFromUrl,
-  urlWithoutReferralCode,
+  urlWithoutMatchingReferralCode,
 } from "../../cloud/referralLinks";
 import { useAtomCommand } from "../../state/use-atom-command";
 import { useT3ConnectAuthPrompt } from "../clerk/useT3ConnectAuthPrompt";
@@ -56,10 +56,11 @@ function captureReferralCode(): string | null {
   return captured.referralCode;
 }
 
-function clearReferralCodeFromUrl(): void {
+function clearReferralCodeFromUrl(referralCode: string): void {
   const url = new URL(window.location.href);
-  if (!referralCodeFromUrl(url)) return;
-  window.history.replaceState(window.history.state, "", urlWithoutReferralCode(url));
+  const cleanedUrl = urlWithoutMatchingReferralCode(url, referralCode);
+  if (!cleanedUrl) return;
+  window.history.replaceState(window.history.state, "", cleanedUrl);
 }
 
 function showClaimResult(result: RelayReferralClaimResult): void {
@@ -95,6 +96,7 @@ export function ReferralClaimCoordinator() {
 
 function ConfiguredReferralClaimCoordinator() {
   const { isLoaded, isSignedIn, userId } = useAuth({ treatPendingAsSignedOut: false });
+  const locationHref = useLocation({ select: (location) => location.href });
   const claimReferral = useAtomCommand(claimManagedRelayReferralCommand, {
     reportFailure: false,
   });
@@ -103,18 +105,21 @@ function ConfiguredReferralClaimCoordinator() {
   const [pendingReferralCode, setPendingReferralCode] = useState<string | null>(null);
   const activeClaimRef = useRef<ReferralClaimAttempt | null>(null);
   const completedClaimRef = useRef<string | null>(null);
+  const initializedReferralRef = useRef(false);
   const promptedSignInRef = useRef<string | null>(null);
   const shouldPromptSignInRef = useRef(false);
 
   useEffect(() => {
     const capturedCode = captureReferralCode();
+    if (!capturedCode && initializedReferralRef.current) return;
+    initializedReferralRef.current = true;
     const initial = referralClaimLoadState(
       capturedCode,
       capturedCode ? null : readPendingReferralCode(),
     );
     shouldPromptSignInRef.current = initial.shouldPromptSignIn;
     setPendingReferralCode(initial.referralCode);
-  }, []);
+  }, [locationHref]);
 
   useEffect(() => {
     if (!isLoaded || isSignedIn || !pendingReferralCode || !shouldPromptSignInRef.current) return;
@@ -155,7 +160,7 @@ function ConfiguredReferralClaimCoordinator() {
           if (!isCurrentAttempt()) return;
           completedClaimRef.current = attemptKey;
           clearPendingReferralCode();
-          clearReferralCodeFromUrl();
+          clearReferralCodeFromUrl(referralCode);
           setPendingReferralCode(null);
           refreshManagedRelayReferralSummary();
           showClaimResult(result.value.result);
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index d4d6dbcf33ba..2fddf59c56de 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -112,14 +112,8 @@ function RootRouteView() {
     );
   }
 
-  if (authGateState.status !== "authenticated" && authGateState.status !== "hosted-static") {
-    return (
-      <>
-        <DocumentTitleSync />
-        <Outlet />
-      </>
-    );
-  }
+  const hasAppShell =
+    authGateState.status === "authenticated" || authGateState.status === "hosted-static";
 
   const appShell = (
     <CommandPalette>
@@ -129,28 +123,39 @@ function RootRouteView() {
     </CommandPalette>
   );
 
+  const routeContent = hasAppShell ? (
+    <>
+      <DocumentTitleSync />
+      <ContrastAppearanceSync />
+      <GlassAppearanceSync />
+      <FontAppearanceSync />
+      {primaryEnvironmentAuthenticated ? <AuthenticatedTracingBootstrap /> : null}
+      <RelayClientInstallDialog />
+      <ConnectOnboardingDialog />
+      <SshPasswordPromptDialog />
+      <ConfirmDialogHost />
+      <SlowRpcRequestToastCoordinator />
+      <HostedStaticEnvironmentBootstrap />
+      {primaryEnvironmentAuthenticated ? <EventRouter /> : null}
+      {primaryEnvironmentAuthenticated ? <PlanAgentSelectionHeal /> : null}
+      {primaryEnvironmentAuthenticated ? <ProviderUpdateLaunchNotification /> : null}
+      {appShell}
+      {/* Above the router: a theme draft is judged by walking the app, so the
+          editor has to survive navigation away from settings. */}
+      <ThemeEditorHost />
+    </>
+  ) : (
+    <>
+      <DocumentTitleSync />
+      <Outlet />
+    </>
+  );
+
   return (
     <ToastProvider>
       <AnchoredToastProvider>
-        <DocumentTitleSync />
-        <ContrastAppearanceSync />
-        <GlassAppearanceSync />
-        <FontAppearanceSync />
-        {primaryEnvironmentAuthenticated ? <AuthenticatedTracingBootstrap /> : null}
-        <RelayClientInstallDialog />
         <ReferralClaimCoordinator />
-        <ConnectOnboardingDialog />
-        <SshPasswordPromptDialog />
-        <ConfirmDialogHost />
-        <SlowRpcRequestToastCoordinator />
-        <HostedStaticEnvironmentBootstrap />
-        {primaryEnvironmentAuthenticated ? <EventRouter /> : null}
-        {primaryEnvironmentAuthenticated ? <PlanAgentSelectionHeal /> : null}
-        {primaryEnvironmentAuthenticated ? <ProviderUpdateLaunchNotification /> : null}
-        {appShell}
-        {/* Above the router: a theme draft is judged by walking the app, so the
-            editor has to survive navigation away from settings. */}
-        <ThemeEditorHost />
+        {routeContent}
       </AnchoredToastProvider>
     </ToastProvider>
   );

From 8d86cc6bfba4d50e8ed20d15881a16ceb46d0f01 Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 19:46:18 +0530
Subject: [PATCH 23/29] fix(web): stop superseded referral retries

---
 .../ReferralClaimCoordinator.logic.test.ts    | 20 +++++++++++++++++++
 .../cloud/ReferralClaimCoordinator.logic.ts   |  3 +++
 .../cloud/ReferralClaimCoordinator.tsx        |  1 +
 3 files changed, 24 insertions(+)

diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts
index a6d5d3333a6a..6689293c717e 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts
@@ -53,6 +53,26 @@ describe("claimReferralWithRetry", () => {
     expect(result).toBe("failure");
     expect(attempts).toBe(4);
   });
+
+  it("does not retry after cancellation during backoff", async () => {
+    let attempts = 0;
+    let isCurrent = true;
+
+    const result = await claimReferralWithRetry({
+      claim: async () => {
+        attempts += 1;
+        return "failure";
+      },
+      shouldContinue: () => isCurrent,
+      shouldRetry: () => true,
+      wait: async () => {
+        isCurrent = false;
+      },
+    });
+
+    expect(result).toBe("failure");
+    expect(attempts).toBe(1);
+  });
 });
 
 describe("isCurrentReferralClaimAttempt", () => {
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts
index 7d4a4adb67c5..fa362f3a4e04 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts
@@ -28,10 +28,12 @@ export function isCurrentReferralClaimAttempt(
 
 export async function claimReferralWithRetry<Result>({
   claim,
+  shouldContinue = () => true,
   shouldRetry,
   wait = waitForRetry,
 }: {
   readonly claim: () => Promise<Result>;
+  readonly shouldContinue?: () => boolean;
   readonly shouldRetry: (result: Result) => boolean;
   readonly wait?: (delay: number) => Promise<void>;
 }): Promise<Result> {
@@ -44,5 +46,6 @@ export async function claimReferralWithRetry<Result>({
     if (retryDelay === undefined) return result;
     failedAttempts += 1;
     await wait(retryDelay);
+    if (!shouldContinue()) return result;
   }
 }
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
index fd5d26bfa595..3a4713a7f3cd 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
@@ -151,6 +151,7 @@ function ConfiguredReferralClaimCoordinator() {
       try {
         const result = await claimReferralWithRetry({
           claim: () => claimReferral({ accountId: userId, referralCode }),
+          shouldContinue: isCurrentAttempt,
           shouldRetry: (claimResult) =>
             isCurrentAttempt() &&
             claimResult._tag !== "Success" &&

From f63405b51eb59bf43895f0cf5d65e302d275b098 Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 19:54:27 +0530
Subject: [PATCH 24/29] fix(web): use themed referral error alert

---
 .../src/components/clerk/ReferralsUserProfilePage.tsx    | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
index a3efe07af54a..47687a6164ef 100644
--- a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
+++ b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
@@ -18,6 +18,7 @@ import {
 import { configuredHostedAppUrl } from "../../hostedPairing";
 import { useCopyToClipboard } from "../../hooks/useCopyToClipboard";
 import { useAtomCommand } from "../../state/use-atom-command";
+import { Alert, AlertDescription, AlertTitle } from "../ui/alert";
 import { Button } from "../ui/button";
 import { Card, CardContent } from "../ui/card";
 import { Input } from "../ui/input";
@@ -189,10 +190,10 @@ export function ReferralsUserProfilePage() {
       }
     >
       {summaryState.error ? (
-        <div className="mb-3 rounded-lg bg-destructive/8 px-3 py-2.5 text-[0.8125rem]" role="alert">
-          <p className="font-medium text-destructive-foreground">Could not load referral points</p>
-          <p className="mt-1 text-xs text-muted-foreground">{summaryState.error}</p>
-        </div>
+        <Alert variant="error" className="mb-3 text-[0.8125rem]">
+          <AlertTitle>Could not load referral points</AlertTitle>
+          <AlertDescription className="text-xs">{summaryState.error}</AlertDescription>
+        </Alert>
       ) : null}
 
       {isInitialLoad ? (

From 0bd26e76fdd4c92b6ab8d24ea04f0417edc7f9f7 Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 20:10:22 +0530
Subject: [PATCH 25/29] fix(referrals): preserve claims during first link

---
 .../settings/SettingsReferralsRouteScreen.tsx | 20 +----
 .../features/settings/referralShare.test.ts   | 28 +++++++
 .../src/features/settings/referralShare.ts    | 22 +++++
 apps/web/src/cloud/linkEnvironment.test.ts    | 80 +++++++++++++++++++
 apps/web/src/cloud/linkEnvironment.ts         | 16 ++++
 apps/web/src/cloud/linkEnvironmentAtoms.ts    |  1 +
 apps/web/src/cloud/referralLinks.test.ts      | 13 ++-
 apps/web/src/cloud/referralLinks.ts           |  8 ++
 apps/web/src/cloud/useCloudLinkController.ts  |  3 +
 .../cloud/ReferralClaimCoordinator.tsx        | 13 +--
 10 files changed, 176 insertions(+), 28 deletions(-)
 create mode 100644 apps/mobile/src/features/settings/referralShare.test.ts
 create mode 100644 apps/mobile/src/features/settings/referralShare.ts

diff --git a/apps/mobile/src/features/settings/SettingsReferralsRouteScreen.tsx b/apps/mobile/src/features/settings/SettingsReferralsRouteScreen.tsx
index 527de2345638..995db27a3e4d 100644
--- a/apps/mobile/src/features/settings/SettingsReferralsRouteScreen.tsx
+++ b/apps/mobile/src/features/settings/SettingsReferralsRouteScreen.tsx
@@ -6,12 +6,7 @@ import {
 } from "@t3tools/client-runtime/state/runtime";
 import type { RelayReferralClaimResult } from "@t3tools/contracts/relay";
 import { DEFAULT_HOSTED_APP_URL } from "@t3tools/shared/connectAuth";
-import {
-  buildReferralLink,
-  buildReferralShareMessage,
-  normalizeReferralCode,
-  REFERRAL_SHARE_TITLE,
-} from "@t3tools/shared/referral";
+import { buildReferralLink, normalizeReferralCode } from "@t3tools/shared/referral";
 import type { ComponentProps } from "react";
 import { useState } from "react";
 import {
@@ -37,6 +32,7 @@ import {
   useManagedRelayReferralSummary,
 } from "../cloud/managedRelayState";
 import { SettingsSection } from "./components/SettingsSection";
+import { shareReferralLink } from "./referralShare";
 
 function showClaimResult(result: RelayReferralClaimResult): void {
   switch (result) {
@@ -169,17 +165,7 @@ export function SettingsReferralsRouteScreen() {
   };
 
   const shareReferral = () => {
-    if (!referralLink) return;
-    void Share.share(
-      {
-        title: REFERRAL_SHARE_TITLE,
-        message: buildReferralShareMessage(referralLink),
-      },
-      {
-        dialogTitle: "Share referral link",
-        subject: REFERRAL_SHARE_TITLE,
-      },
-    );
+    void shareReferralLink(referralLink, (content, options) => Share.share(content, options));
   };
 
   if (!isSignedIn) {
diff --git a/apps/mobile/src/features/settings/referralShare.test.ts b/apps/mobile/src/features/settings/referralShare.test.ts
new file mode 100644
index 000000000000..73635c339c63
--- /dev/null
+++ b/apps/mobile/src/features/settings/referralShare.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it, vi } from "vite-plus/test";
+
+import { shareReferralLink } from "./referralShare";
+
+describe("mobile referral sharing", () => {
+  it("treats dismissing the native share sheet as a no-op", async () => {
+    const share = vi.fn().mockRejectedValue(new Error("Share dismissed"));
+
+    await expect(
+      shareReferralLink("https://app.t3.codes/?ref=ABCD1234EFAB5678", share),
+    ).resolves.toBeUndefined();
+
+    expect(share).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: expect.stringContaining("https://app.t3.codes/?ref=ABCD1234EFAB5678"),
+      }),
+      expect.objectContaining({ dialogTitle: "Share referral link" }),
+    );
+  });
+
+  it("does not open an empty share sheet", async () => {
+    const share = vi.fn();
+
+    await shareReferralLink("", share);
+
+    expect(share).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/mobile/src/features/settings/referralShare.ts b/apps/mobile/src/features/settings/referralShare.ts
new file mode 100644
index 000000000000..4852a8dea778
--- /dev/null
+++ b/apps/mobile/src/features/settings/referralShare.ts
@@ -0,0 +1,22 @@
+import { buildReferralShareMessage, REFERRAL_SHARE_TITLE } from "@t3tools/shared/referral";
+
+type ShareReferral = (
+  content: { readonly title: string; readonly message: string },
+  options: { readonly dialogTitle: string; readonly subject: string },
+) => Promise<unknown>;
+
+export async function shareReferralLink(referralLink: string, share: ShareReferral): Promise<void> {
+  if (!referralLink) return;
+  try {
+    await share(
+      {
+        title: REFERRAL_SHARE_TITLE,
+        message: buildReferralShareMessage(referralLink),
+      },
+      {
+        dialogTitle: "Share referral link",
+        subject: REFERRAL_SHARE_TITLE,
+      },
+    );
+  } catch {}
+}
diff --git a/apps/web/src/cloud/linkEnvironment.test.ts b/apps/web/src/cloud/linkEnvironment.test.ts
index 38e205beabbb..8c78eacd0750 100644
--- a/apps/web/src/cloud/linkEnvironment.test.ts
+++ b/apps/web/src/cloud/linkEnvironment.test.ts
@@ -343,6 +343,86 @@ describe("web cloud link environment client", () => {
     }),
   );
 
+  it.effect("claims a captured referral before linking the first environment", () =>
+    Effect.gen(function* () {
+      const fetchMock = vi
+        .fn()
+        .mockResolvedValueOnce(
+          Response.json({
+            result: "claimed",
+            summary: {
+              points: 0,
+              referralCode: "1111222233334444",
+              awardPoints: 67,
+              qualifiedReferrals: 0,
+              pendingReferrals: 0,
+              hasClaimedReferral: true,
+            },
+          }),
+        )
+        .mockResolvedValueOnce(
+          Response.json({
+            challenge: "challenge",
+            expiresAt: "2026-06-06T00:05:00.000Z",
+          }),
+        )
+        .mockResolvedValueOnce(Response.json("signed-proof"))
+        .mockResolvedValueOnce(
+          Response.json({
+            ok: true,
+            environmentId: TARGET.environmentId,
+            endpoint: {
+              httpBaseUrl: "https://desktop.example.test",
+              wsBaseUrl: "wss://desktop.example.test",
+              providerKind: "cloudflare_tunnel",
+            },
+            endpointRuntime: null,
+            relayIssuer: "https://relay.example.test",
+            cloudUserId: "user-1",
+            environmentCredential: "environment-credential",
+            cloudMintPublicKey: "public-key",
+          }),
+        )
+        .mockResolvedValueOnce(
+          Response.json({ ok: true, endpointRuntimeStatus: { status: "configured" } }),
+        );
+      vi.stubGlobal("fetch", fetchMock);
+
+      yield* withServices(
+        linkPrimaryEnvironmentToCloud({
+          target: TARGET,
+          clerkToken: "clerk-token",
+          referralCode: "ABCD1234EFAB5678",
+        }),
+      );
+
+      expect(String(fetchMock.mock.calls[0]?.[0])).toBe(
+        "https://relay.example.test/v1/client/referrals/claim",
+      );
+      expect(String(fetchMock.mock.calls[3]?.[0])).toBe(
+        "https://relay.example.test/v1/client/environment-links",
+      );
+    }),
+  );
+
+  it.effect("does not link when the captured referral cannot be claimed", () =>
+    Effect.gen(function* () {
+      const fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 503 }));
+      vi.stubGlobal("fetch", fetchMock);
+
+      const error = yield* withServices(
+        linkPrimaryEnvironmentToCloud({
+          target: TARGET,
+          clerkToken: "clerk-token",
+          referralCode: "ABCD1234EFAB5678",
+        }),
+      ).pipe(Effect.flip);
+
+      expect(error.message).toContain("referrals/claim failed before environment linking");
+      expect(fetchMock).toHaveBeenCalledOnce();
+    }),
+  );
+
   it.effect("links publish-only without a managed tunnel", () =>
     Effect.gen(function* () {
       const fetchMock = vi
diff --git a/apps/web/src/cloud/linkEnvironment.ts b/apps/web/src/cloud/linkEnvironment.ts
index a245cbc54db2..154e7775aae6 100644
--- a/apps/web/src/cloud/linkEnvironment.ts
+++ b/apps/web/src/cloud/linkEnvironment.ts
@@ -403,6 +403,7 @@ export function linkPrimaryEnvironmentToCloud(input: {
   readonly target: CloudLinkTarget;
   readonly clerkToken: string;
   readonly mode?: CloudLinkMode;
+  readonly referralCode?: string;
 }): Effect.Effect<
   void,
   CloudEnvironmentLinkError,
@@ -425,6 +426,21 @@ export function linkPrimaryEnvironmentToCloud(input: {
       yield* ensureRelayClientAvailable(EnvironmentId.make(input.target.environmentId));
     }
 
+    if (input.referralCode) {
+      yield* relayClient
+        .claimReferral({
+          clerkToken: input.clerkToken,
+          referralCode: input.referralCode,
+        })
+        .pipe(
+          Effect.mapError(
+            decodedRelayClientError(
+              `${configuredRelayUrl}/v1/client/referrals/claim failed before environment linking`,
+            ),
+          ),
+        );
+    }
+
     const challenge = yield* relayClient
       .createEnvironmentLinkChallenge({
         clerkToken: input.clerkToken,
diff --git a/apps/web/src/cloud/linkEnvironmentAtoms.ts b/apps/web/src/cloud/linkEnvironmentAtoms.ts
index 1094e860e462..de86a3745d43 100644
--- a/apps/web/src/cloud/linkEnvironmentAtoms.ts
+++ b/apps/web/src/cloud/linkEnvironmentAtoms.ts
@@ -26,6 +26,7 @@ export const linkPrimaryEnvironment = createRuntimeCommand(connectionAtomRuntime
     readonly target: CloudLinkTarget;
     readonly clerkToken: string;
     readonly mode?: CloudLinkMode;
+    readonly referralCode?: string;
   }) => linkPrimaryEnvironmentToCloud(input),
 });
 
diff --git a/apps/web/src/cloud/referralLinks.test.ts b/apps/web/src/cloud/referralLinks.test.ts
index 56d8c8afa9d3..9e2872dfd762 100644
--- a/apps/web/src/cloud/referralLinks.test.ts
+++ b/apps/web/src/cloud/referralLinks.test.ts
@@ -1,14 +1,25 @@
-import { describe, expect, it } from "vite-plus/test";
+import { describe, expect, it, vi } from "vite-plus/test";
 
 import {
   buildReferralShareData,
   captureReferralCodeFromUrl,
+  PENDING_REFERRAL_CODE_STORAGE_KEY,
+  readPendingReferralCode,
   referralCodeFromUrl,
   urlWithoutMatchingReferralCode,
   urlWithoutReferralCode,
 } from "./referralLinks";
 
 describe("referralLinks", () => {
+  it("normalizes a pending referral read from storage", () => {
+    const storage = {
+      getItem: vi.fn(() => "abcd1234efab5678"),
+    };
+
+    expect(readPendingReferralCode(storage)).toBe("ABCD1234EFAB5678");
+    expect(storage.getItem).toHaveBeenCalledWith(PENDING_REFERRAL_CODE_STORAGE_KEY);
+  });
+
   it("reads and removes only the referral parameter", () => {
     const url = new URL("https://app.t3.codes/?channel=nightly&ref=abcd1234efab5678#thread");
     expect(referralCodeFromUrl(url)).toBe("ABCD1234EFAB5678");
diff --git a/apps/web/src/cloud/referralLinks.ts b/apps/web/src/cloud/referralLinks.ts
index ecd9b47292ad..c9ea809bbbc2 100644
--- a/apps/web/src/cloud/referralLinks.ts
+++ b/apps/web/src/cloud/referralLinks.ts
@@ -7,6 +7,14 @@ import {
 
 export const PENDING_REFERRAL_CODE_STORAGE_KEY = "t3code.pending-referral-code";
 
+export function readPendingReferralCode(storage: Pick<Storage, "getItem">): string | null {
+  try {
+    return normalizeReferralCode(storage.getItem(PENDING_REFERRAL_CODE_STORAGE_KEY) ?? "");
+  } catch {
+    return null;
+  }
+}
+
 export function referralCodeFromUrl(url: URL): string | null {
   return normalizeReferralCode(url.searchParams.get("ref") ?? "");
 }
diff --git a/apps/web/src/cloud/useCloudLinkController.ts b/apps/web/src/cloud/useCloudLinkController.ts
index d91596880850..5e26cc6c62f0 100644
--- a/apps/web/src/cloud/useCloudLinkController.ts
+++ b/apps/web/src/cloud/useCloudLinkController.ts
@@ -17,6 +17,7 @@ import {
 } from "./linkEnvironmentAtoms";
 import { usePrimaryCloudLinkState } from "./primaryCloudLinkState";
 import { resolveRelayClerkTokenOptions } from "./publicConfig";
+import { readPendingReferralCode } from "./referralLinks";
 
 export interface CloudLinkDesiredState {
   readonly managedTunnel: boolean;
@@ -116,10 +117,12 @@ export function useCloudLinkController() {
         return false;
       }
       if (!linked || managedTunnelActive !== desired.managedTunnel) {
+        const referralCode = readPendingReferralCode(window.localStorage);
         const linkResult = await linkPrimaryEnvironment({
           target,
           clerkToken,
           mode: desired.managedTunnel ? "managed" : "publish_only",
+          ...(referralCode ? { referralCode } : {}),
         });
         if (linkResult._tag === "Failure") {
           if (!isAtomCommandInterrupted(linkResult)) {
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
index 3a4713a7f3cd..8c72837c77c5 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
@@ -17,6 +17,7 @@ import { hasCloudPublicConfig } from "../../cloud/publicConfig";
 import {
   captureReferralCodeFromUrl,
   PENDING_REFERRAL_CODE_STORAGE_KEY,
+  readPendingReferralCode,
   urlWithoutMatchingReferralCode,
 } from "../../cloud/referralLinks";
 import { useAtomCommand } from "../../state/use-atom-command";
@@ -36,14 +37,6 @@ function clearPendingReferralCode(): void {
   } catch {}
 }
 
-function readPendingReferralCode(): string | null {
-  try {
-    return window.localStorage.getItem(PENDING_REFERRAL_CODE_STORAGE_KEY);
-  } catch {
-    return null;
-  }
-}
-
 function captureReferralCode(): string | null {
   const url = new URL(window.location.href);
   const captured = captureReferralCodeFromUrl(url, (referralCode) => {
@@ -115,7 +108,7 @@ function ConfiguredReferralClaimCoordinator() {
     initializedReferralRef.current = true;
     const initial = referralClaimLoadState(
       capturedCode,
-      capturedCode ? null : readPendingReferralCode(),
+      capturedCode ? null : readPendingReferralCode(window.localStorage),
     );
     shouldPromptSignInRef.current = initial.shouldPromptSignIn;
     setPendingReferralCode(initial.referralCode);
@@ -135,7 +128,7 @@ function ConfiguredReferralClaimCoordinator() {
 
   useEffect(() => {
     if (!isLoaded || !isSignedIn || !userId || relayAccountId !== userId) return;
-    const referralCode = pendingReferralCode ?? readPendingReferralCode();
+    const referralCode = pendingReferralCode ?? readPendingReferralCode(window.localStorage);
     if (!referralCode) return;
     const attemptKey = `${userId}:${referralCode}`;
     const attempt = { key: attemptKey };

From f194577bd3816cfa4514fea5a847b3544040c0ed Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Thu, 27 Aug 2026 20:19:04 +0530
Subject: [PATCH 26/29] fix(web): guard blocked referral storage

---
 apps/web/src/cloud/referralLinks.test.ts               | 10 +++++++++-
 apps/web/src/cloud/referralLinks.ts                    |  5 ++++-
 apps/web/src/cloud/useCloudLinkController.ts           |  2 +-
 .../src/components/cloud/ReferralClaimCoordinator.tsx  |  4 ++--
 4 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/apps/web/src/cloud/referralLinks.test.ts b/apps/web/src/cloud/referralLinks.test.ts
index 9e2872dfd762..821e7e2ef89e 100644
--- a/apps/web/src/cloud/referralLinks.test.ts
+++ b/apps/web/src/cloud/referralLinks.test.ts
@@ -16,10 +16,18 @@ describe("referralLinks", () => {
       getItem: vi.fn(() => "abcd1234efab5678"),
     };
 
-    expect(readPendingReferralCode(storage)).toBe("ABCD1234EFAB5678");
+    expect(readPendingReferralCode(() => storage)).toBe("ABCD1234EFAB5678");
     expect(storage.getItem).toHaveBeenCalledWith(PENDING_REFERRAL_CODE_STORAGE_KEY);
   });
 
+  it("treats blocked browser storage as empty", () => {
+    expect(
+      readPendingReferralCode(() => {
+        throw new Error("Storage access denied");
+      }),
+    ).toBeNull();
+  });
+
   it("reads and removes only the referral parameter", () => {
     const url = new URL("https://app.t3.codes/?channel=nightly&ref=abcd1234efab5678#thread");
     expect(referralCodeFromUrl(url)).toBe("ABCD1234EFAB5678");
diff --git a/apps/web/src/cloud/referralLinks.ts b/apps/web/src/cloud/referralLinks.ts
index c9ea809bbbc2..e31514bfbdf6 100644
--- a/apps/web/src/cloud/referralLinks.ts
+++ b/apps/web/src/cloud/referralLinks.ts
@@ -7,8 +7,11 @@ import {
 
 export const PENDING_REFERRAL_CODE_STORAGE_KEY = "t3code.pending-referral-code";
 
-export function readPendingReferralCode(storage: Pick<Storage, "getItem">): string | null {
+export function readPendingReferralCode(
+  getStorage: () => Pick<Storage, "getItem"> = () => window.localStorage,
+): string | null {
   try {
+    const storage = getStorage();
     return normalizeReferralCode(storage.getItem(PENDING_REFERRAL_CODE_STORAGE_KEY) ?? "");
   } catch {
     return null;
diff --git a/apps/web/src/cloud/useCloudLinkController.ts b/apps/web/src/cloud/useCloudLinkController.ts
index 5e26cc6c62f0..0840c932a245 100644
--- a/apps/web/src/cloud/useCloudLinkController.ts
+++ b/apps/web/src/cloud/useCloudLinkController.ts
@@ -117,7 +117,7 @@ export function useCloudLinkController() {
         return false;
       }
       if (!linked || managedTunnelActive !== desired.managedTunnel) {
-        const referralCode = readPendingReferralCode(window.localStorage);
+        const referralCode = readPendingReferralCode();
         const linkResult = await linkPrimaryEnvironment({
           target,
           clerkToken,
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
index 8c72837c77c5..ee618ebc3751 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
@@ -108,7 +108,7 @@ function ConfiguredReferralClaimCoordinator() {
     initializedReferralRef.current = true;
     const initial = referralClaimLoadState(
       capturedCode,
-      capturedCode ? null : readPendingReferralCode(window.localStorage),
+      capturedCode ? null : readPendingReferralCode(),
     );
     shouldPromptSignInRef.current = initial.shouldPromptSignIn;
     setPendingReferralCode(initial.referralCode);
@@ -128,7 +128,7 @@ function ConfiguredReferralClaimCoordinator() {
 
   useEffect(() => {
     if (!isLoaded || !isSignedIn || !userId || relayAccountId !== userId) return;
-    const referralCode = pendingReferralCode ?? readPendingReferralCode(window.localStorage);
+    const referralCode = pendingReferralCode ?? readPendingReferralCode();
     if (!referralCode) return;
     const attemptKey = `${userId}:${referralCode}`;
     const attempt = { key: attemptKey };

From 0b8c757483aec17029872b38103a462630d37dab Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Fri, 28 Aug 2026 02:46:27 +0530
Subject: [PATCH 27/29] fix(referrals): harden account-wide awards

---
 .../src/features/cloud/managedRelayState.ts   |   7 -
 .../settings/SettingsReferralsRouteScreen.tsx |  56 +-
 .../features/settings/SettingsRouteScreen.tsx |   3 +-
 .../features/settings/referralShare.test.ts   |  13 +-
 .../src/features/settings/referralShare.ts    |  28 +-
 apps/web/src/cloud/linkEnvironment.test.ts    |  93 ++-
 apps/web/src/cloud/linkEnvironment.ts         |  25 +-
 .../web/src/cloud/referralClaimResult.test.ts |  16 +
 apps/web/src/cloud/referralClaimResult.ts     |  34 ++
 apps/web/src/cloud/referralLinks.test.ts      |  13 +
 apps/web/src/cloud/referralLinks.ts           |  12 +-
 apps/web/src/cloud/useCloudLinkController.ts  |  13 +-
 .../clerk/ReferralsUserProfilePage.tsx        |  38 +-
 .../clerk/T3ConnectSidebarSignIn.tsx          |   7 +
 .../ReferralClaimCoordinator.logic.test.ts    |  14 -
 .../cloud/ReferralClaimCoordinator.logic.ts   |  10 -
 .../cloud/ReferralClaimCoordinator.tsx        | 100 ++--
 apps/web/src/components/ui/card.tsx           |   1 -
 docs/internals/t3-connect.md                  |   8 +-
 docs/user/referrals.md                        |   3 +-
 .../migration.sql                             |   4 +-
 .../snapshot.json                             |  43 +-
 infra/relay/package.json                      |   1 +
 infra/relay/src/http/Api.test.ts              |   2 +-
 infra/relay/src/persistence/schema.ts         |   5 +
 .../src/referrals/ReferralProgram.test.ts     | 556 ++++++++----------
 infra/relay/src/referrals/ReferralProgram.ts  | 249 +++++---
 .../src/relay/managedRelayState.test.ts       |   2 +-
 packages/contracts/src/relay.ts               |   2 +-
 packages/shared/src/referral.test.ts          |   7 +-
 packages/shared/src/referral.ts               |  12 +-
 pnpm-lock.yaml                                |  33 +-
 pnpm-workspace.yaml                           |   2 +
 33 files changed, 841 insertions(+), 571 deletions(-)
 create mode 100644 apps/web/src/cloud/referralClaimResult.test.ts
 create mode 100644 apps/web/src/cloud/referralClaimResult.ts
 rename infra/relay/migrations/postgres/{20260826230249_complete_logan => 20260827203356_referral_points}/migration.sql (82%)
 rename infra/relay/migrations/postgres/{20260826230249_complete_logan => 20260827203356_referral_points}/snapshot.json (97%)

diff --git a/apps/mobile/src/features/cloud/managedRelayState.ts b/apps/mobile/src/features/cloud/managedRelayState.ts
index b017893a52eb..c72669ea4c95 100644
--- a/apps/mobile/src/features/cloud/managedRelayState.ts
+++ b/apps/mobile/src/features/cloud/managedRelayState.ts
@@ -149,10 +149,3 @@ export function refreshManagedRelayEnvironments(): void {
     managedRelayQueryManager.refreshEnvironments(appAtomRegistry, session.accountId);
   }
 }
-
-export function refreshManagedRelayReferralSummary(): void {
-  const session = appAtomRegistry.get(managedRelaySessionAtom);
-  if (session) {
-    managedRelayQueryManager.refreshReferralSummary(appAtomRegistry, session.accountId);
-  }
-}
diff --git a/apps/mobile/src/features/settings/SettingsReferralsRouteScreen.tsx b/apps/mobile/src/features/settings/SettingsReferralsRouteScreen.tsx
index 995db27a3e4d..7fea4c555264 100644
--- a/apps/mobile/src/features/settings/SettingsReferralsRouteScreen.tsx
+++ b/apps/mobile/src/features/settings/SettingsReferralsRouteScreen.tsx
@@ -1,5 +1,5 @@
 import { useAuth } from "@clerk/expo";
-import { useNavigation } from "@react-navigation/native";
+import { StackActions, useNavigation } from "@react-navigation/native";
 import {
   isAtomCommandInterrupted,
   squashAtomCommandFailure,
@@ -8,12 +8,13 @@ import type { RelayReferralClaimResult } from "@t3tools/contracts/relay";
 import { DEFAULT_HOSTED_APP_URL } from "@t3tools/shared/connectAuth";
 import { buildReferralLink, normalizeReferralCode } from "@t3tools/shared/referral";
 import type { ComponentProps } from "react";
-import { useState } from "react";
+import { useLayoutEffect, useState } from "react";
 import {
   ActivityIndicator,
   Alert,
   Platform,
   Pressable,
+  RefreshControl,
   ScrollView,
   Share,
   View,
@@ -31,15 +32,16 @@ import {
   claimManagedRelayReferralCommand,
   useManagedRelayReferralSummary,
 } from "../cloud/managedRelayState";
+import { hasCloudPublicConfig } from "../cloud/publicConfig";
 import { SettingsSection } from "./components/SettingsSection";
 import { shareReferralLink } from "./referralShare";
 
-function showClaimResult(result: RelayReferralClaimResult): void {
+function showClaimResult(result: RelayReferralClaimResult, awardPoints: number): void {
   switch (result) {
     case "claimed":
       Alert.alert(
         "Referral applied",
-        "Your referrer will receive 67 points after you link your first environment.",
+        `Your referrer will receive ${awardPoints} points after you link your first environment.`,
       );
       return;
     case "already_claimed":
@@ -122,6 +124,18 @@ function ReferralActionRow(props: {
 }
 
 export function SettingsReferralsRouteScreen() {
+  const navigation = useNavigation();
+
+  useLayoutEffect(() => {
+    if (!hasCloudPublicConfig()) {
+      navigation.dispatch(StackActions.replace("SettingsContent"));
+    }
+  }, [navigation]);
+
+  return hasCloudPublicConfig() ? <ConfiguredSettingsReferralsRouteScreen /> : null;
+}
+
+function ConfiguredSettingsReferralsRouteScreen() {
   const { isSignedIn } = useAuth({ treatPendingAsSignedOut: false });
   const navigation = useNavigation();
   const insets = useSafeAreaInsets();
@@ -132,7 +146,6 @@ export function SettingsReferralsRouteScreen() {
   const [referralCode, setReferralCode] = useState("");
   const [isClaiming, setIsClaiming] = useState(false);
   const iconColor = useThemeColor("--color-icon");
-  const iconSuccess = useThemeColor("--color-success");
   const primaryForeground = useThemeColor("--color-primary-foreground");
   const summary = summaryState.data;
   const referralLink = summary
@@ -152,7 +165,7 @@ export function SettingsReferralsRouteScreen() {
     setIsClaiming(false);
     if (result._tag === "Success") {
       setReferralCode("");
-      showClaimResult(result.value.result);
+      showClaimResult(result.value.result, result.value.summary.awardPoints);
       summaryState.refresh();
       return;
     }
@@ -164,8 +177,19 @@ export function SettingsReferralsRouteScreen() {
     );
   };
 
-  const shareReferral = () => {
-    void shareReferralLink(referralLink, (content, options) => Share.share(content, options));
+  const shareReferral = async () => {
+    try {
+      await shareReferralLink(
+        referralLink,
+        (content, options) => Share.share(content, options),
+        summary?.awardPoints,
+      );
+    } catch (cause) {
+      Alert.alert(
+        "Could not share referral link",
+        cause instanceof Error ? cause.message : "Try again.",
+      );
+    }
   };
 
   if (!isSignedIn) {
@@ -200,6 +224,12 @@ export function SettingsReferralsRouteScreen() {
         className="flex-1"
         contentContainerClassName="gap-6 px-5 pt-4"
         contentContainerStyle={{ paddingBottom: Math.max(insets.bottom, 18) + 18 }}
+        refreshControl={
+          <RefreshControl
+            refreshing={summary !== null && summaryState.isPending}
+            onRefresh={summaryState.refresh}
+          />
+        }
       >
         {summaryState.error ? (
           <SettingsSection card title="Referral points">
@@ -263,7 +293,6 @@ export function SettingsReferralsRouteScreen() {
                     accessibilityLabel="Copy referral code"
                     text={summary.referralCode}
                     tintColor={iconColor}
-                    copiedTintColor={iconSuccess}
                   />
                 </View>
                 <ReferralActionRow
@@ -271,16 +300,16 @@ export function SettingsReferralsRouteScreen() {
                   label="Share referral link"
                   detail={referralLink}
                   disabled={!referralLink}
-                  onPress={shareReferral}
+                  onPress={() => void shareReferral()}
                 />
               </SettingsSection>
               <Text className="px-2 text-sm leading-normal text-foreground-muted">
-                Your friend must claim the link before linking their first environment. You receive
-                67 points after that environment connects.
+                Your friend must claim the link before linking their first environment. You receive{" "}
+                {summary.awardPoints} points after that environment connects.
               </Text>
             </View>
 
-            {!summary.hasClaimedReferral ? (
+            {summary.canClaimReferral ? (
               <View className="gap-3">
                 <SettingsSection card title="Use a referral code">
                   <View className="gap-3 p-4">
@@ -289,7 +318,6 @@ export function SettingsReferralsRouteScreen() {
                       autoCapitalize="characters"
                       autoCorrect={false}
                       editable={!isClaiming}
-                      maxLength={19}
                       placeholder="ABCD1234EFAB5678"
                       returnKeyType="done"
                       value={referralCode}
diff --git a/apps/mobile/src/features/settings/SettingsRouteScreen.tsx b/apps/mobile/src/features/settings/SettingsRouteScreen.tsx
index e59ce494a266..9bef2dc4a1a9 100644
--- a/apps/mobile/src/features/settings/SettingsRouteScreen.tsx
+++ b/apps/mobile/src/features/settings/SettingsRouteScreen.tsx
@@ -18,6 +18,7 @@ import {
   settlePromise,
   squashAtomCommandFailure,
 } from "@t3tools/client-runtime/state/runtime";
+import { REFERRAL_AWARD_POINTS } from "@t3tools/shared/referral";
 import { AndroidScreenHeader } from "../../components/AndroidScreenHeader";
 import { AppText as Text } from "../../components/AppText";
 import { supportsAgentAwarenessPush } from "../agent-awareness/capabilities";
@@ -462,7 +463,7 @@ function ConfiguredSettingsRouteScreen() {
               <SettingsRow
                 icon="link"
                 label="Referrals"
-                value="67 points each"
+                value={`${REFERRAL_AWARD_POINTS} points each`}
                 target="SettingsReferrals"
               />
             ) : null}
diff --git a/apps/mobile/src/features/settings/referralShare.test.ts b/apps/mobile/src/features/settings/referralShare.test.ts
index 73635c339c63..e14bceaf5721 100644
--- a/apps/mobile/src/features/settings/referralShare.test.ts
+++ b/apps/mobile/src/features/settings/referralShare.test.ts
@@ -3,8 +3,8 @@ import { describe, expect, it, vi } from "vite-plus/test";
 import { shareReferralLink } from "./referralShare";
 
 describe("mobile referral sharing", () => {
-  it("treats dismissing the native share sheet as a no-op", async () => {
-    const share = vi.fn().mockRejectedValue(new Error("Share dismissed"));
+  it("treats a resolved native dismissal as a no-op", async () => {
+    const share = vi.fn().mockResolvedValue({ action: "dismissedAction" });
 
     await expect(
       shareReferralLink("https://app.t3.codes/?ref=ABCD1234EFAB5678", share),
@@ -18,6 +18,15 @@ describe("mobile referral sharing", () => {
     );
   });
 
+  it("propagates native sharing failures to the screen", async () => {
+    const failure = new Error("Native share failed");
+    const share = vi.fn().mockRejectedValue(failure);
+
+    await expect(
+      shareReferralLink("https://app.t3.codes/?ref=ABCD1234EFAB5678", share),
+    ).rejects.toBe(failure);
+  });
+
   it("does not open an empty share sheet", async () => {
     const share = vi.fn();
 
diff --git a/apps/mobile/src/features/settings/referralShare.ts b/apps/mobile/src/features/settings/referralShare.ts
index 4852a8dea778..7e2ae0bf5e91 100644
--- a/apps/mobile/src/features/settings/referralShare.ts
+++ b/apps/mobile/src/features/settings/referralShare.ts
@@ -5,18 +5,20 @@ type ShareReferral = (
   options: { readonly dialogTitle: string; readonly subject: string },
 ) => Promise<unknown>;
 
-export async function shareReferralLink(referralLink: string, share: ShareReferral): Promise<void> {
+export async function shareReferralLink(
+  referralLink: string,
+  share: ShareReferral,
+  awardPoints?: number,
+): Promise<void> {
   if (!referralLink) return;
-  try {
-    await share(
-      {
-        title: REFERRAL_SHARE_TITLE,
-        message: buildReferralShareMessage(referralLink),
-      },
-      {
-        dialogTitle: "Share referral link",
-        subject: REFERRAL_SHARE_TITLE,
-      },
-    );
-  } catch {}
+  await share(
+    {
+      title: REFERRAL_SHARE_TITLE,
+      message: buildReferralShareMessage(referralLink, awardPoints),
+    },
+    {
+      dialogTitle: "Share referral link",
+      subject: REFERRAL_SHARE_TITLE,
+    },
+  );
 }
diff --git a/apps/web/src/cloud/linkEnvironment.test.ts b/apps/web/src/cloud/linkEnvironment.test.ts
index 8c78eacd0750..c73a94d9c745 100644
--- a/apps/web/src/cloud/linkEnvironment.test.ts
+++ b/apps/web/src/cloud/linkEnvironment.test.ts
@@ -356,7 +356,7 @@ describe("web cloud link environment client", () => {
               awardPoints: 67,
               qualifiedReferrals: 0,
               pendingReferrals: 0,
-              hasClaimedReferral: true,
+              canClaimReferral: false,
             },
           }),
         )
@@ -423,6 +423,97 @@ describe("web cloud link environment client", () => {
     }),
   );
 
+  it.effect("continues linking for every non-rejected referral outcome", () =>
+    Effect.gen(function* () {
+      for (const claimResult of ["already_claimed", "ineligible"] as const) {
+        const fetchMock = vi
+          .fn()
+          .mockResolvedValueOnce(
+            Response.json({
+              result: claimResult,
+              summary: {
+                points: 0,
+                referralCode: "1111222233334444",
+                awardPoints: 67,
+                qualifiedReferrals: 0,
+                pendingReferrals: 0,
+                canClaimReferral: false,
+              },
+            }),
+          )
+          .mockResolvedValueOnce(
+            Response.json({
+              challenge: "challenge",
+              expiresAt: "2026-06-06T00:05:00.000Z",
+            }),
+          )
+          .mockResolvedValueOnce(Response.json("signed-proof"))
+          .mockResolvedValueOnce(
+            Response.json({
+              ok: true,
+              environmentId: TARGET.environmentId,
+              endpoint: {
+                httpBaseUrl: "https://desktop.example.test",
+                wsBaseUrl: "wss://desktop.example.test",
+                providerKind: "cloudflare_tunnel",
+              },
+              endpointRuntime: null,
+              relayIssuer: "https://relay.example.test",
+              cloudUserId: "user-1",
+              environmentCredential: "environment-credential",
+              cloudMintPublicKey: "public-key",
+            }),
+          )
+          .mockResolvedValueOnce(
+            Response.json({ ok: true, endpointRuntimeStatus: { status: "configured" } }),
+          );
+        vi.stubGlobal("fetch", fetchMock);
+
+        yield* withServices(
+          linkPrimaryEnvironmentToCloud({
+            target: TARGET,
+            clerkToken: "clerk-token",
+            referralCode: "ABCD1234EFAB5678",
+          }),
+        );
+
+        expect(fetchMock).toHaveBeenCalledTimes(5);
+      }
+    }),
+  );
+
+  it.effect("rejects invalid and cyclic referral codes before the environment is linked", () =>
+    Effect.gen(function* () {
+      for (const claimResult of ["invalid_code", "self_referral"] as const) {
+        const fetchMock = vi.fn().mockResolvedValue(
+          Response.json({
+            result: claimResult,
+            summary: {
+              points: 0,
+              referralCode: "1111222233334444",
+              awardPoints: 67,
+              qualifiedReferrals: 0,
+              pendingReferrals: 0,
+              canClaimReferral: true,
+            },
+          }),
+        );
+        vi.stubGlobal("fetch", fetchMock);
+
+        const error = yield* withServices(
+          linkPrimaryEnvironmentToCloud({
+            target: TARGET,
+            clerkToken: "clerk-token",
+            referralCode: "ABCD1234EFAB5678",
+          }),
+        ).pipe(Effect.flip);
+
+        expect(error).toMatchObject({ referralClaimResult: claimResult });
+        expect(fetchMock).toHaveBeenCalledOnce();
+      }
+    }),
+  );
+
   it.effect("links publish-only without a managed tunnel", () =>
     Effect.gen(function* () {
       const fetchMock = vi
diff --git a/apps/web/src/cloud/linkEnvironment.ts b/apps/web/src/cloud/linkEnvironment.ts
index 154e7775aae6..1964135f6414 100644
--- a/apps/web/src/cloud/linkEnvironment.ts
+++ b/apps/web/src/cloud/linkEnvironment.ts
@@ -21,6 +21,7 @@ import {
   type RelayEnvironmentLinkResponse,
   type RelayProtectedError as RelayProtectedErrorType,
   type RelayManagedEndpointProviderKind,
+  type RelayReferralClaimResult,
 } from "@t3tools/contracts/relay";
 import { EnvironmentRegistry } from "@t3tools/client-runtime/connection";
 import { request, runStream } from "@t3tools/client-runtime/rpc";
@@ -55,6 +56,10 @@ export class CloudEnvironmentLinkError extends Data.TaggedError("CloudEnvironmen
   readonly message: string;
   readonly cause?: unknown;
   readonly traceId?: string;
+  readonly referralClaimResult?: Extract<
+    RelayReferralClaimResult,
+    "invalid_code" | "self_referral"
+  >;
 }> {}
 
 const relayClientRpcError = (message: string) => (cause: unknown) =>
@@ -427,7 +432,7 @@ export function linkPrimaryEnvironmentToCloud(input: {
     }
 
     if (input.referralCode) {
-      yield* relayClient
+      const claimResponse = yield* relayClient
         .claimReferral({
           clerkToken: input.clerkToken,
           referralCode: input.referralCode,
@@ -439,6 +444,24 @@ export function linkPrimaryEnvironmentToCloud(input: {
             ),
           ),
         );
+      switch (claimResponse.result) {
+        case "claimed":
+        case "already_claimed":
+        case "ineligible":
+          break;
+        case "invalid_code":
+          return yield* new CloudEnvironmentLinkError({
+            message:
+              "The saved referral code is no longer valid. Apply a different code and try again.",
+            referralClaimResult: claimResponse.result,
+          });
+        case "self_referral":
+          return yield* new CloudEnvironmentLinkError({
+            message:
+              "You cannot link an environment while using a referral code from your account chain.",
+            referralClaimResult: claimResponse.result,
+          });
+      }
     }
 
     const challenge = yield* relayClient
diff --git a/apps/web/src/cloud/referralClaimResult.test.ts b/apps/web/src/cloud/referralClaimResult.test.ts
new file mode 100644
index 000000000000..50e108cb1207
--- /dev/null
+++ b/apps/web/src/cloud/referralClaimResult.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { referralClaimMessage } from "./referralClaimResult";
+
+describe("referralClaimMessage", () => {
+  it("describes every claim outcome and uses the server award", () => {
+    expect(referralClaimMessage("claimed", 100)).toMatchObject({
+      type: "success",
+      description: expect.stringContaining("100 points"),
+    });
+    expect(referralClaimMessage("already_claimed").type).toBe("info");
+    expect(referralClaimMessage("invalid_code").type).toBe("warning");
+    expect(referralClaimMessage("self_referral").title).toContain("account chain");
+    expect(referralClaimMessage("ineligible").description).toContain("before linking");
+  });
+});
diff --git a/apps/web/src/cloud/referralClaimResult.ts b/apps/web/src/cloud/referralClaimResult.ts
new file mode 100644
index 000000000000..907c5152e26e
--- /dev/null
+++ b/apps/web/src/cloud/referralClaimResult.ts
@@ -0,0 +1,34 @@
+import type { RelayReferralClaimResult } from "@t3tools/contracts/relay";
+import { REFERRAL_AWARD_POINTS } from "@t3tools/shared/referral";
+
+export interface ReferralClaimMessage {
+  readonly type: "success" | "warning" | "info";
+  readonly title: string;
+  readonly description?: string;
+}
+
+export function referralClaimMessage(
+  result: RelayReferralClaimResult,
+  awardPoints = REFERRAL_AWARD_POINTS,
+): ReferralClaimMessage {
+  switch (result) {
+    case "claimed":
+      return {
+        type: "success",
+        title: "Referral applied",
+        description: `Your referrer will receive ${awardPoints} points after you link your first environment.`,
+      };
+    case "already_claimed":
+      return { type: "info", title: "This account already claimed a referral" };
+    case "invalid_code":
+      return { type: "warning", title: "This referral code is not valid" };
+    case "self_referral":
+      return { type: "warning", title: "You cannot use a referral code from your account chain" };
+    case "ineligible":
+      return {
+        type: "info",
+        title: "Referral code not applied",
+        description: "Referral codes must be claimed before linking an environment.",
+      };
+  }
+}
diff --git a/apps/web/src/cloud/referralLinks.test.ts b/apps/web/src/cloud/referralLinks.test.ts
index 821e7e2ef89e..1f0e79bd514e 100644
--- a/apps/web/src/cloud/referralLinks.test.ts
+++ b/apps/web/src/cloud/referralLinks.test.ts
@@ -3,6 +3,7 @@ import { describe, expect, it, vi } from "vite-plus/test";
 import {
   buildReferralShareData,
   captureReferralCodeFromUrl,
+  clearPendingReferralCode,
   PENDING_REFERRAL_CODE_STORAGE_KEY,
   readPendingReferralCode,
   referralCodeFromUrl,
@@ -11,6 +12,18 @@ import {
 } from "./referralLinks";
 
 describe("referralLinks", () => {
+  it("clears a pending code without exposing storage failures", () => {
+    const removeItem = vi.fn();
+    clearPendingReferralCode(() => ({ removeItem }));
+    expect(removeItem).toHaveBeenCalledWith(PENDING_REFERRAL_CODE_STORAGE_KEY);
+
+    expect(() =>
+      clearPendingReferralCode(() => {
+        throw new Error("storage unavailable");
+      }),
+    ).not.toThrow();
+  });
+
   it("normalizes a pending referral read from storage", () => {
     const storage = {
       getItem: vi.fn(() => "abcd1234efab5678"),
diff --git a/apps/web/src/cloud/referralLinks.ts b/apps/web/src/cloud/referralLinks.ts
index e31514bfbdf6..c458fc69c34f 100644
--- a/apps/web/src/cloud/referralLinks.ts
+++ b/apps/web/src/cloud/referralLinks.ts
@@ -18,6 +18,14 @@ export function readPendingReferralCode(
   }
 }
 
+export function clearPendingReferralCode(
+  getStorage: () => Pick<Storage, "removeItem"> = () => window.localStorage,
+): void {
+  try {
+    getStorage().removeItem(PENDING_REFERRAL_CODE_STORAGE_KEY);
+  } catch {}
+}
+
 export function referralCodeFromUrl(url: URL): string | null {
   return normalizeReferralCode(url.searchParams.get("ref") ?? "");
 }
@@ -53,10 +61,10 @@ export function captureReferralCodeFromUrl(
   return { referralCode, cleanedUrl: urlWithoutReferralCode(url) };
 }
 
-export function buildReferralShareData(referralLink: string) {
+export function buildReferralShareData(referralLink: string, awardPoints?: number) {
   return {
     title: REFERRAL_SHARE_TITLE,
-    text: buildReferralShareMessage(referralLink),
+    text: buildReferralShareMessage(referralLink, awardPoints),
     url: referralLink,
   };
 }
diff --git a/apps/web/src/cloud/useCloudLinkController.ts b/apps/web/src/cloud/useCloudLinkController.ts
index 0840c932a245..9e61f8d15170 100644
--- a/apps/web/src/cloud/useCloudLinkController.ts
+++ b/apps/web/src/cloud/useCloudLinkController.ts
@@ -10,6 +10,7 @@ import { useState } from "react";
 import { toastManager } from "../components/ui/toast";
 import { relayEnvironmentDiscovery } from "../state/relay";
 import { useAtomCommand } from "../state/use-atom-command";
+import { CloudEnvironmentLinkError } from "./linkEnvironment";
 import {
   linkPrimaryEnvironment as linkPrimaryEnvironmentAtom,
   unlinkPrimaryEnvironment as unlinkPrimaryEnvironmentAtom,
@@ -17,7 +18,7 @@ import {
 } from "./linkEnvironmentAtoms";
 import { usePrimaryCloudLinkState } from "./primaryCloudLinkState";
 import { resolveRelayClerkTokenOptions } from "./publicConfig";
-import { readPendingReferralCode } from "./referralLinks";
+import { clearPendingReferralCode, readPendingReferralCode } from "./referralLinks";
 
 export interface CloudLinkDesiredState {
   readonly managedTunnel: boolean;
@@ -126,11 +127,19 @@ export function useCloudLinkController() {
         });
         if (linkResult._tag === "Failure") {
           if (!isAtomCommandInterrupted(linkResult)) {
-            reportUpdateFailure(squashAtomCommandFailure(linkResult));
+            const cause = squashAtomCommandFailure(linkResult);
+            if (
+              cause instanceof CloudEnvironmentLinkError &&
+              cause.referralClaimResult !== undefined
+            ) {
+              clearPendingReferralCode();
+            }
+            reportUpdateFailure(cause);
           }
           primaryCloudLinkState.refresh();
           return false;
         }
+        if (referralCode) clearPendingReferralCode();
       }
       const prefResult = await updatePrimaryEnvironmentPreferences({
         target,
diff --git a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
index 47687a6164ef..e54d700cabe1 100644
--- a/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
+++ b/apps/web/src/components/clerk/ReferralsUserProfilePage.tsx
@@ -2,7 +2,7 @@ import {
   isAtomCommandInterrupted,
   squashAtomCommandFailure,
 } from "@t3tools/client-runtime/state/runtime";
-import type { RelayReferralClaimResult } from "@t3tools/contracts/relay";
+import { REFERRAL_AWARD_POINTS } from "@t3tools/shared/referral";
 import { CheckIcon, CopyIcon, GiftIcon, LinkIcon, Share2Icon, TicketCheckIcon } from "lucide-react";
 import { type ReactNode, useMemo, useState } from "react";
 
@@ -15,6 +15,7 @@ import {
   buildReferralShareData,
   normalizeReferralCode,
 } from "../../cloud/referralLinks";
+import { referralClaimMessage } from "../../cloud/referralClaimResult";
 import { configuredHostedAppUrl } from "../../hostedPairing";
 import { useCopyToClipboard } from "../../hooks/useCopyToClipboard";
 import { useAtomCommand } from "../../state/use-atom-command";
@@ -30,33 +31,6 @@ import {
   ClerkUserProfileRefreshButton,
 } from "./ClerkUserProfilePage";
 
-function claimResultMessage(result: RelayReferralClaimResult): {
-  readonly type: "success" | "warning" | "info";
-  readonly title: string;
-  readonly description?: string;
-} {
-  switch (result) {
-    case "claimed":
-      return {
-        type: "success",
-        title: "Referral applied",
-        description: "Your referrer will receive 67 points after you link your first environment.",
-      };
-    case "already_claimed":
-      return { type: "info", title: "This account already claimed a referral" };
-    case "invalid_code":
-      return { type: "warning", title: "This referral code is not valid" };
-    case "self_referral":
-      return { type: "warning", title: "You cannot use your own referral code" };
-    case "ineligible":
-      return {
-        type: "info",
-        title: "Referral code not applied",
-        description: "Referral codes must be claimed before linking an environment.",
-      };
-  }
-}
-
 function ReferralMetric(props: { readonly label: string; readonly value: number }) {
   return (
     <div className="min-w-0 rounded-lg px-3 py-3 sm:px-4">
@@ -140,7 +114,7 @@ export function ReferralsUserProfilePage() {
     const result = await claimReferral({ accountId, referralCode: normalized });
     setIsClaiming(false);
     if (result._tag === "Success") {
-      const message = claimResultMessage(result.value.result);
+      const message = referralClaimMessage(result.value.result, result.value.summary.awardPoints);
       toastManager.add(message);
       setReferralCode("");
       summaryState.refresh();
@@ -163,7 +137,7 @@ export function ReferralsUserProfilePage() {
     }
 
     try {
-      await navigator.share(buildReferralShareData(referralLink));
+      await navigator.share(buildReferralShareData(referralLink, summary?.awardPoints));
     } catch (error) {
       if (error instanceof Error && error.name === "AbortError") return;
       toastManager.add({
@@ -180,7 +154,7 @@ export function ReferralsUserProfilePage() {
   return (
     <ClerkUserProfilePage
       title="Referrals"
-      description="Earn 67 points when a friend claims your link before connecting their first environment. Your balance follows your T3 account."
+      description={`Earn ${summary?.awardPoints ?? REFERRAL_AWARD_POINTS} points when a friend claims your link before connecting their first environment. Your balance follows your T3 account.`}
       action={
         <ClerkUserProfileRefreshButton
           disabled={isClaiming}
@@ -277,7 +251,7 @@ export function ReferralsUserProfilePage() {
             </CardContent>
           </Card>
 
-          {!summary.hasClaimedReferral ? (
+          {summary.canClaimReferral ? (
             <Card variant="muted">
               <CardContent className="p-4 sm:p-5">
                 <ReferralSectionHeading
diff --git a/apps/web/src/components/clerk/T3ConnectSidebarSignIn.tsx b/apps/web/src/components/clerk/T3ConnectSidebarSignIn.tsx
index 245cf7b1a04d..1c7ff1ebf469 100644
--- a/apps/web/src/components/clerk/T3ConnectSidebarSignIn.tsx
+++ b/apps/web/src/components/clerk/T3ConnectSidebarSignIn.tsx
@@ -34,6 +34,13 @@ function ConfiguredT3ConnectSidebarAvatar() {
         },
       }}
     >
+      <UserButton.MenuItems>
+        <UserButton.Action
+          label="Referrals"
+          labelIcon={<GiftIcon className="size-4" />}
+          open="referrals"
+        />
+      </UserButton.MenuItems>
       <UserButton.UserProfilePage
         label="Mobile clients"
         labelIcon={<SmartphoneIcon className="size-4" />}
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts
index 6689293c717e..08e2753875c2 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.test.ts
@@ -3,22 +3,8 @@ import { describe, expect, it } from "vite-plus/test";
 import {
   claimReferralWithRetry,
   isCurrentReferralClaimAttempt,
-  referralClaimLoadState,
 } from "./ReferralClaimCoordinator.logic";
 
-describe("referralClaimLoadState", () => {
-  it("only prompts sign-in for a referral captured on the current load", () => {
-    expect(referralClaimLoadState("FROM_URL", "FROM_STORAGE")).toEqual({
-      referralCode: "FROM_URL",
-      shouldPromptSignIn: true,
-    });
-    expect(referralClaimLoadState(null, "FROM_STORAGE")).toEqual({
-      referralCode: "FROM_STORAGE",
-      shouldPromptSignIn: false,
-    });
-  });
-});
-
 describe("claimReferralWithRetry", () => {
   it("retries transient failures with bounded backoff", async () => {
     const results = ["failure", "failure", "success"] as const;
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts
index fa362f3a4e04..e993d8ad7afe 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.logic.ts
@@ -8,16 +8,6 @@ function waitForRetry(delay: number): Promise<void> {
   return new Promise((resolve) => globalThis.setTimeout(resolve, delay));
 }
 
-export function referralClaimLoadState(
-  capturedCode: string | null,
-  storedCode: string | null,
-): { referralCode: string | null; shouldPromptSignIn: boolean } {
-  return {
-    referralCode: capturedCode ?? storedCode,
-    shouldPromptSignIn: capturedCode !== null,
-  };
-}
-
 export function isCurrentReferralClaimAttempt(
   isCancelled: boolean,
   activeAttempt: ReferralClaimAttempt | null,
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
index ee618ebc3751..94b858cce225 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
@@ -5,17 +5,18 @@ import {
   isAtomCommandInterrupted,
   squashAtomCommandFailure,
 } from "@t3tools/client-runtime/state/runtime";
-import type { RelayReferralClaimResult } from "@t3tools/contracts/relay";
 import { useLocation } from "@tanstack/react-router";
-import { useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 
 import {
   claimManagedRelayReferralCommand,
   refreshManagedRelayReferralSummary,
 } from "../../cloud/managedRelayState";
 import { hasCloudPublicConfig } from "../../cloud/publicConfig";
+import { referralClaimMessage } from "../../cloud/referralClaimResult";
 import {
   captureReferralCodeFromUrl,
+  clearPendingReferralCode,
   PENDING_REFERRAL_CODE_STORAGE_KEY,
   readPendingReferralCode,
   urlWithoutMatchingReferralCode,
@@ -28,15 +29,8 @@ import {
   claimReferralWithRetry,
   isCurrentReferralClaimAttempt,
   type ReferralClaimAttempt,
-  referralClaimLoadState,
 } from "./ReferralClaimCoordinator.logic";
 
-function clearPendingReferralCode(): void {
-  try {
-    window.localStorage.removeItem(PENDING_REFERRAL_CODE_STORAGE_KEY);
-  } catch {}
-}
-
 function captureReferralCode(): string | null {
   const url = new URL(window.location.href);
   const captured = captureReferralCodeFromUrl(url, (referralCode) => {
@@ -56,32 +50,6 @@ function clearReferralCodeFromUrl(referralCode: string): void {
   window.history.replaceState(window.history.state, "", cleanedUrl);
 }
 
-function showClaimResult(result: RelayReferralClaimResult): void {
-  switch (result) {
-    case "claimed":
-      toastManager.add({
-        type: "success",
-        title: "Referral applied",
-        description: "Your referrer will receive 67 points after you link your first environment.",
-      });
-      return;
-    case "already_claimed":
-      return;
-    case "invalid_code":
-      toastManager.add({ type: "warning", title: "This referral code is not valid" });
-      return;
-    case "self_referral":
-      toastManager.add({ type: "warning", title: "You cannot use your own referral code" });
-      return;
-    case "ineligible":
-      toastManager.add({
-        type: "info",
-        title: "Referral code not applied",
-        description: "Referral codes must be claimed before linking an environment.",
-      });
-  }
-}
-
 export function ReferralClaimCoordinator() {
   if (!hasCloudPublicConfig()) return null;
   return <ConfiguredReferralClaimCoordinator />;
@@ -98,20 +66,22 @@ function ConfiguredReferralClaimCoordinator() {
   const [pendingReferralCode, setPendingReferralCode] = useState<string | null>(null);
   const activeClaimRef = useRef<ReferralClaimAttempt | null>(null);
   const completedClaimRef = useRef<string | null>(null);
+  const retryToastIdRef = useRef<ReturnType<typeof toastManager.add> | null>(null);
   const initializedReferralRef = useRef(false);
   const promptedSignInRef = useRef<string | null>(null);
   const shouldPromptSignInRef = useRef(false);
+  const closeRetryToast = useCallback(() => {
+    if (retryToastIdRef.current === null) return;
+    toastManager.close(retryToastIdRef.current);
+    retryToastIdRef.current = null;
+  }, []);
 
   useEffect(() => {
     const capturedCode = captureReferralCode();
     if (!capturedCode && initializedReferralRef.current) return;
     initializedReferralRef.current = true;
-    const initial = referralClaimLoadState(
-      capturedCode,
-      capturedCode ? null : readPendingReferralCode(),
-    );
-    shouldPromptSignInRef.current = initial.shouldPromptSignIn;
-    setPendingReferralCode(initial.referralCode);
+    shouldPromptSignInRef.current = capturedCode !== null;
+    setPendingReferralCode(capturedCode ?? readPendingReferralCode());
   }, [locationHref]);
 
   useEffect(() => {
@@ -153,28 +123,41 @@ function ConfiguredReferralClaimCoordinator() {
         if (result._tag === "Success") {
           if (!isCurrentAttempt()) return;
           completedClaimRef.current = attemptKey;
+          closeRetryToast();
           clearPendingReferralCode();
           clearReferralCodeFromUrl(referralCode);
           setPendingReferralCode(null);
           refreshManagedRelayReferralSummary();
-          showClaimResult(result.value.result);
+          if (result.value.result !== "already_claimed") {
+            toastManager.add(
+              referralClaimMessage(result.value.result, result.value.summary.awardPoints),
+            );
+          }
           return;
         }
         if (!isCurrentAttempt() || isAtomCommandInterrupted(result)) return;
         const cause = squashAtomCommandFailure(result);
         console.error("[t3-cloud] Could not claim captured referral code", { cause });
-        toastManager.add(
-          stackedThreadToast({
-            type: "error",
-            title: "Referral still pending",
-            description: "Retry before linking an environment so your referrer can receive points.",
-            timeout: 0,
-            actionProps: {
-              children: "Retry",
-              onClick: () => void runClaim(),
+        const retryToast = stackedThreadToast({
+          type: "error",
+          title: "Referral still pending",
+          description: "Retry before linking an environment so your referrer can receive points.",
+          timeout: 0,
+          actionProps: {
+            children: "Retry",
+            onClick: () => void runClaim(),
+          },
+          data: {
+            onClose: () => {
+              retryToastIdRef.current = null;
             },
-          }),
-        );
+          },
+        });
+        if (retryToastIdRef.current === null) {
+          retryToastIdRef.current = toastManager.add(retryToast);
+        } else {
+          toastManager.update(retryToastIdRef.current, retryToast);
+        }
       } finally {
         if (activeClaimRef.current === attempt) activeClaimRef.current = null;
       }
@@ -184,8 +167,17 @@ function ConfiguredReferralClaimCoordinator() {
     return () => {
       isCancelled = true;
       if (activeClaimRef.current === attempt) activeClaimRef.current = null;
+      closeRetryToast();
     };
-  }, [claimReferral, isLoaded, isSignedIn, pendingReferralCode, relayAccountId, userId]);
+  }, [
+    claimReferral,
+    closeRetryToast,
+    isLoaded,
+    isSignedIn,
+    pendingReferralCode,
+    relayAccountId,
+    userId,
+  ]);
 
   return authPrompt;
 }
diff --git a/apps/web/src/components/ui/card.tsx b/apps/web/src/components/ui/card.tsx
index 79a6334f1ccf..aa069b963080 100644
--- a/apps/web/src/components/ui/card.tsx
+++ b/apps/web/src/components/ui/card.tsx
@@ -198,7 +198,6 @@ function CardFooter({ className, render, ...props }: useRender.ComponentProps<"d
 
 export {
   Card,
-  cardVariants,
   CardFrame,
   CardFrameHeader,
   CardFrameTitle,
diff --git a/docs/internals/t3-connect.md b/docs/internals/t3-connect.md
index 93c5eb2a5517..0139b07b080a 100644
--- a/docs/internals/t3-connect.md
+++ b/docs/internals/t3-connect.md
@@ -264,8 +264,12 @@ the ledger instead of trusting a mutable counter.
 
 A signed-in user can claim one code only before their account has an environment link. The claim is
 pending until `linkEnvironment` succeeds for that account. The link handler then qualifies the
-referral and appends one 67-point ledger entry for the referrer. A unique index on referrer, reason,
-and referred user makes retries idempotent.
+referral and appends one 67-point ledger entry for the referrer. The ledger stores the account's
+first historical environment ID. Unique indexes make retries idempotent and allow a physical
+environment to qualify only one referral award, even if it is linked to multiple accounts.
+Claims lock both participating accounts and reject any edge that would create a referral-chain
+cycle. Referral summaries read the account, eligibility, balance, and referral counts in one SQL
+statement so the client never sees aggregates from mixed snapshots.
 
 Web and desktop expose referrals in the Clerk account menu. A hosted `?ref=` link is captured before
 sign-in and claimed after Clerk supplies the account session. Mobile exposes the same relay-backed
diff --git a/docs/user/referrals.md b/docs/user/referrals.md
index 29df3b3384db..c8a8e7c14286 100644
--- a/docs/user/referrals.md
+++ b/docs/user/referrals.md
@@ -18,4 +18,5 @@ You earn 67 points when someone:
 
 A referral appears as pending after the code is claimed. It becomes successful and adds 67 points
 when the referred account links its first environment. A code can be claimed only once per account,
-and you cannot claim your own code.
+one physical environment can qualify only one referral award, and referral chains cannot loop back
+to an account that is already in the chain.
diff --git a/infra/relay/migrations/postgres/20260826230249_complete_logan/migration.sql b/infra/relay/migrations/postgres/20260827203356_referral_points/migration.sql
similarity index 82%
rename from infra/relay/migrations/postgres/20260826230249_complete_logan/migration.sql
rename to infra/relay/migrations/postgres/20260827203356_referral_points/migration.sql
index d7003997805d..52b801392894 100644
--- a/infra/relay/migrations/postgres/20260826230249_complete_logan/migration.sql
+++ b/infra/relay/migrations/postgres/20260827203356_referral_points/migration.sql
@@ -14,10 +14,12 @@ CREATE TABLE "relay_referral_point_entries" (
 	"points" integer NOT NULL,
 	"reason" varchar(32) NOT NULL,
 	"referred_user_id" varchar(191) NOT NULL,
+	"qualifying_environment_id" varchar(191) NOT NULL,
 	"created_at" varchar(64) NOT NULL
 );
 --> statement-breakpoint
 CREATE UNIQUE INDEX "idx_relay_referral_accounts_code" ON "relay_referral_accounts" ("referral_code");--> statement-breakpoint
 CREATE INDEX "idx_relay_referral_accounts_referrer" ON "relay_referral_accounts" ("referrer_user_id","qualified_at");--> statement-breakpoint
 CREATE INDEX "idx_relay_referral_point_entries_user" ON "relay_referral_point_entries" ("user_id","created_at");--> statement-breakpoint
-CREATE UNIQUE INDEX "idx_relay_referral_point_entries_award" ON "relay_referral_point_entries" ("user_id","reason","referred_user_id");
\ No newline at end of file
+CREATE UNIQUE INDEX "idx_relay_referral_point_entries_award" ON "relay_referral_point_entries" ("user_id","reason","referred_user_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "idx_relay_referral_point_entries_environment_award" ON "relay_referral_point_entries" ("reason","qualifying_environment_id");
\ No newline at end of file
diff --git a/infra/relay/migrations/postgres/20260826230249_complete_logan/snapshot.json b/infra/relay/migrations/postgres/20260827203356_referral_points/snapshot.json
similarity index 97%
rename from infra/relay/migrations/postgres/20260826230249_complete_logan/snapshot.json
rename to infra/relay/migrations/postgres/20260827203356_referral_points/snapshot.json
index a688ee0f0c3c..373c0c0e683a 100644
--- a/infra/relay/migrations/postgres/20260826230249_complete_logan/snapshot.json
+++ b/infra/relay/migrations/postgres/20260827203356_referral_points/snapshot.json
@@ -1,7 +1,7 @@
 {
   "version": "8",
   "dialect": "postgres",
-  "id": "a3c85f32-9315-46ec-acce-8ccb82c0edea",
+  "id": "84e959ac-2c9c-425c-a980-e26b93b5fb24",
   "prevIds": ["2374caff-40bf-423c-9255-55e76dddbc2a"],
   "ddl": [
     {
@@ -1279,6 +1279,19 @@
       "schema": "public",
       "table": "relay_referral_point_entries"
     },
+    {
+      "type": "varchar(191)",
+      "typeSchema": null,
+      "notNull": true,
+      "dimensions": 0,
+      "default": null,
+      "generated": null,
+      "identity": null,
+      "name": "qualifying_environment_id",
+      "entityType": "columns",
+      "schema": "public",
+      "table": "relay_referral_point_entries"
+    },
     {
       "type": "varchar(64)",
       "typeSchema": null,
@@ -1719,6 +1732,34 @@
       "schema": "public",
       "table": "relay_referral_point_entries"
     },
+    {
+      "nameExplicit": true,
+      "columns": [
+        {
+          "value": "reason",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        },
+        {
+          "value": "qualifying_environment_id",
+          "isExpression": false,
+          "asc": true,
+          "nullsFirst": false,
+          "opclass": null
+        }
+      ],
+      "isUnique": true,
+      "where": null,
+      "with": "",
+      "method": "btree",
+      "concurrently": false,
+      "name": "idx_relay_referral_point_entries_environment_award",
+      "entityType": "indexes",
+      "schema": "public",
+      "table": "relay_referral_point_entries"
+    },
     {
       "columns": ["environment_id", "environment_public_key", "thread_id"],
       "nameExplicit": false,
diff --git a/infra/relay/package.json b/infra/relay/package.json
index 4e9519671f22..320253800edb 100644
--- a/infra/relay/package.json
+++ b/infra/relay/package.json
@@ -23,6 +23,7 @@
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260601.1",
     "@effect/platform-node": "catalog:",
+    "@effect/sql-pglite": "catalog:",
     "@effect/vitest": "catalog:",
     "@types/node": "catalog:",
     "drizzle-kit": "1.0.0-rc.4",
diff --git a/infra/relay/src/http/Api.test.ts b/infra/relay/src/http/Api.test.ts
index ad0d0b14fbe8..daa3a708e90a 100644
--- a/infra/relay/src/http/Api.test.ts
+++ b/infra/relay/src/http/Api.test.ts
@@ -68,7 +68,7 @@ const referralSummary = {
   awardPoints: 67,
   qualifiedReferrals: 1,
   pendingReferrals: 0,
-  hasClaimedReferral: false,
+  canClaimReferral: true,
 } as const;
 
 function referralService(
diff --git a/infra/relay/src/persistence/schema.ts b/infra/relay/src/persistence/schema.ts
index a75627633253..8d7a4b1da11f 100644
--- a/infra/relay/src/persistence/schema.ts
+++ b/infra/relay/src/persistence/schema.ts
@@ -135,6 +135,7 @@ export const relayReferralPointEntries = pgTable(
     points: integer("points").notNull(),
     reason: varchar("reason", { length: 32 }).notNull().$type<"qualified_referral">(),
     referredUserId: varchar("referred_user_id", { length: 191 }).notNull(),
+    qualifyingEnvironmentId: varchar("qualifying_environment_id", { length: 191 }).notNull(),
     createdAt: varchar("created_at", { length: 64 }).notNull(),
   },
   (table) => [
@@ -144,6 +145,10 @@ export const relayReferralPointEntries = pgTable(
       table.reason,
       table.referredUserId,
     ),
+    uniqueIndex("idx_relay_referral_point_entries_environment_award").on(
+      table.reason,
+      table.qualifyingEnvironmentId,
+    ),
   ],
 );
 
diff --git a/infra/relay/src/referrals/ReferralProgram.test.ts b/infra/relay/src/referrals/ReferralProgram.test.ts
index f3d84f8b466a..773b36b61d32 100644
--- a/infra/relay/src/referrals/ReferralProgram.test.ts
+++ b/infra/relay/src/referrals/ReferralProgram.test.ts
@@ -1,177 +1,49 @@
+import { PgliteClient } from "@effect/sql-pglite";
 import { describe, expect, it } from "@effect/vitest";
-import { PgDialect } from "drizzle-orm/pg-core";
+import { sql } from "drizzle-orm";
+import * as PgDrizzle from "drizzle-orm/effect-pglite";
 import * as Crypto from "effect/Crypto";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 
 import * as RelayDb from "../db.ts";
-import {
-  relayEnvironmentLinks,
-  relayReferralAccounts,
-  relayReferralPointEntries,
-} from "../persistence/schema.ts";
+import { relayReferralAccounts, relayReferralPointEntries } from "../persistence/schema.ts";
 import * as ReferralProgram from "./ReferralProgram.ts";
 
-type ReferralAccount = typeof relayReferralAccounts.$inferSelect;
-type ReferralPointEntry = typeof relayReferralPointEntries.$inferSelect;
+const TEST_SCHEMA = [
+  `create table relay_environment_links (
+    user_id varchar(191) not null,
+    environment_id varchar(191) not null,
+    created_at varchar(64) not null,
+    primary key (user_id, environment_id)
+  )`,
+  `create table relay_referral_accounts (
+    user_id varchar(191) primary key,
+    referral_code varchar(16) not null,
+    referrer_user_id varchar(191),
+    referred_at varchar(64),
+    qualified_at varchar(64),
+    created_at varchar(64) not null,
+    updated_at varchar(64) not null
+  )`,
+  `create unique index idx_relay_referral_accounts_code
+    on relay_referral_accounts (referral_code)`,
+  `create table relay_referral_point_entries (
+    id varchar(36) primary key,
+    user_id varchar(191) not null,
+    points integer not null,
+    reason varchar(32) not null,
+    referred_user_id varchar(191) not null,
+    qualifying_environment_id varchar(191) not null,
+    created_at varchar(64) not null
+  )`,
+  `create unique index idx_relay_referral_point_entries_award
+    on relay_referral_point_entries (user_id, reason, referred_user_id)`,
+  `create unique index idx_relay_referral_point_entries_environment_award
+    on relay_referral_point_entries (reason, qualifying_environment_id)`,
+] as const;
 
-interface FakeReferralState {
-  readonly accounts: Map<string, ReferralAccount>;
-  readonly claimUpdateSql: Array<string>;
-  readonly environmentUsers: Set<string>;
-  readonly pointEntries: Array<ReferralPointEntry>;
-  beforeClaimUpdate?: () => void;
-  pointInsertFailure?: Error;
-}
-
-const hasSelection = (selection: unknown, key: string): boolean =>
-  typeof selection === "object" && selection !== null && key in selection;
-
-function sqlQuery(condition: unknown) {
-  return new PgDialect().sqlToQuery(condition as never);
-}
-
-function makeFakeDb(state: FakeReferralState) {
-  return {
-    select: (selection?: unknown) => ({
-      from: (table: unknown) => {
-        if (table === relayReferralPointEntries) {
-          return {
-            where: (condition: unknown) => {
-              const userId = String(sqlQuery(condition).params[0]);
-              const points = state.pointEntries
-                .filter((entry) => entry.userId === userId)
-                .reduce((sum, entry) => sum + entry.points, 0);
-              return Effect.succeed([{ points }]);
-            },
-          };
-        }
-
-        if (table === relayEnvironmentLinks) {
-          return {
-            where: (condition: unknown) => ({
-              limit: () => {
-                const userId = String(sqlQuery(condition).params[0]);
-                return Effect.succeed(
-                  state.environmentUsers.has(userId) ? [{ environmentId: "environment-1" }] : [],
-                );
-              },
-            }),
-          };
-        }
-
-        expect(table).toBe(relayReferralAccounts);
-        return {
-          where: (condition: unknown) => {
-            const query = sqlQuery(condition);
-            const value = String(query.params[0]);
-
-            if (hasSelection(selection, "referrals")) {
-              const wantsQualified = query.sql.includes('"qualified_at" is not null');
-              const referrals = [...state.accounts.values()].filter(
-                (account) =>
-                  account.referrerUserId === value &&
-                  (wantsQualified ? account.qualifiedAt !== null : account.qualifiedAt === null),
-              ).length;
-              return Effect.succeed([{ referrals }]);
-            }
-
-            if (
-              hasSelection(selection, "userId") &&
-              query.sql.includes('"qualified_at" is null') &&
-              query.sql.includes('from "relay_environment_links"')
-            ) {
-              const referrerUserId = query.sql.includes('"referrer_user_id" =') ? value : null;
-              return Effect.succeed(
-                [...state.accounts.values()]
-                  .filter(
-                    (row) =>
-                      row.referrerUserId !== null &&
-                      row.qualifiedAt === null &&
-                      state.environmentUsers.has(row.userId) &&
-                      (referrerUserId === null || row.referrerUserId === referrerUserId),
-                  )
-                  .map((row) => ({ userId: row.userId })),
-              );
-            }
-
-            const account = hasSelection(selection, "userId")
-              ? [...state.accounts.values()].find((row) => row.referralCode === value)
-              : state.accounts.get(value);
-            return {
-              limit: () => Effect.succeed(account ? [account] : []),
-            };
-          },
-        };
-      },
-    }),
-    insert: (table: unknown) => ({
-      values: (value: ReferralAccount | ReferralPointEntry) => ({
-        onConflictDoNothing: () => ({
-          returning: () => {
-            if (table === relayReferralAccounts) {
-              const account = value as ReferralAccount;
-              const conflict =
-                state.accounts.has(account.userId) ||
-                [...state.accounts.values()].some(
-                  (existing) => existing.referralCode === account.referralCode,
-                );
-              if (conflict) return Effect.succeed([]);
-              state.accounts.set(account.userId, account);
-              return Effect.succeed([account]);
-            }
-
-            expect(table).toBe(relayReferralPointEntries);
-            if (state.pointInsertFailure) return Effect.fail(state.pointInsertFailure);
-            const entry = value as ReferralPointEntry;
-            const conflict = state.pointEntries.some(
-              (existing) =>
-                existing.userId === entry.userId &&
-                existing.reason === entry.reason &&
-                existing.referredUserId === entry.referredUserId,
-            );
-            if (conflict) return Effect.succeed([]);
-            state.pointEntries.push(entry);
-            return Effect.succeed([{ id: entry.id }]);
-          },
-        }),
-      }),
-    }),
-    update: (table: unknown) => {
-      expect(table).toBe(relayReferralAccounts);
-      return {
-        set: (values: Partial<ReferralAccount>) => ({
-          where: (condition: unknown) => {
-            const query = sqlQuery(condition);
-            const userId = String(query.params[0]);
-            const account = state.accounts.get(userId);
-
-            if (values.referrerUserId !== undefined) {
-              state.claimUpdateSql.push(query.sql);
-              return {
-                returning: () => {
-                  const eligible =
-                    account !== undefined &&
-                    account.referrerUserId === null &&
-                    !state.environmentUsers.has(userId);
-                  state.beforeClaimUpdate?.();
-                  if (!eligible || !account) return Effect.succeed([]);
-                  state.accounts.set(userId, { ...account, ...values });
-                  return Effect.succeed([{ userId }]);
-                },
-              };
-            }
-
-            if (account) state.accounts.set(userId, { ...account, ...values });
-            return Effect.void;
-          },
-        }),
-      };
-    },
-  } as unknown as RelayDb.RelayDb["Service"];
-}
-
-function makeTestLayer(state: FakeReferralState) {
+function makeTestLayer() {
   let randomByte = 0;
   const crypto = Crypto.make({
     randomBytes: (size) => {
@@ -180,166 +52,232 @@ function makeTestLayer(state: FakeReferralState) {
     },
     digest: (_algorithm, data) => Effect.succeed(data),
   });
-  const db = makeFakeDb(state);
-  return ReferralProgram.layer.pipe(
-    Layer.provide(
-      Layer.mergeAll(
-        Layer.succeed(RelayDb.RelayDb, db),
-        Layer.succeed(
-          RelayDb.RelayTransactions,
-          RelayDb.RelayTransactions.of({
-            withTransaction: (effect) =>
-              Effect.suspend(() => {
-                const accounts = new Map(state.accounts);
-                const pointEntries = [...state.pointEntries];
-                return effect.pipe(
-                  Effect.tapError(() =>
-                    Effect.sync(() => {
-                      state.accounts.clear();
-                      for (const [userId, account] of accounts) {
-                        state.accounts.set(userId, account);
-                      }
-                      state.pointEntries.splice(0, state.pointEntries.length, ...pointEntries);
-                    }),
-                  ),
-                );
-              }),
-          }),
-        ),
-        Layer.succeed(Crypto.Crypto, crypto),
-      ),
+  const relayDbLayer = Layer.effect(
+    RelayDb.RelayDb,
+    PgDrizzle.makeWithDefaults().pipe(
+      Effect.map((db) => db as unknown as RelayDb.RelayDb["Service"]),
     ),
+  ).pipe(Layer.provide(PgliteClient.layer()));
+
+  return Layer.empty.pipe(
+    Layer.provideMerge(ReferralProgram.layer),
+    Layer.provideMerge(RelayDb.RelayTransactions.layer),
+    Layer.provideMerge(relayDbLayer),
+    Layer.provideMerge(Layer.succeed(Crypto.Crypto, crypto)),
   );
 }
 
-function makeState(): FakeReferralState {
-  return {
-    accounts: new Map(),
-    claimUpdateSql: [],
-    environmentUsers: new Set(),
-    pointEntries: [],
-  };
+const setupDatabase = Effect.gen(function* () {
+  const db = yield* RelayDb.RelayDb;
+  yield* Effect.forEach(TEST_SCHEMA, (statement) => db.execute(sql.raw(statement)), {
+    concurrency: 1,
+    discard: true,
+  });
+});
+
+function linkEnvironment(userId: string, environmentId: string, createdAt: string) {
+  return Effect.gen(function* () {
+    const db = yield* RelayDb.RelayDb;
+    yield* db.execute(
+      sql`insert into relay_environment_links (user_id, environment_id, created_at)
+          values (${userId}, ${environmentId}, ${createdAt})`,
+    );
+  });
+}
+
+function testEffect<A, E>(
+  effect: Effect.Effect<A, E, ReferralProgram.ReferralProgram | RelayDb.RelayDb>,
+) {
+  return Effect.gen(function* () {
+    yield* setupDatabase;
+    return yield* effect;
+  }).pipe(Effect.provide(makeTestLayer()));
 }
 
-describe("ReferralProgram", () => {
-  it.effect("uses all 64 random bits in generated referral codes", () => {
-    const state = makeState();
-    return Effect.gen(function* () {
-      const referrals = yield* ReferralProgram.ReferralProgram;
+describe("ReferralProgram with PostgreSQL", () => {
+  it.effect("uses all 64 random bits and reports historical link eligibility", () =>
+    testEffect(
+      Effect.gen(function* () {
+        const referrals = yield* ReferralProgram.ReferralProgram;
 
-      expect((yield* referrals.getSummary({ userId: "first" })).referralCode).toBe(
-        "0101010101010101",
-      );
-      expect((yield* referrals.getSummary({ userId: "second" })).referralCode).toBe(
-        "0202020202020202",
-      );
-    }).pipe(Effect.provide(makeTestLayer(state)));
-  });
+        expect(yield* referrals.getSummary({ userId: "first" })).toMatchObject({
+          referralCode: "0101010101010101",
+          canClaimReferral: true,
+        });
+        expect((yield* referrals.getSummary({ userId: "second" })).referralCode).toBe(
+          "0202020202020202",
+        );
+
+        yield* linkEnvironment("linked-user", "environment-1", "2026-08-01T00:00:00.000Z");
+        expect(yield* referrals.getSummary({ userId: "linked-user" })).toMatchObject({
+          canClaimReferral: false,
+        });
+      }),
+    ),
+  );
 
-  it.effect("awards 67 account points once when the referred account links", () => {
-    const state = makeState();
-    return Effect.gen(function* () {
-      const referrals = yield* ReferralProgram.ReferralProgram;
-      const referrer = yield* referrals.getSummary({ userId: "referrer" });
-      const claim = yield* referrals.claim({
-        userId: "referred",
-        referralCode: referrer.referralCode.toLowerCase(),
-      });
+  it.effect("claims once, rejects late claims, and prevents referral-chain cycles", () =>
+    testEffect(
+      Effect.gen(function* () {
+        const referrals = yield* ReferralProgram.ReferralProgram;
+        const a = yield* referrals.getSummary({ userId: "account-a" });
+        const b = yield* referrals.getSummary({ userId: "account-b" });
 
-      expect(claim.result).toBe("claimed");
-      expect((yield* referrals.getSummary({ userId: "referrer" })).pendingReferrals).toBe(1);
-      state.environmentUsers.add("referred");
-      expect(yield* referrals.qualify({ userId: "referred" })).toBe(true);
-      expect(yield* referrals.qualify({ userId: "referred" })).toBe(false);
+        const concurrentClaims = yield* Effect.all(
+          [
+            referrals.claim({ userId: "account-a", referralCode: b.referralCode }),
+            referrals.claim({ userId: "account-b", referralCode: a.referralCode }),
+          ],
+          { concurrency: "unbounded" },
+        );
+        expect(concurrentClaims.map((claim) => claim.result).sort()).toEqual([
+          "claimed",
+          "self_referral",
+        ]);
 
-      expect(yield* referrals.getSummary({ userId: "referrer" })).toMatchObject({
-        points: 67,
-        awardPoints: 67,
-        qualifiedReferrals: 1,
-        pendingReferrals: 0,
-      });
-      expect(state.pointEntries).toHaveLength(1);
-    }).pipe(Effect.provide(makeTestLayer(state)));
-  });
+        const referrer = yield* referrals.getSummary({ userId: "referrer" });
+        yield* linkEnvironment("linked-user", "environment-2", "2026-08-02T00:00:00.000Z");
+        expect(
+          (yield* referrals.claim({
+            userId: "linked-user",
+            referralCode: referrer.referralCode,
+          })).result,
+        ).toBe("ineligible");
+        expect(
+          (yield* referrals.claim({
+            userId: "referrer",
+            referralCode: referrer.referralCode,
+          })).result,
+        ).toBe("self_referral");
+        expect(
+          (yield* referrals.claim({
+            userId: "fresh-user",
+            referralCode: "FFFFFFFFFFFFFFFF",
+          })).result,
+        ).toBe("invalid_code");
+      }),
+    ),
+  );
 
-  it.effect("rejects self-referrals and accounts that already linked an environment", () => {
-    const state = makeState();
-    state.environmentUsers.add("linked-user");
-    return Effect.gen(function* () {
-      const referrals = yield* ReferralProgram.ReferralProgram;
-      const referrer = yield* referrals.getSummary({ userId: "referrer" });
+  it.effect("awards one account once under concurrent qualification", () =>
+    testEffect(
+      Effect.gen(function* () {
+        const referrals = yield* ReferralProgram.ReferralProgram;
+        const referrer = yield* referrals.getSummary({ userId: "referrer" });
+        expect(
+          (yield* referrals.claim({
+            userId: "referred",
+            referralCode: referrer.referralCode,
+          })).result,
+        ).toBe("claimed");
+        yield* linkEnvironment("referred", "environment-1", "2026-08-03T00:00:00.000Z");
 
-      expect(
-        (yield* referrals.claim({
-          userId: "referrer",
-          referralCode: referrer.referralCode,
-        })).result,
-      ).toBe("self_referral");
-      expect(
-        (yield* referrals.claim({
-          userId: "linked-user",
-          referralCode: referrer.referralCode,
-        })).result,
-      ).toBe("ineligible");
-    }).pipe(Effect.provide(makeTestLayer(state)));
-  });
+        const qualificationResults = yield* Effect.all(
+          [
+            referrals.qualify({ userId: "referred" }),
+            referrals.qualify({ userId: "referred" }),
+            referrals.qualify({ userId: "referred" }),
+          ],
+          { concurrency: "unbounded" },
+        );
+        expect(qualificationResults.filter(Boolean)).toHaveLength(1);
+        expect(yield* referrals.getSummary({ userId: "referrer" })).toMatchObject({
+          points: 67,
+          awardPoints: 67,
+          qualifiedReferrals: 1,
+          pendingReferrals: 0,
+        });
+      }),
+    ),
+  );
 
-  it.effect("awards a referral when the first link commits during the claim write", () => {
-    const state = makeState();
-    return Effect.gen(function* () {
-      const referrals = yield* ReferralProgram.ReferralProgram;
-      const referrer = yield* referrals.getSummary({ userId: "referrer" });
-      state.beforeClaimUpdate = () => state.environmentUsers.add("referred");
+  it.effect("allows only one award per physical environment across accounts", () =>
+    testEffect(
+      Effect.gen(function* () {
+        const referrals = yield* ReferralProgram.ReferralProgram;
+        const db = yield* RelayDb.RelayDb;
+        const referrer = yield* referrals.getSummary({ userId: "referrer" });
 
-      expect(
-        (yield* referrals.claim({
-          userId: "referred",
-          referralCode: referrer.referralCode,
-        })).result,
-      ).toBe("claimed");
-      expect(state.claimUpdateSql[0]).toContain("not exists");
-      expect(state.claimUpdateSql[0]).toContain('from "relay_environment_links"');
-      expect(yield* referrals.getSummary({ userId: "referrer" })).toMatchObject({
-        points: 67,
-        qualifiedReferrals: 1,
-        pendingReferrals: 0,
-      });
-    }).pipe(Effect.provide(makeTestLayer(state)));
-  });
+        for (const userId of ["referred-a", "referred-b"] as const) {
+          expect(
+            (yield* referrals.claim({ userId, referralCode: referrer.referralCode })).result,
+          ).toBe("claimed");
+          yield* linkEnvironment(userId, "shared-environment", "2026-08-04T00:00:00.000Z");
+        }
 
-  it.effect("keeps a claim recoverable when its immediate point award cannot be persisted", () => {
-    const state = makeState();
-    state.pointInsertFailure = new Error("point insert failed");
-    return Effect.gen(function* () {
-      const referrals = yield* ReferralProgram.ReferralProgram;
-      const referrer = yield* referrals.getSummary({ userId: "referrer" });
-      state.beforeClaimUpdate = () => state.environmentUsers.add("referred");
+        const results = yield* Effect.all(
+          [
+            referrals.qualify({ userId: "referred-a" }),
+            referrals.qualify({ userId: "referred-b" }),
+          ],
+          { concurrency: "unbounded" },
+        );
+        expect(results.filter(Boolean)).toHaveLength(1);
+        expect(yield* referrals.getSummary({ userId: "referrer" })).toMatchObject({
+          points: 67,
+          qualifiedReferrals: 1,
+          pendingReferrals: 1,
+        });
+        const entries = yield* db.select().from(relayReferralPointEntries);
+        expect(entries).toHaveLength(1);
+        expect(entries[0]?.qualifyingEnvironmentId).toBe("shared-environment");
+      }),
+    ),
+  );
 
-      expect(
-        (yield* referrals.claim({
-          userId: "referred",
-          referralCode: referrer.referralCode,
-        })).result,
-      ).toBe("claimed");
-      expect(state.accounts.get("referred")?.referrerUserId).toBe("referrer");
-      expect(state.pointEntries).toHaveLength(0);
+  it.effect("rolls back a partial award and recovers it later", () =>
+    testEffect(
+      Effect.gen(function* () {
+        const referrals = yield* ReferralProgram.ReferralProgram;
+        const db = yield* RelayDb.RelayDb;
+        const referrer = yield* referrals.getSummary({ userId: "referrer" });
+        expect(
+          (yield* referrals.claim({
+            userId: "referred",
+            referralCode: referrer.referralCode,
+          })).result,
+        ).toBe("claimed");
+        yield* linkEnvironment("referred", "environment-1", "2026-08-05T00:00:00.000Z");
+        yield* db.execute(
+          sql.raw(`
+          create function reject_referral_qualification() returns trigger language plpgsql as $$
+          begin
+            if new.qualified_at is not null then
+              raise exception 'qualification update failed';
+            end if;
+            return new;
+          end;
+          $$
+        `),
+        );
+        yield* db.execute(
+          sql.raw(`
+          create trigger reject_referral_qualification
+          before update on relay_referral_accounts
+          for each row execute function reject_referral_qualification()
+        `),
+        );
 
-      const error = yield* Effect.flip(referrals.qualify({ userId: "referred" }));
-      expect(error).toMatchObject({
-        _tag: "ReferralProgramPersistenceError",
-        operation: "qualify-referral",
-        cause: state.pointInsertFailure,
-      });
+        yield* Effect.flip(referrals.qualify({ userId: "referred" }));
+        expect(yield* db.select().from(relayReferralPointEntries)).toHaveLength(0);
+        expect(
+          (yield* db
+            .select({ qualifiedAt: relayReferralAccounts.qualifiedAt })
+            .from(relayReferralAccounts)
+            .where(sql`${relayReferralAccounts.userId} = ${"referred"}`))[0]?.qualifiedAt,
+        ).toBeNull();
 
-      delete state.pointInsertFailure;
-      expect(yield* referrals.recoverPendingAwards({ referrerUserId: "someone-else" })).toBe(0);
-      expect(yield* referrals.recoverPendingAwards({ referrerUserId: "referrer" })).toBe(1);
-      expect(yield* referrals.recoverPendingAwards()).toBe(0);
-      expect(yield* referrals.getSummary({ userId: "referrer" })).toMatchObject({
-        points: 67,
-        qualifiedReferrals: 1,
-        pendingReferrals: 0,
-      });
-    }).pipe(Effect.provide(makeTestLayer(state)));
-  });
+        yield* db.execute(
+          sql.raw("drop trigger reject_referral_qualification on relay_referral_accounts"),
+        );
+        expect(yield* referrals.recoverPendingAwards({ referrerUserId: "referrer" })).toBe(1);
+        expect(yield* referrals.recoverPendingAwards()).toBe(0);
+        expect(yield* referrals.getSummary({ userId: "referrer" })).toMatchObject({
+          points: 67,
+          qualifiedReferrals: 1,
+          pendingReferrals: 0,
+        });
+      }),
+    ),
+  );
 });
diff --git a/infra/relay/src/referrals/ReferralProgram.ts b/infra/relay/src/referrals/ReferralProgram.ts
index 83a77b9dd425..f1a4ca3d16f4 100644
--- a/infra/relay/src/referrals/ReferralProgram.ts
+++ b/infra/relay/src/referrals/ReferralProgram.ts
@@ -3,8 +3,9 @@ import type {
   RelayReferralClaimResult,
   RelayReferralSummary,
 } from "@t3tools/contracts/relay";
-import { normalizeReferralCode } from "@t3tools/shared/referral";
-import { and, count, eq, isNotNull, isNull, sql } from "drizzle-orm";
+import { normalizeReferralCode, REFERRAL_AWARD_POINTS } from "@t3tools/shared/referral";
+import { and, asc, eq, isNotNull, isNull, sql } from "drizzle-orm";
+import { alias } from "drizzle-orm/pg-core";
 import * as Context from "effect/Context";
 import * as Crypto from "effect/Crypto";
 import * as DateTime from "effect/DateTime";
@@ -20,8 +21,6 @@ import {
   relayReferralPointEntries,
 } from "../persistence/schema.ts";
 
-export const REFERRAL_AWARD_POINTS = 67;
-
 type ReferralAccountRecord = typeof relayReferralAccounts.$inferSelect;
 
 export class ReferralProgramPersistenceError extends Schema.TaggedErrorClass<ReferralProgramPersistenceError>()(
@@ -146,59 +145,68 @@ export const make = Effect.gen(function* () {
   const getSummary = Effect.fn("relay.referrals.get_summary")(function* (input: {
     readonly userId: string;
   }) {
-    const account = yield* ensureAccount(input.userId);
-    const [pointRows, qualifiedRows, pendingRows] = yield* Effect.all(
-      [
-        db
-          .select({
-            points: sql<number>`coalesce(sum(${relayReferralPointEntries.points}), 0)`.mapWith(
-              Number,
-            ),
-          })
-          .from(relayReferralPointEntries)
-          .where(eq(relayReferralPointEntries.userId, input.userId)),
-        db
-          .select({ referrals: count() })
-          .from(relayReferralAccounts)
-          .where(
-            and(
-              eq(relayReferralAccounts.referrerUserId, input.userId),
-              isNotNull(relayReferralAccounts.qualifiedAt),
-            ),
-          ),
-        db
-          .select({ referrals: count() })
-          .from(relayReferralAccounts)
-          .where(
-            and(
-              eq(relayReferralAccounts.referrerUserId, input.userId),
-              isNull(relayReferralAccounts.qualifiedAt),
-            ),
-          ),
-      ],
-      { concurrency: "unbounded" },
-    ).pipe(
-      Effect.mapError(
-        (cause) =>
-          new ReferralProgramPersistenceError({
-            operation: "load-summary",
-            userId: input.userId,
-            cause,
-          }),
-      ),
-    );
+    yield* ensureAccount(input.userId);
+    const account = alias(relayReferralAccounts, "referral_account");
+    const rows = yield* db
+      .select({
+        referralCode: account.referralCode,
+        points: sql<number>`(
+            select coalesce(sum(point_entries.points), 0)
+            from ${relayReferralPointEntries} as point_entries
+            where point_entries.user_id = ${input.userId}
+          )`.mapWith(Number),
+        qualifiedReferrals: sql<number>`(
+            select count(*)
+            from ${relayReferralAccounts} as referred_accounts
+            where referred_accounts.referrer_user_id = ${input.userId}
+              and referred_accounts.qualified_at is not null
+          )`.mapWith(Number),
+        pendingReferrals: sql<number>`(
+            select count(*)
+            from ${relayReferralAccounts} as referred_accounts
+            where referred_accounts.referrer_user_id = ${input.userId}
+              and referred_accounts.qualified_at is null
+          )`.mapWith(Number),
+        canClaimReferral: sql<boolean>`(
+          ${account.referrerUserId} is null
+          and not exists (
+            select 1 from ${relayEnvironmentLinks} as environment_links
+            where environment_links.user_id = ${input.userId}
+          )
+        )`.mapWith(Boolean),
+      })
+      .from(account)
+      .where(eq(account.userId, input.userId))
+      .limit(1)
+      .pipe(
+        Effect.mapError(
+          (cause) =>
+            new ReferralProgramPersistenceError({
+              operation: "load-summary",
+              userId: input.userId,
+              cause,
+            }),
+        ),
+      );
+    const summary = rows[0];
+    if (!summary) {
+      return yield* new ReferralProgramPersistenceError({
+        operation: "load-summary",
+        userId: input.userId,
+      });
+    }
 
     return {
-      points: pointRows[0]?.points ?? 0,
-      referralCode: account.referralCode,
+      points: summary.points,
+      referralCode: summary.referralCode,
       awardPoints: REFERRAL_AWARD_POINTS,
-      qualifiedReferrals: qualifiedRows[0]?.referrals ?? 0,
-      pendingReferrals: pendingRows[0]?.referrals ?? 0,
-      hasClaimedReferral: account.referrerUserId !== null,
+      qualifiedReferrals: summary.qualifiedReferrals,
+      pendingReferrals: summary.pendingReferrals,
+      canClaimReferral: summary.canClaimReferral,
     } satisfies RelayReferralSummary;
   });
 
-  const hasEnvironmentLink = Effect.fn("relay.referrals.has_environment_link")(function* (
+  const firstEnvironmentLink = Effect.fn("relay.referrals.first_environment_link")(function* (
     userId: string,
     operation: "claim-referral" | "qualify-referral",
   ) {
@@ -206,6 +214,7 @@ export const make = Effect.gen(function* () {
       .select({ environmentId: relayEnvironmentLinks.environmentId })
       .from(relayEnvironmentLinks)
       .where(eq(relayEnvironmentLinks.userId, userId))
+      .orderBy(asc(relayEnvironmentLinks.createdAt), asc(relayEnvironmentLinks.environmentId))
       .limit(1)
       .pipe(
         Effect.mapError(
@@ -217,12 +226,13 @@ export const make = Effect.gen(function* () {
             }),
         ),
       );
-    return rows.length > 0;
+    return rows[0] ?? null;
   });
 
   const qualifyInCurrentTransaction = Effect.fn("relay.referrals.qualify_in_current_transaction")(
     function* (input: { readonly userId: string }) {
-      if (!(yield* hasEnvironmentLink(input.userId, "qualify-referral"))) return false;
+      const environmentLink = yield* firstEnvironmentLink(input.userId, "qualify-referral");
+      if (!environmentLink) return false;
 
       const account = yield* loadAccount(input.userId);
       if (!account?.referrerUserId || account.qualifiedAt !== null) return false;
@@ -247,6 +257,7 @@ export const make = Effect.gen(function* () {
           points: REFERRAL_AWARD_POINTS,
           reason: "qualified_referral",
           referredUserId: input.userId,
+          qualifyingEnvironmentId: environmentLink.environmentId,
           createdAt: now,
         })
         .onConflictDoNothing()
@@ -344,6 +355,95 @@ export const make = Effect.gen(function* () {
     },
   );
 
+  const claimInCurrentTransaction = Effect.fn("relay.referrals.claim_in_current_transaction")(
+    function* (input: { readonly userId: string; readonly referrerUserId: string }) {
+      yield* db
+        .execute(
+          sql`select ${relayReferralAccounts.userId}
+            from ${relayReferralAccounts}
+            where ${relayReferralAccounts.userId} in (${input.userId}, ${input.referrerUserId})
+            order by ${relayReferralAccounts.userId}
+            for update`,
+        )
+        .pipe(
+          Effect.mapError(
+            (cause) =>
+              new ReferralProgramPersistenceError({
+                operation: "claim-referral",
+                userId: input.userId,
+                cause,
+              }),
+          ),
+        );
+
+      const current = yield* loadAccount(input.userId);
+      if (current?.referrerUserId !== null) return "already_claimed" as const;
+      if (yield* firstEnvironmentLink(input.userId, "claim-referral")) {
+        return "ineligible" as const;
+      }
+
+      const cycleRows = yield* db
+        .select({
+          createsCycle: sql<boolean>`exists (
+          with recursive referral_chain(user_id, referrer_user_id) as (
+            select referral_root.user_id, referral_root.referrer_user_id
+            from ${relayReferralAccounts} as referral_root
+            where referral_root.user_id = ${input.referrerUserId}
+            union
+            select referral_ancestor.user_id, referral_ancestor.referrer_user_id
+            from ${relayReferralAccounts} as referral_ancestor
+            inner join referral_chain
+              on referral_ancestor.user_id = referral_chain.referrer_user_id
+          )
+          select 1 from referral_chain where user_id = ${input.userId}
+        )`.mapWith(Boolean),
+        })
+        .from(relayReferralAccounts)
+        .limit(1)
+        .pipe(
+          Effect.mapError(
+            (cause) =>
+              new ReferralProgramPersistenceError({
+                operation: "claim-referral",
+                userId: input.userId,
+                cause,
+              }),
+          ),
+        );
+      if (cycleRows[0]?.createsCycle) return "self_referral" as const;
+
+      const now = DateTime.formatIso(yield* DateTime.now);
+      const claimed = yield* db
+        .update(relayReferralAccounts)
+        .set({ referrerUserId: input.referrerUserId, referredAt: now, updatedAt: now })
+        .where(
+          and(
+            eq(relayReferralAccounts.userId, input.userId),
+            isNull(relayReferralAccounts.referrerUserId),
+            sql`not exists (
+            select 1 from ${relayEnvironmentLinks}
+            where ${relayEnvironmentLinks.userId} = ${input.userId}
+          )`,
+          ),
+        )
+        .returning({ userId: relayReferralAccounts.userId })
+        .pipe(
+          Effect.mapError(
+            (cause) =>
+              new ReferralProgramPersistenceError({
+                operation: "claim-referral",
+                userId: input.userId,
+                cause,
+              }),
+          ),
+        );
+      if (claimed.length > 0) return "claimed" as const;
+
+      const raced = yield* loadAccount(input.userId);
+      return raced?.referrerUserId ? ("already_claimed" as const) : ("ineligible" as const);
+    },
+  );
+
   const claim = Effect.fn("relay.referrals.claim")(function* (input: {
     readonly userId: string;
     readonly referralCode: string;
@@ -377,42 +477,19 @@ export const make = Effect.gen(function* () {
       } else if (referrerUserId === input.userId) {
         result = "self_referral";
       } else {
-        const now = DateTime.formatIso(yield* DateTime.now);
-        const claimed = yield* db
-          .update(relayReferralAccounts)
-          .set({ referrerUserId, referredAt: now, updatedAt: now })
-          .where(
-            and(
-              eq(relayReferralAccounts.userId, input.userId),
-              isNull(relayReferralAccounts.referrerUserId),
-              sql`not exists (
-                select 1 from ${relayEnvironmentLinks}
-                where ${relayEnvironmentLinks.userId} = ${input.userId}
-              )`,
-            ),
-          )
-          .returning({ userId: relayReferralAccounts.userId })
+        result = yield* transactions
+          .withTransaction(claimInCurrentTransaction({ userId: input.userId, referrerUserId }))
           .pipe(
-            Effect.mapError(
-              (cause) =>
-                new ReferralProgramPersistenceError({
-                  operation: "claim-referral",
-                  userId: input.userId,
-                  cause,
-                }),
+            Effect.mapError((cause) =>
+              isReferralProgramPersistenceError(cause)
+                ? cause
+                : new ReferralProgramPersistenceError({
+                    operation: "claim-referral",
+                    userId: input.userId,
+                    cause,
+                  }),
             ),
           );
-
-        if (claimed.length > 0) {
-          result = "claimed";
-        } else {
-          const current = yield* loadAccount(input.userId);
-          result = current?.referrerUserId
-            ? "already_claimed"
-            : (yield* hasEnvironmentLink(input.userId, "claim-referral"))
-              ? "ineligible"
-              : "already_claimed";
-        }
       }
     }
 
diff --git a/packages/client-runtime/src/relay/managedRelayState.test.ts b/packages/client-runtime/src/relay/managedRelayState.test.ts
index bb670a0bfbd4..fca81b3bd2ad 100644
--- a/packages/client-runtime/src/relay/managedRelayState.test.ts
+++ b/packages/client-runtime/src/relay/managedRelayState.test.ts
@@ -65,7 +65,7 @@ const referralSummary = {
   awardPoints: 67,
   qualifiedReferrals: 1,
   pendingReferrals: 0,
-  hasClaimedReferral: false,
+  canClaimReferral: true,
 } as const;
 
 function resetRegistry() {
diff --git a/packages/contracts/src/relay.ts b/packages/contracts/src/relay.ts
index a36f0809229b..04adf79056c8 100644
--- a/packages/contracts/src/relay.ts
+++ b/packages/contracts/src/relay.ts
@@ -639,7 +639,7 @@ export const RelayReferralSummary = Schema.Struct({
   awardPoints: Schema.Int.check(Schema.isGreaterThan(0)),
   qualifiedReferrals: RelayNonNegativeInt,
   pendingReferrals: RelayNonNegativeInt,
-  hasClaimedReferral: Schema.Boolean,
+  canClaimReferral: Schema.Boolean,
 });
 export type RelayReferralSummary = typeof RelayReferralSummary.Type;
 
diff --git a/packages/shared/src/referral.test.ts b/packages/shared/src/referral.test.ts
index f92f5cc6c8c9..2523a667af71 100644
--- a/packages/shared/src/referral.test.ts
+++ b/packages/shared/src/referral.test.ts
@@ -4,7 +4,6 @@ import {
   buildReferralLink,
   buildReferralShareMessage,
   normalizeReferralCode,
-  REFERRAL_SHARE_TEXT,
   REFERRAL_SHARE_TITLE,
 } from "./referral.js";
 
@@ -29,7 +28,9 @@ describe("referral", () => {
   it("builds accurate cross-platform share copy", () => {
     const link = "https://app.t3.codes/?ref=ABCD1234EFAB5678";
     expect(REFERRAL_SHARE_TITLE).toBe("T3 Code referral");
-    expect(buildReferralShareMessage(link)).toBe(`${REFERRAL_SHARE_TEXT}\n${link}`);
-    expect(buildReferralShareMessage(link)).toContain("I get 67 points");
+    expect(buildReferralShareMessage(link)).toBe(
+      `Try T3 Code with my referral. If you claim it before linking your first environment, I get 67 points.\n${link}`,
+    );
+    expect(buildReferralShareMessage(link, 100)).toContain("I get 100 points");
   });
 });
diff --git a/packages/shared/src/referral.ts b/packages/shared/src/referral.ts
index 61d859f2d9f7..c2ec29817856 100644
--- a/packages/shared/src/referral.ts
+++ b/packages/shared/src/referral.ts
@@ -1,8 +1,7 @@
-export const REFERRAL_CODE_LENGTH = 16;
+const REFERRAL_CODE_LENGTH = 16;
 const REFERRAL_CODE_PATTERN = new RegExp(`^[A-F0-9]{${REFERRAL_CODE_LENGTH}}$`, "u");
 export const REFERRAL_SHARE_TITLE = "T3 Code referral";
-export const REFERRAL_SHARE_TEXT =
-  "Try T3 Code with my referral. If you claim it before linking your first environment, I get 67 points.";
+export const REFERRAL_AWARD_POINTS = 67;
 
 export function normalizeReferralCode(value: string): string | null {
   const code = value.trim().replaceAll("-", "").toUpperCase();
@@ -19,6 +18,9 @@ export function buildReferralLink(hostedAppUrl: string, referralCode: string): s
   return url.toString();
 }
 
-export function buildReferralShareMessage(referralLink: string): string {
-  return `${REFERRAL_SHARE_TEXT}\n${referralLink}`;
+export function buildReferralShareMessage(
+  referralLink: string,
+  awardPoints = REFERRAL_AWARD_POINTS,
+): string {
+  return `Try T3 Code with my referral. If you claim it before linking your first environment, I get ${awardPoints} points.\n${referralLink}`;
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 8986f0f8586a..7ecbd09e218f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -64,6 +64,7 @@ overrides:
   '@effect/platform-node': 4.0.0-beta.103
   '@effect/platform-node-shared': 4.0.0-beta.103
   '@effect/sql-pg': 4.0.0-beta.103
+  '@effect/sql-pglite': 4.0.0-beta.103
   '@effect/sql-sqlite-bun': 4.0.0-beta.103
   '@effect/vitest': 4.0.0-beta.103
   '@effect/vitest>vitest': '-'
@@ -719,10 +720,10 @@ importers:
         version: link:../../packages/shared
       alchemy:
         specifier: 2.0.0-beta.65
-        version: 2.0.0-beta.65(75567d8add6e3362e26fe00f83a97bee)
+        version: 2.0.0-beta.65(04a0b03b072a2401cedb7e596732b3a5)
       drizzle-orm:
         specifier: 1.0.0-rc.4
-        version: 1.0.0-rc.4(@cloudflare/workers-types@4.20260604.1)(@effect/sql-d1@4.0.0-beta.101(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)))(@effect/sql-pg@4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)))(@effect/sql-sqlite-bun@4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)))(@libsql/client@0.17.3(bufferutil@4.1.0)(utf-8-validate@6.0.6))(bun-types@1.3.14)(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))(expo-sqlite@56.0.5(expo@56.0.12)(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.3(@babel/core@7.29.7)(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@types/react@19.2.16)(bufferutil@4.1.0)(react@19.2.6)(utf-8-validate@6.0.6))(react@19.2.6))(mysql2@3.22.4(@types/node@24.12.4))(pg@8.21.0)(zod@4.4.3)
+        version: 1.0.0-rc.4(1092673c7857e2d833af4a5f3ad85f01)
       effect:
         specifier: 4.0.0-beta.103
         version: 4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)
@@ -733,6 +734,9 @@ importers:
       '@effect/platform-node':
         specifier: 4.0.0-beta.103
         version: 4.0.0-beta.103(bufferutil@4.1.0)(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))(ioredis@5.11.0)(utf-8-validate@6.0.6)
+      '@effect/sql-pglite':
+        specifier: 4.0.0-beta.103
+        version: 4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))
       '@effect/vitest':
         specifier: 4.0.0-beta.103
         version: 4.0.0-beta.103(patch_hash=a16b1e870d8c29e4a98b17cc4c638a4ff471753d8ca3487f78a22b759caf951b)(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))
@@ -1980,6 +1984,11 @@ packages:
     peerDependencies:
       effect: 4.0.0-beta.103
 
+  '@effect/sql-pglite@4.0.0-beta.103':
+    resolution: {integrity: sha512-/a8I2rjfW6/0/Tvr70BTrRXXMLUQXbVDamhmnN97l3krWq1br+IH2ltbYn+358pJ+GJ+6UQ+eAR/P10WIs5anQ==}
+    peerDependencies:
+      effect: 4.0.0-beta.103
+
   '@effect/sql-sqlite-bun@4.0.0-beta.103':
     resolution: {integrity: sha512-u10I6SEWgUc1sKrlT0luxOBNzlUXunzxCChrD75pK5khIN1baKlPn2DD3f7bkh20NxwSzOfxF3hWsrO4VktvNg==}
     peerDependencies:
@@ -2033,6 +2042,9 @@ packages:
     resolution: {integrity: sha512-XQsZgjm2EcVUiZQf11UBJQfmZeEmOW8DpI1gsFeln6w0ae0ii4dMQEQ0kjl6DspdWX1aGY1/loyXnP0JS06e/A==}
     engines: {node: '>=0.8.0'}
 
+  '@electric-sql/pglite@0.5.8':
+    resolution: {integrity: sha512-n9tsbUOhwx2epK1V0ZG9Ar4SHWUju04dhmzZXiSBXwBoleOvIfals33NAaWgagQVAL4Rbvx/Ptsu3P+pA09f6Q==}
+
   '@electron/asar@3.4.1':
     resolution: {integrity: sha512-i4/rNPRS84t0vSRa2HorerGRXWyF4vThfHesw0dmcWHp+cspK743UanA0suA5Q5y8kzY2y6YKrvbIUn69BCAiA==}
     engines: {node: '>=10.12.0'}
@@ -6181,7 +6193,7 @@ packages:
       '@effect/sql-libsql': '>=4.0.0-beta.83 || >=4.0.0'
       '@effect/sql-mysql2': '>=4.0.0-beta.83 || >=4.0.0'
       '@effect/sql-pg': 4.0.0-beta.103
-      '@effect/sql-pglite': '>=4.0.0-beta.83 || >=4.0.0'
+      '@effect/sql-pglite': 4.0.0-beta.103
       '@effect/sql-sqlite-bun': 4.0.0-beta.103
       '@effect/sql-sqlite-do': '>=4.0.0-beta.83 || >=4.0.0'
       '@effect/sql-sqlite-node': '>=4.0.0-beta.83 || >=4.0.0'
@@ -11824,6 +11836,11 @@ snapshots:
     transitivePeerDependencies:
       - pg-native
 
+  '@effect/sql-pglite@4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))':
+    dependencies:
+      '@electric-sql/pglite': 0.5.8
+      effect: 4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)
+
   '@effect/sql-sqlite-bun@4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))':
     dependencies:
       effect: 4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)
@@ -11867,6 +11884,8 @@ snapshots:
     dependencies:
       '@types/hammerjs': 2.0.46
 
+  '@electric-sql/pglite@0.5.8': {}
+
   '@electron/asar@3.4.1':
     dependencies:
       commander: 5.1.0
@@ -15416,7 +15435,7 @@ snapshots:
       json-schema-traverse: 1.0.0
       require-from-string: 2.0.2
 
-  alchemy@2.0.0-beta.65(75567d8add6e3362e26fe00f83a97bee):
+  alchemy@2.0.0-beta.65(04a0b03b072a2401cedb7e596732b3a5):
     dependencies:
       '@alchemy.run/node-utils': 0.0.5
       '@aws-sdk/credential-providers': 3.1062.0
@@ -15461,7 +15480,7 @@ snapshots:
       '@effect/platform-node': 4.0.0-beta.103(bufferutil@4.1.0)(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))(ioredis@5.11.0)(utf-8-validate@6.0.6)
       '@effect/sql-pg': 4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))
       drizzle-kit: 1.0.0-rc.4
-      drizzle-orm: 1.0.0-rc.4(@cloudflare/workers-types@4.20260604.1)(@effect/sql-d1@4.0.0-beta.101(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)))(@effect/sql-pg@4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)))(@effect/sql-sqlite-bun@4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)))(@libsql/client@0.17.3(bufferutil@4.1.0)(utf-8-validate@6.0.6))(bun-types@1.3.14)(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))(expo-sqlite@56.0.5(expo@56.0.12)(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.3(@babel/core@7.29.7)(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@types/react@19.2.16)(bufferutil@4.1.0)(react@19.2.6)(utf-8-validate@6.0.6))(react@19.2.6))(mysql2@3.22.4(@types/node@24.12.4))(pg@8.21.0)(zod@4.4.3)
+      drizzle-orm: 1.0.0-rc.4(1092673c7857e2d833af4a5f3ad85f01)
       vite: '@voidzero-dev/vite-plus-core@0.2.2(@types/node@24.12.4)(esbuild@0.28.1)(jiti@2.7.0)(terser@5.48.0)(typescript@6.0.3)(unrun@0.2.39)(yaml@2.9.0)'
       ws: 8.21.0(bufferutil@4.1.0)(utf-8-validate@6.0.6)
     transitivePeerDependencies:
@@ -16484,12 +16503,14 @@ snapshots:
       get-tsconfig: 4.14.0
       jiti: 2.7.0
 
-  drizzle-orm@1.0.0-rc.4(@cloudflare/workers-types@4.20260604.1)(@effect/sql-d1@4.0.0-beta.101(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)))(@effect/sql-pg@4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)))(@effect/sql-sqlite-bun@4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)))(@libsql/client@0.17.3(bufferutil@4.1.0)(utf-8-validate@6.0.6))(bun-types@1.3.14)(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))(expo-sqlite@56.0.5(expo@56.0.12)(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.3(@babel/core@7.29.7)(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@types/react@19.2.16)(bufferutil@4.1.0)(react@19.2.6)(utf-8-validate@6.0.6))(react@19.2.6))(mysql2@3.22.4(@types/node@24.12.4))(pg@8.21.0)(zod@4.4.3):
+  drizzle-orm@1.0.0-rc.4(1092673c7857e2d833af4a5f3ad85f01):
     optionalDependencies:
       '@cloudflare/workers-types': 4.20260604.1
       '@effect/sql-d1': 4.0.0-beta.101(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))
       '@effect/sql-pg': 4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))
+      '@effect/sql-pglite': 4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))
       '@effect/sql-sqlite-bun': 4.0.0-beta.103(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))
+      '@electric-sql/pglite': 0.5.8
       '@libsql/client': 0.17.3(bufferutil@4.1.0)(utf-8-validate@6.0.6)
       bun-types: 1.3.14
       effect: 4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 5d13e60a0476..fdab045b2b64 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -36,6 +36,7 @@ catalog:
   "@effect/platform-node": 4.0.0-beta.103
   "@effect/platform-node-shared": 4.0.0-beta.103
   "@effect/sql-pg": 4.0.0-beta.103
+  "@effect/sql-pglite": 4.0.0-beta.103
   "@effect/sql-sqlite-bun": 4.0.0-beta.103
   "@effect/tsgo": 0.13.2
   "@effect/vitest": 4.0.0-beta.103
@@ -105,6 +106,7 @@ overrides:
   "@effect/platform-node": "catalog:"
   "@effect/platform-node-shared": "catalog:"
   "@effect/sql-pg": "catalog:"
+  "@effect/sql-pglite": "catalog:"
   "@effect/sql-sqlite-bun": "catalog:"
   "@effect/vitest": "catalog:"
   "@effect/vitest>vitest": "-"

From ef3dddd390b97f05ea410214001890857b99072f Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Fri, 28 Aug 2026 02:53:23 +0530
Subject: [PATCH 28/29] fix(web): preserve referrals through blocked storage

---
 apps/web/src/cloud/referralLinks.test.ts      | 24 +++++++++++++-
 apps/web/src/cloud/referralLinks.ts           | 32 ++++++++++++++++---
 apps/web/src/cloud/useCloudLinkController.ts  |  2 +-
 .../cloud/ReferralClaimCoordinator.tsx        |  6 ++--
 4 files changed, 54 insertions(+), 10 deletions(-)

diff --git a/apps/web/src/cloud/referralLinks.test.ts b/apps/web/src/cloud/referralLinks.test.ts
index 1f0e79bd514e..9c37c9bfda65 100644
--- a/apps/web/src/cloud/referralLinks.test.ts
+++ b/apps/web/src/cloud/referralLinks.test.ts
@@ -1,10 +1,11 @@
-import { describe, expect, it, vi } from "vite-plus/test";
+import { afterEach, describe, expect, it, vi } from "vite-plus/test";
 
 import {
   buildReferralShareData,
   captureReferralCodeFromUrl,
   clearPendingReferralCode,
   PENDING_REFERRAL_CODE_STORAGE_KEY,
+  persistPendingReferralCode,
   readPendingReferralCode,
   referralCodeFromUrl,
   urlWithoutMatchingReferralCode,
@@ -12,6 +13,10 @@ import {
 } from "./referralLinks";
 
 describe("referralLinks", () => {
+  afterEach(() => {
+    clearPendingReferralCode(() => ({ removeItem: vi.fn() }));
+  });
+
   it("clears a pending code without exposing storage failures", () => {
     const removeItem = vi.fn();
     clearPendingReferralCode(() => ({ removeItem }));
@@ -41,6 +46,23 @@ describe("referralLinks", () => {
     ).toBeNull();
   });
 
+  it("keeps a captured code available for linking when browser storage is blocked", () => {
+    const url = new URL("https://app.t3.codes/?ref=abcd1234efab5678");
+    const blockedStorage = () => {
+      throw new Error("Storage access denied");
+    };
+
+    expect(
+      captureReferralCodeFromUrl(url, (referralCode) =>
+        persistPendingReferralCode(referralCode, blockedStorage),
+      ),
+    ).toEqual({
+      referralCode: "ABCD1234EFAB5678",
+      cleanedUrl: null,
+    });
+    expect(readPendingReferralCode(blockedStorage)).toBe("ABCD1234EFAB5678");
+  });
+
   it("reads and removes only the referral parameter", () => {
     const url = new URL("https://app.t3.codes/?channel=nightly&ref=abcd1234efab5678#thread");
     expect(referralCodeFromUrl(url)).toBe("ABCD1234EFAB5678");
diff --git a/apps/web/src/cloud/referralLinks.ts b/apps/web/src/cloud/referralLinks.ts
index c458fc69c34f..18d8a6ddba5e 100644
--- a/apps/web/src/cloud/referralLinks.ts
+++ b/apps/web/src/cloud/referralLinks.ts
@@ -7,20 +7,42 @@ import {
 
 export const PENDING_REFERRAL_CODE_STORAGE_KEY = "t3code.pending-referral-code";
 
+let inMemoryPendingReferralCode: string | null = null;
+
+export function persistPendingReferralCode(
+  referralCode: string,
+  getStorage: () => Pick<Storage, "setItem"> = () => window.localStorage,
+): boolean {
+  const normalized = normalizeReferralCode(referralCode);
+  if (!normalized) return false;
+
+  inMemoryPendingReferralCode = normalized;
+  try {
+    getStorage().setItem(PENDING_REFERRAL_CODE_STORAGE_KEY, normalized);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export function readPendingReferralCode(
   getStorage: () => Pick<Storage, "getItem"> = () => window.localStorage,
 ): string | null {
   try {
     const storage = getStorage();
-    return normalizeReferralCode(storage.getItem(PENDING_REFERRAL_CODE_STORAGE_KEY) ?? "");
+    return (
+      inMemoryPendingReferralCode ??
+      normalizeReferralCode(storage.getItem(PENDING_REFERRAL_CODE_STORAGE_KEY) ?? "")
+    );
   } catch {
-    return null;
+    return inMemoryPendingReferralCode;
   }
 }
 
 export function clearPendingReferralCode(
   getStorage: () => Pick<Storage, "removeItem"> = () => window.localStorage,
 ): void {
+  inMemoryPendingReferralCode = null;
   try {
     getStorage().removeItem(PENDING_REFERRAL_CODE_STORAGE_KEY);
   } catch {}
@@ -47,13 +69,15 @@ export function urlWithoutMatchingReferralCode(
 
 export function captureReferralCodeFromUrl(
   url: URL,
-  persist: (referralCode: string) => void,
+  persist: (referralCode: string) => boolean | void,
 ): { referralCode: string; cleanedUrl: string | null } | null {
   const referralCode = referralCodeFromUrl(url);
   if (!referralCode) return null;
 
   try {
-    persist(referralCode);
+    if (persist(referralCode) === false) {
+      return { referralCode, cleanedUrl: null };
+    }
   } catch {
     return { referralCode, cleanedUrl: null };
   }
diff --git a/apps/web/src/cloud/useCloudLinkController.ts b/apps/web/src/cloud/useCloudLinkController.ts
index 9e61f8d15170..8f49a4c13e9e 100644
--- a/apps/web/src/cloud/useCloudLinkController.ts
+++ b/apps/web/src/cloud/useCloudLinkController.ts
@@ -118,7 +118,7 @@ export function useCloudLinkController() {
         return false;
       }
       if (!linked || managedTunnelActive !== desired.managedTunnel) {
-        const referralCode = readPendingReferralCode();
+        const referralCode = linked ? null : readPendingReferralCode();
         const linkResult = await linkPrimaryEnvironment({
           target,
           clerkToken,
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
index 94b858cce225..2303b55c8f94 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
@@ -17,7 +17,7 @@ import { referralClaimMessage } from "../../cloud/referralClaimResult";
 import {
   captureReferralCodeFromUrl,
   clearPendingReferralCode,
-  PENDING_REFERRAL_CODE_STORAGE_KEY,
+  persistPendingReferralCode,
   readPendingReferralCode,
   urlWithoutMatchingReferralCode,
 } from "../../cloud/referralLinks";
@@ -33,9 +33,7 @@ import {
 
 function captureReferralCode(): string | null {
   const url = new URL(window.location.href);
-  const captured = captureReferralCodeFromUrl(url, (referralCode) => {
-    window.localStorage.setItem(PENDING_REFERRAL_CODE_STORAGE_KEY, referralCode);
-  });
+  const captured = captureReferralCodeFromUrl(url, persistPendingReferralCode);
   if (!captured) return null;
   if (captured.cleanedUrl) {
     window.history.replaceState(window.history.state, "", captured.cleanedUrl);

From 28e9f253b8585065fb20fafe830b64bf00559f0c Mon Sep 17 00:00:00 2001
From: T3 Code Test <t3code-test@example.com>
Date: Fri, 28 Aug 2026 02:57:09 +0530
Subject: [PATCH 29/29] fix(web): discard rejected referral URLs

---
 apps/web/src/cloud/referralLinks.test.ts            | 13 +++++++++++++
 apps/web/src/cloud/referralLinks.ts                 | 10 ++++++++++
 apps/web/src/cloud/useCloudLinkController.ts        |  8 +++++++-
 .../components/cloud/ReferralClaimCoordinator.tsx   | 11 ++---------
 4 files changed, 32 insertions(+), 10 deletions(-)

diff --git a/apps/web/src/cloud/referralLinks.test.ts b/apps/web/src/cloud/referralLinks.test.ts
index 9c37c9bfda65..28281290d46e 100644
--- a/apps/web/src/cloud/referralLinks.test.ts
+++ b/apps/web/src/cloud/referralLinks.test.ts
@@ -3,6 +3,7 @@ import { afterEach, describe, expect, it, vi } from "vite-plus/test";
 import {
   buildReferralShareData,
   captureReferralCodeFromUrl,
+  clearReferralCodeFromCurrentUrl,
   clearPendingReferralCode,
   PENDING_REFERRAL_CODE_STORAGE_KEY,
   persistPendingReferralCode,
@@ -91,6 +92,18 @@ describe("referralLinks", () => {
     expect(urlWithoutMatchingReferralCode(currentUrl, "bbbbbbbbbbbbbbbb")).toBe("/#thread");
   });
 
+  it("removes a rejected referral from the current URL", () => {
+    const replaceUrl = vi.fn();
+
+    clearReferralCodeFromCurrentUrl(
+      "abcd1234efab5678",
+      () => new URL("https://app.t3.codes/?channel=nightly&ref=ABCD1234EFAB5678#thread"),
+      replaceUrl,
+    );
+
+    expect(replaceUrl).toHaveBeenCalledWith("/?channel=nightly#thread");
+  });
+
   it("embeds the claim URL in web share text even when a share target drops the url field", () => {
     const referralLink = "https://app.t3.codes/?ref=ABCD1234EFAB5678";
     const shareData = buildReferralShareData(referralLink);
diff --git a/apps/web/src/cloud/referralLinks.ts b/apps/web/src/cloud/referralLinks.ts
index 18d8a6ddba5e..d890f9d3406e 100644
--- a/apps/web/src/cloud/referralLinks.ts
+++ b/apps/web/src/cloud/referralLinks.ts
@@ -67,6 +67,16 @@ export function urlWithoutMatchingReferralCode(
   return urlWithoutReferralCode(url);
 }
 
+export function clearReferralCodeFromCurrentUrl(
+  referralCode: string,
+  getUrl: () => URL = () => new URL(window.location.href),
+  replaceUrl: (url: string) => void = (url) =>
+    window.history.replaceState(window.history.state, "", url),
+): void {
+  const cleanedUrl = urlWithoutMatchingReferralCode(getUrl(), referralCode);
+  if (cleanedUrl) replaceUrl(cleanedUrl);
+}
+
 export function captureReferralCodeFromUrl(
   url: URL,
   persist: (referralCode: string) => boolean | void,
diff --git a/apps/web/src/cloud/useCloudLinkController.ts b/apps/web/src/cloud/useCloudLinkController.ts
index 8f49a4c13e9e..5b66326d60e5 100644
--- a/apps/web/src/cloud/useCloudLinkController.ts
+++ b/apps/web/src/cloud/useCloudLinkController.ts
@@ -18,7 +18,11 @@ import {
 } from "./linkEnvironmentAtoms";
 import { usePrimaryCloudLinkState } from "./primaryCloudLinkState";
 import { resolveRelayClerkTokenOptions } from "./publicConfig";
-import { clearPendingReferralCode, readPendingReferralCode } from "./referralLinks";
+import {
+  clearPendingReferralCode,
+  clearReferralCodeFromCurrentUrl,
+  readPendingReferralCode,
+} from "./referralLinks";
 
 export interface CloudLinkDesiredState {
   readonly managedTunnel: boolean;
@@ -129,10 +133,12 @@ export function useCloudLinkController() {
           if (!isAtomCommandInterrupted(linkResult)) {
             const cause = squashAtomCommandFailure(linkResult);
             if (
+              referralCode &&
               cause instanceof CloudEnvironmentLinkError &&
               cause.referralClaimResult !== undefined
             ) {
               clearPendingReferralCode();
+              clearReferralCodeFromCurrentUrl(referralCode);
             }
             reportUpdateFailure(cause);
           }
diff --git a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
index 2303b55c8f94..132c36fce098 100644
--- a/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
+++ b/apps/web/src/components/cloud/ReferralClaimCoordinator.tsx
@@ -16,10 +16,10 @@ import { hasCloudPublicConfig } from "../../cloud/publicConfig";
 import { referralClaimMessage } from "../../cloud/referralClaimResult";
 import {
   captureReferralCodeFromUrl,
+  clearReferralCodeFromCurrentUrl,
   clearPendingReferralCode,
   persistPendingReferralCode,
   readPendingReferralCode,
-  urlWithoutMatchingReferralCode,
 } from "../../cloud/referralLinks";
 import { useAtomCommand } from "../../state/use-atom-command";
 import { useT3ConnectAuthPrompt } from "../clerk/useT3ConnectAuthPrompt";
@@ -41,13 +41,6 @@ function captureReferralCode(): string | null {
   return captured.referralCode;
 }
 
-function clearReferralCodeFromUrl(referralCode: string): void {
-  const url = new URL(window.location.href);
-  const cleanedUrl = urlWithoutMatchingReferralCode(url, referralCode);
-  if (!cleanedUrl) return;
-  window.history.replaceState(window.history.state, "", cleanedUrl);
-}
-
 export function ReferralClaimCoordinator() {
   if (!hasCloudPublicConfig()) return null;
   return <ConfiguredReferralClaimCoordinator />;
@@ -123,7 +116,7 @@ function ConfiguredReferralClaimCoordinator() {
           completedClaimRef.current = attemptKey;
           closeRetryToast();
           clearPendingReferralCode();
-          clearReferralCodeFromUrl(referralCode);
+          clearReferralCodeFromCurrentUrl(referralCode);
           setPendingReferralCode(null);
           refreshManagedRelayReferralSummary();
           if (result.value.result !== "already_claimed") {