feat(referrals): launch Kilo Pass advocate rewards

Author: jeanduplessis

.specs/impact-referrals.md

@@ -143,6 +143,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 +159,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 +630,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 reward amount and USD 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
@@ -773,6 +786,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/api/cron/kilo-pass-expire-referral-rewards/route.ts

@@ -0,0 +1,45 @@
+import { timingSafeEqual } from 'node:crypto';
+import { NextResponse } from 'next/server';
+
+import { CRON_SECRET } from '@/lib/config.server';
+import { expirePendingKiloPassReferralRewards } from '@/lib/impact/kilo-pass-referrals';
+import { sentryLogger } from '@/lib/utils.server';
+
+if (!CRON_SECRET) {
+  throw new Error('CRON_SECRET is not configured in environment variables');
+}
+
+function isExpectedCronAuthorization(authHeader: string | null): boolean {
+  if (!authHeader) return false;
+
+  const authHeaderBuffer = Buffer.from(authHeader);
+  const expectedAuthBuffer = Buffer.from(`Bearer ${CRON_SECRET}`);
+  if (authHeaderBuffer.length !== expectedAuthBuffer.length) return false;
+
+  return timingSafeEqual(authHeaderBuffer, expectedAuthBuffer);
+}
+
+export async function GET(request: Request) {
+  const authHeader = request.headers.get('authorization');
+  if (!isExpectedCronAuthorization(authHeader)) {
+    sentryLogger(
+      'cron',
+      'warning'
+    )(
+      'SECURITY: Invalid CRON job authorization attempt: ' +
+        (authHeader ? 'Invalid authorization header' : 'Missing authorization header')
+    );
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  const summary = await expirePendingKiloPassReferralRewards();
+
+  return NextResponse.json(
+    {
+      success: true,
+      summary,
+      timestamp: new Date().toISOString(),
+    },
+    { status: 200 }
+  );
+}

apps/web/src/components/profile/ProfileKiloPassSection.tsx

@@ -42,7 +42,7 @@ export function ProfileKiloPassSection() {
           toast.error('Failed to create Stripe checkout session');
           return;
         }
-        window.location.href = result.url;
+        window.location.assign(result.url);
       },
       onError: error => {
         toast.error(error.message || 'Failed to start checkout');

apps/web/src/components/profile/kilo-pass/KiloPassActiveSubscriptionCard.tsx

@@ -5,7 +5,7 @@ import { useState } from 'react';
 import { useQuery } from '@tanstack/react-query';
 
 import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
-import { Badge } from '@/components/ui/badge';
+import { SubscriptionStatusBadge } from '@/components/subscriptions/SubscriptionStatusBadge';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { formatDollars, formatIsoDateString_UsaDateOnlyFormat } from '@/lib/utils';
@@ -14,6 +14,8 @@ import { dayjs } from '@/lib/kilo-pass/dayjs';
 import { useTRPC } from '@/lib/trpc/utils';
 import { getMonthlyPriceUsd } from '@/lib/kilo-pass/bonus';
 
+import { KiloPassReferralButton } from '@/components/referrals/KiloPassReferralButton';
+
 import { KiloPassSubscriptionSettingsModal } from './KiloPassSubscriptionSettingsModal';
 import type { KiloPassSubscription } from './kiloPassSubscription';
 import {
@@ -140,15 +142,18 @@ function HeaderRow() {
           <Coins className="h-5 w-5 text-amber-300" />
         </span>
         <span className="leading-none">
-          <span className="block text-base">Kilo Pass</span>
+          <span className="flex flex-wrap items-center gap-2">
+            <span className="block text-base">Kilo Pass</span>
+            <SubscriptionStatusBadge status={view.status.kind} />
+          </span>
           <span className="text-muted-foreground block text-sm font-normal">
             {view.header.tierLabel} • {view.header.cadenceLabel}
           </span>
         </span>
       </CardTitle>
 
-      <div className="flex items-center gap-2">
-        <Badge variant={view.status.badgeVariant}>{view.status.label}</Badge>
+      <div className="flex flex-wrap items-center justify-end gap-2">
+        <KiloPassReferralButton />
         {providerManagement.externalManagementAction ? (
           <Button asChild variant="outline" size="icon" className="h-9 w-9">
             <a

apps/web/src/components/referrals/ImpactAdvocateReferralCard.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from '@jest/globals';
+
+import { buildImpactAdvocateTokenUrl } from './ImpactAdvocateReferralCard.utils';
+
+describe('buildImpactAdvocateTokenUrl', () => {
+  it('defaults to the KiloClaw Advocate token endpoint for existing callers', () => {
+    expect(buildImpactAdvocateTokenUrl()).toBe('/api/impact-advocate/token');
+  });
+
+  it('requests the Kilo Pass Advocate token without falling back to KiloClaw config', () => {
+    expect(buildImpactAdvocateTokenUrl('kilo_pass')).toBe(
+      '/api/impact-advocate/token?product=kilo_pass'
+    );
+  });
+});