@taskforcehq/taskforce 0.3.302 → 0.3.303

package/dist/server/routes/billing.js

@@ -6,6 +6,7 @@ const BILLING_CONFIG_KEY_PLAN = 'billing.config.v1';
 const PRICE_METADATA_PLAN_VERSION = 'taskforce_plan_version_id';
 const BILLING_DIAGNOSTIC_RETENTION_DAYS = 30;
 const BILLING_DIAGNOSTIC_MAX_PAYLOAD_BYTES = 8 * 1024;
+const BILLING_CHECKOUT_ATTEMPT_RETENTION_DAYS = 14;
 const BILLING_STATUS_RECONCILIATION_TTL_MS = 30_000;
 const TASKFORCE_PROXY_ORIGIN_HOST_HEADER = 'x-taskforce-origin-host';
 const TASKFORCE_PROXY_ORIGIN_PROTO_HEADER = 'x-taskforce-origin-proto';
@@ -26,6 +27,15 @@ function isoFromUnixSeconds(raw) {
         return null;
     return new Date(Math.floor(value) * 1000).toISOString();
 }
+function isIsoTimestampExpired(valueRaw) {
+    const value = String(valueRaw || '').trim();
+    if (!value)
+        return false;
+    const timestamp = Date.parse(value);
+    if (!Number.isFinite(timestamp))
+        return false;
+    return timestamp <= Date.now();
+}
 function parseInterval(raw) {
     const value = String(raw || '').trim().toLowerCase();
     if (value === 'month' || value === 'year')
@@ -230,6 +240,8 @@ function mapStripeStatusToCanonicalState(statusRaw) {
         return 'active';
     if (status === 'past_due')
         return 'grace';
+    if (status === 'incomplete')
+        return 'checkout_pending';
     return 'canceled';
 }
 function isMissingStripeCustomerError(error) {
@@ -474,14 +486,304 @@ function getEntitlementRow(core, userIdRaw) {
     const db = core.getDatabaseAdapter();
     const tenantId = core.getTenantId();
     const row = db.prepare(`
-        SELECT account_id, plan_version_id, entitlement_state
+        SELECT account_id, plan_version_id, entitlement_state, effective_until, updated_by
         FROM account_entitlements
         WHERE tenant_id = ? AND account_id = ?
         LIMIT 1
     `).get(tenantId, userId);
     return row || null;
 }
+function updateCheckoutAttemptStatus(core, sessionIdRaw, status) {
+    const sessionId = String(sessionIdRaw || '').trim();
+    if (!sessionId)
+        return;
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    db.prepare(`
+        UPDATE billing_checkout_attempts
+        SET status = ?, updated_at = ?
+        WHERE tenant_id = ? AND session_id = ?
+    `).run(status, new Date().toISOString(), tenantId, sessionId);
+}
+function expireOpenCheckoutAttempts(core) {
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const now = new Date().toISOString();
+    const result = db.prepare(`
+        UPDATE billing_checkout_attempts
+        SET status = 'expired', updated_at = ?
+        WHERE tenant_id = ?
+          AND status = 'open'
+          AND expires_at IS NOT NULL
+          AND expires_at <> ''
+          AND expires_at <= ?
+    `).run(now, tenantId, now);
+    return Number(result?.changes || 0);
+}
+function purgeTerminalCheckoutAttempts(core) {
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const cutoff = new Date(Date.now() - BILLING_CHECKOUT_ATTEMPT_RETENTION_DAYS * 24 * 60 * 60 * 1000).toISOString();
+    const result = db.prepare(`
+        DELETE FROM billing_checkout_attempts
+        WHERE tenant_id = ?
+          AND status IN ('confirmed', 'superseded', 'expired')
+          AND updated_at <= ?
+    `).run(tenantId, cutoff);
+    return Number(result?.changes || 0);
+}
+function maintainCheckoutAttempts(core) {
+    const expiredRows = expireOpenCheckoutAttempts(core);
+    const purgedRows = purgeTerminalCheckoutAttempts(core);
+    return { expiredRows, purgedRows };
+}
+function normalizeCheckoutAttemptRow(core, row) {
+    if (!row)
+        return null;
+    const sessionId = String(row.session_id || '').trim();
+    const status = String(row.status || '').trim().toLowerCase();
+    if (!sessionId || status !== 'open' || !isIsoTimestampExpired(row.expires_at)) {
+        return row;
+    }
+    updateCheckoutAttemptStatus(core, sessionId, 'expired');
+    return {
+        ...row,
+        status: 'expired',
+        updated_at: new Date().toISOString()
+    };
+}
+function getCheckoutAttemptRow(core, sessionIdRaw) {
+    const sessionId = String(sessionIdRaw || '').trim();
+    if (!sessionId)
+        return null;
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const row = db.prepare(`
+        SELECT session_id, user_id, plan_version_id, billing_interval, status, expires_at, created_at, updated_at
+        FROM billing_checkout_attempts
+        WHERE tenant_id = ? AND session_id = ?
+        LIMIT 1
+    `).get(tenantId, sessionId);
+    return normalizeCheckoutAttemptRow(core, row || null);
+}
+function getCurrentOpenCheckoutAttemptForUser(core, userIdRaw) {
+    const userId = String(userIdRaw || '').trim();
+    if (!userId)
+        return null;
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const rows = db.prepare(`
+        SELECT session_id, user_id, plan_version_id, billing_interval, status, expires_at, created_at, updated_at
+        FROM billing_checkout_attempts
+        WHERE tenant_id = ? AND user_id = ? AND status = 'open'
+        ORDER BY created_at DESC, session_id DESC
+    `).all(tenantId, userId);
+    for (const row of rows) {
+        const normalized = normalizeCheckoutAttemptRow(core, row);
+        if (String(normalized?.status || '').trim().toLowerCase() === 'open') {
+            return normalized;
+        }
+    }
+    return null;
+}
+function getLatestCheckoutAttemptForUser(core, userIdRaw) {
+    const userId = String(userIdRaw || '').trim();
+    if (!userId)
+        return null;
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const row = db.prepare(`
+        SELECT session_id, user_id, plan_version_id, billing_interval, status, expires_at, created_at, updated_at
+        FROM billing_checkout_attempts
+        WHERE tenant_id = ? AND user_id = ?
+        ORDER BY created_at DESC, session_id DESC
+        LIMIT 1
+    `).get(tenantId, userId);
+    return normalizeCheckoutAttemptRow(core, row || null);
+}
+function resolveBillingConflictCode(core, input) {
+    const gate = String(input.gate || '').trim().toLowerCase();
+    if (!gate || gate === 'ok')
+        return null;
+    const latestAttempt = getLatestCheckoutAttemptForUser(core, input.userId);
+    const attemptStatus = String(latestAttempt?.status || '').trim().toLowerCase();
+    if (attemptStatus === 'expired')
+        return 'CHECKOUT_SESSION_EXPIRED';
+    if (attemptStatus === 'superseded')
+        return 'CHECKOUT_SESSION_SUPERSEDED';
+    return null;
+}
+function markLatestOpenCheckoutAttemptConfirmed(core, input) {
+    const planVersionId = String(input.planVersionId || '').trim();
+    if (!planVersionId)
+        return;
+    const currentAttempt = getCurrentOpenCheckoutAttemptForUser(core, input.userId);
+    if (!currentAttempt)
+        return;
+    const currentPlanVersionId = String(currentAttempt.plan_version_id || '').trim();
+    const sessionId = String(currentAttempt.session_id || '').trim();
+    if (!sessionId || currentPlanVersionId !== planVersionId)
+        return;
+    updateCheckoutAttemptStatus(core, sessionId, 'confirmed');
+}
+function recordCheckoutAttempt(core, input) {
+    const sessionId = String(input.sessionId || '').trim();
+    const userId = String(input.userId || '').trim();
+    const planVersionId = String(input.planVersionId || '').trim();
+    const billingInterval = parseInterval(input.billingInterval);
+    if (!sessionId || !userId || !planVersionId || !billingInterval)
+        return;
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const now = new Date().toISOString();
+    const tx = db.transaction(() => {
+        db.prepare(`
+            UPDATE billing_checkout_attempts
+            SET status = 'superseded', updated_at = ?
+            WHERE tenant_id = ? AND user_id = ? AND status = 'open' AND session_id <> ?
+        `).run(now, tenantId, userId, sessionId);
+        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 (?, ?, ?, ?, ?, 'open', ?, ?, ?)
+            ON CONFLICT (session_id) DO UPDATE SET
+                user_id = excluded.user_id,
+                plan_version_id = excluded.plan_version_id,
+                billing_interval = excluded.billing_interval,
+                status = 'open',
+                expires_at = excluded.expires_at,
+                updated_at = excluded.updated_at
+        `).run(sessionId, tenantId, userId, planVersionId, billingInterval, input.expiresAt || null, now, now);
+    });
+    tx();
+}
+function resolveCheckoutLifecycleGuard(core, input) {
+    const currentOpenAttempt = getCurrentOpenCheckoutAttemptForUser(core, input.userId);
+    const checkoutAttempt = input.sessionId
+        ? getCheckoutAttemptRow(core, input.sessionId)
+        : currentOpenAttempt;
+    const attemptStatus = String(checkoutAttempt?.status || '').trim().toLowerCase();
+    const attemptPlanVersionId = String(checkoutAttempt?.plan_version_id || '').trim();
+    if (attemptStatus === 'expired') {
+        return {
+            blocked: true,
+            code: 'CHECKOUT_SESSION_EXPIRED',
+            message: 'This checkout session expired. Choose a plan and start checkout again.'
+        };
+    }
+    if (attemptStatus === 'superseded') {
+        return {
+            blocked: true,
+            code: 'CHECKOUT_SESSION_SUPERSEDED',
+            message: 'This checkout session is no longer current for this account.'
+        };
+    }
+    if (attemptStatus === 'open' && attemptPlanVersionId && input.planVersionId && attemptPlanVersionId !== input.planVersionId) {
+        return {
+            blocked: true,
+            code: 'CHECKOUT_SESSION_SUPERSEDED',
+            message: 'This checkout session is no longer current for this account.'
+        };
+    }
+    const currentBilling = getBillingMirrorRow(core, input.userId);
+    const currentSubscriptionId = String(currentBilling?.stripe_subscription_id || '').trim();
+    if (!currentOpenAttempt && input.subscriptionId && currentSubscriptionId && currentSubscriptionId !== input.subscriptionId) {
+        return {
+            blocked: true,
+            code: 'CHECKOUT_SESSION_SUPERSEDED',
+            message: 'This checkout session is no longer current for this account.'
+        };
+    }
+    const entitlement = getEntitlementRow(core, input.userId);
+    if (!entitlement)
+        return { blocked: false };
+    const currentState = String(entitlement.entitlement_state || '').trim().toLowerCase();
+    const currentPlanVersionId = String(entitlement.plan_version_id || '').trim();
+    const updatedBy = String(entitlement.updated_by || '').trim().toLowerCase();
+    const expiredPendingCheckout = currentState === 'checkout_pending' && isIsoTimestampExpired(entitlement.effective_until);
+    if (expiredPendingCheckout || (currentState === 'pending_plan_selection' && updatedBy === 'checkout-expired')) {
+        return {
+            blocked: true,
+            code: 'CHECKOUT_SESSION_EXPIRED',
+            message: 'This checkout session expired. Choose a plan and start checkout again.'
+        };
+    }
+    if (currentState === 'checkout_pending'
+        && currentPlanVersionId
+        && input.planVersionId
+        && currentPlanVersionId !== input.planVersionId) {
+        return {
+            blocked: true,
+            code: 'CHECKOUT_SESSION_SUPERSEDED',
+            message: 'This checkout session is no longer current for this account.'
+        };
+    }
+    return { blocked: false };
+}
+function isCommercialStateAppAccessible(stateRaw) {
+    const state = String(stateRaw || '').trim().toLowerCase();
+    return state === 'active' || state === 'trialing' || state === 'grace';
+}
+function shouldRecordCheckoutPendingState(entitlement) {
+    if (!entitlement)
+        return true;
+    const currentState = String(entitlement.entitlement_state || '').trim().toLowerCase();
+    return currentState === 'pending_plan_selection'
+        || currentState === 'checkout_pending'
+        || currentState === 'canceled';
+}
+function beginCheckoutPending(core, input) {
+    const planId = resolvePlanIdForVersion(core, input.planVersionId);
+    const updatedBy = input.updatedBy || 'checkout-start';
+    const source = input.source || 'checkout-start';
+    if (typeof core.transitionCanonicalCommercialState === 'function') {
+        core.transitionCanonicalCommercialState({
+            accountId: input.userId,
+            planVersionId: input.planVersionId,
+            state: 'checkout_pending',
+            effectiveUntil: input.effectiveUntil || null,
+            billingMirrorPlanId: planId,
+            source,
+            updatedBy
+        });
+        return;
+    }
+    const db = core.getDatabaseAdapter();
+    const tenantId = core.getTenantId();
+    const now = new Date().toISOString();
+    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.userId, tenantId, input.planVersionId, 'checkout_pending', now, input.effectiveUntil || null, updatedBy, now, now);
+    upsertBillingMirror(core, {
+        userId: input.userId,
+        planId,
+        canonicalState: 'checkout_pending',
+        effectiveUntil: input.effectiveUntil || null
+    });
+}
 function upsertCanonicalEntitlement(core, input) {
+    const updatedBy = input.updatedBy || 'stripe-webhook';
+    if (typeof core.transitionCanonicalCommercialState === 'function') {
+        core.transitionCanonicalCommercialState({
+            accountId: input.userId,
+            planVersionId: input.planVersionId,
+            state: input.state,
+            effectiveAt: input.effectiveAt,
+            effectiveUntil: input.effectiveUntil,
+            billingMirrorPlanId: resolvePlanIdForVersion(core, input.planVersionId),
+            source: updatedBy === 'checkout-confirm' ? 'checkout-confirm' : 'stripe-webhook',
+            updatedBy
+        });
+        return;
+    }
     const db = core.getDatabaseAdapter();
     const tenantId = core.getTenantId();
     const now = new Date().toISOString();
@@ -495,7 +797,7 @@ function upsertCanonicalEntitlement(core, input) {
             effective_until = excluded.effective_until,
             updated_by = excluded.updated_by,
             updated_at = excluded.updated_at
-    `).run(input.userId, tenantId, input.planVersionId, input.state, input.effectiveAt || now, input.effectiveUntil || null, input.updatedBy || 'stripe-webhook', now, now);
+    `).run(input.userId, tenantId, input.planVersionId, input.state, input.effectiveAt || now, input.effectiveUntil || null, updatedBy, now, now);
 }
 function upsertBillingMirror(core, input) {
     const db = core.getDatabaseAdapter();
@@ -546,7 +848,12 @@ function applySubscriptionSnapshot(core, input) {
     const canceledState = stripeStatus === 'canceled'
         ? (currentPeriodEnd && currentPeriodEnd > nowIso ? 'active' : 'canceled')
         : null;
-    const canonicalState = canceledState || mapStripeStatusToCanonicalState(stripeStatus);
+    const mappedCanonicalState = canceledState || mapStripeStatusToCanonicalState(stripeStatus);
+    const preserveExistingAccess = mappedCanonicalState === 'checkout_pending'
+        && isCommercialStateAppAccessible(existingEntitlement?.entitlement_state);
+    const canonicalState = preserveExistingAccess
+        ? String(existingEntitlement?.entitlement_state || 'active').trim().toLowerCase()
+        : mappedCanonicalState;
     const effectiveUntil = stripeStatus === 'canceled'
         ? currentPeriodEnd
         : (currentPeriodEnd || null);
@@ -563,7 +870,17 @@ function applySubscriptionSnapshot(core, input) {
         currentPeriodEnd,
         effectiveUntil
     });
-    if (planVersionId) {
+    if (planVersionId && canonicalState === 'checkout_pending') {
+        if (shouldRecordCheckoutPendingState(existingEntitlement)) {
+            beginCheckoutPending(core, {
+                userId,
+                planVersionId,
+                source,
+                updatedBy: source
+            });
+        }
+    }
+    else if (planVersionId) {
         upsertCanonicalEntitlement(core, {
             userId,
             planVersionId: planVersionId || existingEntitlement?.plan_version_id || core.getDefaultPlanVersionIdByMode('personal', { allowFallback: true }),
@@ -934,12 +1251,23 @@ export function registerBillingRoutes(deps) {
             return;
         }
         try {
+            maintainCheckoutAttempts(core);
             const userId = requestUserId(req);
             const db = core.getDatabaseAdapter();
             const tenantId = core.getTenantId();
-            const billingReconciliation = await reconcileBillingMirrorIfNeeded(core, userId);
-            const row = billingReconciliation.row;
+            const row = getBillingMirrorRow(core, userId);
             const access = core.getAccountAccessStatus(userId);
+            const billingConflictCode = resolveBillingConflictCode(core, {
+                userId,
+                gate: String(access.gate || '')
+            });
+            const resolvedPlanId = String(access.entitlement?.planId || row?.tier || '').trim() || null;
+            const planRow = resolvedPlanId ? db.prepare(`
+                SELECT display_name
+                FROM plan_catalog
+                WHERE tenant_id = ? AND plan_id = ?
+                LIMIT 1
+            `).get(tenantId, resolvedPlanId) : undefined;
             if (!access.hasEntitlement || !access.entitlement) {
                 res.writeHead(200, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({
@@ -951,24 +1279,18 @@ export function registerBillingRoutes(deps) {
                     trialEnd: row?.trial_end || null,
                     currentPeriodEnd: row?.current_period_end || null,
                     effectiveUntil: row?.effective_until || null,
-                    entitlementState: null,
+                    entitlementState: row?.entitlement_state || null,
                     planVersionId: null,
-                    planId: null,
-                    planName: null,
+                    planId: resolvedPlanId,
+                    planName: planRow?.display_name ? String(planRow.display_name) : resolvedPlanId,
                     gate: access.gate,
                     message: access.message,
                     planSelectionRequired: access.planSelectionRequired,
-                    billingConflictCode: billingReconciliation.conflictCode
+                    billingConflictCode
                 }));
                 return;
             }
             const entitlement = access.entitlement;
-            const planRow = db.prepare(`
-                SELECT display_name
-                FROM plan_catalog
-                WHERE tenant_id = ? AND plan_id = ?
-                LIMIT 1
-            `).get(tenantId, entitlement.planId);
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({
                 stripeStatus: row?.stripe_status || null,
@@ -986,7 +1308,7 @@ export function registerBillingRoutes(deps) {
                 gate: access.gate,
                 message: access.message,
                 planSelectionRequired: access.planSelectionRequired,
-                billingConflictCode: billingReconciliation.conflictCode
+                billingConflictCode
             }));
         }
         catch (error) {
@@ -1290,6 +1612,68 @@ export function registerBillingRoutes(deps) {
             rows
         }));
     });
+    addRoute('GET', '/api/taskforce/admin/billing/checkout-attempts', async (req, res) => {
+        if (!ensureCloudBilling(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const db = core.getDatabaseAdapter();
+        const tenantId = core.getTenantId();
+        const requestUrl = parseRequestUrl(req);
+        const limit = parsePositiveIntBounded(requestUrl.searchParams.get('limit'), 50, 1, 200);
+        const filterUserId = String(requestUrl.searchParams.get('userId') || '').trim();
+        const now = new Date().toISOString();
+        const maintenance = maintainCheckoutAttempts(core);
+        const rows = filterUserId
+            ? db.prepare(`
+                SELECT session_id, user_id, plan_version_id, billing_interval, status, expires_at, created_at, updated_at
+                FROM billing_checkout_attempts
+                WHERE tenant_id = ? AND user_id = ?
+                ORDER BY created_at DESC, session_id DESC
+                LIMIT ?
+            `).all(tenantId, filterUserId, limit)
+            : db.prepare(`
+                SELECT session_id, user_id, plan_version_id, billing_interval, status, expires_at, created_at, updated_at
+                FROM billing_checkout_attempts
+                WHERE tenant_id = ?
+                ORDER BY created_at DESC, session_id DESC
+                LIMIT ?
+            `).all(tenantId, limit);
+        const total = filterUserId
+            ? db.prepare(`
+                SELECT COUNT(*) AS count
+                FROM billing_checkout_attempts
+                WHERE tenant_id = ? AND user_id = ?
+            `).get(tenantId, filterUserId)
+            : db.prepare(`
+                SELECT COUNT(*) AS count
+                FROM billing_checkout_attempts
+                WHERE tenant_id = ?
+            `).get(tenantId);
+        const openCount = filterUserId
+            ? db.prepare(`
+                SELECT COUNT(*) AS count
+                FROM billing_checkout_attempts
+                WHERE tenant_id = ? AND user_id = ? AND status = 'open'
+            `).get(tenantId, filterUserId)
+            : db.prepare(`
+                SELECT COUNT(*) AS count
+                FROM billing_checkout_attempts
+                WHERE tenant_id = ? AND status = 'open'
+            `).get(tenantId);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            asOf: now,
+            expiredRowsNormalized: maintenance.expiredRows,
+            purgedTerminalRows: maintenance.purgedRows,
+            total: Number(total?.count || 0),
+            openCount: Number(openCount?.count || 0),
+            rows
+        }));
+    });
     addRoute('POST', '/api/taskforce/admin/billing/prices/import', async (req, res) => {
         if (!ensureCloudBilling(req, res))
             return;
@@ -1388,6 +1772,7 @@ export function registerBillingRoutes(deps) {
             return;
         }
         try {
+            maintainCheckoutAttempts(core);
             const userId = requestUserId(req);
             const currentBillingResult = await reconcileBillingMirrorIfNeeded(core, userId);
             const currentBilling = currentBillingResult.row;
@@ -1551,6 +1936,21 @@ export function registerBillingRoutes(deps) {
                     billingInterval: interval
                 }
             });
+            const checkoutEffectiveUntil = isoFromUnixSeconds(session.expires_at);
+            recordCheckoutAttempt(core, {
+                sessionId: session.id,
+                userId,
+                planVersionId,
+                billingInterval: interval,
+                expiresAt: checkoutEffectiveUntil
+            });
+            if (shouldRecordCheckoutPendingState(currentEntitlement) && !isCommercialStateAppAccessible(currentEntitlement?.entitlement_state)) {
+                beginCheckoutPending(core, {
+                    userId,
+                    planVersionId,
+                    effectiveUntil: checkoutEffectiveUntil
+                });
+            }
             const checkoutUrl = isMockStripeClient(stripe)
                 ? buildMockStripeHostedCheckoutUrl(resolveHostedServerBaseUrl(req), session.id)
                 : (session.url || null);
@@ -1592,11 +1992,30 @@ export function registerBillingRoutes(deps) {
             return;
         }
         try {
+            maintainCheckoutAttempts(core);
             const stripe = getStripeClient();
             const expectedUserId = requestUserId(req);
             const session = await stripe.checkout.sessions.retrieve(sessionId, {
                 expand: ['subscription']
             });
+            const sessionStatus = String(session.status || '').trim().toLowerCase();
+            const paymentStatus = String(session.payment_status || '').trim().toLowerCase();
+            if (session.mode !== 'subscription') {
+                res.writeHead(409, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    error: 'Checkout session is not a subscription checkout.',
+                    code: 'CHECKOUT_SESSION_INVALID_MODE'
+                }));
+                return;
+            }
+            if (sessionStatus !== 'complete' || (paymentStatus !== 'paid' && paymentStatus !== 'no_payment_required')) {
+                res.writeHead(409, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    error: 'Checkout session has not completed yet.',
+                    code: 'CHECKOUT_SESSION_INCOMPLETE'
+                }));
+                return;
+            }
             const metadata = session.metadata || {};
             const customerId = String(session.customer || '').trim();
             const subscriptionId = typeof session.subscription === 'string'
@@ -1615,22 +2034,47 @@ export function registerBillingRoutes(deps) {
                 res.end(JSON.stringify({ error: 'Checkout session does not belong to the current account.' }));
                 return;
             }
+            let resolvedPlanVersionId = null;
+            let subscription = null;
+            if (subscriptionId) {
+                subscription = typeof session.subscription === 'string' || !session.subscription
+                    ? await stripe.subscriptions.retrieve(subscriptionId)
+                    : session.subscription;
+                const priceId = String(subscription.items?.data?.[0]?.price?.id || '').trim();
+                resolvedPlanVersionId = resolvePlanVersionIdForBillingEvent(core, [
+                    subscription.metadata?.planVersionId,
+                    subscription.metadata?.plan_version_id,
+                    metadata.planVersionId,
+                    metadata.plan_version_id
+                ], priceId).planVersionId;
+                const lifecycleGuard = resolveCheckoutLifecycleGuard(core, {
+                    userId: resolvedUserId,
+                    planVersionId: resolvedPlanVersionId,
+                    sessionId,
+                    subscriptionId
+                });
+                if (lifecycleGuard.blocked) {
+                    res.writeHead(409, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({
+                        error: lifecycleGuard.message,
+                        code: lifecycleGuard.code
+                    }));
+                    return;
+                }
+            }
             core.createUserBillingRecord(resolvedUserId);
             upsertBillingMirror(core, {
                 userId: resolvedUserId,
                 stripeCustomerId: customerId || null,
                 stripeSubscriptionId: subscriptionId || null
             });
-            let resolvedPlanVersionId = null;
-            if (session.mode === 'subscription' && subscriptionId) {
-                const subscription = typeof session.subscription === 'string' || !session.subscription
-                    ? await stripe.subscriptions.retrieve(subscriptionId)
-                    : session.subscription;
+            if (subscription) {
                 resolvedPlanVersionId = applySubscriptionSnapshot(core, {
                     userId: resolvedUserId,
                     subscription,
                     source: 'checkout-confirm'
                 }).planVersionId;
+                updateCheckoutAttemptStatus(core, sessionId, 'confirmed');
             }
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({
@@ -1801,6 +2245,7 @@ export function registerBillingRoutes(deps) {
             const db = core.getDatabaseAdapter();
             const tenantId = core.getTenantId();
             purgeExpiredWebhookFailures(core);
+            maintainCheckoutAttempts(core);
             let duplicate = false;
             const tx = db.transaction(() => {
                 const acquired = lockWebhookEvent(core, event);
@@ -1853,11 +2298,31 @@ export function registerBillingRoutes(deps) {
                         });
                         return;
                     }
-                    applySubscriptionSnapshot(core, {
+                    const lifecycleGuard = resolveCheckoutLifecycleGuard(core, {
+                        userId,
+                        planVersionId,
+                        subscriptionId: String(subscription.id || '').trim()
+                    });
+                    if (lifecycleGuard.blocked) {
+                        recordWebhookFailure(core, {
+                            eventId: event.id,
+                            eventType: event.type,
+                            reason: lifecycleGuard.message,
+                            payload: event
+                        });
+                        return;
+                    }
+                    const snapshot = applySubscriptionSnapshot(core, {
                         userId,
                         subscription,
                         source: 'stripe-webhook'
                     });
+                    if (snapshot.canonicalState !== 'checkout_pending') {
+                        markLatestOpenCheckoutAttemptConfirmed(core, {
+                            userId,
+                            planVersionId: snapshot.planVersionId
+                        });
+                    }
                     return;
                 }
                 if (event.type === 'invoice.paid' || event.type === 'invoice.payment_failed') {
@@ -1878,6 +2343,20 @@ export function registerBillingRoutes(deps) {
                         invoice.subscription_details?.metadata?.plan_version_id
                     ], priceId);
                     const planVersionId = planVersionResolution.planVersionId;
+                    const lifecycleGuard = resolveCheckoutLifecycleGuard(core, {
+                        userId,
+                        planVersionId,
+                        subscriptionId
+                    });
+                    if (lifecycleGuard.blocked) {
+                        recordWebhookFailure(core, {
+                            eventId: event.id,
+                            eventType: event.type,
+                            reason: lifecycleGuard.message,
+                            payload: event
+                        });
+                        return;
+                    }
                     const existingEntitlement = getEntitlementRow(core, userId);
                     const canonicalState = event.type === 'invoice.payment_failed' ? 'grace' : 'active';
                     const currentPeriodEnd = invoice.lines?.data?.[0]?.period?.end
@@ -1913,6 +2392,10 @@ export function registerBillingRoutes(deps) {
                         effectiveAt: new Date().toISOString(),
                         effectiveUntil: currentPeriodEnd
                     });
+                    markLatestOpenCheckoutAttemptConfirmed(core, {
+                        userId,
+                        planVersionId
+                    });
                     return;
                 }
             });