fraim 2.0.352 → 2.0.354

package/dist/src/routes/auth-routes.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerPublicAuthRoutes = registerPublicAuthRoutes;
 exports.registerProtectedAuthRoutes = registerProtectedAuthRoutes;
 exports.__resetAuthRouteRateLimitsForTests = __resetAuthRouteRateLimitsForTests;
+const license_presentation_1 = require("../fraim/license-presentation");
 const crypto_1 = require("crypto");
 const email_service_1 = require("../services/email-service");
 const cookie_service_1 = require("../services/cookie-service");
@@ -63,16 +64,6 @@ function issueMobileExchangeCode(apiKey) {
     mobileCodeStore.set(code, { apiKey, expiresAt: Date.now() + MOBILE_CODE_TTL_MS });
     return code;
 }
-function serializeApiKeyLifecycle(apiKeyData) {
-    const rawExpiresAt = apiKeyData?.expiresAt ?? null;
-    const parsedExpiresAt = rawExpiresAt ? new Date(rawExpiresAt) : null;
-    return {
-        status: apiKeyData?.status ?? 'active',
-        expiresAt: parsedExpiresAt && !Number.isNaN(parsedExpiresAt.getTime())
-            ? parsedExpiresAt.toISOString()
-            : null,
-    };
-}
 const recentIpRequests = new Map();
 function pruneOlder(arr, cutoff) {
     return arr.filter(t => t >= cutoff);
@@ -317,7 +308,7 @@ function registerProtectedAuthRoutes(app, deps) {
             return res.status(200).json({
                 ok: true,
                 apiKey: apiKeyData.key,
-                ...serializeApiKeyLifecycle(apiKeyData),
+                ...(0, license_presentation_1.serializeLicenseLifecycle)(apiKeyData),
             });
         }
         catch (err) {
@@ -506,13 +497,13 @@ function registerProtectedAuthRoutes(app, deps) {
                 authMethod: signInMethod,
                 source: req.authSource ?? 'api-key',
                 isFirstSignIn,
-                ...serializeApiKeyLifecycle(apiKeyData),
+                ...(0, license_presentation_1.serializeLicenseLifecycle)(apiKeyData),
                 // Nested user object consumed by public/index.html
                 user: {
                     email: apiKeyData.userId,
                     signInMethod,
                     apiKey: apiKeyData.key,
-                    ...serializeApiKeyLifecycle(apiKeyData),
+                    ...(0, license_presentation_1.serializeLicenseLifecycle)(apiKeyData),
                 },
             });
         }

package/dist/src/services/email-service.js

@@ -122,8 +122,8 @@ class EmailService {
     /**
      * Send subscription activated confirmation
      */
-    async sendSubscriptionActivated(to, plan, amountCents, billingCycle, nextBillingDate, dashboardUrl, founderDiscount = false) {
-        const template = this.generateSubscriptionActivatedTemplate(plan, amountCents, billingCycle, nextBillingDate, dashboardUrl, founderDiscount);
+    async sendSubscriptionActivated(to, plan, amountCents, billingCycle, paidThrough, dashboardUrl, founderDiscount = false) {
+        const template = this.generateSubscriptionActivatedTemplate(plan, amountCents, billingCycle, paidThrough, dashboardUrl, founderDiscount);
         try {
             const result = await this.sendWithResend({
                 from: this.fromEmail,
@@ -144,10 +144,10 @@ class EmailService {
         }
     }
     /**
-     * Send monthly renewal receipt
+     * Send renewal receipt with the verified paid-through deadline
      */
-    async sendRenewalReceipt(to, amount, nextBillingDate, invoiceUrl) {
-        const template = this.generateRenewalReceiptTemplate(amount, nextBillingDate, invoiceUrl);
+    async sendRenewalReceipt(to, amount, paidThrough, invoiceUrl) {
+        const template = this.generateRenewalReceiptTemplate(amount, paidThrough, invoiceUrl);
         const result = await this.sendWithResend({
             from: this.fromEmail,
             to,
@@ -164,8 +164,8 @@ class EmailService {
     /**
      * Send payment failed alert
      */
-    async sendPaymentFailed(to, billingPortalUrl, gracePeriodEndsAt) {
-        const template = this.generatePaymentFailedTemplate(billingPortalUrl, gracePeriodEndsAt);
+    async sendPaymentFailed(to, billingPortalUrl, validThrough) {
+        const template = this.generatePaymentFailedTemplate(billingPortalUrl, validThrough);
         const result = await this.sendWithResend({
             from: this.fromEmail,
             to,
@@ -182,8 +182,8 @@ class EmailService {
     /**
      * Send payment retry succeeded
      */
-    async sendPaymentRestored(to, nextBillingDate) {
-        const template = this.generatePaymentRestoredTemplate(nextBillingDate);
+    async sendPaymentRestored(to, paidThrough) {
+        const template = this.generatePaymentRestoredTemplate(paidThrough);
         const result = await this.sendWithResend({
             from: this.fromEmail,
             to,
@@ -216,6 +216,9 @@ class EmailService {
         console.log(`✅ Subscription cancelled email sent to ${to}`, { id: result.data?.id });
     }
     // ========== Email Template Generators ==========
+    formatValidityDate(date) {
+        return `${date.toISOString().replace('T', ' ').replace(/\.\d{3}Z$/, '')} UTC`;
+    }
     generateEmailCodeTemplate(actionUrl, code, purpose) {
         const expiresInMinutes = 15;
         const isRequestAccess = purpose === 'request-access';
@@ -361,7 +364,7 @@ class EmailService {
 
         <h3>Upgrade to Pro for:</h3>
         <ul>
-            <li>Unlimited usage (no expiration)</li>
+            <li>Subscription access through the verified paid-through date</li>
             <li>Priority support</li>
             <li>Advanced workflows</li>
             <li>Team collaboration features</li>
@@ -378,7 +381,7 @@ class EmailService {
 </body>
 </html>
             `,
-            text: `How's FRAIM working for you?\n\nYou've been using FRAIM for a week now. We hope it's helping you manage your AI agents more effectively!\n\nYour trial ends in ${daysRemaining} days (${expiresAt.toLocaleDateString()})\n\nUpgrade to Pro for:\n- Unlimited usage (no expiration)\n- Priority support\n- Advanced workflows\n- Team collaboration features\n\nSpecial offer for early adopters: 90% off for pre-seed, pre-revenue founders!\n\nUpgrade: ${this.baseUrl}/upgrade`
+            text: `How's FRAIM working for you?\n\nYou've been using FRAIM for a week now. We hope it's helping you manage your AI agents more effectively!\n\nYour trial ends in ${daysRemaining} days (${expiresAt.toLocaleDateString()})\n\nUpgrade to Pro for:\n- Subscription access through the verified paid-through date\n- Priority support\n- Advanced workflows\n- Team collaboration features\n\nSpecial offer for early adopters: 90% off for pre-seed, pre-revenue founders!\n\nUpgrade: ${this.baseUrl}/upgrade`
         };
     }
     generateTrialExpiringTemplate(expiresAt, daysRemaining) {
@@ -493,7 +496,7 @@ class EmailService {
             text: `Your FRAIM trial has ended\n\nYour 14-day trial expired on ${expiredAt.toLocaleDateString()}.\n\nYour data is safe and preserved. Upgrade now to reactivate your account and continue using FRAIM.\n\nPricing plans:\n- Regular: $200/month or $2,000/year\n- Founders (90% off): $20/month or $200/year\n\nReactivate your account: ${this.baseUrl}/upgrade`
         };
     }
-    generateSubscriptionActivatedTemplate(plan, amountCents, billingCycle, nextBillingDate, dashboardUrl, founderDiscount) {
+    generateSubscriptionActivatedTemplate(plan, amountCents, billingCycle, paidThrough, dashboardUrl, founderDiscount) {
         const formattedAmount = (amountCents / 100).toFixed(2);
         const displayAmount = `$${formattedAmount}`;
         const cycleText = billingCycle === 'monthly' ? 'month' : 'year';
@@ -541,7 +544,7 @@ class EmailService {
         <ul>
             <li><strong>Plan:</strong> ${plan}${founderDiscount ? ' (Founder Discount - 90% off)' : ''}</li>
             <li><strong>Amount:</strong> ${displayAmount}/${cycleText}</li>
-            <li><strong>Next billing date:</strong> ${nextBillingDate.toLocaleDateString()}</li>
+            <li><strong>Verified paid-through:</strong> ${this.formatValidityDate(paidThrough)}</li>
         </ul>
 
         <p>${dashboardAccess.lead}</p>
@@ -561,7 +564,7 @@ class EmailService {
 </body>
 </html>
             `,
-            text: `Welcome to FRAIM Pro!\n\nPayment confirmed! Your subscription is now active.\n\nSubscription Details:\n- Plan: ${plan}${founderDiscount ? ' (Founder Discount - 90% off)' : ''}\n- Amount: ${displayAmount}/${cycleText}\n- Next billing date: ${nextBillingDate.toLocaleDateString()}\n\n${dashboardAccess.lead}\n${dashboardAccess.buttonText}\nWatch onboarding videos: ${this.baseUrl}/resources.html#videos\n\nManage subscription: ${this.baseUrl}/billing`
+            text: `Welcome to FRAIM Pro!\n\nPayment confirmed! Your subscription is now active.\n\nSubscription Details:\n- Plan: ${plan}${founderDiscount ? ' (Founder Discount - 90% off)' : ''}\n- Amount: ${displayAmount}/${cycleText}\n- Verified paid-through: ${this.formatValidityDate(paidThrough)}\n\n${dashboardAccess.lead}\n${dashboardAccess.buttonText}\nWatch onboarding videos: ${this.baseUrl}/resources.html#videos\n\nManage subscription: ${this.baseUrl}/billing`
         };
     }
     generateDashboardAccessSection(dashboardUrl, ctaLabel) {
@@ -572,7 +575,7 @@ class EmailService {
             buttonText: `${ctaLabel}: ${dashboardUrl}`
         };
     }
-    generateRenewalReceiptTemplate(amount, nextBillingDate, invoiceUrl) {
+    generateRenewalReceiptTemplate(amount, paidThrough, invoiceUrl) {
         const formattedAmount = (amount / 100).toFixed(2);
         return {
             subject: `Receipt for FRAIM Pro - ${formattedAmount}`,
@@ -595,7 +598,7 @@ class EmailService {
         <div class="receipt">
             <h3>Receipt Details:</h3>
             <p><strong>Amount charged:</strong> ${formattedAmount}</p>
-            <p><strong>Next billing date:</strong> ${nextBillingDate.toLocaleDateString()}</p>
+            <p><strong>Verified paid-through:</strong> ${this.formatValidityDate(paidThrough)}</p>
             ${invoiceUrl ? `<p><a href="${invoiceUrl}">Download Invoice</a></p>` : ''}
         </div>
 
@@ -609,11 +612,18 @@ class EmailService {
 </body>
 </html>
             `,
-            text: `Payment Receipt\n\nThank you for your continued subscription to FRAIM Pro!\n\nReceipt Details:\n- Amount charged: ${formattedAmount}\n- Next billing date: ${nextBillingDate.toLocaleDateString()}\n${invoiceUrl ? `- Invoice: ${invoiceUrl}\n` : ''}\nYour subscription remains active with no changes.\n\nManage subscription: ${this.baseUrl}/billing`
+            text: `Payment Receipt\n\nThank you for your continued subscription to FRAIM Pro!\n\nReceipt Details:\n- Amount charged: ${formattedAmount}\n- Verified paid-through: ${this.formatValidityDate(paidThrough)}\n${invoiceUrl ? `- Invoice: ${invoiceUrl}\n` : ''}\nYour subscription remains active with no changes.\n\nManage subscription: ${this.baseUrl}/billing`
         };
     }
-    generatePaymentFailedTemplate(billingPortalUrl, gracePeriodEndsAt) {
-        const daysRemaining = Math.ceil((gracePeriodEndsAt.getTime() - Date.now()) / (1000 * 60 * 60 * 24));
+    generatePaymentFailedTemplate(billingPortalUrl, validThrough) {
+        const validity = validThrough === null
+            ? 'No deadline (authorized manual grant)'
+            : this.formatValidityDate(validThrough);
+        const accessStatus = validThrough === null
+            ? 'Your separately authorized manual grant remains in effect. It does not indicate a successful payment.'
+            : validThrough.getTime() > Date.now()
+                ? 'Your existing access remains available until the deadline shown below.'
+                : 'Your access deadline has passed. Renew successfully to restore subscription access.';
         return {
             subject: '🚨 FRAIM: Payment Failed - Action Required',
             html: `
@@ -642,21 +652,21 @@ class EmailService {
 
         <div class="alert">
             <strong>Your FRAIM subscription payment was declined.</strong><br>
-            Your access has been suspended.
+            ${accessStatus}
         </div>
 
         <p><strong>What this means:</strong></p>
         <ul>
-            <li>Your API key has been suspended and won't work</li>
-            <li>You have ${daysRemaining} days to update your payment method</li>
-            <li>After ${gracePeriodEndsAt.toLocaleDateString()}, your subscription will be cancelled</li>
+            <li><strong>Valid through:</strong> ${validity}</li>
+            <li>No automatic grace period applies after verified paid-through.</li>
+            <li>Any authorized manual extension is separate from payment and is included in this access deadline.</li>
         </ul>
 
         <p><strong>To restore access:</strong></p>
         <ol>
             <li>Click the button below to update your payment method</li>
-            <li>Your subscription will be automatically renewed</li>
-            <li>Your API key will be reactivated immediately</li>
+            <li>Complete a successful renewal payment</li>
+            <li>Subscription access updates when the paid service period is verified</li>
         </ol>
 
         <a href="${billingPortalUrl}" style="display:inline-block;padding:12px 24px;background-color:#dc3545;color:#ffffff !important;text-decoration:none;border-radius:5px;margin:20px 0;font-weight:bold">Update Payment Method</a>
@@ -669,10 +679,10 @@ class EmailService {
 </body>
 </html>
             `,
-            text: `⚠️ Payment Failed\n\nYour FRAIM subscription payment was declined. Your access has been suspended.\n\nWhat this means:\n- Your API key has been suspended and won't work\n- You have ${daysRemaining} days to update your payment method\n- After ${gracePeriodEndsAt.toLocaleDateString()}, your subscription will be cancelled\n\nTo restore access:\n1. Update your payment method: ${billingPortalUrl}\n2. Your subscription will be automatically renewed\n3. Your API key will be reactivated immediately\n\nNeed help? Reply to this email.`
+            text: `Payment Failed\n\nYour FRAIM subscription payment was declined. ${accessStatus}\n\nValid through: ${validity}\nNo automatic grace period applies after verified paid-through.\nAny authorized manual extension is separate from payment and is included in this access deadline.\n\nTo restore subscription access:\n1. Update your payment method: ${billingPortalUrl}\n2. Complete a successful renewal payment\n3. Subscription access updates when the paid service period is verified\n\nNeed help? Reply to this email.`
         };
     }
-    generatePaymentRestoredTemplate(nextBillingDate) {
+    generatePaymentRestoredTemplate(paidThrough) {
         return {
             subject: '✅ Payment successful - FRAIM access restored',
             html: `
@@ -705,7 +715,7 @@ class EmailService {
         </div>
 
         <p>Your API key is now active again and you can continue using FRAIM.</p>
-        <p><strong>Next billing date:</strong> ${nextBillingDate.toLocaleDateString()}</p>
+        <p><strong>Verified paid-through:</strong> ${this.formatValidityDate(paidThrough)}</p>
 
         <a href="${this.baseUrl}/dashboard" style="display:inline-block;padding:12px 24px;background-color:#10b981;color:#ffffff !important;text-decoration:none;border-radius:5px;margin:20px 0;font-weight:bold">Continue Using FRAIM</a>
 
@@ -716,10 +726,13 @@ class EmailService {
 </body>
 </html>
             `,
-            text: `✅ Access Restored!\n\nPayment successful! Your FRAIM subscription has been renewed.\n\nYour API key is now active again and you can continue using FRAIM.\n\nNext billing date: ${nextBillingDate.toLocaleDateString()}\n\nContinue using FRAIM: ${this.baseUrl}/dashboard`
+            text: `✅ Access Restored!\n\nPayment successful! Your FRAIM subscription has been renewed.\n\nYour API key is now active again and you can continue using FRAIM.\n\nVerified paid-through: ${this.formatValidityDate(paidThrough)}\n\nContinue using FRAIM: ${this.baseUrl}/dashboard`
         };
     }
     generateSubscriptionCancelledTemplate(endsAt) {
+        const accessStatus = endsAt.getTime() > Date.now()
+            ? 'Access remains available until this deadline.'
+            : 'Subscription access has ended.';
         return {
             subject: 'FRAIM subscription cancelled',
             html: `
@@ -748,7 +761,8 @@ class EmailService {
 
         <div class="info">
             <p><strong>Your subscription has been cancelled.</strong></p>
-            <p>Your access remains active until: ${endsAt.toLocaleDateString()}</p>
+            <p>Valid through: ${this.formatValidityDate(endsAt)}</p>
+            <p>${accessStatus}</p>
         </div>
 
         <p>After this date:</p>
@@ -758,7 +772,7 @@ class EmailService {
             <li>Your data will be preserved for 30 days</li>
         </ul>
 
-        <p><strong>Changed your mind?</strong> You can reactivate your subscription anytime before ${endsAt.toLocaleDateString()}.</p>
+        <p><strong>Changed your mind?</strong> Visit the billing portal to review your subscription options.</p>
 
         <a href="${this.baseUrl}/billing" style="display:inline-block;padding:12px 24px;background-color:#10b981;color:#ffffff !important;text-decoration:none;border-radius:5px;margin:20px 0;font-weight:bold">Reactivate Subscription</a>
 
@@ -770,7 +784,7 @@ class EmailService {
 </body>
 </html>
             `,
-            text: `Subscription Cancelled\n\nYour subscription has been cancelled.\n\nYour access remains active until: ${endsAt.toLocaleDateString()}\n\nAfter this date:\n- Your API key will stop working\n- You won't be able to run workflows\n- Your data will be preserved for 30 days\n\nChanged your mind? You can reactivate your subscription anytime before ${endsAt.toLocaleDateString()}.\n\nReactivate: ${this.baseUrl}/billing\n\nWe're sorry to see you go. Reply to this email to let us know how we can improve.`
+            text: `Subscription Cancelled\n\nYour subscription has been cancelled.\n\nValid through: ${this.formatValidityDate(endsAt)}\n${accessStatus}\n\nAfter this date:\n- Your API key will stop working\n- You won't be able to run workflows\n- Your data will be preserved for 30 days\n\nChanged your mind? Visit the billing portal to review your subscription options.\n\nReactivate: ${this.baseUrl}/billing\n\nWe're sorry to see you go. Reply to this email to let us know how we can improve.`
         };
     }
     generateThankYouTemplate(customerName, issueTitle, improvements) {

package/dist/src/services/mcp-service.js

@@ -134,6 +134,17 @@ class McpService {
             else if (method === 'ping') {
                 result = {};
             }
+            else if (method === 'fraim/session/validate') {
+                const sessionId = typeof params?.sessionId === 'string' ? params.sessionId.trim() : '';
+                if (!sessionId || !context.userId || !(await this.dbService.getSessionByUserIdAndSessionId(context.userId, sessionId))) {
+                    // Issue #2093 — sessions do not expire, so the rejection names the two
+                    // causes that remain: the session is unknown, or it belongs elsewhere.
+                    const error = new Error('FRAIM session is unknown or not accessible with this account. Call fraim_connect again.');
+                    error.code = -32001;
+                    throw error;
+                }
+                result = { valid: true };
+            }
             else if (method === 'notifications/initialized') {
                 // Notifications don't need a response
                 return null;
@@ -640,9 +651,16 @@ class McpService {
         return (0, quality_evidence_1.buildQualityRejectionMessage)(jobName, currentPhase, errors);
     }
     async maybeBuildPersonaLockResponse(jobName, userId, apiKey, consumeJobCredit = false) {
-        if (!(0, feature_flags_1.isPersonaEntitlementsEnabled)() || !userId) {
+        if (!userId) {
             return null;
         }
+        if (!(0, feature_flags_1.isPersonaEntitlementsEnabled)()) {
+            const key = apiKey
+                ? await this.dbService.verifyApiKey(apiKey)
+                : await this.dbService.getApiKeyByUserId(userId, false);
+            if (key?.accessScope !== 'persona')
+                return null;
+        }
         const decision = await (0, persona_entitlement_service_1.evaluatePersonaAccess)(this.dbService, userId, jobName, apiKey, `/fraim-brain?job=${encodeURIComponent(jobName)}`);
         if (decision.allowed) {
             if (consumeJobCredit && decision.entitlement?.hireMode === 'job' && decision.personaKey) {

package/dist/src/services/persona-entitlement-service.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.computeSubscriptionActive = computeSubscriptionActive;
+exports.hasUsablePersonaEntitlement = hasUsablePersonaEntitlement;
 exports.resolvePersonaAccessStatuses = resolvePersonaAccessStatuses;
 exports.buildUngatedPersonaWorkspaceState = buildUngatedPersonaWorkspaceState;
 exports.buildPersonaHireUrl = buildPersonaHireUrl;
@@ -10,25 +11,41 @@ exports.getWorkspacePersonaState = getWorkspacePersonaState;
 exports.evaluatePersonaAccess = evaluatePersonaAccess;
 const persona_hiring_1 = require("../config/persona-hiring");
 const persona_capability_bundles_1 = require("../config/persona-capability-bundles");
+const current_license_1 = require("../fraim/current-license");
 const workspace_identity_1 = require("./workspace-identity");
 const DEFAULT_JOB_CREDITS = 1;
 // The one place the "is the persona system gating this workspace?" question is
 // answered. A workspace is subscribed if it explicitly opted in (personaSystemActive)
-// or has ever held an active entitlement. Shared by getWorkspacePersonaState and
+// or has a recurring purchase record. Shared by getWorkspacePersonaState and
 // evaluatePersonaAccess so display and enforcement can never diverge.
 function computeSubscriptionActive(apiKeyData, entitlements) {
-    return apiKeyData?.personaSystemActive === true || entitlements.some((e) => e.status === 'active');
+    return apiKeyData?.accessScope === 'persona' || apiKeyData?.personaSystemActive === true
+        || entitlements.some((e) => e.status === 'active' || !!e.stripeSubscriptionId);
+}
+/** Access and display share expiry and credit checks, including exact deadlines. */
+function hasUsablePersonaEntitlement(entitlement, now = Date.now()) {
+    if (entitlement.status !== 'active')
+        return false;
+    if (entitlement.expiresAt && !(new Date(entitlement.expiresAt).getTime() > now))
+        return false;
+    if (entitlement.hireMode === 'fulltime' && entitlement.stripeSubscriptionId
+        && entitlement.purchaseSource !== 'manual' && !entitlement.expiresAt && !entitlement.billingAccessVerified)
+        return false;
+    return entitlement.hireMode !== 'job' || (entitlement.jobCreditsRemaining || 0) > 0;
 }
 // Single source of truth for per-persona access, mirroring evaluatePersonaAccess's
 // gating rules exactly:
-//   - `ungated` (feature flag OFF, or legacy/never-subscribed workspace) => every
+//   - `ungated` (legacy/never-subscribed workspace) => every
 //     persona is accessible ('hired').
 //   - otherwise => 'hired' iff the workspace holds an active entitlement for it.
 // Pure and DB-free so it is trivially testable and callable from either code path.
 function resolvePersonaAccessStatuses(ungated, entitlements) {
+    // MAESTRO is the catalog's full-team hire; it owns no individual jobs.
+    const maestroActive = entitlements.some((entitlement) => entitlement.personaKey === 'maestro'
+        && entitlement.hireMode === 'fulltime' && hasUsablePersonaEntitlement(entitlement));
     const activeByKey = new Map();
     for (const entitlement of entitlements) {
-        if (entitlement.status !== 'active')
+        if (!hasUsablePersonaEntitlement(entitlement))
             continue;
         const list = activeByKey.get(entitlement.personaKey) || [];
         list.push(entitlement);
@@ -42,16 +59,13 @@ function resolvePersonaAccessStatuses(ungated, entitlements) {
             personaName: bundle.catalogMetadata.displayName,
             personaRole: bundle.catalogMetadata.role,
             hireUrl: buildPersonaHireUrl(bundle.personaKey, bundle.defaultHireMode),
-            status: (ungated || active.length > 0) ? 'hired' : 'locked',
+            status: (ungated || maestroActive || active.length > 0) ? 'hired' : 'locked',
             seatCount,
         };
     });
 }
-// The persona-entitlements feature is OFF: there is no gating, so every persona is
-// accessible. Returned by /api/personas/me instead of a 404 so downstream consumers
-// (the Hub especially) inherit "flag off => all employees available" rather than
-// inventing their own fallback. Matches maybeBuildPersonaLockResponse, which also
-// short-circuits to "allowed" when the flag is off. No DB lookup is required.
+// Legacy workspaces with the rollout flag off retain their ungated presentation.
+// Purchased persona scope uses getWorkspacePersonaState even while rollout is off.
 function buildUngatedPersonaWorkspaceState(userId, apiKey) {
     return {
         featureFlagEnabled: false,
@@ -154,7 +168,7 @@ async function syncPersonaEntitlementPurchase(dbService, input) {
         jobCreditsIncluded,
         jobCreditsRemaining,
         activatedAt: existing?.activatedAt || new Date(),
-        expiresAt: input.expiresAt ?? existing?.expiresAt ?? null,
+        expiresAt: input.expiresAt !== undefined ? input.expiresAt : existing?.expiresAt ?? null,
         canceledAt: input.status === 'expired' ? new Date() : null,
         metadata: mergeMetadata(existing?.metadata, input.metadata)
     });
@@ -188,11 +202,40 @@ async function syncPersonaEntitlementFromCheckoutSession(dbService, session, pur
         metadata: session.metadata || {}
     });
 }
-async function getWorkspacePersonaState(dbService, userId, apiKey) {
+/** Recurring purchases inherit exact-subscription billing, never another hire's account access. */
+async function hydratePersonaBilling(dbService, entitlements, scope) {
+    const subscriptions = new Map();
+    return Promise.all(entitlements.map(async (entitlement) => {
+        if (entitlement.hireMode !== 'fulltime' || entitlement.purchaseSource === 'manual')
+            return entitlement;
+        const deny = { ...entitlement, status: 'expired', expiresAt: new Date(0), billingAccessVerified: false };
+        const subscriptionId = entitlement.stripeSubscriptionId;
+        if (!subscriptionId)
+            return deny;
+        if (!subscriptions.has(subscriptionId)) {
+            subscriptions.set(subscriptionId, dbService.getApiKeyByStripeSubscriptionId(subscriptionId));
+        }
+        const key = await subscriptions.get(subscriptionId);
+        if (!key || key.stripeSubscriptionId !== subscriptionId
+            || (key.userId && normalizeEmail(key.userId) !== scope.userId)
+            || (entitlement.userId && normalizeEmail(entitlement.userId) !== scope.userId)
+            || (key.orgId && key.orgId !== scope.orgId)
+            || (entitlement.orgId && entitlement.orgId !== scope.orgId)
+            || (key.workspaceId && key.workspaceId !== scope.workspaceId)
+            || (entitlement.workspaceId && entitlement.workspaceId !== scope.workspaceId)
+            || (key.stripeCustomerId && entitlement.stripeCustomerId && key.stripeCustomerId !== entitlement.stripeCustomerId))
+            return deny;
+        const usable = (0, current_license_1.hasUsableLicense)(key);
+        return { ...entitlement, billingAccessVerified: usable,
+            status: usable ? 'active' : key.status === 'suspended' ? 'suspended' : 'expired',
+            expiresAt: (0, current_license_1.effectiveLicenseExpiry)(key) };
+    }));
+}
+async function getWorkspacePersonaState(dbService, userId, apiKey, featureFlagEnabled = true) {
     const normalizedUserId = normalizeEmail(userId);
     let apiKeyData = null;
     if (apiKey) {
-        apiKeyData = await dbService.getApiKeyByKey(apiKey);
+        apiKeyData = await dbService.verifyApiKey(apiKey);
     }
     if (!apiKeyData) {
         apiKeyData = await dbService.getApiKeyByUserId(normalizedUserId, false);
@@ -206,9 +249,13 @@ async function getWorkspacePersonaState(dbService, userId, apiKey) {
     let entitlements = await dbService.getPersonaEntitlementsByWorkspaceId(workspace.workspaceId, false);
     // Fallback: when the local dev workspace has no API key the workspaceId may not
     // match the cust: prefix written by the Stripe checkout sync. Look up by userId.
-    if (entitlements.length === 0) {
+    if (entitlements.length === 0 && !apiKeyData?.workspaceId && !apiKeyData?.stripeCustomerId) {
         entitlements = await dbService.getPersonaEntitlementsByUserId(normalizedUserId, false);
     }
+    const subscriptionActive = computeSubscriptionActive(apiKeyData, entitlements);
+    const hydratedEntitlements = await hydratePersonaBilling(dbService, entitlements, {
+        userId: normalizedUserId, orgId: workspace.orgId, workspaceId: workspace.workspaceId
+    });
     const catalog = (0, persona_capability_bundles_1.listPersonaCapabilityBundles)().map((bundle) => ({
         personaKey: bundle.personaKey,
         personaName: bundle.catalogMetadata.displayName,
@@ -216,23 +263,23 @@ async function getWorkspacePersonaState(dbService, userId, apiKey) {
         hireUrl: buildPersonaHireUrl(bundle.personaKey, bundle.defaultHireMode),
         protectedJobs: bundle.protectedJobs
     }));
-    const knownPersonaKeys = new Set(entitlements.map((entitlement) => entitlement.personaKey));
-    const subscriptionActive = computeSubscriptionActive(apiKeyData, entitlements);
+    const personas = resolvePersonaAccessStatuses(!subscriptionActive, hydratedEntitlements);
+    const hiredPersonaKeys = new Set(personas.filter((persona) => persona.status === 'hired').map((persona) => persona.personaKey));
     return {
-        featureFlagEnabled: true,
+        featureFlagEnabled,
         featureFlags: {
-            personaEntitlementsEnabled: true
+            personaEntitlementsEnabled: featureFlagEnabled
         },
         subscriptionActive,
         workspaceId: workspace.workspaceId,
         userId: normalizedUserId,
         apiKey: apiKeyData?.key || apiKey || null,
-        entitlements: entitlements.map((entitlement) => ({
+        entitlements: hydratedEntitlements.map((entitlement) => ({
             personaKey: entitlement.personaKey,
             personaName: entitlement.personaName,
             personaRole: entitlement.personaRole,
             hireMode: entitlement.hireMode,
-            status: entitlement.status,
+            status: entitlement.status === 'active' && !hasUsablePersonaEntitlement(entitlement) ? 'expired' : entitlement.status,
             jobCreditsRemaining: entitlement.jobCreditsRemaining,
             expiresAt: entitlement.expiresAt ? entitlement.expiresAt.toISOString() : null,
             hireUrl: buildPersonaHireUrl(entitlement.personaKey, entitlement.hireMode),
@@ -242,21 +289,21 @@ async function getWorkspacePersonaState(dbService, userId, apiKey) {
         })),
         catalog,
         lockedPersonas: catalog
-            .filter((persona) => !knownPersonaKeys.has(persona.personaKey))
+            .filter((persona) => !hiredPersonaKeys.has(persona.personaKey))
             .map((persona) => ({
             ...persona,
             status: 'locked'
         })),
         // Authoritative per-persona verdict: a non-subscribed (legacy) workspace is
         // ungated, so all personas are accessible; a subscribed one gates to owned.
-        personas: resolvePersonaAccessStatuses(!subscriptionActive, entitlements),
+        personas,
     };
 }
 async function evaluatePersonaAccess(dbService, userId, jobName, apiKey, returnTo) {
     const normalizedUserId = normalizeEmail(userId);
     let apiKeyData = null;
     if (apiKey) {
-        apiKeyData = await dbService.getApiKeyByKey(apiKey);
+        apiKeyData = await dbService.verifyApiKey(apiKey);
     }
     if (!apiKeyData) {
         apiKeyData = await dbService.getApiKeyByUserId(normalizedUserId, false);
@@ -267,11 +314,11 @@ async function evaluatePersonaAccess(dbService, userId, jobName, apiKey, returnT
         stripeCustomerId: apiKeyData?.stripeCustomerId,
         workspaceId: apiKeyData?.workspaceId
     });
-    const workspaceEntitlements = await dbService.getPersonaEntitlementsByWorkspaceId(workspace.workspaceId, false);
+    const rawEntitlements = await dbService.getPersonaEntitlementsByWorkspaceId(workspace.workspaceId, false);
     // Legacy bypass: if the workspace has never subscribed to the persona system,
     // all jobs are freely accessible — no lock enforcement. Same rule the Hub
     // display inherits via resolvePersonaAccessStatuses(!subscriptionActive, ...).
-    const subscriptionActive = computeSubscriptionActive(apiKeyData, workspaceEntitlements);
+    const subscriptionActive = computeSubscriptionActive(apiKeyData, rawEntitlements);
     if (!subscriptionActive) {
         return {
             allowed: true,
@@ -280,8 +327,11 @@ async function evaluatePersonaAccess(dbService, userId, jobName, apiKey, returnT
             ownedPersonaKeys: []
         };
     }
+    const workspaceEntitlements = await hydratePersonaBilling(dbService, rawEntitlements, {
+        userId: normalizedUserId, orgId: workspace.orgId, workspaceId: workspace.workspaceId
+    });
     const ownedPersonaKeys = Array.from(new Set(workspaceEntitlements
-        .filter((entitlement) => entitlement.status === 'active')
+        .filter((entitlement) => hasUsablePersonaEntitlement(entitlement))
         .map((entitlement) => entitlement.personaKey)
         .filter((personaKey) => (0, persona_hiring_1.isPersonaHireKey)(personaKey))));
     const protectedPersonaKey = (0, persona_capability_bundles_1.getProtectedPersonaForJob)(jobName);
@@ -296,8 +346,14 @@ async function evaluatePersonaAccess(dbService, userId, jobName, apiKey, returnT
             ownedPersonaKeys
         };
     }
-    const fulltimeEntitlement = await dbService.getPersonaEntitlement(workspace.workspaceId, protectedPersonaKey, 'fulltime');
-    if (fulltimeEntitlement && fulltimeEntitlement.status === 'active') {
+    const maestroEntitlement = workspaceEntitlements.find((entitlement) => entitlement.personaKey === 'maestro'
+        && entitlement.hireMode === 'fulltime' && hasUsablePersonaEntitlement(entitlement));
+    if (maestroEntitlement) {
+        return { allowed: true, personaKey: protectedPersonaKey, workspaceId: workspace.workspaceId,
+            ownedPersonaKeys, entitlement: maestroEntitlement };
+    }
+    const fulltimeEntitlement = workspaceEntitlements.find(entitlement => entitlement.personaKey === protectedPersonaKey && entitlement.hireMode === 'fulltime');
+    if (fulltimeEntitlement && hasUsablePersonaEntitlement(fulltimeEntitlement)) {
         return {
             allowed: true,
             personaKey: protectedPersonaKey,
@@ -306,8 +362,8 @@ async function evaluatePersonaAccess(dbService, userId, jobName, apiKey, returnT
             entitlement: fulltimeEntitlement
         };
     }
-    const jobEntitlement = await dbService.getPersonaEntitlement(workspace.workspaceId, protectedPersonaKey, 'job');
-    if (jobEntitlement && jobEntitlement.status === 'active' && (jobEntitlement.jobCreditsRemaining || 0) > 0) {
+    const jobEntitlement = workspaceEntitlements.find(entitlement => entitlement.personaKey === protectedPersonaKey && entitlement.hireMode === 'job');
+    if (jobEntitlement && hasUsablePersonaEntitlement(jobEntitlement)) {
         return {
             allowed: true,
             personaKey: protectedPersonaKey,
@@ -330,7 +386,9 @@ async function evaluatePersonaAccess(dbService, userId, jobName, apiKey, returnT
         hireUrl = process.env.STRIPE_BILLING_PORTAL_URL || '/billing';
         ctaLabel = `Restore ${persona.displayName}`;
     }
-    else if (priorEntitlement?.status === 'expired') {
+    else if (priorEntitlement && (priorEntitlement.status === 'expired'
+        || (priorEntitlement.expiresAt && new Date(priorEntitlement.expiresAt).getTime() <= Date.now())
+        || (priorEntitlement.hireMode === 'fulltime' && !hasUsablePersonaEntitlement(priorEntitlement)))) {
         message = `${persona.displayName} was previously active in this workspace but is no longer active. Reactivate ${persona.displayName} to resume this request.`;
         ctaLabel = `Reactivate ${persona.displayName}`;
     }