@taskforcehq/taskforce 0.3.305 → 0.3.307

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

@@ -180,6 +180,16 @@ function setupBillingSchema(db) {
             created_at TEXT NOT NULL,
             updated_at TEXT NOT NULL
         );
+        CREATE TABLE plan_feature_matrix (
+            tenant_id TEXT NOT NULL,
+            plan_version_id TEXT NOT NULL,
+            feature_key TEXT NOT NULL,
+            access TEXT NOT NULL DEFAULT 'disabled',
+            config_json TEXT NOT NULL DEFAULT '{}',
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL,
+            PRIMARY KEY (tenant_id, plan_version_id, feature_key)
+        );
         CREATE TABLE plan_catalog (
             plan_id TEXT PRIMARY KEY,
             tenant_id TEXT NOT NULL,
@@ -188,6 +198,16 @@ function setupBillingSchema(db) {
             created_at TEXT NOT NULL,
             updated_at TEXT NOT NULL
         );
+        CREATE TABLE plan_feature_catalog_overrides (
+            tenant_id TEXT NOT NULL,
+            feature_key TEXT NOT NULL,
+            public_label TEXT,
+            public_description TEXT,
+            public_display_order INTEGER,
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL,
+            PRIMARY KEY (tenant_id, feature_key)
+        );
         CREATE TABLE account_entitlements (
             account_id TEXT PRIMARY KEY,
             tenant_id TEXT NOT NULL,
@@ -208,6 +228,32 @@ function setupBillingSchema(db) {
         );
     `);
 }
+function readMockPlanVersionFeatures(db, tenantId, planVersionId) {
+    try {
+        return db.prepare(`
+            SELECT feature_key, access, config_json
+            FROM plan_feature_matrix
+            WHERE tenant_id = ? AND plan_version_id = ?
+        `).all(tenantId, planVersionId).reduce((acc, row) => {
+            const featureKey = String(row?.feature_key || '').trim();
+            if (!featureKey)
+                return acc;
+            acc[featureKey] = {
+                featureKey,
+                access: String(row?.access || '').trim(),
+                config: row?.config_json ? JSON.parse(String(row.config_json)) : {}
+            };
+            return acc;
+        }, {});
+    }
+    catch (error) {
+        const message = String(error?.message || '');
+        if (message.toLowerCase().includes('no such table: plan_feature_matrix')) {
+            return {};
+        }
+        throw error;
+    }
+}
 function buildBillingRouteHandlers(db, opts) {
     const routes = new Map();
     const tenantId = 'default';
@@ -288,12 +334,69 @@ function buildBillingRouteHandlers(db, opts) {
                     seatLimit: row?.seat_limit === null || row?.seat_limit === undefined ? null : Number(row.seat_limit),
                     trialDays: Number.isFinite(Number(metadata?.trialDays)) ? Number(metadata.trialDays) : 0,
                     metadata,
-                    features: {},
+                    features: readMockPlanVersionFeatures(db, tenantId, String(row?.plan_version_id || '')),
                     createdAt: '',
                     updatedAt: ''
                 };
             });
         },
+        listPlanFeatureCatalog: () => {
+            const overrides = db.prepare(`
+                SELECT feature_key, public_label, public_description, public_display_order
+                FROM plan_feature_catalog_overrides
+                WHERE tenant_id = ?
+            `).all(tenantId);
+            const overrideMap = new Map(overrides.map((row) => [
+                String(row.feature_key || '').trim(),
+                {
+                    publicLabel: row.public_label ?? null,
+                    publicDescription: row.public_description ?? null,
+                    publicDisplayOrder: row.public_display_order ?? null
+                }
+            ]));
+            return [
+                {
+                    featureKey: 'collaboration.team_management',
+                    label: 'Team Management',
+                    description: 'Allow managing members, invites, roles, and collaboration settings.',
+                    publicLabel: overrideMap.get('collaboration.team_management')?.publicLabel ?? null,
+                    publicDescription: overrideMap.get('collaboration.team_management')?.publicDescription ?? null,
+                    publicDisplayOrder: overrideMap.get('collaboration.team_management')?.publicDisplayOrder ?? 40,
+                    allowedAccessModes: ['enabled', 'disabled'],
+                    configTemplate: {}
+                },
+                {
+                    featureKey: 'context.uploads',
+                    label: 'Document Cloud Storage',
+                    description: 'Allow cloud document storage with an optional storage allowance in MB.',
+                    publicLabel: overrideMap.get('context.uploads')?.publicLabel ?? null,
+                    publicDescription: overrideMap.get('context.uploads')?.publicDescription ?? null,
+                    publicDisplayOrder: overrideMap.get('context.uploads')?.publicDisplayOrder ?? 30,
+                    allowedAccessModes: ['enabled', 'disabled'],
+                    configTemplate: { storageLimitMb: 1024 }
+                },
+                {
+                    featureKey: 'workspace.workspaces',
+                    label: 'Workspaces',
+                    description: 'Allow multiple workspaces with a configurable workspace limit.',
+                    publicLabel: overrideMap.get('workspace.workspaces')?.publicLabel ?? null,
+                    publicDescription: overrideMap.get('workspace.workspaces')?.publicDescription ?? null,
+                    publicDisplayOrder: overrideMap.get('workspace.workspaces')?.publicDisplayOrder ?? 10,
+                    allowedAccessModes: ['enabled', 'disabled'],
+                    configTemplate: { maxWorkspaces: 1 }
+                },
+                {
+                    featureKey: 'collaboration.ai_profiles',
+                    label: 'AI Profiles',
+                    description: 'Allow registered AI collaborator profiles with an optional per-workspace limit.',
+                    publicLabel: overrideMap.get('collaboration.ai_profiles')?.publicLabel ?? null,
+                    publicDescription: overrideMap.get('collaboration.ai_profiles')?.publicDescription ?? null,
+                    publicDisplayOrder: overrideMap.get('collaboration.ai_profiles')?.publicDisplayOrder ?? 20,
+                    allowedAccessModes: ['enabled', 'limited', 'disabled'],
+                    configTemplate: { maxAiProfiles: 1 }
+                }
+            ];
+        },
         getAccountEntitlement: () => {
             const entitlement = opts?.accessStatus?.entitlement;
             return {
@@ -691,6 +794,72 @@ describe('Billing Webhook Routes', () => {
         `).get();
         expect(String(failure?.reason || '')).toContain('no longer current for this account');
     });
+    it('allows authoritative subscription webhooks to recover accounts after the local checkout expired', 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 billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
+            VALUES ('default', 'team-v1', 'month', 'price_team_month', 1, ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO user_billing (
+                user_id, tenant_id, stripe_customer_id, entitlement_state, created_at, updated_at
+            ) VALUES ('u1', 'default', 'cus_123', 'pending_plan_selection', ?, ?)
+        `).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', 'pending_plan_selection', ?, NULL, 'checkout-expired', ?, ?)
+        `).run(now, now, now);
+        mockConstructEvent.mockReturnValue({
+            id: 'evt_checkout_expired_recovery',
+            type: 'customer.subscription.updated',
+            data: {
+                object: {
+                    id: 'sub_123',
+                    customer: 'cus_123',
+                    status: 'active',
+                    trial_end: null,
+                    metadata: { planVersionId: 'team-v1' },
+                    items: {
+                        data: [{
+                                current_period_end: Math.floor(Date.now() / 1000) + 86400,
+                                price: { id: 'price_team_month', recurring: { interval: 'month' } }
+                            }]
+                    }
+                }
+            }
+        });
+        const req = createMockReq('{"id":"evt_checkout_expired_recovery"}', {
+            '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: 'team-v1',
+            entitlement_state: 'active',
+            updated_by: 'stripe-webhook'
+        }));
+        const failure = db.prepare(`
+            SELECT reason
+            FROM stripe_webhook_failures
+            WHERE event_id = 'evt_checkout_expired_recovery'
+            ORDER BY created_at DESC
+            LIMIT 1
+        `).get();
+        expect(failure).toBeUndefined();
+    });
     it('ignores stale subscription webhooks for active accounts when a newer checkout attempt is open', async () => {
         const now = new Date().toISOString();
         db.prepare(`
@@ -821,6 +990,9 @@ describe('Billing Webhook Routes', () => {
         const firstCall = mockCheckoutCreate.mock.calls[0];
         const args = (Array.isArray(firstCall) ? firstCall[0] : {});
         expect(String(args.success_url || '')).toContain('/?screen=plans&checkout=success');
+        expect(String(args.success_url || '')).toContain('planId=collab');
+        expect(String(args.success_url || '')).toContain('planVersionId=collab-v1');
+        expect(String(args.success_url || '')).toContain('interval=month');
         expect(String(args.cancel_url || '')).toContain('/?screen=plans&checkout=cancel');
         expect(String(args.cancel_url || '')).toContain('planId=collab');
         expect(String(args.cancel_url || '')).toContain('planVersionId=collab-v1');
@@ -1133,6 +1305,9 @@ describe('Billing Webhook Routes', () => {
         expect(res.statusCode).toBe(200);
         const args = mockCheckoutCreate.mock.calls.at(-1)?.[0];
         expect(String(args.success_url || '')).toContain('http://localhost:5174/?screen=plans&checkout=success');
+        expect(String(args.success_url || '')).toContain('planId=collab');
+        expect(String(args.success_url || '')).toContain('planVersionId=collab-v1');
+        expect(String(args.success_url || '')).toContain('interval=month');
         expect(String(args.cancel_url || '')).toContain('http://localhost:5174/?screen=plans&checkout=cancel');
         expect(JSON.parse(res.body)).toEqual(expect.objectContaining({
             checkoutState: 'checkout',
@@ -1167,6 +1342,9 @@ describe('Billing Webhook Routes', () => {
         expect(res.statusCode).toBe(200);
         const args = mockCheckoutCreate.mock.calls.at(-1)?.[0];
         expect(String(args.success_url || '')).toContain('http://localhost:5174/?screen=plans&checkout=success');
+        expect(String(args.success_url || '')).toContain('planId=collab');
+        expect(String(args.success_url || '')).toContain('planVersionId=collab-v1');
+        expect(String(args.success_url || '')).toContain('interval=month');
     });
     it('builds direct cloud checkout return URLs from the actual request protocol when forwarded proto is absent', async () => {
         const now = new Date().toISOString();
@@ -1192,6 +1370,9 @@ describe('Billing Webhook Routes', () => {
         expect(res.statusCode).toBe(200);
         const args = mockCheckoutCreate.mock.calls.at(-1)?.[0];
         expect(String(args.success_url || '')).toContain('http://127.0.0.1:4173/?screen=plans&checkout=success');
+        expect(String(args.success_url || '')).toContain('planId=collab');
+        expect(String(args.success_url || '')).toContain('planVersionId=collab-v1');
+        expect(String(args.success_url || '')).toContain('interval=month');
         expect(String(args.cancel_url || '')).toContain('http://127.0.0.1:4173/?screen=plans&checkout=cancel');
     });
     it('applies a free plan immediately without creating a Stripe checkout session', async () => {
@@ -1822,6 +2003,118 @@ describe('Billing Webhook Routes', () => {
             status: 'open'
         }));
     });
+    it('does not mutate billing mirror or canonical entitlement when the purchased plan version is still unresolved', async () => {
+        const now = new Date().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_plan_unresolved', 'default', 'u1', 'pro-v1', 'month', 'open', ?, ?, ?)
+        `).run(new Date(Date.now() + 60 * 60 * 1000).toISOString(), 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', 'free-v1', 'active', ?, 'seed', ?, ?)
+        `).run(now, 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_existing', 'sub_existing', 'free', 'active', ?, ?)
+        `).run(now, now);
+        mockCheckoutRetrieve.mockResolvedValueOnce({
+            id: 'cs_plan_unresolved',
+            mode: 'subscription',
+            status: 'complete',
+            payment_status: 'paid',
+            customer: 'cus_123',
+            subscription: 'sub_unmapped',
+            metadata: { userId: 'u1' }
+        });
+        mockSubscriptionRetrieve.mockResolvedValueOnce({
+            id: 'sub_unmapped',
+            customer: 'cus_123',
+            status: 'active',
+            trial_end: null,
+            metadata: { userId: 'u1' },
+            items: {
+                data: [{
+                        id: 'si_unmapped',
+                        current_period_end: Math.floor(Date.now() / 1000) + 86400,
+                        price: { id: 'price_unmapped', recurring: { interval: 'month' } }
+                    }]
+            }
+        });
+        const confirmHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session/confirm');
+        const req = createMockReq(JSON.stringify({
+            sessionId: 'cs_plan_unresolved'
+        }), {
+            '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 completed, but the purchased plan could not be resolved yet.',
+            code: 'CHECKOUT_PLAN_VERSION_UNRESOLVED'
+        });
+        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: 'free-v1',
+            entitlement_state: 'active'
+        }));
+        const billingRow = db.prepare(`
+            SELECT stripe_customer_id, stripe_subscription_id, tier, entitlement_state
+            FROM user_billing
+            WHERE tenant_id = 'default' AND user_id = 'u1'
+            LIMIT 1
+        `).get();
+        expect(billingRow).toEqual(expect.objectContaining({
+            stripe_customer_id: 'cus_existing',
+            stripe_subscription_id: 'sub_existing',
+            tier: 'free',
+            entitlement_state: 'active'
+        }));
+        const attempt = db.prepare(`
+            SELECT status
+            FROM billing_checkout_attempts
+            WHERE tenant_id = 'default' AND session_id = 'cs_plan_unresolved'
+            LIMIT 1
+        `).get();
+        expect(attempt).toEqual(expect.objectContaining({
+            status: 'open'
+        }));
+    });
+    it('rejects checkout confirmation when the session belongs to a different account', async () => {
+        mockCheckoutRetrieve.mockResolvedValueOnce({
+            id: 'cs_wrong_account',
+            mode: 'subscription',
+            status: 'complete',
+            payment_status: 'paid',
+            customer: 'cus_other',
+            subscription: 'sub_other',
+            metadata: { userId: 'u2' }
+        });
+        const confirmHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session/confirm');
+        const req = createMockReq(JSON.stringify({
+            sessionId: 'cs_wrong_account'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const res = createMockRes();
+        await confirmHandler(req, res, {});
+        expect(res.statusCode).toBe(403);
+        expect(JSON.parse(res.body)).toEqual({
+            error: 'Checkout session does not belong to the current account.',
+            code: 'CHECKOUT_SESSION_ACCOUNT_MISMATCH'
+        });
+        expect(mockSubscriptionRetrieve).not.toHaveBeenCalled();
+    });
     it('rejects checkout confirmation when a newer pending checkout superseded the session plan', async () => {
         const now = new Date().toISOString();
         db.prepare(`
@@ -2119,7 +2412,30 @@ describe('Billing Webhook Routes', () => {
         `).get();
         expect(purged).toBeUndefined();
     });
-    it('rejects manual stripe price option listing now that pricing is import-only', async () => {
+    it('lists active Stripe price options for the requested interval', async () => {
+        mockPricesList.mockResolvedValueOnce({
+            data: [
+                {
+                    id: 'price_month_1',
+                    active: true,
+                    currency: 'usd',
+                    unit_amount: 1900,
+                    nickname: 'Monthly Core',
+                    recurring: { interval: 'month' },
+                    product: { id: 'prod_core', name: 'Core' }
+                },
+                {
+                    id: 'price_year_1',
+                    active: true,
+                    currency: 'usd',
+                    unit_amount: 19000,
+                    nickname: 'Yearly Core',
+                    recurring: { interval: 'year' },
+                    product: { id: 'prod_core', name: 'Core' }
+                }
+            ],
+            has_more: false
+        });
         const route = routeHandlers.get('GET /api/taskforce/admin/billing/stripe-price-options');
         expect(route).toBeTypeOf('function');
         const req = createMockReq('', {
@@ -2128,9 +2444,19 @@ describe('Billing Webhook Routes', () => {
         req.url = '/api/taskforce/admin/billing/stripe-price-options?interval=month';
         const res = createMockRes();
         await route(req, res, {});
-        expect(res.statusCode).toBe(410);
+        expect(res.statusCode).toBe(200);
         const body = JSON.parse(res.body);
-        expect(body.code).toBe('BILLING_PRICE_MANUAL_MAPPING_REMOVED');
+        expect(body.options).toEqual([
+            expect.objectContaining({
+                stripePriceId: 'price_month_1',
+                interval: 'month',
+                unitAmount: 1900,
+                currency: 'usd',
+                nickname: 'Monthly Core',
+                productId: 'prod_core',
+                productName: 'Core'
+            })
+        ]);
     });
     it('keeps active imported price mappings during Stripe import when the Stripe price is still active but lacks plan metadata', async () => {
         const now = new Date().toISOString();
@@ -2171,12 +2497,23 @@ describe('Billing Webhook Routes', () => {
         `).get();
         expect(row.active).toBe(1);
     });
-    it('rejects manual price mapping upserts now that pricing is import-only', async () => {
+    it('upserts manual Stripe price mappings and deactivates the prior active mapping', async () => {
         const now = new Date().toISOString();
         db.prepare(`
             INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
             VALUES ('collab-v1', 'default', 'collab', 1, 1, '{}', ?, ?)
         `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at)
+            VALUES ('default', 'collab-v1', 'month', 'price_old', 'stripe', 1, 1500, 'usd', ?, ?)
+        `).run(now, now);
+        mockPriceRetrieve.mockResolvedValueOnce({
+            id: 'price_new',
+            active: true,
+            currency: 'usd',
+            unit_amount: 2400,
+            recurring: { interval: 'month' }
+        });
         const upsertRoute = routeHandlers.get('PUT /api/taskforce/admin/billing/price-mappings');
         expect(upsertRoute).toBeTypeOf('function');
         const upsertReq = createMockReq(JSON.stringify({
@@ -2187,10 +2524,27 @@ describe('Billing Webhook Routes', () => {
         }), { 'x-taskforce-runtime-mode': 'cloud' });
         const upsertRes = createMockRes();
         await upsertRoute(upsertReq, upsertRes, {});
-        expect(upsertRes.statusCode).toBe(410);
-        expect(JSON.parse(upsertRes.body)).toEqual(expect.objectContaining({
-            code: 'BILLING_PRICE_MANUAL_MAPPING_REMOVED'
+        expect(upsertRes.statusCode).toBe(200);
+        const body = JSON.parse(upsertRes.body);
+        expect(body.mapping).toEqual(expect.objectContaining({
+            plan_version_id: 'collab-v1',
+            billing_interval: 'month',
+            stripe_price_id: 'price_new',
+            pricing_type: 'stripe',
+            active: 1,
+            unit_amount: 2400,
+            currency: 'usd'
         }));
+        const rows = db.prepare(`
+            SELECT stripe_price_id, active, unit_amount
+            FROM billing_price_mappings
+            WHERE tenant_id = 'default' AND plan_version_id = 'collab-v1' AND billing_interval = 'month'
+            ORDER BY stripe_price_id ASC
+        `).all();
+        expect(rows).toEqual([
+            { stripe_price_id: 'price_new', active: 1, unit_amount: 2400 },
+            { stripe_price_id: 'price_old', active: 0, unit_amount: 1500 }
+        ]);
     });
     it('rejects manual reuse of a Stripe price id across multiple plan versions', async () => {
         const now = new Date().toISOString();
@@ -2211,7 +2565,19 @@ describe('Billing Webhook Routes', () => {
         }), { 'x-taskforce-runtime-mode': 'cloud' });
         const firstRes = createMockRes();
         await upsertRoute(firstReq, firstRes, {});
-        expect(firstRes.statusCode).toBe(410);
+        expect(firstRes.statusCode).toBe(200);
+        const secondReq = createMockReq(JSON.stringify({
+            planVersionId: 'team-v1',
+            interval: 'month',
+            stripePriceId: 'price_shared',
+            active: true
+        }), { 'x-taskforce-runtime-mode': 'cloud' });
+        const secondRes = createMockRes();
+        await upsertRoute(secondReq, secondRes, {});
+        expect(secondRes.statusCode).toBe(409);
+        expect(JSON.parse(secondRes.body)).toEqual(expect.objectContaining({
+            code: 'BILLING_PRICE_ALREADY_ASSIGNED'
+        }));
     });
     it('keeps reused active mappings during Stripe import when the shared Stripe price is still active', async () => {
         const now = new Date().toISOString();
@@ -2260,12 +2626,16 @@ describe('Billing Webhook Routes', () => {
             { plan_version_id: 'team-v1', stripe_price_id: 'price_shared', active: 1 }
         ]);
     });
-    it('rejects manual free price mapping upserts now that pricing is import-only', async () => {
+    it('supports manual free price mappings and deactivation', async () => {
         const now = new Date().toISOString();
         db.prepare(`
             INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
             VALUES ('starter-v1', 'default', 'starter', 1, 1, '{}', ?, ?)
         `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at)
+            VALUES ('default', 'starter-v1', 'month', 'price_old', 'stripe', 1, 1500, 'usd', ?, ?)
+        `).run(now, now);
         const upsertRoute = routeHandlers.get('PUT /api/taskforce/admin/billing/price-mappings');
         expect(upsertRoute).toBeTypeOf('function');
         const upsertReq = createMockReq(JSON.stringify({
@@ -2276,10 +2646,41 @@ describe('Billing Webhook Routes', () => {
         }), { 'x-taskforce-runtime-mode': 'cloud' });
         const upsertRes = createMockRes();
         await upsertRoute(upsertReq, upsertRes, {});
-        expect(upsertRes.statusCode).toBe(410);
+        expect(upsertRes.statusCode).toBe(200);
         expect(JSON.parse(upsertRes.body)).toEqual(expect.objectContaining({
-            code: 'BILLING_PRICE_MANUAL_MAPPING_REMOVED'
+            mapping: expect.objectContaining({
+                plan_version_id: 'starter-v1',
+                billing_interval: 'month',
+                stripe_price_id: 'free:starter-v1:month',
+                pricing_type: 'free',
+                active: 1,
+                unit_amount: 0,
+                currency: null
+            })
         }));
+        const deactivateRoute = routeHandlers.get('POST /api/taskforce/admin/billing/price-mappings/deactivate');
+        expect(deactivateRoute).toBeTypeOf('function');
+        const deactivateReq = createMockReq(JSON.stringify({
+            planVersionId: 'starter-v1',
+            interval: 'month'
+        }), { 'x-taskforce-runtime-mode': 'cloud' });
+        const deactivateRes = createMockRes();
+        await deactivateRoute(deactivateReq, deactivateRes, {});
+        expect(deactivateRes.statusCode).toBe(200);
+        expect(JSON.parse(deactivateRes.body)).toEqual(expect.objectContaining({
+            success: true,
+            changedRows: 2
+        }));
+        const rows = db.prepare(`
+            SELECT stripe_price_id, pricing_type, active
+            FROM billing_price_mappings
+            WHERE tenant_id = 'default' AND plan_version_id = 'starter-v1' AND billing_interval = 'month'
+            ORDER BY stripe_price_id ASC
+        `).all();
+        expect(rows).toEqual([
+            { stripe_price_id: 'free:starter-v1:month', pricing_type: 'free', active: 0 },
+            { stripe_price_id: 'price_old', pricing_type: 'stripe', active: 0 }
+        ]);
     });
     it('rejects webhook failure diagnostics for non-admin', async () => {
         const nonAdminHandlers = buildBillingRouteHandlers(db, { isAdmin: false });
@@ -2332,6 +2733,8 @@ describe('Billing Webhook Routes', () => {
         expect(res.statusCode).toBe(200);
         const body = JSON.parse(res.body);
         expect(body.plans).toBeInstanceOf(Array);
+        expect(body.pageTitle).toBe('Subscription Plans');
+        expect(body.pageDescription).toBe('Manage your subscription and explore available features. Your current plan is highlighted below.');
         expect(body.pricingSource).toEqual({
             environment: 'production',
             runtimeMode: 'cloud'
@@ -2357,6 +2760,185 @@ describe('Billing Webhook Routes', () => {
         expect(freePlan.pricing.year).toBeNull();
         expect(proPlan.defaultVersion.trialDays).toBe(0);
     });
+    it('invalidates cached public pricing when billing mappings change', async () => {
+        const now = new Date().toISOString();
+        routeHandlers = buildBillingRouteHandlers(db);
+        const pricingRoute = routeHandlers.get('GET /api/taskforce/public/pricing');
+        expect(pricingRoute).toBeTypeOf('function');
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('pro-v1', 'default', 'pro', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (
+                tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at
+            ) VALUES ('default', 'pro-v1', 'month', 'price_pro_month', 'stripe', 1, 1200, 'usd', ?, ?)
+        `).run(now, now);
+        const firstReq = createMockReq('', { 'x-taskforce-runtime-mode': 'cloud' });
+        const firstRes = createMockRes();
+        await pricingRoute(firstReq, firstRes, {});
+        expect(firstRes.statusCode).toBe(200);
+        const firstBody = JSON.parse(firstRes.body);
+        expect(firstBody.plans.find((p) => p.planId === 'pro')?.pricing?.month?.unitAmount).toBe(1200);
+        const updatedAt = new Date(Date.now() + 1000).toISOString();
+        db.prepare(`
+            UPDATE billing_price_mappings
+            SET unit_amount = 2400, updated_at = ?
+            WHERE tenant_id = 'default' AND plan_version_id = 'pro-v1' AND billing_interval = 'month'
+        `).run(updatedAt);
+        const secondReq = createMockReq('', { 'x-taskforce-runtime-mode': 'cloud' });
+        const secondRes = createMockRes();
+        await pricingRoute(secondReq, secondRes, {});
+        expect(secondRes.statusCode).toBe(200);
+        const secondBody = JSON.parse(secondRes.body);
+        expect(secondBody.plans.find((p) => p.planId === 'pro')?.pricing?.month?.unitAmount).toBe(2400);
+    });
+    it('invalidates cached public pricing when plan features change', async () => {
+        const now = new Date().toISOString();
+        routeHandlers = buildBillingRouteHandlers(db);
+        const pricingRoute = routeHandlers.get('GET /api/taskforce/public/pricing');
+        expect(pricingRoute).toBeTypeOf('function');
+        db.exec(`
+            CREATE TABLE IF NOT EXISTS plan_feature_matrix (
+                tenant_id TEXT NOT NULL,
+                plan_version_id TEXT NOT NULL,
+                feature_key TEXT NOT NULL,
+                access TEXT NOT NULL,
+                config_json TEXT,
+                created_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL,
+                PRIMARY KEY (tenant_id, plan_version_id, feature_key)
+            )
+        `);
+        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, pricing_type, active, unit_amount, currency, created_at, updated_at
+            ) VALUES ('default', 'pro-v1', 'month', 'price_pro_month', 'stripe', 1, 1200, 'usd', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO plan_feature_matrix (tenant_id, plan_version_id, feature_key, access, config_json, created_at, updated_at)
+            VALUES ('default', 'pro-v1', 'ai.chat', 'enabled', '{}', ?, ?)
+        `).run(now, now);
+        const firstReq = createMockReq('', { 'x-taskforce-runtime-mode': 'cloud' });
+        const firstRes = createMockRes();
+        await pricingRoute(firstReq, firstRes, {});
+        expect(firstRes.statusCode).toBe(200);
+        const firstBody = JSON.parse(firstRes.body);
+        expect(firstBody.plans.find((p) => p.planId === 'pro')?.features).toEqual([
+            expect.objectContaining({ featureKey: 'ai.chat' })
+        ]);
+        const updatedAt = new Date(Date.now() + 1000).toISOString();
+        db.prepare(`
+            UPDATE plan_feature_matrix
+            SET access = 'disabled', updated_at = ?
+            WHERE tenant_id = 'default' AND plan_version_id = 'pro-v1' AND feature_key = 'ai.chat'
+        `).run(updatedAt);
+        const secondReq = createMockReq('', { 'x-taskforce-runtime-mode': 'cloud' });
+        const secondRes = createMockRes();
+        await pricingRoute(secondReq, secondRes, {});
+        expect(secondRes.statusCode).toBe(200);
+        const secondBody = JSON.parse(secondRes.body);
+        expect(secondBody.plans.find((p) => p.planId === 'pro')?.features).toEqual([]);
+    });
+    it('includes public feature copy and invalidates cached public pricing when catalog overrides change', async () => {
+        const now = new Date().toISOString();
+        routeHandlers = buildBillingRouteHandlers(db);
+        const pricingRoute = routeHandlers.get('GET /api/taskforce/public/pricing');
+        expect(pricingRoute).toBeTypeOf('function');
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('pro-v1', 'default', 'pro', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (
+                tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at
+            ) VALUES ('default', 'pro-v1', 'month', 'price_pro_month', 'stripe', 1, 1200, 'usd', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO plan_feature_matrix (tenant_id, plan_version_id, feature_key, access, config_json, created_at, updated_at)
+            VALUES ('default', 'pro-v1', 'collaboration.ai_profiles', 'enabled', '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO plan_feature_catalog_overrides (tenant_id, feature_key, public_label, public_description, created_at, updated_at)
+            VALUES ('default', 'collaboration.ai_profiles', 'AI teammates', 'Add reusable AI teammates to your workspace.', ?, ?)
+        `).run(now, now);
+        const firstReq = createMockReq('', { 'x-taskforce-runtime-mode': 'cloud' });
+        const firstRes = createMockRes();
+        await pricingRoute(firstReq, firstRes, {});
+        expect(firstRes.statusCode).toBe(200);
+        const firstBody = JSON.parse(firstRes.body);
+        expect(firstBody.plans.find((p) => p.planId === 'pro')?.features).toEqual([
+            expect.objectContaining({
+                featureKey: 'collaboration.ai_profiles',
+                label: 'AI Profiles',
+                publicLabel: 'AI teammates',
+                publicDescription: 'Add reusable AI teammates to your workspace.'
+            })
+        ]);
+        const updatedAt = new Date(Date.now() + 1000).toISOString();
+        db.prepare(`
+            UPDATE plan_feature_catalog_overrides
+            SET public_label = 'AI copilots', updated_at = ?
+            WHERE tenant_id = 'default' AND feature_key = 'collaboration.ai_profiles'
+        `).run(updatedAt);
+        const secondReq = createMockReq('', { 'x-taskforce-runtime-mode': 'cloud' });
+        const secondRes = createMockRes();
+        await pricingRoute(secondReq, secondRes, {});
+        expect(secondRes.statusCode).toBe(200);
+        const secondBody = JSON.parse(secondRes.body);
+        expect(secondBody.plans.find((p) => p.planId === 'pro')?.features).toEqual([
+            expect.objectContaining({
+                featureKey: 'collaboration.ai_profiles',
+                publicLabel: 'AI copilots'
+            })
+        ]);
+    });
+    it('orders public pricing features by catalog display order', async () => {
+        const now = new Date().toISOString();
+        routeHandlers = buildBillingRouteHandlers(db);
+        const pricingRoute = routeHandlers.get('GET /api/taskforce/public/pricing');
+        expect(pricingRoute).toBeTypeOf('function');
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, seat_limit, metadata_json, created_at, updated_at)
+            VALUES ('pro-v1', 'default', 'pro', 1, 1, 5, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (
+                tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at
+            ) VALUES ('default', 'pro-v1', 'month', 'price_pro_month', 'stripe', 1, 1800, 'usd', ?, ?)
+        `).run(now, now);
+        for (const feature of [
+            { key: 'collaboration.team_management', access: 'enabled', config: '{}' },
+            { key: 'collaboration.invites', access: 'enabled', config: '{}' },
+            { key: 'collaboration.seat_limit', access: 'limited', config: '{"seat_limit":5}' },
+            { key: 'context.uploads', access: 'enabled', config: '{"storageLimitMb":24}' },
+            { key: 'workspace.workspaces', access: 'enabled', config: '{"maxWorkspaces":1}' },
+            { key: 'collaboration.ai_profiles', access: 'limited', config: '{"maxAiProfiles":4}' }
+        ]) {
+            db.prepare(`
+                INSERT INTO plan_feature_matrix (tenant_id, plan_version_id, feature_key, access, config_json, created_at, updated_at)
+                VALUES ('default', 'pro-v1', ?, ?, ?, ?, ?)
+            `).run(feature.key, feature.access, feature.config, now, now);
+        }
+        const req = createMockReq('', { 'x-taskforce-runtime-mode': 'cloud' });
+        const res = createMockRes();
+        await pricingRoute(req, res, {});
+        expect(res.statusCode).toBe(200);
+        const body = JSON.parse(res.body);
+        const orderedPlan = body.plans.find((plan) => plan.planId === 'pro');
+        expect(orderedPlan.features.map((feature) => feature.featureKey)).toEqual([
+            'workspace.workspaces',
+            'collaboration.ai_profiles',
+            'context.uploads',
+            'collaboration.team_management'
+        ]);
+        expect(orderedPlan.features.map((feature) => feature.featureKey)).not.toContain('collaboration.invites');
+        expect(orderedPlan.features.map((feature) => feature.featureKey)).not.toContain('collaboration.seat_limit');
+    });
     it('returns the pricing environment derived from the cloud host', async () => {
         routeHandlers = buildBillingRouteHandlers(db);
         const pricingRoute = routeHandlers.get('GET /api/taskforce/public/pricing');
@@ -2369,6 +2951,7 @@ describe('Billing Webhook Routes', () => {
         await pricingRoute(req, res, {});
         expect(res.statusCode).toBe(200);
         const body = JSON.parse(res.body);
+        expect(body.pageTitle).toBe('Subscription Plans');
         expect(body.pricingSource).toEqual({
             environment: 'performance',
             runtimeMode: 'cloud'