@taskforcehq/taskforce 0.3.302 → 0.3.304

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

@@ -5,8 +5,20 @@ 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 mockCheckoutCreate = vi.fn(async () => ({
+    id: 'cs_test',
+    url: 'https://example.test/checkout',
+    expires_at: Math.floor(Date.now() / 1000) + (24 * 60 * 60)
+}));
+const mockCheckoutRetrieve = vi.fn(async (id) => ({
+    id,
+    mode: 'subscription',
+    status: 'complete',
+    payment_status: 'paid',
+    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: [] }));
@@ -130,6 +142,17 @@ function setupBillingSchema(db) {
             purge_after TEXT NOT NULL,
             created_at TEXT NOT NULL
         );
+        CREATE TABLE billing_checkout_attempts (
+            session_id TEXT PRIMARY KEY,
+            tenant_id TEXT NOT NULL,
+            user_id TEXT NOT NULL,
+            plan_version_id TEXT NOT NULL,
+            billing_interval TEXT,
+            status TEXT NOT NULL DEFAULT 'open',
+            expires_at TEXT,
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL
+        );
         CREATE TABLE billing_price_mappings (
             tenant_id TEXT NOT NULL,
             plan_version_id TEXT NOT NULL,
@@ -188,6 +211,18 @@ function setupBillingSchema(db) {
 function buildBillingRouteHandlers(db, opts) {
     const routes = new Map();
     const tenantId = 'default';
+    const resolvePlanIdForVersion = (planVersionIdRaw) => {
+        const planVersionId = String(planVersionIdRaw || '').trim();
+        if (!planVersionId)
+            return '';
+        const row = db.prepare(`
+            SELECT plan_id
+            FROM plan_versions
+            WHERE tenant_id = ? AND plan_version_id = ?
+            LIMIT 1
+        `).get(tenantId, planVersionId);
+        return String(row?.plan_id || '').trim();
+    };
     const core = {
         getDatabaseAdapter: () => db,
         getTenantId: () => tenantId,
@@ -200,6 +235,37 @@ function buildBillingRouteHandlers(db, opts) {
                 ON CONFLICT (user_id) DO NOTHING
             `).run(userId, tenantId, now, now);
         },
+        transitionCanonicalCommercialState: (input) => {
+            const now = new Date().toISOString();
+            const planVersionId = String(input.planVersionId || '').trim();
+            const effectiveAt = input.effectiveAt || now;
+            const effectiveUntil = input.effectiveUntil || null;
+            db.prepare(`
+                INSERT INTO account_entitlements (
+                    account_id, tenant_id, plan_version_id, entitlement_state, effective_at, effective_until, updated_by, created_at, updated_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT (account_id) DO UPDATE SET
+                    plan_version_id = excluded.plan_version_id,
+                    entitlement_state = excluded.entitlement_state,
+                    effective_at = excluded.effective_at,
+                    effective_until = excluded.effective_until,
+                    updated_by = excluded.updated_by,
+                    updated_at = excluded.updated_at
+            `).run(input.accountId, tenantId, planVersionId, input.state, effectiveAt, effectiveUntil, input.updatedBy, input.createdAt || now, input.updatedAt || now);
+            const planId = typeof input.billingMirrorPlanId === 'string'
+                ? input.billingMirrorPlanId
+                : resolvePlanIdForVersion(planVersionId);
+            db.prepare(`
+                INSERT INTO user_billing (
+                    user_id, tenant_id, tier, entitlement_state, effective_until, created_at, updated_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT (user_id) DO UPDATE SET
+                    tier = excluded.tier,
+                    entitlement_state = excluded.entitlement_state,
+                    effective_until = excluded.effective_until,
+                    updated_at = excluded.updated_at
+            `).run(input.accountId, tenantId, planId, input.state, effectiveUntil, now, now);
+        },
         listPlanCatalog: () => [
             { planId: 'pro', displayName: 'Pro Plan', status: 'active', createdAt: '', updatedAt: '' },
             { planId: 'inactive-plan', displayName: 'Inactive', status: 'archived', createdAt: '', updatedAt: '' },
@@ -228,23 +294,25 @@ function buildBillingRouteHandlers(db, opts) {
                 };
             });
         },
-        getAccountEntitlement: () => ({
-            accountId: 'u1',
-            planVersionId: 'pro-v1',
-            planId: 'pro',
-            state: 'active',
-            effectiveAt: null,
-            effectiveUntil: null,
-            updatedBy: null,
-            createdAt: '',
-            updatedAt: ''
-        }),
-        getAccountAccessStatus: () => ({
+        getAccountEntitlement: () => {
+            const entitlement = opts?.accessStatus?.entitlement;
+            return {
+                accountId: String(entitlement?.accountId || 'u1'),
+                planVersionId: String(entitlement?.planVersionId || 'pro-v1'),
+                planId: String(entitlement?.planId || 'pro'),
+                state: String(entitlement?.state || 'active'),
+                effectiveAt: entitlement?.effectiveAt ?? null,
+                effectiveUntil: entitlement?.effectiveUntil ?? null,
+                updatedBy: null,
+                createdAt: '',
+                updatedAt: ''
+            };
+        },
+        getAccountAccessStatus: () => opts?.accessStatus || ({
             gate: 'ok',
             hasEntitlement: true,
             canAccessApp: true,
             canAccessPlans: true,
-            signupMonetizationStrategy: 'auto_assign_default',
             planSelectionRequired: false,
             message: null,
             entitlement: {
@@ -421,6 +489,286 @@ describe('Billing Webhook Routes', () => {
         `).get();
         expect(failure.reason).toContain('Unknown price mapping');
     });
+    it('keeps blocked accounts in checkout_pending when Stripe reports an incomplete subscription', 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, entitlement_state, created_at, updated_at)
+            VALUES ('u1', 'default', 'cus_123', 'checkout_pending', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO account_entitlements (
+                account_id, tenant_id, plan_version_id, entitlement_state, effective_at, updated_by, created_at, updated_at
+            ) VALUES ('u1', 'default', 'pro-v1', 'checkout_pending', ?, 'checkout-start', ?, ?)
+        `).run(now, now, now);
+        mockConstructEvent.mockReturnValue({
+            id: 'evt_incomplete_subscription',
+            type: 'customer.subscription.updated',
+            data: {
+                object: {
+                    id: 'sub_123',
+                    customer: 'cus_123',
+                    status: 'incomplete',
+                    trial_end: null,
+                    metadata: { planVersionId: 'pro-v1' },
+                    items: {
+                        data: [{
+                                current_period_end: Math.floor(Date.now() / 1000) + 86400,
+                                price: { id: 'price_pro_month', recurring: { interval: 'month' } }
+                            }]
+                    }
+                }
+            }
+        });
+        const req = createMockReq('{"id":"evt_incomplete_subscription"}', {
+            '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, entitlement_state, updated_by
+            FROM account_entitlements
+            WHERE account_id = 'u1' AND tenant_id = 'default'
+            LIMIT 1
+        `).get();
+        expect(entitlement).toEqual(expect.objectContaining({
+            plan_version_id: 'pro-v1',
+            entitlement_state: 'checkout_pending',
+            updated_by: 'stripe-webhook'
+        }));
+        const billing = db.prepare(`
+            SELECT entitlement_state, stripe_status, stripe_subscription_id
+            FROM user_billing
+            WHERE user_id = 'u1' AND tenant_id = 'default'
+            LIMIT 1
+        `).get();
+        expect(billing).toEqual(expect.objectContaining({
+            entitlement_state: 'checkout_pending',
+            stripe_status: 'incomplete',
+            stripe_subscription_id: 'sub_123'
+        }));
+    });
+    it('preserves active access when Stripe reports an incomplete subscription for an already-active account', 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, 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, updated_by, created_at, updated_at
+            ) VALUES ('u1', 'default', 'pro-v1', 'active', ?, 'stripe-webhook', ?, ?)
+        `).run(now, now, now);
+        mockConstructEvent.mockReturnValue({
+            id: 'evt_incomplete_active_account',
+            type: 'customer.subscription.updated',
+            data: {
+                object: {
+                    id: 'sub_123',
+                    customer: 'cus_123',
+                    status: 'incomplete',
+                    trial_end: null,
+                    metadata: { planVersionId: 'pro-v1' },
+                    items: {
+                        data: [{
+                                current_period_end: Math.floor(Date.now() / 1000) + 86400,
+                                price: { id: 'price_pro_month', recurring: { interval: 'month' } }
+                            }]
+                    }
+                }
+            }
+        });
+        const req = createMockReq('{"id":"evt_incomplete_active_account"}', {
+            '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 entitlement_state, updated_by
+            FROM account_entitlements
+            WHERE account_id = 'u1' AND tenant_id = 'default'
+            LIMIT 1
+        `).get();
+        expect(entitlement).toEqual(expect.objectContaining({
+            entitlement_state: 'active',
+            updated_by: 'stripe-webhook'
+        }));
+        const billing = db.prepare(`
+            SELECT entitlement_state, stripe_status
+            FROM user_billing
+            WHERE user_id = 'u1' AND tenant_id = 'default'
+            LIMIT 1
+        `).get();
+        expect(billing).toEqual(expect.objectContaining({
+            entitlement_state: 'active',
+            stripe_status: 'incomplete'
+        }));
+    });
+    it('ignores superseded subscription webhook events for a stale checkout plan selection', 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', 'pro-v1', 'month', 'price_pro_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_123', 'checkout_pending', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO account_entitlements (
+                account_id, tenant_id, plan_version_id, entitlement_state, effective_at, effective_until, updated_by, created_at, updated_at
+            ) VALUES ('u1', 'default', 'team-v1', 'checkout_pending', ?, ?, 'checkout-start', ?, ?)
+        `).run(now, new Date(Date.now() + 60 * 60 * 1000).toISOString(), now, now);
+        mockConstructEvent.mockReturnValue({
+            id: 'evt_stale_checkout_superseded',
+            type: 'customer.subscription.updated',
+            data: {
+                object: {
+                    id: 'sub_123',
+                    customer: 'cus_123',
+                    status: 'active',
+                    trial_end: null,
+                    metadata: { planVersionId: 'pro-v1' },
+                    items: {
+                        data: [{
+                                current_period_end: Math.floor(Date.now() / 1000) + 86400,
+                                price: { id: 'price_pro_month', recurring: { interval: 'month' } }
+                            }]
+                    }
+                }
+            }
+        });
+        const req = createMockReq('{"id":"evt_stale_checkout_superseded"}', {
+            '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, entitlement_state
+            FROM account_entitlements
+            WHERE account_id = 'u1' AND tenant_id = 'default'
+            LIMIT 1
+        `).get();
+        expect(entitlement).toEqual(expect.objectContaining({
+            plan_version_id: 'team-v1',
+            entitlement_state: 'checkout_pending'
+        }));
+        const failure = db.prepare(`
+            SELECT reason
+            FROM stripe_webhook_failures
+            WHERE event_id = 'evt_stale_checkout_superseded'
+            ORDER BY created_at DESC
+            LIMIT 1
+        `).get();
+        expect(String(failure?.reason || '')).toContain('no longer current for this account');
+    });
+    it('ignores stale subscription webhooks for active accounts when a newer checkout attempt is open', 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 ('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', 'pro-v1', 'month', 'price_pro_month', 1, ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO user_billing (
+                user_id, tenant_id, stripe_customer_id, tier, entitlement_state, created_at, updated_at
+            ) VALUES ('u1', 'default', 'cus_123', 'starter', 'active', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO account_entitlements (
+                account_id, tenant_id, plan_version_id, entitlement_state, effective_at, updated_by, created_at, updated_at
+            ) VALUES ('u1', 'default', 'starter-v1', 'active', ?, 'free-plan-selection', ?, ?)
+        `).run(now, now, now);
+        db.prepare(`
+            INSERT INTO billing_checkout_attempts (
+                session_id, tenant_id, user_id, plan_version_id, billing_interval, status, expires_at, created_at, updated_at
+            ) VALUES ('cs_newer', 'default', 'u1', 'team-v1', 'month', 'open', ?, ?, ?)
+        `).run(new Date(Date.now() + 60 * 60 * 1000).toISOString(), now, now);
+        mockConstructEvent.mockReturnValue({
+            id: 'evt_active_stale_checkout',
+            type: 'customer.subscription.updated',
+            data: {
+                object: {
+                    id: 'sub_stale',
+                    customer: 'cus_123',
+                    status: 'active',
+                    trial_end: null,
+                    metadata: { planVersionId: 'pro-v1' },
+                    items: {
+                        data: [{
+                                current_period_end: Math.floor(Date.now() / 1000) + 86400,
+                                price: { id: 'price_pro_month', recurring: { interval: 'month' } }
+                            }]
+                    }
+                }
+            }
+        });
+        const req = createMockReq('{"id":"evt_active_stale_checkout"}', {
+            '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, entitlement_state
+            FROM account_entitlements
+            WHERE account_id = 'u1' AND tenant_id = 'default'
+            LIMIT 1
+        `).get();
+        expect(entitlement).toEqual(expect.objectContaining({
+            plan_version_id: 'starter-v1',
+            entitlement_state: 'active'
+        }));
+        const failure = db.prepare(`
+            SELECT reason
+            FROM stripe_webhook_failures
+            WHERE event_id = 'evt_active_stale_checkout'
+            ORDER BY created_at DESC
+            LIMIT 1
+        `).get();
+        expect(String(failure?.reason || '')).toContain('no longer current for this account');
+    });
     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();
@@ -558,7 +906,7 @@ describe('Billing Webhook Routes', () => {
         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 () => {
+    it('records checkout_pending when a blocked account starts a paid 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)
@@ -568,10 +916,11 @@ describe('Billing Webhook Routes', () => {
             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: [] });
+        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', 'pending_plan_selection', ?, ?, ?)
+        `).run(now, now, now);
         const checkoutHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session');
         const req = createMockReq(JSON.stringify({
             planVersionId: 'collab-v1',
@@ -583,10 +932,178 @@ describe('Billing Webhook Routes', () => {
         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();
-    });
+        expect(JSON.parse(res.body)).toEqual(expect.objectContaining({
+            checkoutState: 'checkout',
+            id: 'cs_test'
+        }));
+        const entitlement = db.prepare(`
+            SELECT plan_version_id, entitlement_state, updated_by
+            FROM account_entitlements
+            WHERE tenant_id = 'default' AND account_id = 'u1'
+            LIMIT 1
+        `).get();
+        expect(entitlement).toEqual(expect.objectContaining({
+            plan_version_id: 'collab-v1',
+            entitlement_state: 'checkout_pending',
+            updated_by: 'checkout-start'
+        }));
+        const billing = db.prepare(`
+            SELECT tier, entitlement_state, effective_until
+            FROM user_billing
+            WHERE tenant_id = 'default' AND user_id = 'u1'
+            LIMIT 1
+        `).get();
+        expect(billing).toEqual(expect.objectContaining({
+            tier: 'collab',
+            entitlement_state: 'checkout_pending'
+        }));
+        expect(typeof billing?.effective_until).toBe('string');
+    });
+    it('does not downgrade an active account to checkout_pending when starting paid 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 account_entitlements (
+                account_id, tenant_id, plan_version_id, entitlement_state, effective_at, updated_by, created_at, updated_at
+            ) VALUES ('u1', 'default', 'pro-v1', 'active', ?, 'stripe-webhook', ?, ?)
+        `).run(now, now, now);
+        db.prepare(`
+            INSERT INTO user_billing (
+                user_id, tenant_id, stripe_customer_id, tier, entitlement_state, created_at, updated_at
+            ) VALUES ('u1', 'default', 'cus_existing', 'pro', 'active', ?, ?)
+        `).run(now, now);
+        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);
+        const entitlement = db.prepare(`
+            SELECT plan_version_id, entitlement_state, updated_by
+            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',
+            updated_by: 'stripe-webhook'
+        }));
+        const billing = db.prepare(`
+            SELECT tier, entitlement_state
+            FROM user_billing
+            WHERE tenant_id = 'default' AND user_id = 'u1'
+            LIMIT 1
+        `).get();
+        expect(billing).toEqual(expect.objectContaining({
+            tier: 'pro',
+            entitlement_state: 'active'
+        }));
+    });
+    it('supersedes a stale checkout_pending selection when the user retries paid checkout', async () => {
+        const now = new Date().toISOString();
+        const previousExpiry = new Date(Date.now() - (60 * 60 * 1000)).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 account_entitlements (
+                account_id, tenant_id, plan_version_id, entitlement_state, effective_at, effective_until, updated_by, created_at, updated_at
+            ) VALUES ('u1', 'default', 'pro-v1', 'checkout_pending', ?, ?, 'checkout-start', ?, ?)
+        `).run(now, previousExpiry, now, now);
+        db.prepare(`
+            INSERT INTO user_billing (
+                user_id, tenant_id, tier, entitlement_state, effective_until, created_at, updated_at
+            ) VALUES ('u1', 'default', 'pro', 'checkout_pending', ?, ?, ?)
+        `).run(previousExpiry, now, now);
+        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);
+        const entitlement = db.prepare(`
+            SELECT plan_version_id, entitlement_state, effective_until
+            FROM account_entitlements
+            WHERE tenant_id = 'default' AND account_id = 'u1'
+            LIMIT 1
+        `).get();
+        expect(entitlement).toEqual(expect.objectContaining({
+            plan_version_id: 'team-v1',
+            entitlement_state: 'checkout_pending'
+        }));
+        expect(entitlement?.effective_until).not.toBe(previousExpiry);
+        const billing = db.prepare(`
+            SELECT tier, entitlement_state, effective_until
+            FROM user_billing
+            WHERE tenant_id = 'default' AND user_id = 'u1'
+            LIMIT 1
+        `).get();
+        expect(billing).toEqual(expect.objectContaining({
+            tier: 'team',
+            entitlement_state: 'checkout_pending'
+        }));
+        expect(billing?.effective_until).not.toBe(previousExpiry);
+    });
+    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(`
@@ -1063,6 +1580,282 @@ describe('Billing Webhook Routes', () => {
             entitlement_state: 'active'
         }));
     });
+    it('does not activate entitlement when the checkout session is still incomplete', 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 account_entitlements (
+                account_id, tenant_id, plan_version_id, entitlement_state, effective_at, updated_by, created_at, updated_at
+            ) VALUES ('u1', 'default', 'pro-v1', 'checkout_pending', ?, 'checkout-start', ?, ?)
+        `).run(now, now, now);
+        mockCheckoutRetrieve.mockResolvedValueOnce({
+            id: 'cs_open_123',
+            mode: 'subscription',
+            status: 'open',
+            payment_status: 'unpaid',
+            customer: 'cus_123',
+            subscription: 'sub_123',
+            metadata: { userId: 'u1' }
+        });
+        const confirmHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session/confirm');
+        const req = createMockReq(JSON.stringify({
+            sessionId: 'cs_open_123'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const res = createMockRes();
+        await confirmHandler(req, res, {});
+        expect(res.statusCode).toBe(409);
+        expect(JSON.parse(res.body)).toEqual({
+            error: 'Checkout session has not completed yet.',
+            code: 'CHECKOUT_SESSION_INCOMPLETE'
+        });
+        expect(mockSubscriptionRetrieve).not.toHaveBeenCalledWith('sub_123');
+        const entitlement = db.prepare(`
+            SELECT plan_version_id, entitlement_state, updated_by
+            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: 'checkout_pending',
+            updated_by: 'checkout-start'
+        }));
+    });
+    it('rejects checkout confirmation when a newer pending checkout superseded the session 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 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', 'pro-v1', 'month', 'price_pro_month', 1, ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO account_entitlements (
+                account_id, tenant_id, plan_version_id, entitlement_state, effective_at, effective_until, updated_by, created_at, updated_at
+            ) VALUES ('u1', 'default', 'team-v1', 'checkout_pending', ?, ?, 'checkout-start', ?, ?)
+        `).run(now, new Date(Date.now() + 60 * 60 * 1000).toISOString(), now, now);
+        const confirmHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session/confirm');
+        const req = createMockReq(JSON.stringify({
+            sessionId: 'cs_stale_123'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const res = createMockRes();
+        await confirmHandler(req, res, {});
+        expect(res.statusCode).toBe(409);
+        expect(JSON.parse(res.body)).toEqual({
+            error: 'This checkout session is no longer current for this account.',
+            code: 'CHECKOUT_SESSION_SUPERSEDED'
+        });
+        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: 'team-v1',
+            entitlement_state: 'checkout_pending'
+        }));
+    });
+    it('records the latest active-account checkout attempt and rejects confirmation for a superseded 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 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', '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', 'team-v1', 'month', 'price_team_month', 1, ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO user_billing (
+                user_id, tenant_id, tier, entitlement_state, created_at, updated_at
+            ) VALUES ('u1', 'default', 'starter', 'active', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO account_entitlements (
+                account_id, tenant_id, plan_version_id, entitlement_state, effective_at, updated_by, created_at, updated_at
+            ) VALUES ('u1', 'default', 'starter-v1', 'active', ?, 'free-plan-selection', ?, ?)
+        `).run(now, now, now);
+        mockCheckoutCreate
+            .mockResolvedValueOnce({
+            id: 'cs_old',
+            url: 'https://example.test/checkout/old',
+            expires_at: Math.floor(Date.now() / 1000) + (24 * 60 * 60)
+        })
+            .mockResolvedValueOnce({
+            id: 'cs_new',
+            url: 'https://example.test/checkout/new',
+            expires_at: Math.floor(Date.now() / 1000) + (24 * 60 * 60)
+        });
+        const checkoutHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session');
+        const firstReq = createMockReq(JSON.stringify({
+            planVersionId: 'pro-v1',
+            interval: 'month'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const firstRes = createMockRes();
+        await checkoutHandler(firstReq, firstRes, {});
+        expect(firstRes.statusCode).toBe(200);
+        const secondReq = createMockReq(JSON.stringify({
+            planVersionId: 'team-v1',
+            interval: 'month'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const secondRes = createMockRes();
+        await checkoutHandler(secondReq, secondRes, {});
+        expect(secondRes.statusCode).toBe(200);
+        const attempts = db.prepare(`
+            SELECT session_id, plan_version_id, status
+            FROM billing_checkout_attempts
+            WHERE tenant_id = 'default' AND user_id = 'u1'
+            ORDER BY session_id ASC
+        `).all();
+        expect(attempts).toEqual([
+            { session_id: 'cs_new', plan_version_id: 'team-v1', status: 'open' },
+            { session_id: 'cs_old', plan_version_id: 'pro-v1', status: 'superseded' }
+        ]);
+        mockCheckoutRetrieve.mockResolvedValueOnce({
+            id: 'cs_old',
+            mode: 'subscription',
+            status: 'complete',
+            payment_status: 'paid',
+            customer: 'cus_123',
+            subscription: 'sub_old',
+            metadata: { userId: 'u1', planVersionId: 'pro-v1' }
+        });
+        mockSubscriptionRetrieve.mockResolvedValueOnce({
+            id: 'sub_old',
+            customer: 'cus_123',
+            status: 'active',
+            trial_end: null,
+            metadata: { userId: 'u1', planVersionId: 'pro-v1' },
+            items: {
+                data: [{
+                        id: 'si_old',
+                        current_period_end: Math.floor(Date.now() / 1000) + 86400,
+                        price: { id: 'price_pro_month', recurring: { interval: 'month' } }
+                    }]
+            }
+        });
+        const confirmHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session/confirm');
+        const confirmReq = createMockReq(JSON.stringify({
+            sessionId: 'cs_old'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const confirmRes = createMockRes();
+        await confirmHandler(confirmReq, confirmRes, {});
+        expect(confirmRes.statusCode).toBe(409);
+        expect(JSON.parse(confirmRes.body)).toEqual({
+            error: 'This checkout session is no longer current for this account.',
+            code: 'CHECKOUT_SESSION_SUPERSEDED'
+        });
+    });
+    it('ignores subscription webhooks for a stale subscription after a newer checkout already won', 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 ('team-v1', 'default', 'team', 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 ('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, tier, entitlement_state, created_at, updated_at
+            ) VALUES ('u1', 'default', 'cus_123', 'sub_current', 'team', 'active', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO account_entitlements (
+                account_id, tenant_id, plan_version_id, entitlement_state, effective_at, updated_by, created_at, updated_at
+            ) VALUES ('u1', 'default', 'team-v1', 'active', ?, 'checkout-confirm', ?, ?)
+        `).run(now, now, now);
+        mockConstructEvent.mockReturnValue({
+            id: 'evt_stale_subscription_after_confirm',
+            type: 'customer.subscription.updated',
+            data: {
+                object: {
+                    id: 'sub_old',
+                    customer: 'cus_123',
+                    status: 'active',
+                    trial_end: null,
+                    metadata: { planVersionId: 'pro-v1' },
+                    items: {
+                        data: [{
+                                current_period_end: Math.floor(Date.now() / 1000) + 86400,
+                                price: { id: 'price_pro_month', recurring: { interval: 'month' } }
+                            }]
+                    }
+                }
+            }
+        });
+        const req = createMockReq('{"id":"evt_stale_subscription_after_confirm"}', {
+            '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, entitlement_state
+            FROM account_entitlements
+            WHERE account_id = 'u1' AND tenant_id = 'default'
+            LIMIT 1
+        `).get();
+        expect(entitlement).toEqual(expect.objectContaining({
+            plan_version_id: 'team-v1',
+            entitlement_state: 'active'
+        }));
+        const failure = db.prepare(`
+            SELECT reason
+            FROM stripe_webhook_failures
+            WHERE event_id = 'evt_stale_subscription_after_confirm'
+            ORDER BY created_at DESC
+            LIMIT 1
+        `).get();
+        expect(String(failure?.reason || '')).toContain('no longer current for this account');
+    });
     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();
@@ -1092,6 +1885,49 @@ describe('Billing Webhook Routes', () => {
             reason: 'diagnostic-1'
         }));
     });
+    it('lists checkout attempt diagnostics for system admin and purges old terminal rows', async () => {
+        const now = new Date().toISOString();
+        const stale = new Date(Date.now() - 20 * 24 * 60 * 60 * 1000).toISOString();
+        db.prepare(`
+            INSERT INTO billing_checkout_attempts (
+                session_id, tenant_id, user_id, plan_version_id, billing_interval, status, expires_at, created_at, updated_at
+            ) VALUES ('cs_keep_open', 'default', 'u1', 'team-v1', 'month', 'open', ?, ?, ?)
+        `).run(new Date(Date.now() + 60 * 60 * 1000).toISOString(), now, now);
+        db.prepare(`
+            INSERT INTO billing_checkout_attempts (
+                session_id, tenant_id, user_id, plan_version_id, billing_interval, status, expires_at, created_at, updated_at
+            ) VALUES ('cs_purge_old', 'default', 'u1', 'pro-v1', 'month', 'superseded', ?, ?, ?)
+        `).run(stale, stale, stale);
+        db.prepare(`
+            INSERT INTO billing_checkout_attempts (
+                session_id, tenant_id, user_id, plan_version_id, billing_interval, status, expires_at, created_at, updated_at
+            ) VALUES ('cs_expire_now', 'default', 'u2', 'pro-v1', 'month', 'open', ?, ?, ?)
+        `).run(new Date(Date.now() - 60 * 1000).toISOString(), now, now);
+        const route = routeHandlers.get('GET /api/taskforce/admin/billing/checkout-attempts');
+        expect(route).toBeTypeOf('function');
+        const req = createMockReq('', {
+            'x-taskforce-runtime-mode': 'cloud'
+        });
+        req.url = '/api/taskforce/admin/billing/checkout-attempts?limit=10';
+        const res = createMockRes();
+        await route(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const payload = JSON.parse(res.body);
+        expect(payload.purgedTerminalRows).toBeGreaterThanOrEqual(1);
+        expect(payload.expiredRowsNormalized).toBeGreaterThanOrEqual(1);
+        expect(payload.openCount).toBe(1);
+        expect(payload.rows).toEqual(expect.arrayContaining([
+            expect.objectContaining({ session_id: 'cs_keep_open', status: 'open' }),
+            expect.objectContaining({ session_id: 'cs_expire_now', status: 'expired' })
+        ]));
+        const purged = db.prepare(`
+            SELECT session_id
+            FROM billing_checkout_attempts
+            WHERE session_id = 'cs_purge_old'
+            LIMIT 1
+        `).get();
+        expect(purged).toBeUndefined();
+    });
     it('lists stripe price options filtered by interval for system admin', async () => {
         mockPricesList.mockResolvedValueOnce({
             data: [
@@ -1329,6 +2165,18 @@ describe('Billing Webhook Routes', () => {
         await route(req, res, {});
         expect(res.statusCode).toBe(403);
     });
+    it('rejects checkout attempt diagnostics for non-admin', async () => {
+        const nonAdminHandlers = buildBillingRouteHandlers(db, { isAdmin: false });
+        const route = nonAdminHandlers.get('GET /api/taskforce/admin/billing/checkout-attempts');
+        expect(route).toBeTypeOf('function');
+        const req = createMockReq('', {
+            'x-taskforce-runtime-mode': 'cloud'
+        });
+        req.url = '/api/taskforce/admin/billing/checkout-attempts';
+        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);
@@ -1433,7 +2281,94 @@ describe('Billing Webhook Routes', () => {
         expect(body.planVersionId).toBe('pro-v1');
         expect(body.entitlementState).toBe('active');
     });
-    it('reconciles stale entitlement from Stripe when billing status is requested', async () => {
+    it('prefers canonical checkout_pending state over stale billing mirror state in billing status payload', async () => {
+        routeHandlers = buildBillingRouteHandlers(db, {
+            accessStatus: {
+                gate: 'checkout_pending',
+                hasEntitlement: true,
+                canAccessApp: false,
+                canAccessPlans: true,
+                planSelectionRequired: false,
+                message: 'Complete checkout to continue.',
+                entitlement: {
+                    accountId: 'u1',
+                    planVersionId: 'pro-v1',
+                    planId: 'pro',
+                    state: 'checkout_pending',
+                    effectiveAt: null,
+                    effectiveUntil: null
+                }
+            }
+        });
+        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_pro_month', 'active', 'starter', '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).toEqual(expect.objectContaining({
+            planId: 'pro',
+            planName: 'Pro Plan',
+            planVersionId: 'pro-v1',
+            entitlementState: 'checkout_pending',
+            gate: 'checkout_pending',
+            message: 'Complete checkout to continue.',
+            planSelectionRequired: false,
+            billingConflictCode: null,
+            stripeStatus: 'active',
+            stripeCustomerId: 'cus_123',
+            stripeSubscriptionId: 'sub_123'
+        }));
+    });
+    it('returns checkout conflict code in billing status when the latest attempt expired', async () => {
+        routeHandlers = buildBillingRouteHandlers(db, {
+            accessStatus: {
+                gate: 'plan_selection_required',
+                hasEntitlement: true,
+                canAccessApp: false,
+                canAccessPlans: true,
+                planSelectionRequired: true,
+                message: 'Choose a plan to continue.',
+                entitlement: {
+                    accountId: 'u1',
+                    planVersionId: 'pro-v1',
+                    planId: 'pro',
+                    state: 'pending_plan_selection',
+                    effectiveAt: null,
+                    effectiveUntil: null
+                }
+            }
+        });
+        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 billing_checkout_attempts (
+                session_id, tenant_id, user_id, plan_version_id, billing_interval, status, expires_at, created_at, updated_at
+            ) VALUES ('cs_expired_status', 'default', 'u1', 'pro-v1', 'month', 'expired', ?, ?, ?)
+        `).run(new Date(Date.now() - 60 * 1000).toISOString(), 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);
+        const body = JSON.parse(res.body);
+        expect(body.billingConflictCode).toBe('CHECKOUT_SESSION_EXPIRED');
+    });
+    it('does not reconcile stale billing state from Stripe when billing status is requested', async () => {
         const now = new Date().toISOString();
         const stale = new Date(Date.now() - 60_000).toISOString();
         db.prepare(`
@@ -1456,21 +2391,19 @@ describe('Billing Webhook Routes', () => {
         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', ?, ?, ?)
+            ) VALUES ('u1', 'default', 'pro-v1', 'active', ?, ?, ?)
         `).run(stale, stale, stale);
         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');
+        expect(mockSubscriptionRetrieve).not.toHaveBeenCalled();
+        expect(mockCustomersList).not.toHaveBeenCalled();
+        expect(mockSubscriptionList).not.toHaveBeenCalled();
+        const body = JSON.parse(res.body);
+        expect(body.planVersionId).toBe('pro-v1');
+        expect(body.planName).toBe('Pro Plan');
     });
     it('skips Stripe reconciliation for fresh billing mirror rows when billing status is requested', async () => {
         const now = new Date().toISOString();
@@ -1501,7 +2434,7 @@ describe('Billing Webhook Routes', () => {
         expect(mockCustomersList).not.toHaveBeenCalled();
         expect(mockSubscriptionList).not.toHaveBeenCalled();
     });
-    it('repairs billing status from an active Stripe subscription discovered by account email', async () => {
+    it('does not discover Stripe subscriptions by account email 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)
@@ -1539,11 +2472,13 @@ describe('Billing Webhook Routes', () => {
         const res = createMockRes();
         await statusRoute(req, res, {});
         expect(res.statusCode).toBe(200);
+        expect(mockCustomersList).not.toHaveBeenCalled();
+        expect(mockSubscriptionList).not.toHaveBeenCalled();
         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');
+        expect(body.stripeCustomerId).toBeNull();
+        expect(body.stripeSubscriptionId).toBeNull();
     });
     it('prefers subscription metadata over shared price fallback during webhook processing', async () => {
         const now = new Date().toISOString();