@taskforcehq/taskforce 0.3.303 → 0.3.305

package/dist/server/routes/authSupport.js

@@ -0,0 +1,81 @@
+import { resolveEffectiveEmailConfig } from '../email.js';
+import { resolveDeploymentConfig } from '../../config/deployment.js';
+export function resolveBooleanSetting(value, fallback) {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number')
+        return value !== 0;
+    const normalized = String(value || '').trim().toLowerCase();
+    if (!normalized)
+        return fallback;
+    if (['1', 'true', 'yes', 'on'].includes(normalized))
+        return true;
+    if (['0', 'false', 'no', 'off'].includes(normalized))
+        return false;
+    return fallback;
+}
+export function getRouteEmailConfig(core, context) {
+    if (context.authConfig?.runtimeMode !== 'cloud') {
+        return resolveEffectiveEmailConfig(process.env, { provider: 'console' });
+    }
+    const globalSettings = core.getGlobalSettings();
+    return resolveEffectiveEmailConfig(process.env, globalSettings.email || null);
+}
+export function buildAuthFlowBehavior(core) {
+    const globalSettings = core.getGlobalSettings();
+    const authSettings = globalSettings.auth || {};
+    const authRateLimitMaxRequestsRaw = Number(authSettings.authRateLimitMaxRequests);
+    const authRateLimitWindowMsRaw = Number(authSettings.authRateLimitWindowMs);
+    return {
+        allowSelfRegistration: resolveBooleanSetting(authSettings.allowSelfRegistration, true),
+        requireVerifiedEmail: resolveBooleanSetting(authSettings.requireVerifiedEmail, true),
+        defaultNewUserBetaAccess: resolveBooleanSetting(authSettings.defaultNewUserBetaAccess, false),
+        authRateLimitEnabled: resolveBooleanSetting(authSettings.authRateLimitEnabled, true),
+        authRateLimitMaxRequests: Number.isFinite(authRateLimitMaxRequestsRaw) && authRateLimitMaxRequestsRaw >= 1
+            ? Math.floor(authRateLimitMaxRequestsRaw)
+            : 10,
+        authRateLimitWindowMs: Number.isFinite(authRateLimitWindowMsRaw) && authRateLimitWindowMsRaw >= 1000
+            ? Math.floor(authRateLimitWindowMsRaw)
+            : 15 * 60_000,
+    };
+}
+export function buildAuthBehavior(core) {
+    const authBehavior = buildAuthFlowBehavior(core);
+    const onboardingPolicy = core.getOnboardingPolicy();
+    return {
+        ...authBehavior,
+        onboardingPolicyMode: onboardingPolicy.mode,
+        onboardingPlanVersionId: onboardingPolicy.planVersionId
+    };
+}
+export function buildSiteBehavior(core) {
+    const globalSettings = core.getGlobalSettings();
+    const siteSettings = globalSettings.site || {};
+    return {
+        showRunTaskforceLocally: resolveBooleanSetting(siteSettings.showRunTaskforceLocally, true),
+        pricingPageEnabled: resolveBooleanSetting(siteSettings.pricingPageEnabled, true)
+    };
+}
+export function shouldExposeDevAuthTokens() {
+    const explicit = String(process.env.TASKFORCE_AUTH_EXPOSE_DEV_TOKENS || '').trim().toLowerCase();
+    return explicit === '1' || explicit === 'true' || explicit === 'yes';
+}
+export function resolveRuntimeConfigBaseUrl(req) {
+    const host = String(req.headers['x-forwarded-host'] || req.headers.host || '').trim();
+    if (!host)
+        return '';
+    const proto = String(req.headers['x-forwarded-proto'] || '').trim().toLowerCase() === 'https'
+        ? 'https'
+        : (req.socket?.encrypted ? 'https' : 'http');
+    return `${proto}://${host}`.replace(/\/+$/, '');
+}
+export function resolvePublicAuthBaseUrl(req) {
+    const configured = String(process.env.TASKFORCE_AUTH_PUBLIC_BASE_URL || '').trim().replace(/\/+$/, '');
+    if (configured)
+        return configured;
+    const host = String(req.headers['x-forwarded-host'] || req.headers.host || '').trim();
+    const proto = String(req.headers['x-forwarded-proto'] || '').trim().toLowerCase() === 'http' ? 'http' : 'https';
+    if (!host)
+        return resolveDeploymentConfig(process.env).cloudBaseUrl || 'https://app.taskforcehq.ai';
+    return `${proto}://${host}`;
+}

package/dist/server/routes/billing.d.ts

@@ -1,6 +1,6 @@
 import type { IncomingMessage } from 'http';
 import type { TaskforceCore } from '../../core/Taskforce.js';
-import type { RouteHandler, RouteContext } from '../routes.js';
+import { type RouteHandler, type RouteContext } from './primitives.js';
 export type BillingInterval = 'month' | 'year';
 export type BillingPricingType = 'stripe' | 'free';
 export interface BillingRouteDependencies {

package/dist/server/routes/billing.js

@@ -1,5 +1,5 @@
 import Stripe from 'stripe';
-import { parseJsonBody } from '../routes.js';
+import { parseJsonBody } from './primitives.js';
 import { resolveTaskforceCloudEnvironmentFromHostname } from '../../config/cloudEnvironment.js';
 import { buildMockStripeHostedCheckoutUrl, completeMockStripeCheckoutSession, createMockStripeClient, isMockStripeClient, isMockStripeEnabled, readMockStripeCheckoutSession, renderMockStripeCheckoutHtml } from '../mockStripe.js';
 const BILLING_CONFIG_KEY_PLAN = 'billing.config.v1';
@@ -733,72 +733,18 @@ function shouldRecordCheckoutPendingState(entitlement) {
         || 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
+    core.transitionCanonicalCommercialState({
+        accountId: input.userId,
+        planVersionId: input.planVersionId,
+        state: 'checkout_pending',
+        effectiveUntil: input.effectiveUntil || null,
+        billingMirrorPlanId: resolvePlanIdForVersion(core, input.planVersionId),
+        source,
+        updatedBy
     });
 }
-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();
-    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, input.state, input.effectiveAt || now, input.effectiveUntil || null, updatedBy, now, now);
-}
 function upsertBillingMirror(core, input) {
     const db = core.getDatabaseAdapter();
     const tenantId = core.getTenantId();
@@ -849,11 +795,15 @@ function applySubscriptionSnapshot(core, input) {
         ? (currentPeriodEnd && currentPeriodEnd > nowIso ? 'active' : 'canceled')
         : null;
     const mappedCanonicalState = canceledState || mapStripeStatusToCanonicalState(stripeStatus);
+    const existingPlanVersionId = String(existingEntitlement?.plan_version_id || '').trim();
     const preserveExistingAccess = mappedCanonicalState === 'checkout_pending'
+        && Boolean(planVersionId)
+        && existingPlanVersionId === planVersionId
         && isCommercialStateAppAccessible(existingEntitlement?.entitlement_state);
     const canonicalState = preserveExistingAccess
         ? String(existingEntitlement?.entitlement_state || 'active').trim().toLowerCase()
         : mappedCanonicalState;
+    const billingConfirmedSource = source === 'stripe-webhook' || source === 'checkout-confirm';
     const effectiveUntil = stripeStatus === 'canceled'
         ? currentPeriodEnd
         : (currentPeriodEnd || null);
@@ -880,13 +830,15 @@ function applySubscriptionSnapshot(core, input) {
             });
         }
     }
-    else if (planVersionId) {
-        upsertCanonicalEntitlement(core, {
-            userId,
+    else if (planVersionId && billingConfirmedSource) {
+        core.transitionCanonicalCommercialState({
+            accountId: userId,
             planVersionId: planVersionId || existingEntitlement?.plan_version_id || core.getDefaultPlanVersionIdByMode('personal', { allowFallback: true }),
             state: canonicalState,
             effectiveAt: trialEnd || nowIso,
             effectiveUntil,
+            billingMirrorPlanId: resolvePlanIdForVersion(core, planVersionId),
+            source,
             updatedBy: source
         });
     }
@@ -1378,18 +1330,11 @@ export function registerBillingRoutes(deps) {
             res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
             return;
         }
-        try {
-            const requestUrl = parseRequestUrl(req);
-            const interval = parseInterval(requestUrl.searchParams.get('interval'));
-            const options = await listStripePriceOptions(interval);
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ options }));
-        }
-        catch (error) {
-            const statusCode = resolveErrorStatusCode(error, 400);
-            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: String(error?.message || 'Unable to list Stripe prices'), code: error?.code }));
-        }
+        res.writeHead(410, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            error: 'Manual Stripe price selection has been removed. Refresh prices from Stripe metadata instead.',
+            code: 'BILLING_PRICE_MANUAL_MAPPING_REMOVED'
+        }));
     });
     addRoute('PUT', '/api/taskforce/admin/billing/price-mappings', async (req, res) => {
         if (!ensureCloudBilling(req, res))
@@ -1399,121 +1344,11 @@ export function registerBillingRoutes(deps) {
             res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
             return;
         }
-        const body = await parseJsonBody(req);
-        const planVersionId = String(body?.planVersionId || '').trim();
-        const interval = parseInterval(body?.interval);
-        const pricingType = parsePricingType(body?.pricingType) || 'stripe';
-        const stripePriceId = String(body?.stripePriceId || '').trim();
-        const setActive = body?.active === false ? false : true;
-        if (!planVersionId || !interval) {
-            res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: 'planVersionId and interval are required.', code: 'BILLING_MAPPING_INPUT_REQUIRED' }));
-            return;
-        }
-        if (pricingType === 'stripe' && !stripePriceId) {
-            res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: 'stripePriceId is required for Stripe pricing.', code: 'BILLING_MAPPING_STRIPE_PRICE_REQUIRED' }));
-            return;
-        }
-        const db = core.getDatabaseAdapter();
-        const tenantId = core.getTenantId();
-        const versionExists = db.prepare(`
-            SELECT plan_version_id
-            FROM plan_versions
-            WHERE tenant_id = ? AND plan_version_id = ?
-            LIMIT 1
-        `).get(tenantId, planVersionId);
-        if (!versionExists?.plan_version_id) {
-            res.writeHead(404, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: 'Plan version not found.', code: 'PLAN_VERSION_NOT_FOUND' }));
-            return;
-        }
-        try {
-            const now = new Date().toISOString();
-            const targetStripePriceId = pricingType === 'free'
-                ? buildFreePricingSyntheticId(planVersionId, interval)
-                : stripePriceId;
-            let unitAmount = 0;
-            let currency = null;
-            if (pricingType === 'stripe') {
-                const stripe = getStripeClient();
-                const stripePrice = await stripe.prices.retrieve(stripePriceId);
-                const stripeInterval = parseInterval(stripePrice.recurring?.interval || '');
-                if (!stripePrice.active) {
-                    res.writeHead(422, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ error: 'Stripe price is not active.', code: 'STRIPE_PRICE_INACTIVE' }));
-                    return;
-                }
-                if (!stripeInterval) {
-                    res.writeHead(422, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ error: 'Stripe price must be recurring month/year.', code: 'STRIPE_PRICE_INTERVAL_UNSUPPORTED' }));
-                    return;
-                }
-                if (stripeInterval !== interval) {
-                    res.writeHead(422, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ error: `Stripe price interval (${stripeInterval}) does not match requested interval (${interval}).`, code: 'STRIPE_PRICE_INTERVAL_MISMATCH' }));
-                    return;
-                }
-                unitAmount = typeof stripePrice.unit_amount === 'number' ? stripePrice.unit_amount : null;
-                currency = stripePrice.currency || null;
-            }
-            const beforeRows = db.prepare(`
-                SELECT plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency
-                FROM billing_price_mappings
-                WHERE tenant_id = ? AND plan_version_id = ? AND billing_interval = ?
-                ORDER BY stripe_price_id ASC
-            `).all(tenantId, planVersionId, interval);
-            if (setActive) {
-                db.prepare(`
-                    UPDATE billing_price_mappings
-                    SET active = 0, updated_at = ?
-                    WHERE tenant_id = ?
-                      AND plan_version_id = ?
-                      AND billing_interval = ?
-                      AND stripe_price_id <> ?
-                      AND active = 1
-                `).run(now, tenantId, planVersionId, interval, targetStripePriceId);
-            }
-            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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                ON CONFLICT (tenant_id, plan_version_id, billing_interval, stripe_price_id) DO UPDATE SET
-                    pricing_type = excluded.pricing_type,
-                    active = excluded.active,
-                    unit_amount = excluded.unit_amount,
-                    currency = excluded.currency,
-                    updated_at = excluded.updated_at
-            `).run(tenantId, planVersionId, interval, targetStripePriceId, pricingType, setActive ? 1 : 0, unitAmount, currency, now, now);
-            const mapping = db.prepare(`
-                SELECT plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at
-                FROM billing_price_mappings
-                WHERE tenant_id = ? AND plan_version_id = ? AND billing_interval = ? AND stripe_price_id = ?
-                LIMIT 1
-            `).get(tenantId, planVersionId, interval, targetStripePriceId);
-            const afterRows = db.prepare(`
-                SELECT plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency
-                FROM billing_price_mappings
-                WHERE tenant_id = ? AND plan_version_id = ? AND billing_interval = ?
-                ORDER BY stripe_price_id ASC
-            `).all(tenantId, planVersionId, interval);
-            auditAdminAction(req, 'billing-price-mapping-upsert', {
-                planVersionId,
-                interval,
-                pricingType,
-                stripePriceId: pricingType === 'free' ? null : stripePriceId,
-                active: setActive,
-                before: beforeRows,
-                after: afterRows
-            });
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ mapping }));
-        }
-        catch (error) {
-            const statusCode = resolveErrorStatusCode(error, 400);
-            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: String(error?.message || 'Unable to upsert price mapping'), code: error?.code }));
-        }
+        res.writeHead(410, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            error: 'Manual billing price mappings have been removed. Import Stripe prices instead.',
+            code: 'BILLING_PRICE_MANUAL_MAPPING_REMOVED'
+        }));
     });
     addRoute('POST', '/api/taskforce/admin/billing/price-mappings/deactivate', async (req, res) => {
         if (!ensureCloudBilling(req, res))
@@ -1523,51 +1358,11 @@ export function registerBillingRoutes(deps) {
             res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
             return;
         }
-        const body = await parseJsonBody(req);
-        const planVersionId = String(body?.planVersionId || '').trim();
-        const interval = parseInterval(body?.interval);
-        const stripePriceId = String(body?.stripePriceId || '').trim();
-        if (!planVersionId || !interval) {
-            res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: 'planVersionId and interval are required.', code: 'BILLING_MAPPING_TARGET_REQUIRED' }));
-            return;
-        }
-        const db = core.getDatabaseAdapter();
-        const tenantId = core.getTenantId();
-        const now = new Date().toISOString();
-        const beforeRows = db.prepare(`
-            SELECT plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency
-            FROM billing_price_mappings
-            WHERE tenant_id = ? AND plan_version_id = ? AND billing_interval = ?
-            ORDER BY stripe_price_id ASC
-        `).all(tenantId, planVersionId, interval);
-        const result = stripePriceId
-            ? db.prepare(`
-                UPDATE billing_price_mappings
-                SET active = 0, updated_at = ?
-                WHERE tenant_id = ? AND plan_version_id = ? AND billing_interval = ? AND stripe_price_id = ?
-            `).run(now, tenantId, planVersionId, interval, stripePriceId)
-            : db.prepare(`
-                UPDATE billing_price_mappings
-                SET active = 0, updated_at = ?
-                WHERE tenant_id = ? AND plan_version_id = ? AND billing_interval = ?
-            `).run(now, tenantId, planVersionId, interval);
-        const afterRows = db.prepare(`
-            SELECT plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency
-            FROM billing_price_mappings
-            WHERE tenant_id = ? AND plan_version_id = ? AND billing_interval = ?
-            ORDER BY stripe_price_id ASC
-        `).all(tenantId, planVersionId, interval);
-        auditAdminAction(req, 'billing-price-mapping-deactivate', {
-            planVersionId,
-            interval,
-            stripePriceId: stripePriceId || null,
-            changedRows: Number(result?.changes || 0),
-            before: beforeRows,
-            after: afterRows
-        });
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ success: true, changedRows: Number(result?.changes || 0) }));
+        res.writeHead(410, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            error: 'Manual billing price mappings have been removed. Refresh Stripe prices instead.',
+            code: 'BILLING_PRICE_MANUAL_MAPPING_REMOVED'
+        }));
     });
     addRoute('GET', '/api/taskforce/admin/billing/webhook-failures', async (req, res) => {
         if (!ensureCloudBilling(req, res))
@@ -1821,8 +1616,8 @@ export function registerBillingRoutes(deps) {
             const stripe = getStripeClient();
             let currentSubscriptionId = String(currentBilling?.stripe_subscription_id || '').trim();
             const currentCustomerId = String(currentBilling?.stripe_customer_id || '').trim();
-            const currentPlanVersionId = String(currentEntitlement?.plan_version_id || '').trim();
-            const currentInterval = parseInterval(String(currentBilling?.billing_interval || '').trim());
+            let currentPlanVersionId = String(currentEntitlement?.plan_version_id || '').trim();
+            let currentInterval = parseInterval(String(currentBilling?.billing_interval || '').trim());
             const stripeAccountDiscovery = await discoverStripeAccountStateForUser(core, {
                 userId,
                 normalizedEmail: normalizedUserEmail,
@@ -1838,8 +1633,13 @@ export function registerBillingRoutes(deps) {
                 return;
             }
             let resolvedCustomerId = currentCustomerId || String(stripeAccountDiscovery.preferredCustomerId || '').trim();
-            if (!currentSubscriptionId && stripeAccountDiscovery.activeSubscriptions.length === 1) {
-                const activeSubscription = stripeAccountDiscovery.activeSubscriptions[0];
+            const activeSubscription = stripeAccountDiscovery.activeSubscriptions.length === 1
+                ? stripeAccountDiscovery.activeSubscriptions[0]
+                : null;
+            let discoveredPlanVersionId = null;
+            let discoveredInterval = null;
+            let discoveredStripePriceId = null;
+            if (!currentSubscriptionId && activeSubscription) {
                 currentSubscriptionId = String(activeSubscription.subscription?.id || '').trim();
                 resolvedCustomerId = String(activeSubscription.customerId || '').trim() || resolvedCustomerId;
                 if (currentSubscriptionId || resolvedCustomerId) {
@@ -1856,7 +1656,28 @@ export function registerBillingRoutes(deps) {
                     stripeCustomerId: resolvedCustomerId
                 });
             }
-            if (currentSubscriptionId && currentPlanVersionId === planVersionId && currentInterval === interval) {
+            if (activeSubscription) {
+                const activeSubscriptionPriceId = String(activeSubscription.subscription?.items?.data?.[0]?.price?.id || '').trim();
+                discoveredStripePriceId = activeSubscriptionPriceId || null;
+                const activePlanVersionId = resolvePlanVersionIdForBillingEvent(core, [
+                    activeSubscription.subscription?.metadata?.planVersionId,
+                    activeSubscription.subscription?.metadata?.plan_version_id
+                ], activeSubscriptionPriceId).planVersionId;
+                discoveredPlanVersionId = activePlanVersionId;
+                discoveredInterval = parseInterval(activeSubscription.subscription?.items?.data?.[0]?.price?.recurring?.interval || '');
+                if (!currentPlanVersionId && activePlanVersionId) {
+                    currentPlanVersionId = activePlanVersionId;
+                }
+                if (!currentInterval) {
+                    currentInterval = discoveredInterval;
+                }
+            }
+            const isCurrentRequestedPlan = (currentPlanVersionId === planVersionId && currentInterval === interval) || (Boolean(currentSubscriptionId)
+                && discoveredPlanVersionId === planVersionId
+                && discoveredInterval === interval) || (Boolean(currentSubscriptionId)
+                && discoveredStripePriceId === priceId
+                && discoveredInterval === interval);
+            if (currentSubscriptionId && isCurrentRequestedPlan) {
                 res.writeHead(200, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({
                     checkoutState: 'already_current_plan',
@@ -1868,6 +1689,17 @@ export function registerBillingRoutes(deps) {
             if (currentSubscriptionId) {
                 const current = await stripe.subscriptions.retrieve(currentSubscriptionId);
                 const itemId = current.items.data[0]?.id;
+                const currentStripePriceId = String(current.items.data[0]?.price?.id || '').trim();
+                const currentSubscriptionInterval = parseInterval(current.items.data[0]?.price?.recurring?.interval || '');
+                if (currentStripePriceId === priceId && currentSubscriptionInterval === interval) {
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({
+                        checkoutState: 'already_current_plan',
+                        planVersionId,
+                        message: 'You are already on this plan.'
+                    }));
+                    return;
+                }
                 if (!itemId) {
                     res.writeHead(400, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({ error: 'Subscription has no updatable line item.' }));
@@ -1892,7 +1724,7 @@ export function registerBillingRoutes(deps) {
                 res.end(JSON.stringify({
                     checkoutState: 'updated',
                     planVersionId,
-                    message: 'Your subscription was updated successfully.'
+                    message: 'Your subscription update was submitted. Changes will appear after Stripe confirms the update.'
                 }));
                 return;
             }
@@ -2062,20 +1894,52 @@ export function registerBillingRoutes(deps) {
                     return;
                 }
             }
+            if (!subscriptionId || !subscription) {
+                res.writeHead(409, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    error: 'Checkout session is still finalizing your subscription.',
+                    code: 'CHECKOUT_SESSION_INCOMPLETE'
+                }));
+                return;
+            }
             core.createUserBillingRecord(resolvedUserId);
             upsertBillingMirror(core, {
                 userId: resolvedUserId,
                 stripeCustomerId: customerId || null,
                 stripeSubscriptionId: subscriptionId || null
             });
-            if (subscription) {
-                resolvedPlanVersionId = applySubscriptionSnapshot(core, {
-                    userId: resolvedUserId,
-                    subscription,
-                    source: 'checkout-confirm'
-                }).planVersionId;
-                updateCheckoutAttemptStatus(core, sessionId, 'confirmed');
+            const snapshot = applySubscriptionSnapshot(core, {
+                userId: resolvedUserId,
+                subscription,
+                source: 'checkout-confirm'
+            });
+            resolvedPlanVersionId = snapshot.planVersionId;
+            if (!resolvedPlanVersionId) {
+                res.writeHead(409, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    error: 'Checkout completed, but the purchased plan could not be resolved yet.',
+                    code: 'CHECKOUT_PLAN_VERSION_UNRESOLVED'
+                }));
+                return;
             }
+            const updatedEntitlement = getEntitlementRow(core, resolvedUserId);
+            const updatedPlanVersionId = String(updatedEntitlement?.plan_version_id || '').trim();
+            const updatedState = String(updatedEntitlement?.entitlement_state || '').trim().toLowerCase();
+            const canonicalSettled = snapshot.canonicalState !== 'checkout_pending'
+                && updatedPlanVersionId === resolvedPlanVersionId
+                && updatedState === snapshot.canonicalState;
+            if (!canonicalSettled) {
+                console.warn(`[Taskforce Billing] Checkout confirmation still settling for user=${resolvedUserId} session=${sessionId} subscription=${subscriptionId || '(missing)'} `
+                    + `planVersionId=${resolvedPlanVersionId} canonicalState=${snapshot.canonicalState} persistedPlanVersionId=${updatedPlanVersionId || '(missing)'} `
+                    + `persistedState=${updatedState || '(missing)'}`);
+                res.writeHead(409, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    error: 'Checkout session is still finalizing your plan.',
+                    code: 'CHECKOUT_SESSION_INCOMPLETE'
+                }));
+                return;
+            }
+            updateCheckoutAttemptStatus(core, sessionId, 'confirmed');
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({
                 success: true,
@@ -2140,7 +2004,7 @@ export function registerBillingRoutes(deps) {
             const baseUrl = resolveBaseUrl(req);
             const session = await stripe.billingPortal.sessions.create({
                 customer: customerId,
-                return_url: `${baseUrl}/settings`
+                return_url: `${baseUrl}/?screen=plans`
             });
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ url: session.url, returnBaseUrl: baseUrl }));
@@ -2385,12 +2249,15 @@ export function registerBillingRoutes(deps) {
                         });
                         return;
                     }
-                    upsertCanonicalEntitlement(core, {
-                        userId,
+                    core.transitionCanonicalCommercialState({
+                        accountId: userId,
                         planVersionId: planVersionId || existingEntitlement?.plan_version_id || core.getDefaultPlanVersionIdByMode('personal', { allowFallback: true }),
                         state: canonicalState,
                         effectiveAt: new Date().toISOString(),
-                        effectiveUntil: currentPeriodEnd
+                        effectiveUntil: currentPeriodEnd,
+                        billingMirrorPlanId: resolvePlanIdForVersion(core, planVersionId),
+                        source: 'stripe-webhook',
+                        updatedBy: 'stripe-webhook'
                     });
                     markLatestOpenCheckoutAttemptConfirmed(core, {
                         userId,