fraim 2.0.297 → 2.0.299

package/dist/src/cli/utils/user-config.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getLayerBackend = getLayerBackend;
+exports.isLayerMisconfigured = isLayerMisconfigured;
 exports.setLayerBackend = setLayerBackend;
 exports.readUserFraimConfig = readUserFraimConfig;
 exports.writeUserFraimConfig = writeUserFraimConfig;
@@ -29,6 +30,25 @@ function getLayerBackend(layer) {
         return getManagerStorageConfig();
     return null;
 }
+/**
+ * Returns true when the layer has a config entry whose backend is recognized
+ * but the required pointer field is missing (git with no gitUrl, local-folder
+ * with no localPath). Callers use this to distinguish "not configured" from
+ * "misconfigured" so the UI can surface a warning instead of silently falling
+ * back to single-machine. (issue #1465, R3)
+ */
+function isLayerMisconfigured(layer) {
+    const raw = layer === 'org'
+        ? readUserFraimConfig().organization
+        : readUserFraimConfig().managerStorage;
+    if (!raw || typeof raw !== 'object')
+        return false;
+    if (raw.backend === 'git' && !raw.gitUrl)
+        return true;
+    if (raw.backend === 'local-folder' && !raw.localPath)
+        return true;
+    return false;
+}
 /** Write the backend config for a named layer (issue #834). */
 function setLayerBackend(layer, config) {
     if (layer === 'org') {

package/dist/src/config/persona-capability-bundles.js

@@ -113,11 +113,20 @@ exports.PERSONA_CAPABILITY_BUNDLES = {
         defaultHireMode: 'job',
         lockCopy: 'Hire SEChar to unlock security setup, review, and findings-command work for this request.'
     },
+    travis: {
+        personaKey: 'travis',
+        bundleId: 'persona-travis-core',
+        catalogMetadata: buildCatalogMetadata('travis', ['travel-planning', 'travel-disruption-rebooking', 'travel-fare-watch']),
+        protectedJobs: ['travel-planning', 'travel-disruption-rebooking', 'travel-fare-watch'],
+        protectedAliases: ['travel-agent', 'travel', 'trip-planning', 'rebooking', 'fare-watch', 'flight-watch'],
+        defaultHireMode: 'job',
+        lockCopy: 'Hire TRAVis to unlock trip planning, fare watching, travel disruption handling, and rebooking support for this request.'
+    },
     ashley: {
         personaKey: 'ashley',
         bundleId: 'persona-ashley-core',
         catalogMetadata: buildCatalogMetadata('ashley', ['chief-of-staff-briefing', 'executive-assistant', 'analyze-transcript']),
-        protectedJobs: ['chief-of-staff-briefing', 'calendar-triage', 'meeting-preparation', 'executive-assistant', 'analyze-transcript', 'travel-planning', 'travel-disruption-rebooking'],
+        protectedJobs: ['chief-of-staff-briefing', 'calendar-triage', 'meeting-preparation', 'executive-assistant', 'analyze-transcript'],
         protectedAliases: ['executive-assistant', 'operations-assistant'],
         defaultHireMode: 'job',
         lockCopy: 'Hire AshLey to unlock executive-assistant work for this request.'

package/dist/src/config/persona-hiring.js

@@ -199,6 +199,15 @@ exports.PERSONA_HIRE_CATALOG = {
         jobPriceCents: 890,
         fulltimePriceCents: 4990,
     },
+    travis: {
+        displayName: 'TRAVis',
+        role: 'Travel Agent',
+        emoji: '\u{1F9ED}',
+        gradient: 'linear-gradient(135deg, #0f766e 0%, #0ea5e9 100%)',
+        blurb: 'Plans trips, watches fares, handles travel disruptions, and helps with rebooking options while keeping provider limits and booking boundaries clear.',
+        jobPriceCents: 890,
+        fulltimePriceCents: 4990,
+    },
     ashley: {
         displayName: 'AshLey',
         role: 'Executive Assistant',
@@ -251,6 +260,7 @@ exports.PERSONA_AVATAR_CATALOG = {
     ricardo: { seed: 'RICARDO-recruiter', bg: 'ede9fe', style: 'notionists' },
     hari: { seed: 'HARI-hr', bg: 'ccfbf1', style: 'notionists' },
     careena: { seed: 'CAREENA-career-coach', bg: 'e0f2fe', style: 'notionists' },
+    travis: { seed: 'TRAVIS-travel-agent', bg: 'ccfbf1', style: 'notionists' },
     sade: { seed: 'SADE-salesforce', bg: 'bae6fd', style: 'notionists' },
     sam: { seed: 'SAM-sales-account', bg: 'd1fae5', style: 'notionists' },
     casey: { seed: 'CASEY-cx', bg: 'a5f3fc', style: 'notionists' },

package/dist/src/core/ai-mentor.js

@@ -83,7 +83,7 @@ class AIMentor {
         const validOutcomes = (0, resolve_phase_edge_1.discriminantKeys)(onSuccess)
             .map((key) => `"${key}"`)
             .join(' | ');
-        return `\n\n---\n\n## Report Back\nWhen this phase is done, call \`seekMentoring({ jobName: "${jobName}", issueNumber: "<issue_number>", currentPhase: "${phaseId}", status: "complete", findings: { issueType: "<outcome>" } })\` with one of: ${validOutcomes}.${failureNote}`;
+        return `\n\n---\n\n## Report Back\nWhen this phase is done, call \`seekMentoring({ jobName: "${jobName}", issueNumber: "<issue_number>", currentPhase: "${phaseId}", status: "complete", findings: { phaseOutcome: "<outcome>" } })\` with one of: ${validOutcomes}.${failureNote}`;
     }
     /** Phase-authority content injected for all phased workflows. Loaded from orchestration/phase-authority.md. */
     async getPhaseAuthorityContent() {
@@ -173,7 +173,14 @@ class AIMentor {
             nextPhaseId = (0, resolve_phase_edge_1.resolvePhaseEdge)(phaseFlow.onSuccess, (0, resolve_phase_edge_1.resolveDiscriminant)(findings, evidence));
         }
         let message = '';
-        if (nextPhaseId) {
+        if (nextPhaseId === resolve_phase_edge_1.WAITING_FOR_NEXT_INVOCATION) {
+            message += [
+                '### Waiting For Next Invocation',
+                '',
+                'Send a concise status update that this recurring assignment is waiting for its next scheduled check, then stop.'
+            ].join('\n');
+        }
+        else if (nextPhaseId) {
             message += `Moving to the next phase: **${nextPhaseId}**.\n\n`;
             let nextInstructions = workflow.phases.get(nextPhaseId);
             if (nextInstructions) {

package/dist/src/core/handoff-contracts.js

@@ -96,6 +96,42 @@ function validateAddressFeedbackApproval(evidence) {
     }
     return null;
 }
+function isAbsoluteHttpUrl(url) {
+    if (typeof url !== 'string' || !url)
+        return false;
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+function validateReviewArtifactEntry(artifact, index) {
+    const errors = [];
+    const label = `evidence.reviewHandoff.artifacts[${index}]`;
+    if (!artifact || typeof artifact !== 'object' || Array.isArray(artifact)) {
+        errors.push(`${label} must be an object`);
+        return errors;
+    }
+    const entry = artifact;
+    if ('kind' in entry && !('type' in entry)) {
+        errors.push(`${label} uses kind but must use type — use type, not kind for artifact type (e.g. "markdown", "docx", "source_file")`);
+    }
+    else if (!entry.type || typeof entry.type !== 'string' || !entry.type.trim()) {
+        errors.push(`${label}.type must be a non-empty string (e.g. "markdown", "docx", "source_file")`);
+    }
+    if (!entry.label || typeof entry.label !== 'string' || !entry.label.trim()) {
+        errors.push(`${label}.label must be a non-empty string`);
+    }
+    if ('url' in entry) {
+        errors.push(`${label} must not include url — artifact_set artifacts are local files; use path`);
+    }
+    if (!entry.path || typeof entry.path !== 'string' || !entry.path.trim()) {
+        errors.push(`${label}.path must be a non-empty local path`);
+    }
+    return errors;
+}
 /**
  * Validates evidence.reviewHandoff. Returns null if valid, or an array of
  * human-readable error strings describing what is wrong.
@@ -103,9 +139,16 @@ function validateAddressFeedbackApproval(evidence) {
  * Required minimum shape:
  * {
  *   reviewRequired: boolean,
- *   reviewTarget: object | null,
  *   artifacts: array,
+ *   // when reviewRequired is true:
+ *   reviewTarget: { type: "pull_request", label: string, url: string } | { type: "artifact_set", label: string },
+ *   reviewActions: [{ kind: "approve", ... }, { kind: "request_changes", ... }],
  * }
+ *
+ * Hub normalizers (server.ts + script.js) both read reviewTarget.type, not .kind.
+ * Using reviewTarget.kind produces a payload that passes validation but is silently
+ * un-renderable. This validator enforces the renderable contract so malformed payloads
+ * are rejected before phase advancement.
  */
 function validateReviewHandoff(value) {
     if (value === undefined || value === null) {
@@ -119,7 +162,42 @@ function validateReviewHandoff(value) {
     if (typeof obj.reviewRequired !== 'boolean') {
         errors.push(`evidence.reviewHandoff.reviewRequired must be a boolean (got ${obj.reviewRequired === undefined ? 'missing' : typeof obj.reviewRequired})`);
     }
+    // artifacts must always be present and be an array
+    if (!('artifacts' in obj) || !Array.isArray(obj.artifacts)) {
+        errors.push('evidence.reviewHandoff.artifacts must be an array');
+    }
     if (obj.reviewRequired === true) {
+        const target = obj.reviewTarget;
+        if (target === undefined || target === null) {
+            errors.push('evidence.reviewHandoff.reviewTarget must be a non-null object with type equal to "pull_request" or "artifact_set" when reviewRequired is true');
+        }
+        else if (typeof target !== 'object' || Array.isArray(target)) {
+            errors.push('evidence.reviewHandoff.reviewTarget must be an object with type equal to "pull_request" or "artifact_set"');
+        }
+        else {
+            const t = target;
+            if ('kind' in t && !('type' in t)) {
+                errors.push(`evidence.reviewHandoff.reviewTarget uses kind but must use type — use type, not kind (e.g. { type: "pull_request", label: "...", url: "https://..." })`);
+            }
+            else if (t.type !== 'pull_request' && t.type !== 'artifact_set') {
+                errors.push(`evidence.reviewHandoff.reviewTarget.type must be "pull_request" or "artifact_set" (got ${t.type === undefined ? 'missing' : JSON.stringify(t.type)})`);
+            }
+            else if (t.type === 'pull_request') {
+                if (!isAbsoluteHttpUrl(t.url)) {
+                    errors.push(`evidence.reviewHandoff.reviewTarget.url must be an absolute http or https URL for a pull_request target (got ${t.url === undefined ? 'missing' : JSON.stringify(t.url)})`);
+                }
+                if (Array.isArray(obj.artifacts) && obj.artifacts.length > 0) {
+                    errors.push('evidence.reviewHandoff.artifacts must be empty for a pull_request target — the PR is the complete review surface; set artifacts: []');
+                }
+            }
+            else if (t.type === 'artifact_set') {
+                if (Array.isArray(obj.artifacts)) {
+                    obj.artifacts.forEach((art, i) => {
+                        errors.push(...validateReviewArtifactEntry(art, i));
+                    });
+                }
+            }
+        }
         if (!Array.isArray(obj.reviewActions) || obj.reviewActions.length === 0) {
             errors.push('evidence.reviewHandoff.reviewActions must be a non-empty array when reviewRequired is true');
         }
@@ -135,6 +213,12 @@ function validateReviewHandoff(value) {
             }
         }
     }
+    else if (obj.reviewRequired === false && Array.isArray(obj.artifacts)) {
+        // For reviewRequired:false, validate any supplied artifact entries (no approval semantics required)
+        obj.artifacts.forEach((art, i) => {
+            errors.push(...validateReviewArtifactEntry(art, i));
+        });
+    }
     return errors.length > 0 ? errors : null;
 }
 /**
@@ -152,18 +236,39 @@ function validateNextJobRecommendations(value) {
         return ['evidence.nextJobRecommendations must be an array'];
     }
     const errors = [];
+    if (value.length > 3) {
+        errors.push('evidence.nextJobRecommendations must contain at most 3 entries');
+    }
     value.forEach((entry, i) => {
         if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
             errors.push(`evidence.nextJobRecommendations[${i}] must be an object`);
             return;
         }
         const rec = entry;
+        if ('jobName' in rec && !('jobId' in rec)) {
+            errors.push(`evidence.nextJobRecommendations[${i}] uses jobName, but runnable recommendations must use jobId. Use jobId, not jobName.`);
+        }
         if (typeof rec.jobId !== 'string' || !rec.jobId.trim()) {
             errors.push(`evidence.nextJobRecommendations[${i}].jobId must be a non-empty string`);
         }
         if (typeof rec.label !== 'string' || !rec.label.trim()) {
             errors.push(`evidence.nextJobRecommendations[${i}].label must be a non-empty string`);
         }
+        if (typeof rec.label === 'string' && rec.label.length > 60) {
+            errors.push(`evidence.nextJobRecommendations[${i}].label must be 60 characters or fewer`);
+        }
+        if (rec.reason !== undefined && typeof rec.reason !== 'string') {
+            errors.push(`evidence.nextJobRecommendations[${i}].reason must be a string when present`);
+        }
+        if (typeof rec.reason === 'string' && rec.reason.length > 200) {
+            errors.push(`evidence.nextJobRecommendations[${i}].reason must be 200 characters or fewer`);
+        }
+        if (rec.contextSummary !== undefined && typeof rec.contextSummary !== 'string') {
+            errors.push(`evidence.nextJobRecommendations[${i}].contextSummary must be a string when present`);
+        }
+        if (typeof rec.contextSummary === 'string' && rec.contextSummary.length > 300) {
+            errors.push(`evidence.nextJobRecommendations[${i}].contextSummary must be 300 characters or fewer`);
+        }
     });
     return errors.length > 0 ? errors : null;
 }
@@ -282,8 +387,12 @@ const REVIEW_HANDOFF_SCHEMA = `\`\`\`javascript
 evidence: {
   reviewHandoff: {
     reviewRequired: true,
-    reviewTarget: { kind: "pull_request", url: "<PR URL>" } | { kind: "artifact_set", files: ["<path>"] } | null,
-    artifacts: [{ label: "<label>", path: "<path>", kind: "<kind>" }],
+    // Pull request review (PR is the complete review surface -- set artifacts: []):
+    reviewTarget: { type: "pull_request", label: "Pull request", url: "https://github.com/org/repo/pull/N" },
+    artifacts: [],
+    // -- OR -- artifact set review (local generated files):
+    // reviewTarget: { type: "artifact_set", label: "Review bundle" },
+    // artifacts: [{ type: "markdown", label: "<label>", path: "<local-path>" }],
     summary: "<optional summary>",
     reviewActions: [
       { kind: "approve", label: "Approve" },
@@ -291,7 +400,8 @@ evidence: {
     ]
   }
 }
-\`\`\``;
+\`\`\`
+Note: reviewTarget uses "type" (not "kind"). Action entries use "kind" -- these are different fields.`;
 const NEXT_JOB_RECOMMENDATIONS_SCHEMA = `\`\`\`javascript
 evidence: {
   nextJobRecommendations: [

package/dist/src/core/resolve-phase-edge.js

@@ -15,13 +15,15 @@
  * change inert for every job that authors no map.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FEEDBACK_PHASE_ID = void 0;
+exports.FEEDBACK_PHASE_ID = exports.WAITING_FOR_NEXT_INVOCATION = void 0;
 exports.resolvePhaseEdge = resolvePhaseEdge;
 exports.resolveDiscriminant = resolveDiscriminant;
 exports.discriminantKeys = discriminantKeys;
 exports.derivePredecessorPhase = derivePredecessorPhase;
 /** The default discriminant, and the mandatory key on every authored map. */
 const DEFAULT_DISCRIMINANT = 'default';
+/** Reserved transition target that parks a recurring job until the scheduler invokes it again. */
+exports.WAITING_FOR_NEXT_INVOCATION = 'waiting-for-next-invocation';
 /**
  * Resolve an edge to the next phase id.
  *

package/dist/src/fraim/db-service.js

@@ -172,6 +172,8 @@ class FraimDbService {
         this.orgAuditCollection = this.db.collection('fraim_org_audit');
         // Issue #1345 — job execution modes (Coached/Trusted).
         this.jobExecutionModesCollection = this.db.collection('fraim_job_execution_modes');
+        // Issue #1431 — per-user referral codes.
+        this.referralCodesCollection = this.db.collection('fraim_referral_codes');
     }
     async initializeIndexes() {
         if (!this.db)
@@ -252,6 +254,9 @@ class FraimDbService {
         await this.auditLogCollection.createIndex({ sequence: 1 }).catch(() => { });
         await this.auditLogCollection.createIndex({ userId: 1, ts: -1 }).catch(() => { });
         await this.auditLogCollection.createIndex({ ts: -1 }).catch(() => { });
+        // Issue #1431 — referral codes: one code per user, globally unique codes.
+        await this.referralCodesCollection.createIndex({ userId: 1 }, { unique: true }).catch(() => { });
+        await this.referralCodesCollection.createIndex({ code: 1 }, { unique: true }).catch(() => { });
     }
     async createSession(session) {
         if (!this.sessionsCollection)
@@ -613,6 +618,65 @@ class FraimDbService {
             throw new Error('DB not connected');
         return await this.signupsCollection.findOne({ email });
     }
+    async setSignupAttribution(email, data) {
+        if (!this.signupsCollection)
+            throw new Error('DB not connected');
+        const now = new Date();
+        await this.signupsCollection.updateOne({ email }, {
+            $setOnInsert: {
+                email,
+                name: '',
+                company: '',
+                source: data.source,
+                timestamp: now,
+                ipAddress: data.ipAddress,
+                userAgent: data.userAgent,
+                ...(data.referrerName ? { referrerName: data.referrerName } : {}),
+                ...(data.referralCodeUsed ? { referralCodeUsed: data.referralCodeUsed } : {}),
+            },
+        }, { upsert: true });
+    }
+    generateReferralCodeString() {
+        const crypto = require('crypto');
+        const ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+        const bytes = crypto.randomBytes(12);
+        return Array.from(bytes).map((b) => ALPHABET[b % ALPHABET.length]).join('');
+    }
+    async getReferralCode(userId) {
+        if (!this.referralCodesCollection)
+            throw new Error('DB not connected');
+        return await this.referralCodesCollection.findOne({ userId });
+    }
+    async getOrCreateReferralCode(userId) {
+        if (!this.referralCodesCollection)
+            throw new Error('DB not connected');
+        const existing = await this.referralCodesCollection.findOne({ userId });
+        if (existing)
+            return existing.code;
+        for (let attempt = 0; attempt < 5; attempt++) {
+            const code = this.generateReferralCodeString();
+            try {
+                await this.referralCodesCollection.insertOne({ userId, code, createdAt: new Date() });
+                return code;
+            }
+            catch (err) {
+                if (err?.code === 11000) {
+                    const row = await this.referralCodesCollection.findOne({ userId });
+                    if (row)
+                        return row.code;
+                    continue;
+                }
+                throw err;
+            }
+        }
+        throw new Error('Failed to generate unique referral code after retries');
+    }
+    async validateReferralCode(code) {
+        if (!this.referralCodesCollection)
+            throw new Error('DB not connected');
+        const exists = await this.referralCodesCollection.findOne({ code });
+        return exists !== null;
+    }
     /** Get existing API key by userId (email for self-serve) */
     async getApiKeyByUserId(userId, activeOnly = true) {
         if (!this.db)

package/dist/src/local-mcp-server/learning-context-builder.js

@@ -1131,11 +1131,15 @@ function resolveTeamContextFile(workspaceRoot, key) {
     if (key === 'org' || key === 'orgRules') {
         const cachePath = (0, path_1.join)((0, pack_home_1.resolvePackHome)('org').contentRoot, relativePath);
         if ((0, fs_1.existsSync)(cachePath)) {
+            const fraimDir = (0, project_fraim_paths_1.getUserFraimDirPath)();
+            const orgDisplayPath = cachePath.startsWith(fraimDir)
+                ? (0, project_fraim_paths_1.getUserFraimDisplayPath)(cachePath.slice(fraimDir.length).replace(/\\/g, '/').replace(/^\//, ''))
+                : cachePath.replace(/\\/g, '/');
             return {
                 present: true,
                 readPath: cachePath,
                 writePath: '',
-                displayPath: (0, project_fraim_paths_1.getUserFraimDisplayPath)(`org/${relativePath}`),
+                displayPath: orgDisplayPath,
                 scope,
                 managedByOrgSync: true
             };
@@ -1146,16 +1150,16 @@ function resolveTeamContextFile(workspaceRoot, key) {
         const managerCachePath = (0, path_1.join)(managerHome.contentRoot, relativePath);
         if ((0, fs_1.existsSync)(managerCachePath)) {
             const fraimDir = (0, project_fraim_paths_1.getUserFraimDirPath)();
-            const relToFraim = managerCachePath.startsWith(fraimDir)
-                ? managerCachePath.slice(fraimDir.length).replace(/\\/g, '/').replace(/^\//, '')
-                : `personalized-employee/${relativePath}`;
+            const mgrDisplayPath = managerCachePath.startsWith(fraimDir)
+                ? (0, project_fraim_paths_1.getUserFraimDisplayPath)(managerCachePath.slice(fraimDir.length).replace(/\\/g, '/').replace(/^\//, ''))
+                : managerCachePath.replace(/\\/g, '/');
             return {
                 present: true,
                 readPath: managerCachePath,
-                writePath: '',
-                displayPath: (0, project_fraim_paths_1.getUserFraimDisplayPath)(relToFraim),
+                writePath: managerHome.requiresPublish ? '' : managerCachePath,
+                displayPath: mgrDisplayPath,
                 scope,
-                managedByManagerSync: true
+                ...(managerHome.requiresPublish ? { managedByManagerSync: true } : {})
             };
         }
     }

package/dist/src/local-mcp-server/learning-usage-attestation.js

@@ -25,15 +25,22 @@ const learning_context_builder_1 = require("./learning-context-builder");
 var learning_firing_parser_2 = require("./learning-firing-parser");
 Object.defineProperty(exports, "parseFiringSection", { enumerable: true, get: function () { return learning_firing_parser_2.parseFiringSection; } });
 Object.defineProperty(exports, "extractLegacyTitle", { enumerable: true, get: function () { return learning_firing_parser_2.extractLegacyTitle; } });
+const ENTRY_INDEX_READS = [
+    { scope: 'manager', level: 'machine' },
+    { scope: 'manager', level: 'project' },
+    { scope: 'org', level: 'machine' },
+    { scope: 'reverse', level: 'machine' },
+    { scope: 'reverse', level: 'project' },
+];
 function buildEntryIndex(workspaceRoot, userId) {
     const byId = new Map();
     const byTitle = new Map();
-    // Every scope a firing could name: the manager's own entries, the org entries
-    // the agent also reads, and the manager-coaching family.
-    for (const scope of ['manager', 'org', 'reverse']) {
+    // Keep this list in parity with the preserved-entry levels that the offer
+    // path can surface. Storage resolution stays inside readPreservedLearnings.
+    for (const { scope, level } of ENTRY_INDEX_READS) {
         let entries = [];
         try {
-            entries = (0, learning_context_builder_1.readPreservedLearnings)(workspaceRoot, userId, scope);
+            entries = (0, learning_context_builder_1.readPreservedLearnings)(workspaceRoot, userId, scope, level);
         }
         catch {
             continue;

package/dist/src/local-mcp-server/stdio-server.js

@@ -53,6 +53,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FraimLocalMCPServer = exports.FraimTemplateEngine = void 0;
 exports.parseExecutionModeFromResponse = parseExecutionModeFromResponse;
+exports.buildExecutionModeForwardUrl = buildExecutionModeForwardUrl;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const os_1 = require("os");
@@ -450,6 +451,19 @@ function parseExecutionModeFromResponse(text) {
         return null;
     }
 }
+// Issue #1443: the Hub's run registry is keyed by the host CLI's own session id
+// (run.sessionId, discovered from host stdout well after spawn — see
+// applyRunHostSessionSignal in ai-hub/server.ts), which has no relationship to the
+// FRAIM/MCP session id this proxy carries on every tool call. A lookup by the latter
+// never matches. FRAIM_HUB_RUN_ID is stamped into this process's env at spawn time
+// (AiHubServer.withHubRunIdEnv) specifically so this forward can target the run
+// directly; fall back to the (unreliable) session-based route only when the Hub that
+// spawned this process predates that fix.
+function buildExecutionModeForwardUrl(hubBase, hubRunId, requestSessionId) {
+    return hubRunId
+        ? `${hubBase}/api/ai-hub/runs/${encodeURIComponent(hubRunId)}/execution-mode`
+        : `${hubBase}/api/ai-hub/runs/by-session/${encodeURIComponent(requestSessionId)}/execution-mode`;
+}
 class FraimLocalMCPServer {
     constructor(writer) {
         this.config = null;
@@ -1427,7 +1441,8 @@ class FraimLocalMCPServer {
                 const hubBase = process.env.FRAIM_HUB_BASE_URL;
                 const em = parseExecutionModeFromResponse(responseText);
                 if (hubBase && em) {
-                    axios_1.default.post(`${hubBase}/api/ai-hub/runs/by-session/${encodeURIComponent(requestSessionId)}/execution-mode`, em, { headers: { 'Content-Type': 'application/json' } }).catch((err) => {
+                    const forwardUrl = buildExecutionModeForwardUrl(hubBase, process.env.FRAIM_HUB_RUN_ID, requestSessionId);
+                    axios_1.default.post(forwardUrl, em, { headers: { 'Content-Type': 'application/json' } }).catch((err) => {
                         this.log(`[req:${requestId}] execution-mode forward failed: ${err instanceof Error ? err.message : String(err)}`);
                     });
                 }
@@ -1500,6 +1515,25 @@ class FraimLocalMCPServer {
             return null;
         }
     }
+    async validateNextJobRecommendationJobIds(value, mentor) {
+        if (!Array.isArray(value))
+            return [];
+        const errors = [];
+        for (let i = 0; i < value.length; i++) {
+            const entry = value[i];
+            if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+                continue;
+            const jobId = entry.jobId;
+            if (typeof jobId !== 'string' || !jobId.trim())
+                continue;
+            const normalizedJobId = jobId.trim();
+            const job = await mentor.getJobOverview(normalizedJobId);
+            if (!job) {
+                errors.push(`evidence.nextJobRecommendations[${i}].jobId must reference a known FRAIM job (got "${normalizedJobId}")`);
+            }
+        }
+        return errors;
+    }
     async finalizeLocalToolTextResponse(request, requestSessionId, requestId, text) {
         const response = {
             jsonrpc: '2.0',
@@ -2255,6 +2289,7 @@ class FraimLocalMCPServer {
                         findings: args.findings,
                         phases: handoffPhaseMap,
                     });
+                    handoffErrors.push(...await this.validateNextJobRecommendationJobIds(args.evidence?.nextJobRecommendations, mentor));
                     if (handoffErrors.length > 0) {
                         const missingField = handoffErrors[0].includes('reviewHandoff') ? 'reviewHandoff'
                             : handoffErrors[0].includes('nextJobRecommendations') ? 'nextJobRecommendations'

package/dist/src/middleware/auth.js

@@ -38,7 +38,7 @@ class AuthMiddleware {
                 res.setHeader('WWW-Authenticate', `Bearer resource_metadata="${mcpResourceMetadataUrl}"`);
             }
         };
-        const publicPrefixes = ['/admin', '/dashboard', '/health', '/pricing', '/fraim-brain', '/installers', '/api/signup', '/api/sales', '/api/request-access', '/api/installer-key', '/api/installer-download', '/api/installer-availability', '/api/payment/bypass', '/api/pricing', '/api/personas/catalog', '/api/ai-hub/ui/releases', '/ai-hub-remote', '/auth', '/portfolio'];
+        const publicPrefixes = ['/admin', '/dashboard', '/health', '/pricing', '/fraim-brain', '/installers', '/api/signup', '/api/sales', '/api/request-access', '/api/installer-key', '/api/installer-download', '/api/installer-availability', '/api/payment/bypass', '/api/pricing', '/api/personas/catalog', '/api/ai-hub/ui/releases', '/ai-hub-remote', '/auth', '/portfolio', '/api/referral'];
         // Analytics dashboard is public, but API routes are protected
         const isAnalyticsPublic = p === '/analytics' || p === '/analytics/' || p.startsWith('/analytics/') && p.endsWith('.html');
         const isOAuthMetadataPublic = p === '/.well-known/oauth-authorization-server'

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

@@ -417,6 +417,45 @@ function registerProtectedAuthRoutes(app, deps) {
             return res.status(500).json({ ok: false });
         }
     });
+    app.get('/api/account/referral-code', async (req, res) => {
+        try {
+            const apiKeyData = req.apiKeyData;
+            if (!apiKeyData)
+                return res.status(401).json({ ok: false });
+            const record = await dbService.getReferralCode(apiKeyData.userId);
+            return res.status(200).json({ code: record?.code ?? null });
+        }
+        catch (err) {
+            console.error('[FRAIM AUTH] /api/account/referral-code GET error:', err instanceof Error ? err.message : String(err));
+            return res.status(500).json({ ok: false });
+        }
+    });
+    app.post('/api/account/referral-code', async (req, res) => {
+        try {
+            const apiKeyData = req.apiKeyData;
+            if (!apiKeyData)
+                return res.status(401).json({ ok: false });
+            const code = await dbService.getOrCreateReferralCode(apiKeyData.userId);
+            return res.status(200).json({ code });
+        }
+        catch (err) {
+            console.error('[FRAIM AUTH] /api/account/referral-code POST error:', err instanceof Error ? err.message : String(err));
+            return res.status(500).json({ ok: false });
+        }
+    });
+    app.get('/api/referral/validate', async (req, res) => {
+        try {
+            const code = String(req.query.code || '').trim().toUpperCase();
+            if (!code)
+                return res.status(200).json({ valid: false });
+            const valid = await dbService.validateReferralCode(code);
+            return res.status(200).json({ valid });
+        }
+        catch (err) {
+            console.error('[FRAIM AUTH] /api/referral/validate error:', err instanceof Error ? err.message : String(err));
+            return res.status(500).json({ valid: false });
+        }
+    });
     app.get('/api/account/activity', async (req, res) => {
         try {
             const apiKeyData = req.apiKeyData;

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

@@ -118,7 +118,7 @@ function registerOAuthRoutes(app, deps) {
     });
     // Helper used by both providers to finalise authentication once we have a verified email.
     async function completeSignIn(req, res, params) {
-        const { verifiedEmail, provider, surface, redirectTo, intent, hubReturn } = params;
+        const { verifiedEmail, provider, surface, redirectTo, intent, hubReturn, referrerName, referralCode } = params;
         const lower = verifiedEmail.toLowerCase();
         const apiKeyData = await dbService.getApiKeyByUserId(lower, false);
         let apiKeyForHubReturn = apiKeyData?.key ?? '';
@@ -141,6 +141,17 @@ function registerOAuthRoutes(app, deps) {
         }
         if (!apiKeyData && intent === 'signup') {
             apiKeyForHubReturn = await (0, account_provisioning_1.ensureTrialApiKey)(dbService, lower);
+            // Issue #1431: write attribution once for new OAuth accounts. Uses upsert
+            // with $setOnInsert so repeat signups never overwrite original attribution.
+            if (referrerName || referralCode) {
+                await dbService.setSignupAttribution(lower, {
+                    source: `oauth:${provider}`,
+                    ...(referrerName ? { referrerName } : {}),
+                    ...(referralCode ? { referralCodeUsed: referralCode.toUpperCase() } : {}),
+                    userAgent: typeof req.headers['user-agent'] === 'string' ? req.headers['user-agent'] : undefined,
+                    ipAddress: (0, oauth_helpers_1.clientIpFromReq)(req),
+                }).catch(() => { });
+            }
         }
         const sessionId = (0, oauth_helpers_1.generateSessionId)();
         await dbService.createAuthSession({
@@ -174,6 +185,8 @@ function registerOAuthRoutes(app, deps) {
         const intent = pickIntent(req.query.intent);
         const redirectTo = (0, oauth_helpers_1.safeRedirectPath)(req.query.redirect_to, (0, oauth_helpers_1.defaultRedirectForSurface)(surface));
         const hubReturn = safeLoopbackHubReturn(req.query.hub_return);
+        const referrerName = typeof req.query.referrer_name === 'string' ? req.query.referrer_name.trim().slice(0, 200) : undefined;
+        const referralCode = typeof req.query.referral_code === 'string' ? req.query.referral_code.trim().toUpperCase().slice(0, 20) : undefined;
         try {
             const codeVerifier = (0, oauth_helpers_1.generatePkceVerifier)();
             const stateNonce = (0, oauth_helpers_1.generateStateNonce)();
@@ -187,6 +200,8 @@ function registerOAuthRoutes(app, deps) {
                 stateNonce,
                 redirectTo,
                 hubReturn,
+                ...(referrerName ? { referrerName } : {}),
+                ...(referralCode ? { referralCode } : {}),
             });
             (0, cookie_service_1.setOAuthPendingCookie)(res, pendingId);
             await (0, audit_log_1.auditLog)('OAUTH_START', { provider, surface, ip: (0, oauth_helpers_1.clientIpFromReq)(req), outcome: 'success' });
@@ -297,6 +312,8 @@ function registerOAuthRoutes(app, deps) {
                 redirectTo: pending.redirectTo,
                 intent: pickIntent(pending.intent),
                 hubReturn: pending.hubReturn,
+                referrerName: pending.referrerName,
+                referralCode: pending.referralCode,
             });
         }
         catch (err) {
@@ -391,6 +408,8 @@ function registerOAuthRoutes(app, deps) {
                 redirectTo: pending.redirectTo,
                 intent: pickIntent(pending.intent),
                 hubReturn: pending.hubReturn,
+                referrerName: pending.referrerName,
+                referralCode: pending.referralCode,
             });
         }
         catch (err) {

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

@@ -130,7 +130,7 @@ class AdminService {
      * Security: prevents unauthorized access by requiring email ownership verification.
      */
     async requestAccess(body, req) {
-        const { email, name, company, useCase } = body;
+        const { email, name, company, useCase, referrerName, referralCode } = body;
         // Issue #691: signup is now email + verification code only. Name/company
         // are optional lead-capture fields (createWebsiteSignup below already
         // tolerates missing values); the trial key itself never required them.
@@ -150,11 +150,14 @@ class AdminService {
                 source: 'request-access',
                 timestamp: new Date(),
                 ipAddress,
-                userAgent
+                userAgent,
+                ...(referrerName ? { referrerName: referrerName.trim() } : {}),
+                ...(referralCode ? { referralCodeUsed: referralCode.trim().toUpperCase() } : {}),
             });
         }
         catch {
             // Ignore duplicate or other signup errors; email verification still proceeds.
+            // Attribution write-once: duplicate emails silently fail, preserving first attribution.
         }
         const verificationToken = (0, crypto_1.randomBytes)(32).toString('hex');
         const verificationCode = (0, email_code_1.generateEmailCode)();
@@ -166,7 +169,9 @@ class AdminService {
             verified: false,
             expiresAt,
             createdAt: new Date(),
-            usedAt: null
+            usedAt: null,
+            ...(referrerName ? { referrerName: referrerName.trim() } : {}),
+            ...(referralCode ? { referralCode: referralCode.trim().toUpperCase() } : {}),
         });
         const emailService = new email_service_1.EmailService();
         const baseUrl = process.env.BASE_URL || 'https://fraimworks.ai';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.297",
+  "version": "2.0.299",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {