@taskforcehq/taskforce 0.3.169 → 0.3.300

package/dist/server/routes/billing.test.js

@@ -0,0 +1,1631 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { Readable } from 'stream';
+import Database from 'better-sqlite3';
+import { registerBillingRoutes } from './billing';
+const mockConstructEvent = vi.fn();
+const mockPricesList = vi.fn(async () => ({ data: [], has_more: false }));
+const mockPriceRetrieve = vi.fn(async (id) => ({ id, active: true, currency: 'usd', unit_amount: 1500, recurring: { interval: 'month' } }));
+const mockCheckoutCreate = vi.fn(async () => ({ id: 'cs_test', url: 'https://example.test/checkout' }));
+const mockCheckoutRetrieve = vi.fn(async (id) => ({ id, mode: 'subscription', customer: 'cus_123', subscription: 'sub_123', metadata: { userId: 'u1' } }));
+const mockPortalCreate = vi.fn(async () => ({ id: 'bps_test', url: 'https://example.test/portal' }));
+const mockSubscriptionCancel = vi.fn(async () => ({ id: 'sub_test', status: 'canceled' }));
+const mockSubscriptionList = vi.fn(async () => ({ data: [] }));
+const mockCustomersList = vi.fn(async () => ({ data: [] }));
+const mockSubscriptionUpdate = vi.fn(async (id, input) => ({
+    id,
+    customer: 'cus_123',
+    status: 'active',
+    trial_end: null,
+    metadata: {
+        userId: 'u1',
+        planVersionId: String(input?.metadata?.planVersionId || 'pro-v1')
+    },
+    items: {
+        data: [{
+                id: 'si_123',
+                current_period_end: Math.floor(Date.now() / 1000) + 86400,
+                price: { id: String(input?.items?.[0]?.price || 'price_pro_month'), recurring: { interval: 'month' } }
+            }]
+    }
+}));
+const mockSubscriptionRetrieve = vi.fn(async (id) => ({
+    id,
+    customer: 'cus_123',
+    status: 'active',
+    trial_end: null,
+    metadata: { userId: 'u1', planVersionId: 'pro-v1' },
+    items: {
+        data: [{
+                id: 'si_123',
+                current_period_end: Math.floor(Date.now() / 1000) + 86400,
+                price: { id: 'price_pro_month', recurring: { interval: 'month' } }
+            }]
+    }
+}));
+vi.mock('stripe', () => ({
+    default: class StripeMock {
+        webhooks = {
+            constructEvent: mockConstructEvent
+        };
+        prices = {
+            list: mockPricesList,
+            retrieve: mockPriceRetrieve
+        };
+        checkout = {
+            sessions: {
+                create: mockCheckoutCreate,
+                retrieve: mockCheckoutRetrieve
+            }
+        };
+        billingPortal = {
+            sessions: {
+                create: mockPortalCreate
+            }
+        };
+        customers = {
+            list: mockCustomersList
+        };
+        subscriptions = {
+            cancel: mockSubscriptionCancel,
+            retrieve: mockSubscriptionRetrieve,
+            update: mockSubscriptionUpdate,
+            list: mockSubscriptionList
+        };
+        constructor(_apiKey) { }
+    }
+}));
+function createMockReq(body, headers = {}) {
+    const req = Readable.from([Buffer.from(body, 'utf8')]);
+    req.headers = headers;
+    return req;
+}
+function createMockRes() {
+    const response = {
+        statusCode: 200,
+        headers: {},
+        body: '',
+        writeHead: vi.fn((statusCode, headers) => {
+            response.statusCode = statusCode;
+            response.headers = headers || {};
+            return response;
+        }),
+        end: vi.fn((payload) => {
+            response.body = String(payload || '');
+            return response;
+        })
+    };
+    return response;
+}
+function setupBillingSchema(db) {
+    db.exec(`
+        CREATE TABLE user_billing (
+            user_id TEXT PRIMARY KEY,
+            tenant_id TEXT NOT NULL,
+            stripe_customer_id TEXT,
+            stripe_subscription_id TEXT,
+            stripe_price_id TEXT,
+            stripe_status TEXT,
+            tier TEXT NOT NULL DEFAULT '',
+            billing_interval TEXT,
+            entitlement_state TEXT NOT NULL DEFAULT 'active',
+            trial_end TEXT,
+            current_period_end TEXT,
+            effective_until TEXT,
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL
+        );
+        CREATE TABLE stripe_webhook_events (
+            event_id TEXT PRIMARY KEY,
+            tenant_id TEXT NOT NULL,
+            event_type TEXT NOT NULL,
+            processed_at TEXT NOT NULL
+        );
+        CREATE TABLE stripe_webhook_failures (
+            id TEXT PRIMARY KEY,
+            tenant_id TEXT NOT NULL,
+            event_id TEXT NOT NULL,
+            event_type TEXT,
+            reason TEXT NOT NULL,
+            payload_excerpt TEXT,
+            purge_after TEXT NOT NULL,
+            created_at TEXT NOT NULL
+        );
+        CREATE TABLE billing_price_mappings (
+            tenant_id TEXT NOT NULL,
+            plan_version_id TEXT NOT NULL,
+            billing_interval TEXT NOT NULL,
+            stripe_price_id TEXT NOT NULL,
+            pricing_type TEXT NOT NULL DEFAULT 'stripe',
+            active INTEGER NOT NULL DEFAULT 1,
+            unit_amount INTEGER,
+            currency TEXT,
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL,
+            PRIMARY KEY (tenant_id, plan_version_id, billing_interval, stripe_price_id)
+        );
+        CREATE UNIQUE INDEX idx_billing_price_mappings_active_interval
+        ON billing_price_mappings (tenant_id, plan_version_id, billing_interval)
+        WHERE active = 1;
+        CREATE TABLE plan_versions (
+            plan_version_id TEXT PRIMARY KEY,
+            tenant_id TEXT NOT NULL,
+            plan_id TEXT NOT NULL,
+            version_number INTEGER NOT NULL,
+            is_default INTEGER NOT NULL DEFAULT 0,
+            seat_limit INTEGER,
+            metadata_json TEXT NOT NULL DEFAULT '{}',
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL
+        );
+        CREATE TABLE plan_catalog (
+            plan_id TEXT PRIMARY KEY,
+            tenant_id TEXT NOT NULL,
+            display_name TEXT NOT NULL,
+            status TEXT NOT NULL DEFAULT 'active',
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL
+        );
+        CREATE TABLE account_entitlements (
+            account_id TEXT PRIMARY KEY,
+            tenant_id TEXT NOT NULL,
+            plan_version_id TEXT NOT NULL,
+            entitlement_state TEXT NOT NULL DEFAULT 'active',
+            effective_at TEXT,
+            effective_until TEXT,
+            updated_by TEXT,
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL
+        );
+        CREATE TABLE system_settings (
+            tenant_id TEXT NOT NULL,
+            settings_key TEXT NOT NULL,
+            payload TEXT,
+            updated_at TEXT NOT NULL,
+            PRIMARY KEY (tenant_id, settings_key)
+        );
+    `);
+}
+function buildBillingRouteHandlers(db, opts) {
+    const routes = new Map();
+    const tenantId = 'default';
+    const core = {
+        getDatabaseAdapter: () => db,
+        getTenantId: () => tenantId,
+        createUserBillingRecord: (userId) => {
+            const now = new Date().toISOString();
+            db.prepare(`
+                INSERT INTO user_billing (
+                    user_id, tenant_id, tier, entitlement_state, created_at, updated_at
+                ) VALUES (?, ?, '', 'active', ?, ?)
+                ON CONFLICT (user_id) DO NOTHING
+            `).run(userId, tenantId, now, now);
+        },
+        listPlanCatalog: () => [
+            { planId: 'pro', displayName: 'Pro Plan', status: 'active', createdAt: '', updatedAt: '' },
+            { planId: 'inactive-plan', displayName: 'Inactive', status: 'archived', createdAt: '', updatedAt: '' },
+            { planId: 'empty-plan', displayName: 'Empty', status: 'active', createdAt: '', updatedAt: '' },
+            { planId: 'starter', displayName: 'Starter', status: 'active', createdAt: '', updatedAt: '' }
+        ],
+        listPlanVersions: (planId) => {
+            return db.prepare(`
+                SELECT plan_version_id, plan_id, version_number, is_default, seat_limit, metadata_json
+                FROM plan_versions
+                WHERE tenant_id = ? AND plan_id = ?
+                ORDER BY version_number ASC
+            `).all(tenantId, planId).map((row) => {
+                const metadata = row?.metadata_json ? JSON.parse(String(row.metadata_json)) : {};
+                return {
+                    planVersionId: String(row?.plan_version_id || ''),
+                    planId: String(row?.plan_id || ''),
+                    versionNumber: Number(row?.version_number || 1),
+                    isDefault: Number(row?.is_default || 0) === 1,
+                    seatLimit: row?.seat_limit === null || row?.seat_limit === undefined ? null : Number(row.seat_limit),
+                    trialDays: Number.isFinite(Number(metadata?.trialDays)) ? Number(metadata.trialDays) : 0,
+                    metadata,
+                    features: {},
+                    createdAt: '',
+                    updatedAt: ''
+                };
+            });
+        },
+        getAccountEntitlement: () => ({
+            accountId: 'u1',
+            planVersionId: 'pro-v1',
+            planId: 'pro',
+            state: 'active',
+            effectiveAt: null,
+            effectiveUntil: null,
+            updatedBy: null,
+            createdAt: '',
+            updatedAt: ''
+        }),
+        getAccountAccessStatus: () => ({
+            gate: 'ok',
+            hasEntitlement: true,
+            canAccessApp: true,
+            canAccessPlans: true,
+            signupMonetizationStrategy: 'auto_assign_default',
+            planSelectionRequired: false,
+            message: null,
+            entitlement: {
+                accountId: 'u1',
+                planVersionId: 'pro-v1',
+                planId: 'pro',
+                state: 'active',
+                effectiveAt: null,
+                effectiveUntil: null
+            }
+        }),
+        getBillingMirrorProfileForPlanVersion: (planVersionId) => ({
+            planId: planVersionId.startsWith('pro') ? 'pro' : 'starter',
+            entitlementState: 'active'
+        }),
+        resolveUserIdentity: () => opts?.userIdentity === undefined
+            ? {
+                userId: 'u1',
+                email: 'owner@example.com',
+                systemRole: 'user',
+                betaAccess: true
+            }
+            : opts.userIdentity,
+        updateAccountEntitlement: vi.fn().mockReturnValue({
+            accountId: 'u1',
+            planVersionId: 'starter-v1',
+            planId: 'starter',
+            state: 'active',
+            effectiveAt: null,
+            effectiveUntil: null
+        })
+    };
+    registerBillingRoutes({
+        addRoute: (method, path, handler) => routes.set(`${method} ${path}`, handler),
+        core,
+        context: {
+            getRuntimeMode: () => 'cloud'
+        },
+        ensureAuthenticatedUser: () => true,
+        ensureAdminRole: () => opts?.isAdmin !== false,
+        requestUserId: () => 'u1',
+        resolveErrorStatusCode: (_error, fallback = 500) => fallback,
+        auditAdminAction: () => { }
+    });
+    return routes;
+}
+describe('Billing Webhook Routes', () => {
+    const originalEnv = { ...process.env };
+    let db;
+    let webhookHandler;
+    let routeHandlers;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        db = new Database(':memory:');
+        setupBillingSchema(db);
+        routeHandlers = buildBillingRouteHandlers(db);
+        webhookHandler = routeHandlers.get('POST /api/taskforce/billing/webhook');
+        process.env.TASKFORCE_BILLING_ENABLED = 'true';
+        process.env.TASKFORCE_STRIPE_SECRET_KEY = 'sk_test_123';
+        process.env.TASKFORCE_STRIPE_WEBHOOK_SECRET = 'whsec_123';
+    });
+    afterEach(() => {
+        process.env = { ...originalEnv };
+        db.close();
+    });
+    it('returns 400 for invalid webhook signature', async () => {
+        mockConstructEvent.mockImplementation(() => {
+            throw new Error('invalid signature');
+        });
+        const req = createMockReq('{"id":"evt_bad"}', {
+            'x-taskforce-runtime-mode': 'cloud',
+            'stripe-signature': 'bad_signature'
+        });
+        const res = createMockRes();
+        await webhookHandler(req, res, {});
+        expect(res.statusCode).toBe(400);
+    });
+    it('returns 200 no-op for duplicate event id', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO stripe_webhook_events (event_id, tenant_id, event_type, processed_at)
+            VALUES (?, 'default', ?, ?)
+        `).run('evt_dupe', 'invoice.paid', now);
+        mockConstructEvent.mockReturnValue({
+            id: 'evt_dupe',
+            type: 'invoice.paid',
+            data: {
+                object: {
+                    customer: 'cus_1',
+                    lines: { data: [{ price: { id: 'price_1', recurring: { interval: 'month' } } }] }
+                }
+            }
+        });
+        const req = createMockReq('{"id":"evt_dupe"}', {
+            'x-taskforce-runtime-mode': 'cloud',
+            'stripe-signature': 'sig'
+        });
+        const res = createMockRes();
+        await webhookHandler(req, res, {});
+        expect(res.statusCode).toBe(200);
+        expect(JSON.parse(res.body)).toEqual({ received: true, duplicate: true });
+    });
+    it('returns 500 on processing failure so Stripe can retry', async () => {
+        mockConstructEvent.mockReturnValue({
+            id: 'evt_fail',
+            type: 'invoice.paid',
+            data: {
+                object: {
+                    customer: 'cus_missing',
+                    lines: { data: [{ price: { id: 'price_1', recurring: { interval: 'month' } } }] }
+                }
+            }
+        });
+        const req = createMockReq('{"id":"evt_fail"}', {
+            'x-taskforce-runtime-mode': 'cloud',
+            'stripe-signature': 'sig'
+        });
+        const res = createMockRes();
+        await webhookHandler(req, res, {});
+        expect(res.statusCode).toBe(500);
+        const failures = db.prepare(`SELECT event_id, reason FROM stripe_webhook_failures WHERE event_id = ?`).all('evt_fail');
+        expect(failures.length).toBeGreaterThan(0);
+        expect(failures[0]?.reason || '').toContain('Unable to resolve user for invoice event.');
+    });
+    it('preserves existing entitlement on unknown price_id and logs failure', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO user_billing (user_id, tenant_id, stripe_customer_id, entitlement_state, created_at, updated_at)
+            VALUES ('u1', 'default', 'cus_123', 'active', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO account_entitlements (
+                account_id, tenant_id, plan_version_id, entitlement_state, effective_at, created_at, updated_at
+            ) VALUES ('u1', 'default', 'starter-v1', 'active', ?, ?, ?)
+        `).run(now, now, now);
+        mockConstructEvent.mockReturnValue({
+            id: 'evt_unknown_price',
+            type: 'customer.subscription.updated',
+            data: {
+                object: {
+                    id: 'sub_123',
+                    customer: 'cus_123',
+                    status: 'active',
+                    trial_end: null,
+                    metadata: {},
+                    items: {
+                        data: [{
+                                current_period_end: Math.floor(Date.now() / 1000) + 86400,
+                                price: { id: 'price_unknown', recurring: { interval: 'month' } }
+                            }]
+                    }
+                }
+            }
+        });
+        const req = createMockReq('{"id":"evt_unknown_price"}', {
+            'x-taskforce-runtime-mode': 'cloud',
+            'stripe-signature': 'sig'
+        });
+        const res = createMockRes();
+        await webhookHandler(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const entitlement = db.prepare(`
+            SELECT plan_version_id
+            FROM account_entitlements
+            WHERE account_id = 'u1' AND tenant_id = 'default'
+        `).get();
+        expect(entitlement.plan_version_id).toBe('starter-v1');
+        const failure = db.prepare(`
+            SELECT reason
+            FROM stripe_webhook_failures
+            WHERE event_id = 'evt_unknown_price'
+            ORDER BY created_at DESC
+            LIMIT 1
+        `).get();
+        expect(failure.reason).toContain('Unknown price mapping');
+    });
+    it('purges expired webhook failures during webhook processing', async () => {
+        const past = new Date(Date.now() - 48 * 60 * 60 * 1000).toISOString();
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO stripe_webhook_failures (id, tenant_id, event_id, event_type, reason, payload_excerpt, purge_after, created_at)
+            VALUES ('whf_old', 'default', 'evt_old', 'invoice.paid', 'old', '{}', ?, ?)
+        `).run(past, now);
+        db.prepare(`
+            INSERT INTO stripe_webhook_events (event_id, tenant_id, event_type, processed_at)
+            VALUES ('evt_dup_for_purge', 'default', 'invoice.paid', ?)
+        `).run(now);
+        mockConstructEvent.mockReturnValue({
+            id: 'evt_dup_for_purge',
+            type: 'invoice.paid',
+            data: { object: { customer: 'cus_1', lines: { data: [] } } }
+        });
+        const req = createMockReq('{"id":"evt_dup_for_purge"}', {
+            'x-taskforce-runtime-mode': 'cloud',
+            'stripe-signature': 'sig'
+        });
+        const res = createMockRes();
+        await webhookHandler(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const row = db.prepare(`SELECT id FROM stripe_webhook_failures WHERE id = 'whf_old'`).get();
+        expect(row).toBeUndefined();
+    });
+    it('creates checkout session with plans success/cancel URLs and selection context', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('collab-v1', 'default', 'collab', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
+            VALUES ('default', 'collab-v1', 'month', 'price_collab_month', 1, ?, ?)
+        `).run(now, now);
+        const checkoutHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session');
+        expect(checkoutHandler).toBeTypeOf('function');
+        const req = createMockReq(JSON.stringify({
+            planVersionId: 'collab-v1',
+            interval: 'month'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const res = createMockRes();
+        await checkoutHandler(req, res, {});
+        expect(res.statusCode).toBe(200);
+        expect(mockCheckoutCreate).toHaveBeenCalledTimes(1);
+        const firstCall = mockCheckoutCreate.mock.calls[0];
+        const args = (Array.isArray(firstCall) ? firstCall[0] : {});
+        expect(String(args.success_url || '')).toContain('/?screen=plans&checkout=success');
+        expect(String(args.cancel_url || '')).toContain('/?screen=plans&checkout=cancel');
+        expect(String(args.cancel_url || '')).toContain('planId=collab');
+        expect(String(args.cancel_url || '')).toContain('planVersionId=collab-v1');
+        expect(String(args.cancel_url || '')).toContain('interval=month');
+        expect(args.line_items?.[0]?.price).toBe('price_collab_month');
+        expect(args.customer).toBeUndefined();
+        expect(args.customer_email).toBe('owner@example.com');
+    });
+    it('uses per-version trial days when creating checkout', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('collab-v1', 'default', 'collab', 1, 1, '{"trialDays":21}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
+            VALUES ('default', 'collab-v1', 'month', 'price_collab_month', 1, ?, ?)
+        `).run(now, now);
+        const checkoutHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session');
+        const req = createMockReq(JSON.stringify({
+            planVersionId: 'collab-v1',
+            interval: 'month'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const res = createMockRes();
+        await checkoutHandler(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const args = mockCheckoutCreate.mock.calls.at(-1)?.[0];
+        expect(args.subscription_data?.trial_period_days).toBe(21);
+    });
+    it('omits Stripe trial period when the selected version trialDays is 0', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('collab-v1', 'default', 'collab', 1, 1, '{"trialDays":0}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
+            VALUES ('default', 'collab-v1', 'month', 'price_collab_month', 1, ?, ?)
+        `).run(now, now);
+        const checkoutHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session');
+        const req = createMockReq(JSON.stringify({
+            planVersionId: 'collab-v1',
+            interval: 'month'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const res = createMockRes();
+        await checkoutHandler(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const args = mockCheckoutCreate.mock.calls.at(-1)?.[0];
+        expect(args.subscription_data?.trial_period_days).toBeUndefined();
+    });
+    it('creates checkout session with existing stripe customer and no customer_email override', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('collab-v1', 'default', 'collab', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
+            VALUES ('default', 'collab-v1', 'month', 'price_collab_month', 1, ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO user_billing (user_id, tenant_id, stripe_customer_id, entitlement_state, created_at, updated_at)
+            VALUES ('u1', 'default', 'cus_existing', 'active', ?, ?)
+        `).run(now, now);
+        const checkoutHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session');
+        const req = createMockReq(JSON.stringify({
+            planVersionId: 'collab-v1',
+            interval: 'month'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const res = createMockRes();
+        await checkoutHandler(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const args = mockCheckoutCreate.mock.calls.at(-1)?.[0];
+        expect(args.customer).toBe('cus_existing');
+        expect(args.customer_email).toBeUndefined();
+    });
+    it('reuses an existing Stripe customer discovered by account email before creating checkout', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('collab-v1', 'default', 'collab', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
+            VALUES ('default', 'collab-v1', 'month', 'price_collab_month', 1, ?, ?)
+        `).run(now, now);
+        mockCustomersList.mockResolvedValueOnce({
+            data: [{ id: 'cus_email_match' }]
+        });
+        mockSubscriptionList.mockResolvedValueOnce({ data: [] });
+        const checkoutHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session');
+        const req = createMockReq(JSON.stringify({
+            planVersionId: 'collab-v1',
+            interval: 'month'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const res = createMockRes();
+        await checkoutHandler(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const args = mockCheckoutCreate.mock.calls.at(-1)?.[0];
+        expect(args.customer).toBe('cus_email_match');
+        expect(args.customer_email).toBeUndefined();
+    });
+    it('builds checkout return URLs from explicit local proxy origin headers', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('collab-v1', 'default', 'collab', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
+            VALUES ('default', 'collab-v1', 'month', 'price_collab_month', 1, ?, ?)
+        `).run(now, now);
+        const checkoutHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session');
+        const req = createMockReq(JSON.stringify({
+            planVersionId: 'collab-v1',
+            interval: 'month'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'performance-app.taskforcehq.ai',
+            'x-taskforce-origin-host': 'localhost:5174',
+            'x-taskforce-origin-proto': 'http',
+            'x-taskforce-origin-base-url': 'http://localhost:5174',
+            'x-taskforce-origin-runtime': 'local-proxy',
+            'x-forwarded-host': 'localhost:5174',
+            'x-forwarded-proto': 'http'
+        });
+        const res = createMockRes();
+        await checkoutHandler(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const args = mockCheckoutCreate.mock.calls.at(-1)?.[0];
+        expect(String(args.success_url || '')).toContain('http://localhost:5174/?screen=plans&checkout=success');
+        expect(String(args.cancel_url || '')).toContain('http://localhost:5174/?screen=plans&checkout=cancel');
+        expect(JSON.parse(res.body)).toEqual(expect.objectContaining({
+            checkoutState: 'checkout',
+            returnBaseUrl: 'http://localhost:5174'
+        }));
+    });
+    it('prefers explicit proxy-origin headers over generic forwarded host values', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('collab-v1', 'default', 'collab', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
+            VALUES ('default', 'collab-v1', 'month', 'price_collab_month', 1, ?, ?)
+        `).run(now, now);
+        const checkoutHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session');
+        const req = createMockReq(JSON.stringify({
+            planVersionId: 'collab-v1',
+            interval: 'month'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'performance-app.taskforcehq.ai',
+            'x-taskforce-origin-host': 'localhost:5174',
+            'x-taskforce-origin-proto': 'http',
+            'x-taskforce-origin-runtime': 'local-proxy',
+            'x-forwarded-host': 'performance-app.taskforcehq.ai',
+            'x-forwarded-proto': 'https'
+        });
+        const res = createMockRes();
+        await checkoutHandler(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const args = mockCheckoutCreate.mock.calls.at(-1)?.[0];
+        expect(String(args.success_url || '')).toContain('http://localhost:5174/?screen=plans&checkout=success');
+    });
+    it('builds direct cloud checkout return URLs from the actual request protocol when forwarded proto is absent', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('collab-v1', 'default', 'collab', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
+            VALUES ('default', 'collab-v1', 'month', 'price_collab_month', 1, ?, ?)
+        `).run(now, now);
+        const checkoutHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session');
+        const req = createMockReq(JSON.stringify({
+            planVersionId: 'collab-v1',
+            interval: 'month'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: '127.0.0.1:4173'
+        });
+        req.socket = { encrypted: false };
+        const res = createMockRes();
+        await checkoutHandler(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const args = mockCheckoutCreate.mock.calls.at(-1)?.[0];
+        expect(String(args.success_url || '')).toContain('http://127.0.0.1:4173/?screen=plans&checkout=success');
+        expect(String(args.cancel_url || '')).toContain('http://127.0.0.1:4173/?screen=plans&checkout=cancel');
+    });
+    it('applies a free plan immediately without creating a Stripe checkout session', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('starter-v1', 'default', 'starter', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at)
+            VALUES ('default', 'starter-v1', 'month', 'free:starter-v1:month', 'free', 1, 0, NULL, ?, ?)
+        `).run(now, now);
+        const checkoutHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session');
+        const req = createMockReq(JSON.stringify({
+            planVersionId: 'starter-v1',
+            interval: 'month'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const res = createMockRes();
+        await checkoutHandler(req, res, {});
+        expect(res.statusCode).toBe(200);
+        expect(mockCheckoutCreate).not.toHaveBeenCalled();
+        expect(res.body).toContain('"checkoutState":"free"');
+    });
+    it('falls back to stripe email collection when user identity email is unavailable', async () => {
+        routeHandlers = buildBillingRouteHandlers(db, { userIdentity: { userId: 'u1', email: null, systemRole: 'user', betaAccess: true } });
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('collab-v1', 'default', 'collab', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
+            VALUES ('default', 'collab-v1', 'month', 'price_collab_month', 1, ?, ?)
+        `).run(now, now);
+        const checkoutHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session');
+        const req = createMockReq(JSON.stringify({
+            planVersionId: 'collab-v1',
+            interval: 'month'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const res = createMockRes();
+        await checkoutHandler(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const args = mockCheckoutCreate.mock.calls.at(-1)?.[0];
+        expect(args.customer).toBeUndefined();
+        expect(args.customer_email).toBeUndefined();
+    });
+    it('returns a clear error when the saved stripe customer no longer exists', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('collab-v1', 'default', 'collab', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
+            VALUES ('default', 'collab-v1', 'month', 'price_collab_month', 1, ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO user_billing (user_id, tenant_id, stripe_customer_id, entitlement_state, created_at, updated_at)
+            VALUES ('u1', 'default', 'cus_missing', 'active', ?, ?)
+        `).run(now, now);
+        mockCheckoutCreate.mockImplementationOnce(async () => {
+            const error = new Error('No such customer: cus_missing');
+            error.code = 'resource_missing';
+            throw error;
+        });
+        const checkoutHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session');
+        const req = createMockReq(JSON.stringify({
+            planVersionId: 'collab-v1',
+            interval: 'month'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const res = createMockRes();
+        await checkoutHandler(req, res, {});
+        expect(res.statusCode).toBe(409);
+        expect(JSON.parse(res.body)).toEqual({
+            error: 'The saved Stripe customer for this account could not be found. Please contact support before retrying checkout.',
+            code: 'BILLING_STRIPE_CUSTOMER_MISSING'
+        });
+    });
+    it('updates existing subscriptions without creating a checkout session', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('pro-v2', 'default', 'pro', 2, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
+            VALUES ('default', 'pro-v2', 'year', 'price_pro_year', 1, ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO user_billing (
+                user_id, tenant_id, stripe_customer_id, stripe_subscription_id, stripe_price_id, billing_interval, entitlement_state, created_at, updated_at
+            ) VALUES ('u1', 'default', 'cus_existing', 'sub_existing', 'price_pro_month', 'month', 'active', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO account_entitlements (
+                account_id, tenant_id, plan_version_id, entitlement_state, created_at, updated_at
+            ) VALUES ('u1', 'default', 'starter-v1', 'active', ?, ?)
+        `).run(now, now);
+        const checkoutHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session');
+        const req = createMockReq(JSON.stringify({
+            planVersionId: 'pro-v2',
+            interval: 'year'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const res = createMockRes();
+        await checkoutHandler(req, res, {});
+        expect(res.statusCode).toBe(200);
+        expect(mockSubscriptionUpdate).toHaveBeenCalledWith('sub_existing', expect.objectContaining({
+            items: [{ id: 'si_123', price: 'price_pro_year' }]
+        }));
+        expect(mockCheckoutCreate).not.toHaveBeenCalled();
+        expect(JSON.parse(res.body)).toEqual(expect.objectContaining({
+            checkoutState: 'updated'
+        }));
+    });
+    it('does not create a second checkout session for the same paid plan', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('pro-v1', 'default', 'pro', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
+            VALUES ('default', 'pro-v1', 'month', 'price_pro_month', 1, ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO user_billing (
+                user_id, tenant_id, stripe_customer_id, stripe_subscription_id, stripe_price_id, stripe_status, tier, billing_interval, entitlement_state, created_at, updated_at
+            ) VALUES ('u1', 'default', 'cus_123', 'sub_123', 'price_pro_month', 'active', 'pro', 'month', 'active', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO account_entitlements (
+                account_id, tenant_id, plan_version_id, entitlement_state, effective_at, created_at, updated_at
+            ) VALUES ('u1', 'default', 'pro-v1', 'active', ?, ?, ?)
+        `).run(now, now, now);
+        mockSubscriptionList.mockResolvedValueOnce({
+            data: [{ id: 'sub_123', status: 'active' }]
+        });
+        const checkoutHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session');
+        const req = createMockReq(JSON.stringify({
+            planVersionId: 'pro-v1',
+            interval: 'month'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const res = createMockRes();
+        await checkoutHandler(req, res, {});
+        expect(res.statusCode).toBe(200);
+        expect(mockCheckoutCreate).not.toHaveBeenCalled();
+        expect(mockSubscriptionUpdate).not.toHaveBeenCalled();
+        expect(JSON.parse(res.body)).toEqual(expect.objectContaining({
+            checkoutState: 'already_current_plan',
+            planVersionId: 'pro-v1'
+        }));
+    });
+    it('discovers an active paid subscription by account email and blocks a duplicate purchase', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('pro-v1', 'default', 'pro', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
+            VALUES ('default', 'pro-v1', 'month', 'price_pro_month', 1, ?, ?)
+        `).run(now, now);
+        mockCustomersList.mockResolvedValueOnce({
+            data: [{ id: 'cus_email_match' }]
+        });
+        mockSubscriptionList.mockResolvedValueOnce({
+            data: [{
+                    id: 'sub_email_match',
+                    customer: 'cus_email_match',
+                    status: 'active',
+                    trial_end: null,
+                    metadata: { userId: 'u1', planVersionId: 'pro-v1' },
+                    items: {
+                        data: [{
+                                id: 'si_email_match',
+                                current_period_end: Math.floor(Date.now() / 1000) + 86400,
+                                price: { id: 'price_pro_month', recurring: { interval: 'month' } }
+                            }]
+                    }
+                }]
+        });
+        const checkoutHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session');
+        const req = createMockReq(JSON.stringify({
+            planVersionId: 'pro-v1',
+            interval: 'month'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const res = createMockRes();
+        await checkoutHandler(req, res, {});
+        expect(res.statusCode).toBe(200);
+        expect(mockCheckoutCreate).not.toHaveBeenCalled();
+        expect(JSON.parse(res.body)).toEqual(expect.objectContaining({
+            checkoutState: 'already_current_plan',
+            planVersionId: 'pro-v1'
+        }));
+        const mirrored = db.prepare(`
+            SELECT stripe_customer_id, stripe_subscription_id
+            FROM user_billing
+            WHERE tenant_id = 'default' AND user_id = 'u1'
+            LIMIT 1
+        `).get();
+        expect(mirrored).toEqual(expect.objectContaining({
+            stripe_customer_id: 'cus_email_match',
+            stripe_subscription_id: 'sub_email_match'
+        }));
+    });
+    it('updates the existing paid subscription instead of creating a second checkout', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('pro-v1', 'default', 'pro', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('team-v1', 'default', 'team', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
+            VALUES ('default', 'team-v1', 'month', 'price_team_month', 1, ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO user_billing (
+                user_id, tenant_id, stripe_customer_id, stripe_subscription_id, stripe_price_id, stripe_status, tier, billing_interval, entitlement_state, created_at, updated_at
+            ) VALUES ('u1', 'default', 'cus_123', 'sub_123', 'price_pro_month', 'active', 'pro', 'month', 'active', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO account_entitlements (
+                account_id, tenant_id, plan_version_id, entitlement_state, effective_at, created_at, updated_at
+            ) VALUES ('u1', 'default', 'pro-v1', 'active', ?, ?, ?)
+        `).run(now, now, now);
+        mockSubscriptionList.mockResolvedValueOnce({
+            data: [{ id: 'sub_123', status: 'active' }]
+        });
+        mockSubscriptionUpdate.mockResolvedValueOnce({
+            id: 'sub_123',
+            customer: 'cus_123',
+            status: 'active',
+            trial_end: null,
+            metadata: { userId: 'u1', planVersionId: 'team-v1' },
+            items: {
+                data: [{
+                        id: 'si_123',
+                        current_period_end: Math.floor(Date.now() / 1000) + 86400,
+                        price: { id: 'price_team_month', recurring: { interval: 'month' } }
+                    }]
+            }
+        });
+        const checkoutHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session');
+        const req = createMockReq(JSON.stringify({
+            planVersionId: 'team-v1',
+            interval: 'month'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const res = createMockRes();
+        await checkoutHandler(req, res, {});
+        expect(res.statusCode).toBe(200);
+        expect(mockCheckoutCreate).not.toHaveBeenCalled();
+        expect(mockSubscriptionUpdate).toHaveBeenCalledWith('sub_123', expect.objectContaining({
+            items: [{ id: 'si_123', price: 'price_team_month' }]
+        }));
+        expect(JSON.parse(res.body)).toEqual(expect.objectContaining({
+            checkoutState: 'updated',
+            planVersionId: 'team-v1'
+        }));
+        const entitlement = db.prepare(`
+            SELECT plan_version_id
+            FROM account_entitlements
+            WHERE tenant_id = 'default' AND account_id = 'u1'
+            LIMIT 1
+        `).get();
+        expect(entitlement?.plan_version_id).toBe('team-v1');
+    });
+    it('updates the existing subscription when only the interval changes on the same plan', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('pro-v1', 'default', 'pro', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
+            VALUES ('default', 'pro-v1', 'month', 'price_pro_month', 1, ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
+            VALUES ('default', 'pro-v1', 'year', 'price_pro_year', 1, ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO user_billing (
+                user_id, tenant_id, stripe_customer_id, stripe_subscription_id, stripe_price_id, stripe_status, tier, billing_interval, entitlement_state, created_at, updated_at
+            ) VALUES ('u1', 'default', 'cus_123', 'sub_123', 'price_pro_month', 'active', 'pro', 'month', 'active', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO account_entitlements (
+                account_id, tenant_id, plan_version_id, entitlement_state, effective_at, created_at, updated_at
+            ) VALUES ('u1', 'default', 'pro-v1', 'active', ?, ?, ?)
+        `).run(now, now, now);
+        mockSubscriptionList.mockResolvedValueOnce({
+            data: [{ id: 'sub_123', status: 'active' }]
+        });
+        mockSubscriptionUpdate.mockResolvedValueOnce({
+            id: 'sub_123',
+            customer: 'cus_123',
+            status: 'active',
+            trial_end: null,
+            metadata: { userId: 'u1', planVersionId: 'pro-v1' },
+            items: {
+                data: [{
+                        id: 'si_123',
+                        current_period_end: Math.floor(Date.now() / 1000) + 86400,
+                        price: { id: 'price_pro_year', recurring: { interval: 'year' } }
+                    }]
+            }
+        });
+        const checkoutHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session');
+        const req = createMockReq(JSON.stringify({
+            planVersionId: 'pro-v1',
+            interval: 'year'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const res = createMockRes();
+        await checkoutHandler(req, res, {});
+        expect(res.statusCode).toBe(200);
+        expect(mockCheckoutCreate).not.toHaveBeenCalled();
+        expect(mockSubscriptionUpdate).toHaveBeenCalledWith('sub_123', expect.objectContaining({
+            items: [{ id: 'si_123', price: 'price_pro_year' }]
+        }));
+        expect(JSON.parse(res.body)).toEqual(expect.objectContaining({
+            checkoutState: 'updated',
+            planVersionId: 'pro-v1'
+        }));
+    });
+    it('confirms a successful checkout session and updates the entitlement immediately', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('pro-v1', 'default', 'pro', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
+            VALUES ('default', 'pro-v1', 'month', 'price_pro_month', 1, ?, ?)
+        `).run(now, now);
+        const confirmHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session/confirm');
+        expect(confirmHandler).toBeTypeOf('function');
+        const req = createMockReq(JSON.stringify({
+            sessionId: 'cs_success_123'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const res = createMockRes();
+        await confirmHandler(req, res, {});
+        expect(res.statusCode).toBe(200);
+        expect(mockCheckoutRetrieve).toHaveBeenCalledWith('cs_success_123', expect.objectContaining({
+            expand: ['subscription']
+        }));
+        expect(mockSubscriptionRetrieve).toHaveBeenCalledWith('sub_123');
+        const entitlement = db.prepare(`
+            SELECT plan_version_id, entitlement_state
+            FROM account_entitlements
+            WHERE tenant_id = 'default' AND account_id = 'u1'
+            LIMIT 1
+        `).get();
+        expect(entitlement).toEqual(expect.objectContaining({
+            plan_version_id: 'pro-v1',
+            entitlement_state: 'active'
+        }));
+    });
+    it('lists webhook failure diagnostics for system admin', async () => {
+        const now = new Date().toISOString();
+        const old = new Date(Date.now() - 48 * 60 * 60 * 1000).toISOString();
+        db.prepare(`
+            INSERT INTO stripe_webhook_failures (id, tenant_id, event_id, event_type, reason, payload_excerpt, purge_after, created_at)
+            VALUES ('whf_keep_1', 'default', 'evt_1', 'invoice.paid', 'diagnostic-1', '{"id":"evt_1"}', ?, ?)
+        `).run(new Date(Date.now() + 48 * 60 * 60 * 1000).toISOString(), now);
+        db.prepare(`
+            INSERT INTO stripe_webhook_failures (id, tenant_id, event_id, event_type, reason, payload_excerpt, purge_after, created_at)
+            VALUES ('whf_purge_1', 'default', 'evt_old', 'invoice.paid', 'diagnostic-old', '{"id":"evt_old"}', ?, ?)
+        `).run(old, now);
+        const route = routeHandlers.get('GET /api/taskforce/admin/billing/webhook-failures');
+        expect(route).toBeTypeOf('function');
+        const req = createMockReq('', {
+            'x-taskforce-runtime-mode': 'cloud'
+        });
+        req.url = '/api/taskforce/admin/billing/webhook-failures?limit=10';
+        const res = createMockRes();
+        await route(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const payload = JSON.parse(res.body);
+        expect(payload.purgedExpiredRows).toBeGreaterThanOrEqual(1);
+        expect(payload.total).toBeGreaterThanOrEqual(1);
+        expect(Array.isArray(payload.rows)).toBe(true);
+        expect(payload.rows[0]).toEqual(expect.objectContaining({
+            event_id: 'evt_1',
+            reason: 'diagnostic-1'
+        }));
+    });
+    it('lists stripe price options filtered by interval for system admin', async () => {
+        mockPricesList.mockResolvedValueOnce({
+            data: [
+                { id: 'price_month_1', active: true, currency: 'usd', unit_amount: 1200, recurring: { interval: 'month' }, nickname: 'Monthly', product: 'prod_1' },
+                { id: 'price_year_1', active: true, currency: 'usd', unit_amount: 12000, recurring: { interval: 'year' }, nickname: 'Yearly', product: 'prod_1' }
+            ],
+            has_more: false
+        });
+        const route = routeHandlers.get('GET /api/taskforce/admin/billing/stripe-price-options');
+        expect(route).toBeTypeOf('function');
+        const req = createMockReq('', {
+            'x-taskforce-runtime-mode': 'cloud'
+        });
+        req.url = '/api/taskforce/admin/billing/stripe-price-options?interval=month';
+        const res = createMockRes();
+        await route(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const body = JSON.parse(res.body);
+        expect(Array.isArray(body.options)).toBe(true);
+        expect(body.options.length).toBe(1);
+        expect(body.options[0]).toEqual(expect.objectContaining({
+            stripePriceId: 'price_month_1',
+            interval: 'month'
+        }));
+    });
+    it('keeps active manual price mappings during Stripe import when the price is still active but lacks plan metadata', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('collab-v1', 'default', 'collab', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at)
+            VALUES ('default', 'collab-v1', 'month', 'price_manual', 'stripe', 1, 1900, 'usd', ?, ?)
+        `).run(now, now);
+        mockPricesList.mockResolvedValueOnce({
+            data: [
+                {
+                    id: 'price_manual',
+                    active: true,
+                    currency: 'usd',
+                    unit_amount: 1900,
+                    recurring: { interval: 'month' },
+                    metadata: {}
+                }
+            ],
+            has_more: false
+        });
+        const route = routeHandlers.get('POST /api/taskforce/admin/billing/prices/import');
+        expect(route).toBeTypeOf('function');
+        const req = createMockReq('', {
+            'x-taskforce-runtime-mode': 'cloud'
+        });
+        const res = createMockRes();
+        await route(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const row = db.prepare(`
+            SELECT active
+            FROM billing_price_mappings
+            WHERE tenant_id = 'default' AND stripe_price_id = 'price_manual'
+            LIMIT 1
+        `).get();
+        expect(row.active).toBe(1);
+    });
+    it('upserts price mappings and deactivates prior active mapping for same version interval', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('collab-v1', 'default', 'collab', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at)
+            VALUES ('default', 'collab-v1', 'month', 'price_old', 'stripe', 1, 1100, 'usd', ?, ?)
+        `).run(now, now);
+        mockPriceRetrieve.mockResolvedValueOnce({
+            id: 'price_new',
+            active: true,
+            currency: 'usd',
+            unit_amount: 1500,
+            recurring: { interval: 'month' }
+        });
+        const upsertRoute = routeHandlers.get('PUT /api/taskforce/admin/billing/price-mappings');
+        expect(upsertRoute).toBeTypeOf('function');
+        const upsertReq = createMockReq(JSON.stringify({
+            planVersionId: 'collab-v1',
+            interval: 'month',
+            stripePriceId: 'price_new',
+            active: true
+        }), { 'x-taskforce-runtime-mode': 'cloud' });
+        const upsertRes = createMockRes();
+        await upsertRoute(upsertReq, upsertRes, {});
+        expect(upsertRes.statusCode).toBe(200);
+        const rows = db.prepare(`
+            SELECT stripe_price_id, active
+            FROM billing_price_mappings
+            WHERE tenant_id = 'default' AND plan_version_id = 'collab-v1' AND billing_interval = 'month'
+            ORDER BY stripe_price_id ASC
+        `).all();
+        expect(rows).toEqual([
+            { stripe_price_id: 'price_new', active: 1 },
+            { stripe_price_id: 'price_old', active: 0 }
+        ]);
+    });
+    it('allows the same stripe price id to be assigned to multiple plan versions', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('collab-v1', 'default', 'collab', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('team-v1', 'default', 'team', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        mockPriceRetrieve.mockResolvedValue({
+            id: 'price_shared',
+            active: true,
+            currency: 'usd',
+            unit_amount: 1900,
+            recurring: { interval: 'month' }
+        });
+        const upsertRoute = routeHandlers.get('PUT /api/taskforce/admin/billing/price-mappings');
+        const firstReq = createMockReq(JSON.stringify({
+            planVersionId: 'collab-v1',
+            interval: 'month',
+            stripePriceId: 'price_shared',
+            active: true
+        }), { 'x-taskforce-runtime-mode': 'cloud' });
+        const firstRes = createMockRes();
+        await upsertRoute(firstReq, firstRes, {});
+        expect(firstRes.statusCode).toBe(200);
+        const secondReq = createMockReq(JSON.stringify({
+            planVersionId: 'team-v1',
+            interval: 'month',
+            stripePriceId: 'price_shared',
+            active: true
+        }), { 'x-taskforce-runtime-mode': 'cloud' });
+        const secondRes = createMockRes();
+        await upsertRoute(secondReq, secondRes, {});
+        expect(secondRes.statusCode).toBe(200);
+        const rows = db.prepare(`
+            SELECT plan_version_id, stripe_price_id, active
+            FROM billing_price_mappings
+            WHERE tenant_id = 'default' AND stripe_price_id = 'price_shared'
+            ORDER BY plan_version_id ASC
+        `).all();
+        expect(rows).toEqual([
+            { plan_version_id: 'collab-v1', stripe_price_id: 'price_shared', active: 1 },
+            { plan_version_id: 'team-v1', stripe_price_id: 'price_shared', active: 1 }
+        ]);
+    });
+    it('keeps reused mappings for other plan versions during Stripe import', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('collab-v1', 'default', 'collab', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('team-v1', 'default', 'team', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at)
+            VALUES ('default', 'collab-v1', 'month', 'price_shared', 'stripe', 1, 1900, 'usd', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at)
+            VALUES ('default', 'team-v1', 'month', 'price_shared', 'stripe', 1, 1900, 'usd', ?, ?)
+        `).run(now, now);
+        mockPricesList.mockResolvedValueOnce({
+            data: [
+                {
+                    id: 'price_shared',
+                    active: true,
+                    currency: 'usd',
+                    unit_amount: 1900,
+                    recurring: { interval: 'month' },
+                    metadata: { taskforce_plan_version_id: 'collab-v1' }
+                }
+            ],
+            has_more: false
+        });
+        const route = routeHandlers.get('POST /api/taskforce/admin/billing/prices/import');
+        const req = createMockReq('', { 'x-taskforce-runtime-mode': 'cloud' });
+        const res = createMockRes();
+        await route(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const rows = db.prepare(`
+            SELECT plan_version_id, stripe_price_id, active
+            FROM billing_price_mappings
+            WHERE tenant_id = 'default' AND stripe_price_id = 'price_shared'
+            ORDER BY plan_version_id ASC
+        `).all();
+        expect(rows).toEqual([
+            { plan_version_id: 'collab-v1', stripe_price_id: 'price_shared', active: 1 },
+            { plan_version_id: 'team-v1', stripe_price_id: 'price_shared', active: 1 }
+        ]);
+    });
+    it('upserts explicit free pricing without requiring a Stripe price id', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('starter-v1', 'default', 'starter', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        const upsertRoute = routeHandlers.get('PUT /api/taskforce/admin/billing/price-mappings');
+        expect(upsertRoute).toBeTypeOf('function');
+        const upsertReq = createMockReq(JSON.stringify({
+            planVersionId: 'starter-v1',
+            interval: 'month',
+            pricingType: 'free',
+            active: true
+        }), { 'x-taskforce-runtime-mode': 'cloud' });
+        const upsertRes = createMockRes();
+        await upsertRoute(upsertReq, upsertRes, {});
+        expect(upsertRes.statusCode).toBe(200);
+        const row = db.prepare(`
+            SELECT stripe_price_id, pricing_type, active, unit_amount
+            FROM billing_price_mappings
+            WHERE tenant_id = 'default' AND plan_version_id = 'starter-v1' AND billing_interval = 'month'
+            LIMIT 1
+        `).get();
+        expect(row.stripe_price_id).toBe('free:starter-v1:month');
+        expect(row.pricing_type).toBe('free');
+        expect(row.active).toBe(1);
+        expect(row.unit_amount).toBe(0);
+    });
+    it('rejects webhook failure diagnostics for non-admin', async () => {
+        const nonAdminHandlers = buildBillingRouteHandlers(db, { isAdmin: false });
+        const route = nonAdminHandlers.get('GET /api/taskforce/admin/billing/webhook-failures');
+        expect(route).toBeTypeOf('function');
+        const req = createMockReq('', {
+            'x-taskforce-runtime-mode': 'cloud'
+        });
+        req.url = '/api/taskforce/admin/billing/webhook-failures';
+        const res = createMockRes();
+        await route(req, res, {});
+        expect(res.statusCode).toBe(403);
+    });
+    it('returns public pricing catalog with cached Stripe amounts without auth', async () => {
+        const now = new Date().toISOString();
+        routeHandlers = buildBillingRouteHandlers(db);
+        const pricingRoute = routeHandlers.get('GET /api/taskforce/public/pricing');
+        expect(pricingRoute).toBeTypeOf('function');
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('pro-v1', 'default', 'pro', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('starter-v1', 'default', 'starter', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at)
+            VALUES ('default', 'pro-v1', 'month', 'price_pro_month', 'stripe', 1, 1500, 'usd', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at)
+            VALUES ('default', 'starter-v1', 'month', 'free:starter-v1:month', 'free', 1, 0, NULL, ?, ?)
+        `).run(now, now);
+        const req = createMockReq('', { 'x-taskforce-runtime-mode': 'cloud' });
+        const res = createMockRes();
+        await pricingRoute(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const body = JSON.parse(res.body);
+        expect(body.plans).toBeInstanceOf(Array);
+        expect(body.pricingSource).toEqual({
+            environment: 'production',
+            runtimeMode: 'cloud'
+        });
+        // Only active plans with versions should be returned (pro, starter)
+        // inactive-plan (archived) and empty-plan (no versions) are excluded.
+        expect(body.plans.length).toBe(2);
+        const proPlan = body.plans.find((p) => p.planId === 'pro');
+        const freePlan = body.plans.find((p) => p.planId === 'starter');
+        expect(proPlan).toBeDefined();
+        expect(freePlan).toBeDefined();
+        // Pro plan has mapped prices
+        const monthPricing = proPlan.pricing.month;
+        expect(monthPricing).not.toBeNull();
+        expect(monthPricing.unitAmount).toBe(1500);
+        expect(monthPricing.currency).toBe('usd');
+        expect(monthPricing.stripePriceId).toBe('price_pro_month');
+        expect(proPlan.pricing.year).toBeNull();
+        // Free plan is explicitly free, not "missing"
+        expect(freePlan.pricing.month.pricingType).toBe('free');
+        expect(freePlan.pricing.month.unitAmount).toBe(0);
+        expect(freePlan.pricing.month.stripePriceId).toBeNull();
+        expect(freePlan.pricing.year).toBeNull();
+        expect(proPlan.defaultVersion.trialDays).toBe(0);
+    });
+    it('returns the pricing environment derived from the cloud host', async () => {
+        routeHandlers = buildBillingRouteHandlers(db);
+        const pricingRoute = routeHandlers.get('GET /api/taskforce/public/pricing');
+        expect(pricingRoute).toBeTypeOf('function');
+        const req = createMockReq('', {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'performance-app.taskforcehq.ai'
+        });
+        const res = createMockRes();
+        await pricingRoute(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const body = JSON.parse(res.body);
+        expect(body.pricingSource).toEqual({
+            environment: 'performance',
+            runtimeMode: 'cloud'
+        });
+    });
+    it('rejects local runtime pricing requests so they cannot serve local catalog data', async () => {
+        routeHandlers = buildBillingRouteHandlers(db);
+        const pricingRoute = routeHandlers.get('GET /api/taskforce/public/pricing');
+        expect(pricingRoute).toBeTypeOf('function');
+        const req = createMockReq('', { 'x-taskforce-runtime-mode': 'local' });
+        const res = createMockRes();
+        await pricingRoute(req, res, {});
+        expect(res.statusCode).toBe(500);
+        expect(JSON.parse(res.body)).toEqual({
+            error: 'Pricing must be served through the configured cloud pricing proxy in local runtime.'
+        });
+    });
+    it('returns plan display name in billing status payload', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_catalog (plan_id, tenant_id, display_name, status, created_at, updated_at)
+            VALUES ('pro', 'default', 'Pro Plan', 'active', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO user_billing (
+                user_id, tenant_id, stripe_customer_id, stripe_subscription_id, stripe_price_id, stripe_status, tier, billing_interval, entitlement_state, created_at, updated_at
+            ) VALUES ('u1', 'default', 'cus_123', 'sub_123', 'price_123', 'active', 'pro', 'month', 'active', ?, ?)
+        `).run(now, now);
+        const statusRoute = routeHandlers.get('GET /api/taskforce/billing/status');
+        expect(statusRoute).toBeTypeOf('function');
+        const req = createMockReq('', { 'x-taskforce-runtime-mode': 'cloud' });
+        const res = createMockRes();
+        await statusRoute(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const body = JSON.parse(res.body);
+        expect(body.planId).toBe('pro');
+        expect(body.planName).toBe('Pro Plan');
+        expect(body.planVersionId).toBe('pro-v1');
+        expect(body.entitlementState).toBe('active');
+    });
+    it('reconciles stale entitlement from Stripe when billing status is requested', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_catalog (plan_id, tenant_id, display_name, status, created_at, updated_at)
+            VALUES ('pro', 'default', 'Pro Plan', 'active', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('pro-v1', 'default', 'pro', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
+            VALUES ('default', 'pro-v1', 'month', 'price_pro_month', 1, ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO user_billing (
+                user_id, tenant_id, stripe_customer_id, stripe_subscription_id, stripe_price_id, stripe_status, tier, billing_interval, entitlement_state, created_at, updated_at
+            ) VALUES ('u1', 'default', 'cus_123', 'sub_123', 'price_old', 'active', 'starter', 'month', 'active', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO account_entitlements (
+                account_id, tenant_id, plan_version_id, entitlement_state, effective_at, created_at, updated_at
+            ) VALUES ('u1', 'default', 'starter-v1', 'active', ?, ?, ?)
+        `).run(now, now, now);
+        const statusRoute = routeHandlers.get('GET /api/taskforce/billing/status');
+        const req = createMockReq('', { 'x-taskforce-runtime-mode': 'cloud' });
+        const res = createMockRes();
+        await statusRoute(req, res, {});
+        expect(res.statusCode).toBe(200);
+        expect(mockSubscriptionRetrieve).toHaveBeenCalledWith('sub_123');
+        const entitlement = db.prepare(`
+            SELECT plan_version_id
+            FROM account_entitlements
+            WHERE tenant_id = 'default' AND account_id = 'u1'
+            LIMIT 1
+        `).get();
+        expect(entitlement?.plan_version_id).toBe('pro-v1');
+    });
+    it('repairs billing status from an active Stripe subscription discovered by account email', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_catalog (plan_id, tenant_id, display_name, status, created_at, updated_at)
+            VALUES ('pro', 'default', 'Pro Plan', 'active', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('pro-v1', 'default', 'pro', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
+            VALUES ('default', 'pro-v1', 'month', 'price_pro_month', 1, ?, ?)
+        `).run(now, now);
+        mockCustomersList.mockResolvedValueOnce({
+            data: [{ id: 'cus_email_match' }]
+        });
+        mockSubscriptionList.mockResolvedValueOnce({
+            data: [{
+                    id: 'sub_email_match',
+                    customer: 'cus_email_match',
+                    status: 'active',
+                    trial_end: null,
+                    metadata: { userId: 'u1', planVersionId: 'pro-v1' },
+                    items: {
+                        data: [{
+                                id: 'si_email_match',
+                                current_period_end: Math.floor(Date.now() / 1000) + 86400,
+                                price: { id: 'price_pro_month', recurring: { interval: 'month' } }
+                            }]
+                    }
+                }]
+        });
+        const statusRoute = routeHandlers.get('GET /api/taskforce/billing/status');
+        const req = createMockReq('', { 'x-taskforce-runtime-mode': 'cloud' });
+        const res = createMockRes();
+        await statusRoute(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const body = JSON.parse(res.body);
+        expect(body.planId).toBe('pro');
+        expect(body.planVersionId).toBe('pro-v1');
+        expect(body.stripeCustomerId).toBe('cus_email_match');
+        expect(body.stripeSubscriptionId).toBe('sub_email_match');
+    });
+    it('prefers subscription metadata over shared price fallback during webhook processing', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('starter-v1', 'default', 'starter', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('team-v1', 'default', 'team', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at)
+            VALUES ('default', 'starter-v1', 'month', 'price_shared', 'stripe', 1, 1900, 'usd', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at)
+            VALUES ('default', 'team-v1', 'month', 'price_shared', 'stripe', 1, 1900, 'usd', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO user_billing (user_id, tenant_id, stripe_customer_id, entitlement_state, created_at, updated_at)
+            VALUES ('u1', 'default', 'cus_123', 'active', ?, ?)
+        `).run(now, now);
+        mockConstructEvent.mockReturnValue({
+            id: 'evt_shared_metadata',
+            type: 'customer.subscription.updated',
+            data: {
+                object: {
+                    id: 'sub_123',
+                    customer: 'cus_123',
+                    status: 'active',
+                    trial_end: null,
+                    metadata: { planVersionId: 'team-v1' },
+                    items: {
+                        data: [{
+                                current_period_end: Math.floor(Date.now() / 1000) + 86400,
+                                price: { id: 'price_shared', recurring: { interval: 'month' } }
+                            }]
+                    }
+                }
+            }
+        });
+        const req = createMockReq('{"id":"evt_shared_metadata"}', {
+            'x-taskforce-runtime-mode': 'cloud',
+            'stripe-signature': 'sig'
+        });
+        const res = createMockRes();
+        await webhookHandler(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const entitlement = db.prepare(`
+            SELECT plan_version_id
+            FROM account_entitlements
+            WHERE account_id = 'u1' AND tenant_id = 'default'
+            LIMIT 1
+        `).get();
+        expect(entitlement.plan_version_id).toBe('team-v1');
+    });
+    it('logs webhook failure when shared price fallback is ambiguous and metadata is missing', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('starter-v1', 'default', 'starter', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('team-v1', 'default', 'team', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at)
+            VALUES ('default', 'starter-v1', 'month', 'price_shared', 'stripe', 1, 1900, 'usd', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at)
+            VALUES ('default', 'team-v1', 'month', 'price_shared', 'stripe', 1, 1900, 'usd', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO user_billing (user_id, tenant_id, stripe_customer_id, entitlement_state, created_at, updated_at)
+            VALUES ('u1', 'default', 'cus_456', 'active', ?, ?)
+        `).run(now, now);
+        mockConstructEvent.mockReturnValue({
+            id: 'evt_shared_ambiguous',
+            type: 'customer.subscription.updated',
+            data: {
+                object: {
+                    id: 'sub_456',
+                    customer: 'cus_456',
+                    status: 'active',
+                    trial_end: null,
+                    metadata: {},
+                    items: {
+                        data: [{
+                                current_period_end: Math.floor(Date.now() / 1000) + 86400,
+                                price: { id: 'price_shared', recurring: { interval: 'month' } }
+                            }]
+                    }
+                }
+            }
+        });
+        const req = createMockReq('{"id":"evt_shared_ambiguous"}', {
+            'x-taskforce-runtime-mode': 'cloud',
+            'stripe-signature': 'sig'
+        });
+        const res = createMockRes();
+        await webhookHandler(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const failure = db.prepare(`
+            SELECT reason
+            FROM stripe_webhook_failures
+            WHERE event_id = 'evt_shared_ambiguous'
+            ORDER BY created_at DESC
+            LIMIT 1
+        `).get();
+        expect(failure.reason).toContain('Ambiguous price mapping');
+    });
+});