feat(referrals): add Kilo Pass referrals (#3465)

Author: jeanduplessis

.specs/impact-referrals.md

@@ -18,6 +18,7 @@ Updated 2026-05-06 -- require Impact Advocate reward redemption after local Kilo
 Updated 2026-05-12 -- note price-versioned KiloClaw billing preserves referral semantics.
 Updated 2026-05-22 -- renamed to `.specs/impact-referrals.md` and expanded to Kilo Pass referrals.
 Updated 2026-05-28 -- classify enforced Stripe EFW refunds as adverse payments.
+Updated 2026-05-29 -- name the Impact-facing Kilo Pass reward unit `Kilo Pass Bonus Credits`.
 
 ## Conventions
 
@@ -143,6 +144,8 @@ not stack with, the normal Kilo Pass monthly/promo bonus for that issuance.
 Existing Impact Performance conversion events drive Impact Advocate conversion state. The system uses `Sale (71659)` as
 the paid-conversion event for referral conversion and renewal reporting. When referral wins attribution for a paid
 conversion, local referral rewards are authoritative and affiliate SALE reporting for the same conversion is suppressed.
+Impact Advocate reward redemption is used only for reporting synchronization: KiloClaw redeems after local free-month
+application, and Kilo Pass redeems after local referral bonus allocation.
 
 ## Rules
 
@@ -157,8 +160,9 @@ conversion, local referral rewards are authoritative and affiliate SALE reportin
    - UTT UUID: `A7138521-9724-4b8f-95f4-1db2fbae81141`
    - Advocate widget ID: `p/51699/w/referrerWidget`
 
-3. Existing unscoped Impact Advocate configuration MAY remain as KiloClaw fallback configuration only. Kilo Pass MUST
-   require explicit Kilo Pass Advocate program/widget configuration and MUST NOT fall back to KiloClaw configuration.
+3. Impact Advocate account SID, auth token, and tenant alias MAY be shared across Advocate programs. KiloClaw and Kilo
+   Pass MUST each require explicit product-scoped Advocate program ID and widget ID configuration. Products MUST NOT
+   fall back to unscoped or other-product program/widget configuration.
 
 4. Kilo Pass MUST use a different Impact Advocate program ID and widget ID than KiloClaw.
 
@@ -627,6 +631,16 @@ conversion, local referral rewards are authoritative and affiliate SALE reportin
 158. Impact reward redemption state is for reporting and reconciliation only. It MUST NOT be the source of truth for
      local reward eligibility, application, cancellation, or reversal.
 
+158a. For Kilo Pass, when a local referral bonus reward is allocated/granted, the system MUST queue asynchronous Impact
+      Advocate reward lookup and single-reward redemption using the USD-denominated reward amount and the
+      `Kilo Pass Bonus Credits` unit so Impact reporting matches Kilo allocation state.
+
+158b. Kilo Pass Impact Advocate reward redemption MUST be idempotently queued per local reward and MUST NOT block paid
+      conversion processing, reward ledger creation, reward application, billing settlement, or user access.
+
+158c. Kilo Pass Impact reward lookup and redemption state is for reporting and reconciliation only. It MUST NOT be the
+      source of truth for local reward eligibility, application, cancellation, or reversal.
+
 ### Refunds, Reversals, and Fraud
 
 159. Rewards from a qualifying Stripe payment MUST be treated as adverse when Stripe reports a chargeback or when
@@ -762,6 +776,10 @@ conversion, local referral rewards are authoritative and affiliate SALE reportin
 
 ## Changelog
 
+### 2026-05-29 -- Name the Kilo Pass Impact reward unit
+
+Kilo Pass reward synchronization sends the `Kilo Pass Bonus Credits` unit to Impact Advocate while retaining the USD-denominated local reward amount.
+
 ### 2026-05-28 -- Enforced EFW refunds are adverse payments
 
 Classified an enforced Stripe Early Fraud Warning refund as an adverse qualifying payment for both covered products. Pending or earned-but-unapplied rewards cancel, already-applied rewards require support review, and later refund or chargeback delivery must remain idempotent.
@@ -773,6 +791,16 @@ conversions. The first positively paid settlement using a supported fingerprinta
 instrument opportunity; reused instruments retain ordinary monthly-ramp bonus behavior but do not receive the
 introductory promo or create Kilo Pass referral rewards. Annual behavior remains outside this restriction.
 
+### 2026-05-26 -- Redeem allocated Kilo Pass rewards in Impact Advocate
+
+Kilo Pass referral bonus allocation now queues Impact Advocate reward lookup and redemption using the USD reward amount,
+for reporting synchronization only. The local reward ledger remains authoritative.
+
+### 2026-05-25 -- Require product-scoped Advocate program/widget configuration
+
+Removed KiloClaw fallback to unscoped Impact Advocate program/widget configuration. KiloClaw and Kilo Pass now both
+require explicit product-scoped Advocate program ID and widget ID while sharing account SID, auth token, and tenant alias.
+
 ### 2026-05-22 -- Rename and expand to Kilo Pass
 
 Renamed `.specs/kiloclaw-referrals.md` to `.specs/impact-referrals.md`. Generalized shared Impact Advocate referral

apps/web/src/app/(app)/claw/components/billing/PlanSelectionDialog.tsx

@@ -20,9 +20,6 @@ import {
   type KiloClawSignupDisplay,
   type KiloPassUpsellActivationPreview,
 } from './billing-types';
-import { KILO_PASS_MONTHLY_FIRST_2_MONTHS_PROMO_CUTOFF } from '@/lib/kilo-pass/constants';
-import { dayjs } from '@/lib/kilo-pass/dayjs';
-
 type Cadence = 'monthly' | 'yearly';
 type Tier = '19' | '49' | '199';
 
@@ -137,7 +134,7 @@ function TierCard({
           Up to <span className="text-emerald-300">40%</span> free bonus credits
         </div>
         <div className="text-xs leading-relaxed text-emerald-300">
-          First 2 months: +50% free bonus credits
+          First month: +50% free bonus credits
         </div>
       </div>
 
@@ -293,8 +290,6 @@ function HostingOnlyPlanCard({
 
 function CreditsHowItWorks() {
   const [open, setOpen] = useState(false);
-  const showTwoMonthPromo = dayjs().utc().isBefore(KILO_PASS_MONTHLY_FIRST_2_MONTHS_PROMO_CUTOFF);
-
   return (
     <div className="border-border/50 mb-3.5 overflow-hidden rounded-lg border">
       <button
@@ -320,15 +315,13 @@ function CreditsHowItWorks() {
               expire monthly.
             </span>
           </div>
-          {showTwoMonthPromo ? (
-            <div className="text-muted-foreground flex items-start gap-2 py-0.5 text-xs">
-              <Check className="mt-0.5 h-3.5 w-3.5 shrink-0 text-emerald-400" />
-              <span>
-                First-time subscribers receive <span className="text-emerald-300">50%</span> free
-                bonus credits for the first two months.
-              </span>
-            </div>
-          ) : null}
+          <div className="text-muted-foreground flex items-start gap-2 py-0.5 text-xs">
+            <Check className="mt-0.5 h-3.5 w-3.5 shrink-0 text-emerald-400" />
+            <span>
+              First-time subscribers receive <span className="text-emerald-300">50%</span> free
+              bonus credits for the first month.
+            </span>
+          </div>
         </div>
       )}
     </div>
@@ -519,7 +512,7 @@ export function PlanSelectionDialog({ open, onOpenChange }: PlanSelectionDialogP
   const kiloPassUpsell = useMutation(
     trpc.kiloclaw.createKiloPassUpsellCheckout.mutationOptions({
       onSuccess: data => {
-        if (data.url) window.location.href = data.url;
+        if (data.url) window.location.assign(data.url);
       },
     })
   );

apps/web/src/app/(app)/claw/components/billing/WelcomePage.tsx

@@ -19,9 +19,6 @@ import {
   type KiloClawSignupDisplay,
   type KiloPassUpsellActivationPreview,
 } from './billing-types';
-import { KILO_PASS_MONTHLY_FIRST_2_MONTHS_PROMO_CUTOFF } from '@/lib/kilo-pass/constants';
-import { dayjs } from '@/lib/kilo-pass/dayjs';
-
 type Cadence = 'monthly' | 'yearly';
 type Tier = '19' | '49' | '199';
 
@@ -130,7 +127,7 @@ function TierCard({
           Up to <span className="text-emerald-300">40%</span> free bonus credits
         </div>
         <div className="text-xs leading-relaxed text-emerald-300">
-          First 2 months: +50% free bonus credits
+          First month: +50% free bonus credits
         </div>
       </div>
 
@@ -286,8 +283,6 @@ function HostingOnlyPlanCard({
 
 function CreditsHowItWorks() {
   const [open, setOpen] = useState(false);
-  const showTwoMonthPromo = dayjs().utc().isBefore(KILO_PASS_MONTHLY_FIRST_2_MONTHS_PROMO_CUTOFF);
-
   return (
     <div className="border-border/50 mb-3.5 overflow-hidden rounded-lg border">
       <button
@@ -313,15 +308,13 @@ function CreditsHowItWorks() {
               expire monthly.
             </span>
           </div>
-          {showTwoMonthPromo ? (
-            <div className="text-muted-foreground flex items-start gap-2 py-0.5 text-xs">
-              <Check className="mt-0.5 h-3.5 w-3.5 shrink-0 text-emerald-400" />
-              <span>
-                First-time subscribers receive <span className="text-emerald-300">50%</span> free
-                bonus credits for the first two months.
-              </span>
-            </div>
-          ) : null}
+          <div className="text-muted-foreground flex items-start gap-2 py-0.5 text-xs">
+            <Check className="mt-0.5 h-3.5 w-3.5 shrink-0 text-emerald-400" />
+            <span>
+              First-time subscribers receive <span className="text-emerald-300">50%</span> free
+              bonus credits for the first month.
+            </span>
+          </div>
         </div>
       )}
     </div>
@@ -512,7 +505,7 @@ export function WelcomePage() {
   const kiloPassUpsell = useMutation(
     trpc.kiloclaw.createKiloPassUpsellCheckout.mutationOptions({
       onSuccess: data => {
-        if (data.url) window.location.href = data.url;
+        if (data.url) window.location.assign(data.url);
       },
     })
   );

apps/web/src/app/(app)/subscriptions/kilo-pass/page.tsx

@@ -1,7 +1,21 @@
+import { redirect } from 'next/navigation';
+
 import { PageContainer } from '@/components/layouts/PageContainer';
 import { KiloPassDetail } from '@/components/subscriptions/kilo-pass/KiloPassDetail';
+import { db } from '@/lib/drizzle';
+import { getKiloPassStateForUser } from '@/lib/kilo-pass/state';
+import { getUserFromAuthOrRedirect } from '@/lib/user/server';
+
+export default async function KiloPassSubscriptionPage() {
+  const user = await getUserFromAuthOrRedirect(
+    '/users/sign_in?callbackPath=/subscriptions/kilo-pass'
+  );
+  const subscription = await getKiloPassStateForUser(db, user.id);
+
+  if (!subscription) {
+    redirect('/subscriptions');
+  }
 
-export default function KiloPassSubscriptionPage() {
   return (
     <PageContainer>
       <KiloPassDetail />

apps/web/src/app/(app)/subscriptions/kilo-pass/refer/page.tsx

@@ -0,0 +1,24 @@
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+
+import { ImpactAdvocateReferralWidget } from '@/components/referrals/ImpactAdvocateReferralCard';
+import { KiloPassReferralPageContent } from '@/components/referrals/KiloPassReferralPageContent';
+import { useTRPC } from '@/lib/trpc/utils';
+
+export default function KiloPassReferralPage() {
+  const trpc = useTRPC();
+  const rewardSummary = useQuery(trpc.kiloPass.getReferralRewardSummary.queryOptions());
+
+  return (
+    <KiloPassReferralPageContent
+      summary={rewardSummary.data ?? null}
+      isLoading={rewardSummary.isLoading}
+      errorMessage={
+        rewardSummary.isError ? 'Rewards are temporarily unavailable. Try again in a minute.' : null
+      }
+    >
+      <ImpactAdvocateReferralWidget product="kilo_pass" />
+    </KiloPassReferralPageContent>
+  );
+}

apps/web/src/app/admin/components/KiloclawReferralsInvestigation.test.ts

@@ -11,17 +11,26 @@ function referralRow(params: {
   qualified: boolean;
   disqualificationReason: string | null;
   impactReportState: string;
+  product?: 'kiloclaw' | 'kilo_pass';
+  rewardStatus?: string;
 }) {
+  const product = params.product ?? 'kiloclaw';
+  const productLabel = product === 'kilo_pass' ? 'Kilo Pass' : 'KiloClaw';
+
   return {
     referral: {
       id: params.referralId,
+      product,
+      productLabel,
       impactReferralId: 'RS-SUPPORT',
       createdAt: '2026-04-01T00:00:00.000Z',
     },
     referee: { id: `${params.referralId}-referee`, email: params.refereeEmail, name: null },
     sourceTouch: null,
     conversion: {
       id: `${params.referralId}-conversion`,
+      product,
+      paymentProvider: product === 'kilo_pass' ? 'stripe' : 'credits',
       winningTouchType: 'referral',
       sourcePaymentId: params.paymentId,
       qualified: params.qualified,
@@ -33,21 +42,52 @@ function referralRow(params: {
         id: `${params.referralId}-decision`,
         beneficiaryUserId: 'referrer-1',
         beneficiaryRole: 'referrer',
+        product,
         outcome: params.qualified ? 'granted' : 'disqualified',
         reason: params.disqualificationReason,
-        monthsGranted: params.qualified ? 1 : 0,
+        rewardKind: product === 'kilo_pass' ? 'kilo_pass_bonus' : 'kiloclaw_free_month',
+        monthsGranted: product === 'kiloclaw' && params.qualified ? 1 : 0,
+        rewardPercent: product === 'kilo_pass' ? 0.5 : null,
+        sourceTier: product === 'kilo_pass' ? 'tier_49' : null,
+        rewardAmountUsd: product === 'kilo_pass' && params.qualified ? 24.5 : null,
         createdAt: '2026-04-10T00:00:00.000Z',
       },
     ],
-    rewards: [],
+    rewards: params.qualified
+      ? [
+          {
+            id: `${params.referralId}-reward`,
+            product,
+            beneficiaryUserId: 'referrer-1',
+            beneficiaryRole: 'referrer',
+            rewardKind: product === 'kilo_pass' ? 'kilo_pass_bonus' : 'kiloclaw_free_month',
+            status: params.rewardStatus ?? 'applied',
+            monthsGranted: product === 'kiloclaw' ? 1 : 0,
+            rewardPercent: product === 'kilo_pass' ? 0.5 : null,
+            sourceTier: product === 'kilo_pass' ? 'tier_49' : null,
+            rewardAmountUsd: product === 'kilo_pass' ? 24.5 : null,
+            earnedAt: '2026-04-10T00:00:00.000Z',
+            appliedAt: params.rewardStatus === 'pending' ? null : '2026-04-10T00:05:00.000Z',
+            expiresAt: '2027-04-10T00:00:00.000Z',
+            reviewReason:
+              params.rewardStatus === 'review_required' ? 'referral_payment_chargeback' : null,
+            appliesToKiloPassSubscriptionId: null,
+            consumedKiloPassIssuanceId: null,
+            consumedKiloPassIssuanceItemId: null,
+          },
+        ]
+      : [],
     rewardApplications: params.qualified
       ? [
           {
             id: `${params.referralId}-application`,
             beneficiaryUserId: 'referrer-1',
             subscriptionId: '55555555-5555-4555-8555-555555555555',
             previousRenewalBoundary: '2026-05-01T12:00:00.000Z',
+            product,
             newRenewalBoundary: '2026-06-01T12:00:00.000Z',
+            localOperationId: null,
+            stripeOperationId: null,
             appliedAt: '2026-04-10T00:05:00.000Z',
           },
         ]
@@ -63,11 +103,32 @@ function referralRow(params: {
         responseStatusCode: params.impactReportState === 'failed' ? 400 : null,
       },
     ],
+    impactRewardRedemptions: [],
   };
 }
 
 const result = {
+  product: 'kiloclaw' as const,
+  productLabel: 'KiloClaw',
   referrer: { id: 'referrer-1', email: 'referrer@example.com', name: 'Referrer' },
+  participantRegistrations: [
+    {
+      id: '55555555-5555-4555-8555-555555555556',
+      programKey: 'kiloclaw' as const,
+      registrationState: 'pending',
+      registeredAt: null,
+      lastRegistrationAttemptAt: null,
+      lastErrorCode: null,
+      lastErrorMessage: null,
+      latestAttempt: {
+        id: '55555555-5555-4555-8555-555555555557',
+        deliveryState: 'queued',
+        responseStatusCode: null,
+        nextRetryAt: '2026-04-11T00:00:00.000Z',
+        createdAt: '2026-04-10T00:00:00.000Z',
+      },
+    },
+  ],
   referrals: [
     referralRow({
       referralId: 'qualified-referral',
@@ -95,10 +156,14 @@ describe('KiloclawReferralsInvestigationResults', () => {
     );
 
     expect(html).toContain('referrer@example.com');
+    expect(html).toContain('KiloClaw referrer');
+    expect(html).toContain('kiloclaw: pending');
+    expect(html).toContain('Latest attempt: queued');
     expect(html).toContain('Qualified');
     expect(html).toContain('Disqualified');
     expect(html).toContain('referral_self_referral');
     expect(html).toContain('granted');
+    expect(html).toContain('applied, 1 month');
     expect(html).toContain('delivered, tracker 71659, order qualified-payment');
     expect(html).toContain('failed, tracker 71659, order disqualified-payment, HTTP 400');
     expect(html).toContain('May 1, 2026 to');