fraim-hub 2.0.296 → 2.0.298

package/dist/src/ai-hub/desktop-main.js

@@ -630,12 +630,24 @@ async function bootstrap() {
     });
     await launchDesktopShell(options);
 }
-// Issue #1415: self-execution is now gated on `require.main === module` in addition to the
+function isDirectElectronEntry() {
+    if (require.main === module)
+        return true;
+    const currentFile = path_1.default.resolve(__filename).toLowerCase();
+    return process.argv.some((arg) => {
+        try {
+            return path_1.default.resolve(arg).toLowerCase() === currentFile;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+// Issue #1415: self-execution is gated on a direct Electron entry check in addition to the
 // existing Electron-main-process check, so `desktop-launcher.ts` requiring this file (bundled or
-// materialized) does not double-run bootstrap — the launcher calls the exported `bootstrap`
-// explicitly instead. Direct invocation (`npm run hub:desktop`, Electron-launching test suites)
-// is unaffected: this file is still `require.main` in that case.
-if (require.main === module && process.versions.electron && process.type !== 'renderer') {
+// materialized) does not double-run bootstrap. Electron's loader can own `require.main`, so
+// direct test launches also match the resolved script path in argv.
+if (isDirectElectronEntry() && process.versions.electron && process.type !== 'renderer') {
     bootstrap().catch(async (error) => {
         console.error(error instanceof Error ? error.message : error);
         await stopServerOnce();

package/dist/src/ai-hub/hosts.js

@@ -2257,13 +2257,15 @@ class FakeHostRuntime {
     detectEmployees() {
         return this.employees;
     }
-    startRun(hostId, _projectPath, message, handlers, _sessionId) {
+    startRun(hostId, _projectPath, message, handlers, _sessionId, launchContext) {
         this.lastStartMessage = message;
+        this.lastLaunchContext = launchContext;
         const reply = this.startReply ?? this.fakeEmployeeReply('start', message);
         return this.fakeProcess(hostId, reply, handlers);
     }
-    continueRun(hostId, _projectPath, sessionId, message, handlers) {
+    continueRun(hostId, _projectPath, sessionId, message, handlers, launchContext) {
         this.lastContinueMessage = message;
+        this.lastLaunchContext = launchContext;
         return this.fakeProcess(hostId, this.fakeEmployeeReply('continue', message), handlers);
     }
     startDirectRun(hostId, _message, _projectPath, handlers, _sessionId) {

package/dist/src/ai-hub/manager-turns.js

@@ -50,7 +50,7 @@ function buildCommunicationStyleNote() {
 function buildBackgroundTaskPolicyNote() {
     return [
         '',
-        '[Background task policy] You are running in Hub headless mode. Never end your turn while background tasks (bash commands started with run_in_background=true, or sub-agents) are still active. Instead: monitor them, poll for results, and provide periodic progress commentary to the manager. Only end your turn when all background tasks have finished, or when you genuinely need a user decision or input to continue. If you exit while a background task is active, the Hub loses the link to that task permanently.',
+        '[Background task policy] You are running in Hub headless mode. Never end your turn while background tasks (bash commands started with run_in_background=true, or sub-agents) are still active. Instead: monitor them, poll for results, and provide periodic progress commentary to the manager. Only end your turn when all background tasks have finished, or when you genuinely need a user decision or input to continue. If you exit while a background task is active, the Hub loses the link to that task permanently. Background tasks and Monitor watchers cannot survive this turn ending: the next turn is a new process with no link to the old one (Windows: hard-killed; Unix: orphaned). The two things that reliably work: run the command synchronously in the foreground within this turn, or supervise it with `npx tsx ~/.fraim/scripts/exec-with-timeout.ts --supervise <name> --timeout <n> -- <command>` and poll `--status`/`--wait` (or `--stop` to cancel) without ending your turn.',
     ].join('\n');
 }
 // Issue #732: a plain continue of the SAME active job must not re-load the job.

package/dist/src/ai-hub/server.js

@@ -39,6 +39,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.findAvailablePortExcluding = exports.findAvailablePort = exports.AiHubServer = exports.HubConnectorStatusStore = exports.HostConfigStore = exports.DeploymentStore = void 0;
 exports.selfHealBrokenManagedAgents = selfHealBrokenManagedAgents;
 exports.configureFraimForHubAgent = configureFraimForHubAgent;
+exports.installAgentAndRefreshDetection = installAgentAndRefreshDetection;
 exports.hubCommandVersion = hubCommandVersion;
 exports.buildOpenFileInvocation = buildOpenFileInvocation;
 const express_1 = __importDefault(require("express"));
@@ -1760,6 +1761,30 @@ async function configureFraimForHubAgent(hubId) {
         return { configured: false, error: e instanceof Error ? e.message : String(e) };
     }
 }
+// Issue #1429: extracted from the install-agent route so the post-install cache-invalidation
+// policy is directly unit-testable with fake deps (no real npm install, no running HTTP
+// server) rather than only reachable by exercising the whole route.
+//
+// Root cause of #1429: this used to invalidate only when `outcome.outcome === 'standard'`.
+// When the CLI is installed via FRAIM's own managed-Node fallback (`outcome === 'managed'` -
+// exactly what happens when a CLI is reachable only through FRAIM's managed install
+// directory, not the Hub process's inherited system PATH), the cache was never invalidated,
+// so `detectEmployees()` (which backs `configured-agents`/`reconfigure-surfaces`/the employee
+// roster) kept serving its pre-install "unavailable" answer for up to
+// `EMPLOYEE_DETECTION_TTL_MS` (5 minutes) while `check-agent`'s uncached `hubCommandVersion()`
+// found the freshly-installed managed copy immediately - the exact divergence reported.
+// `selfHealBrokenManagedAgents()` already establishes the correct pattern (invalidate
+// unconditionally after any successful install); this now matches it.
+async function installAgentAndRefreshDetection(option, systemPath, deps) {
+    const outcome = await (0, managed_agent_install_1.installManagedAgent)(option, systemPath, deps);
+    // Issue #1010/#1429: something is now installed that was not before - via a standard
+    // system-PATH install OR FRAIM's own managed-Node fallback - so the cached agent-
+    // availability answer is stale either way. Drop it here rather than waiting out the TTL,
+    // so the newly installed CLI shows as available immediately regardless of which install
+    // path produced it.
+    (0, hosts_1.invalidateEmployeeDetectionCache)();
+    return outcome;
+}
 // Exported for direct unit testing of the Defect D fix (issue #1284/#1285):
 // asserting this resolves via a real system install and skips a poisoned
 // project-local node_modules/.bin entry, without spinning up a full server.
@@ -2199,6 +2224,7 @@ function buildHubBackgroundTaskContinueMessage(run) {
         `Session id: ${run.sessionId || 'unknown'}`,
         'The background task may still be running as an orphan process. Check whether its results are available on disk and continue your work.',
         'If results are not yet available, wait briefly or check again. Once you have the results, continue with your original plan.',
+        'Going forward, do not end your turn while this kind of task is active: either run it synchronously in the foreground, or supervise it with `npx tsx ~/.fraim/scripts/exec-with-timeout.ts --supervise <name> --timeout <n> -- <command>` and poll `--status`/`--wait` without ending your turn — ending the turn is what put this task at risk the first time.',
     ].join('\n');
 }
 // #1419 (Change 3): auto-resume when the only unresolved condition is a
@@ -2224,6 +2250,7 @@ function buildHubBackgroundTaskLostContinueMessage(run, killedDescription) {
         `A background task was killed when a turn ended before it reached a terminal state: ${killedDescription || describeKilledBackgroundTasks(run)}.`,
         'Its result is unknown, not passing or failing.',
         'Check for partial output first; if none exists, re-run the work and say plainly that this is a re-run because the prior attempt\'s result was never observed.',
+        'When you re-run it, do not repeat the mistake: run it synchronously in the foreground, or supervise it with `npx tsx ~/.fraim/scripts/exec-with-timeout.ts --supervise <name> --timeout <n> -- <command>` and poll `--status`/`--wait` without ending your turn — ending the turn is what killed it the first time.',
     ].join('\n');
 }
 function isHumanActionGate(run) {
@@ -3130,6 +3157,28 @@ class AiHubServer {
             launchContext: { agent: resolved.agent, env },
         };
     }
+    // Issue #1443: stamp the Hub's own run id into the spawned host process's
+    // env so the local FRAIM MCP proxy (a grandchild of this spawn, wired to
+    // the host CLI over stdio) can report run-scoped signals like executionMode
+    // back to the correct run. The proxy has no other way to know it: the FRAIM
+    // workflow/MCP session id it carries is minted independently of any Hub run,
+    // and the host CLI's own session id (`run.sessionId`, set via
+    // applyRunHostSessionSignal) is not known until the host reports it — often
+    // well after the FRAIM MCP tools have already fired. FRAIM_HUB_RUN_ID is set
+    // at spawn time instead, so it is available for the entire life of the
+    // process. Call this at every startRun/continueRun call site (Direct-mode
+    // spawns are exempt — they never load FRAIM, so there is nothing to report).
+    withHubRunIdEnv(launchContext, runId) {
+        return { ...launchContext, env: { ...(launchContext.env || {}), FRAIM_HUB_RUN_ID: runId } };
+    }
+    // Shared by both the runId-keyed and legacy by-session execution-mode routes.
+    applyExecutionModeToRun(runId, body) {
+        const normalizedMode = body.mode === 'trusted' ? 'trusted' : 'coached';
+        const normalizedRuns = typeof body.completedRuns === 'number' ? body.completedRuns : 0;
+        this.runRegistry.update(runId, (current) => {
+            current.executionMode = { mode: normalizedMode, completedRuns: normalizedRuns };
+        });
+    }
     configuredAgentIdForConversation(conversation, employees) {
         const existingConfiguredAgentId = typeof conversation.configuredAgentId === 'string'
             ? conversation.configuredAgentId.trim()
@@ -3328,9 +3377,17 @@ class AiHubServer {
     conversationRecordFromRun(run) {
         const lastUpdatedAt = run.updatedAt || new Date().toISOString();
         const stages = deriveStages(run, run.projectPath);
+        const rawScope = run.scope
+            ?? run.invokedArea;
+        const recordScope = rawScope === 'manager' || rawScope === 'company' ? rawScope : 'project';
+        const recordProjectPath = recordScope === 'manager'
+            ? conversation_store_1.MANAGER_SCOPE_KEY
+            : recordScope === 'company'
+                ? conversation_store_1.COMPANY_SCOPE_KEY
+                : path_1.default.resolve(run.projectPath);
         const record = {
             id: run.conversationId || run.id,
-            projectPath: path_1.default.resolve(run.projectPath),
+            projectPath: recordProjectPath,
             title: run.conversationTitle || run.jobTitle || run.jobId,
             jobId: run.jobId,
             jobTitle: run.jobTitle || run.jobId,
@@ -3392,9 +3449,7 @@ class AiHubServer {
             sourceTrigger: run.sourceTrigger,
             // Issue #708: carry the invocation scope so the record lands in (and is keyed to)
             // the right bucket. Falls back to the legacy client `invokedArea` when present.
-            scope: run.scope
-                ?? run.invokedArea
-                ?? 'project',
+            scope: recordScope,
             run: {
                 stages,
                 currentPhase: run.currentPhase || null,
@@ -3509,7 +3564,7 @@ class AiHubServer {
                     this.maybeStartDelegatedChildRuns(updated);
                 });
             },
-        }, startSessionSeedForHost(run.hostId, run.id), freshLaunch.launchContext);
+        }, startSessionSeedForHost(run.hostId, run.id), this.withHubRunIdEnv(freshLaunch.launchContext, run.id));
         this.runRegistry.attachChildIfRunning(run.id, freshChild);
     }
     scheduleRunConversationPersistence(run, activeId) {
@@ -3802,7 +3857,7 @@ class AiHubServer {
             onExit: (exitCode) => {
                 this.handleRunExit(currentRun.id, exitCode, options.postPark);
             },
-        }, launch.launchContext);
+        }, this.withHubRunIdEnv(launch.launchContext, currentRun.id));
         this.runRegistry.attachChildIfRunning(currentRun.id, child);
         const updated = this.runRegistry.get(currentRun.id);
         if (updated)
@@ -4133,7 +4188,7 @@ class AiHubServer {
                 }
                 this.runRegistry.dispose(childRun.id);
             },
-        }, startSessionSeedForHost(managerRun.hostId, childRun.id), childLaunch.launchContext);
+        }, startSessionSeedForHost(managerRun.hostId, childRun.id), this.withHubRunIdEnv(childLaunch.launchContext, childRun.id));
         this.runRegistry.attachChildIfRunning(childRun.id, child);
     }
     notifyManagerOfDelegatedChild(managerRunId, childRun) {
@@ -4290,7 +4345,7 @@ class AiHubServer {
                 if (latestManager)
                     this.drainPendingDelegatedReviews(latestManager);
             },
-        }, managerLaunch.launchContext);
+        }, this.withHubRunIdEnv(managerLaunch.launchContext, managerRun.id));
         this.runRegistry.attachChildIfRunning(managerRun.id, child);
     }
     computeFirstRun(projectPath, jobCount, personas) {
@@ -5227,8 +5282,8 @@ class AiHubServer {
                         },
                     };
                     const child = strategy === 'resume_same_host'
-                        ? this.hostRuntime.continueRun(run.hostId, run.projectPath, priorSessionId, hostMessage, handlers, resolved.launchContext)
-                        : this.hostRuntime.startRun(run.hostId, run.projectPath, hostMessage, handlers, startSessionSeedForHost(run.hostId, run.id), resolved.launchContext);
+                        ? this.hostRuntime.continueRun(run.hostId, run.projectPath, priorSessionId, hostMessage, handlers, this.withHubRunIdEnv(resolved.launchContext, run.id))
+                        : this.hostRuntime.startRun(run.hostId, run.projectPath, hostMessage, handlers, startSessionSeedForHost(run.hostId, run.id), this.withHubRunIdEnv(resolved.launchContext, run.id));
                     this.runRegistry.attachChildIfRunning(run.id, child);
                     attemptedRunId = null;
                     console.info(`[ai-hub] hub.agent_switch.${strategy}`, {
@@ -5693,7 +5748,7 @@ class AiHubServer {
                         loginHint: `Once installed, click "Check if Ready" to verify ${option.label} is on your PATH.`,
                     });
                 }
-                const outcome = await (0, managed_agent_install_1.installManagedAgent)({ label: option.label, installPackage: option.installPackage, launchCommand: option.launchCommand }, systemPath, { runProcess: hubRunProcess, commandVersion: hubCommandVersion });
+                const outcome = await installAgentAndRefreshDetection({ label: option.label, installPackage: option.installPackage, launchCommand: option.launchCommand }, systemPath, { runProcess: hubRunProcess, commandVersion: hubCommandVersion });
                 if (outcome.outcome === 'standard' && outcome.npmGlobalBinDirs.length > 0) {
                     process.env.PATH = (0, managed_agent_paths_1.appendBinDirsToPath)(systemPath, outcome.npmGlobalBinDirs);
                 }
@@ -5701,12 +5756,6 @@ class AiHubServer {
                 if (!mcp.configured) {
                     console.warn(`[ai-hub] install-agent: FRAIM add-ide did not run for ${option.label} (${outcome.outcome} install): ${mcp.error || 'unknown reason'}`);
                 }
-                if (outcome.outcome === 'standard') {
-                    // Issue #1010: something is now installed that was not before, so the cached
-                    // agent-availability answer is stale. Drop it here rather than waiting out the
-                    // TTL, so the newly installed CLI shows as available immediately.
-                    (0, hosts_1.invalidateEmployeeDetectionCache)();
-                }
                 return res.json({
                     ok: true,
                     message: `${option.label} installed successfully.`,
@@ -5832,21 +5881,35 @@ class AiHubServer {
         });
         // Issue #1345: accept executionMode forwarded from get_fraim_job response by the local proxy.
         // The proxy parses the Execution Mode Context block and POSTs here; Hub script reads from run poll.
+        //
+        // Issue #1443: the local proxy's only stable identity for "which run is this" is the
+        // Hub's own run id (see withHubRunIdEnv / FRAIM_HUB_RUN_ID) — the FRAIM/MCP session id it
+        // carries is unrelated to any Hub run, and the host CLI's own session id (run.sessionId)
+        // often isn't known yet when the first get_fraim_job call fires. Runs by id, not session.
+        this.app.post('/api/ai-hub/runs/:runId/execution-mode', (req, res) => {
+            if (!this.requireTrustedHubOrigin(req, res))
+                return;
+            const run = this.runRegistry.get(req.params.runId);
+            if (!run)
+                return res.status(404).json({ error: 'Run not found.' });
+            this.applyExecutionModeToRun(run.id, req.body);
+            return res.json({ ok: true });
+        });
+        // Legacy fallback for a local proxy build that predates #1443 and has not yet been
+        // updated to send FRAIM_HUB_RUN_ID. Session-id correlation is unreliable by construction
+        // (see the comment above), so this only succeeds when a run happens to already carry a
+        // matching sessionId; it exists to avoid a hard 404 during a mixed-version rollout, not as
+        // a supported correlation path.
         this.app.post('/api/ai-hub/runs/by-session/:sessionId/execution-mode', (req, res) => {
             if (!this.requireTrustedHubOrigin(req, res))
                 return;
             const { sessionId } = req.params;
-            const { mode, completedRuns } = req.body;
             if (!sessionId)
                 return res.status(400).json({ error: 'sessionId required' });
-            const normalizedMode = mode === 'trusted' ? 'trusted' : 'coached';
-            const normalizedRuns = typeof completedRuns === 'number' ? completedRuns : 0;
             const run = this.runRegistry.all().find((r) => r.sessionId === sessionId);
             if (!run)
                 return res.status(404).json({ error: 'Run not found for session.' });
-            this.runRegistry.update(run.id, (current) => {
-                current.executionMode = { mode: normalizedMode, completedRuns: normalizedRuns };
-            });
+            this.applyExecutionModeToRun(run.id, req.body);
             return res.json({ ok: true });
         });
         this.app.post('/api/ai-hub/runs', (req, res) => {
@@ -6031,7 +6094,7 @@ class AiHubServer {
                             this.maybeStartDelegatedChildRuns(updated);
                         });
                     },
-                }, startSessionSeedForHost(hostId, run.id), launchContext);
+                }, startSessionSeedForHost(hostId, run.id), this.withHubRunIdEnv(launchContext, run.id));
                 this.runRegistry.attachChildIfRunning(run.id, child);
                 // Issue #442: spawn the Direct run via startDirectRun so CliHostRuntime
                 // uses buildDirectStartPlan (--strict-mcp-config, raw stdin) rather than
@@ -6250,7 +6313,7 @@ class AiHubServer {
                                 this.maybeStartDelegatedChildRuns(updated);
                             });
                         },
-                    }, startSessionSeedForHost(run.hostId, run.id), freshLaunch.launchContext);
+                    }, startSessionSeedForHost(run.hostId, run.id), this.withHubRunIdEnv(freshLaunch.launchContext, run.id));
                     this.runRegistry.attachChildIfRunning(run.id, freshChild);
                     const refreshedFresh = this.runRegistry.get(run.id);
                     return res.json(refreshedFresh ? this.enrichRunForResponse(refreshedFresh) : refreshedFresh);
@@ -6335,7 +6398,7 @@ class AiHubServer {
                             this.maybeStartDelegatedChildRuns(updated);
                         });
                     },
-                }, continueLaunch.launchContext, deliveryIntent);
+                }, this.withHubRunIdEnv(continueLaunch.launchContext, run.id), deliveryIntent);
                 if (!startedCodexReviewApprovalFallback)
                     this.runRegistry.attachChildIfRunning(run.id, child);
                 const refreshed = this.runRegistry.get(run.id);
@@ -6494,7 +6557,7 @@ class AiHubServer {
                     onExit: (exitCode) => {
                         this.handleRunExit(run.id, exitCode);
                     },
-                }, launchContext);
+                }, this.withHubRunIdEnv(launchContext, run.id));
                 this.runRegistry.attachChildIfRunning(run.id, child);
                 res.status(201).json(this.enrichRunForResponse(this.runRegistry.get(run.id) ?? run));
             }
@@ -7263,7 +7326,7 @@ class AiHubServer {
                             this.finalizeRunConversationProjection(run.id, updated.conversationId || updated.id);
                         this.runRegistry.dispose(run.id);
                     },
-                }, startSessionSeedForHost(hostId, run.id), launchContext);
+                }, startSessionSeedForHost(hostId, run.id), this.withHubRunIdEnv(launchContext, run.id));
                 // Update the registry entry with the real child process handle.
                 this.runRegistry.attachChildIfRunning(run.id, child);
                 return res.json({ runId: run.id, status: 'started', employee: employeeId, job: jobName });
@@ -7423,7 +7486,7 @@ class AiHubServer {
                 this.deploymentStore.update(deployment.id, (d) => { d.activeRunId = undefined; });
                 this.runRegistry.dispose(run.id);
             },
-        }, startSessionSeedForHost(hostId, run.id), launchContext);
+        }, startSessionSeedForHost(hostId, run.id), this.withHubRunIdEnv(launchContext, run.id));
         this.runRegistry.create(run, child);
         return run;
     }
@@ -7579,7 +7642,7 @@ class AiHubServer {
                             this.scheduleRunConversationPersistence(updated, updated.conversationId || updated.id);
                     },
                     onExit: (code) => this.handleRunExit(runId, code, postPark),
-                }, launchContext);
+                }, this.withHubRunIdEnv(launchContext, runId));
                 this.runRegistry.attachChildIfRunning(runId, child);
             }, delay);
             if (tid.unref)

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-hub",
-  "version": "2.0.296",
+  "version": "2.0.298",
   "description": "FRAIM Hub local companion package.",
   "author": "Sid Mathur <sid.mathur@gmail.com>",
   "homepage": "https://github.com/mathursrus/FRAIM#readme",
@@ -211,7 +211,7 @@
     "electron-updater": "^6.8.9",
     "express": "^5.2.1",
     "extract-zip": "^2.0.1",
-    "fraim": "2.0.296",
+    "fraim": "2.0.298",
     "mongodb": "^7.0.0",
     "node-cron": "4.2.1",
     "node-edge-tts": "^1.2.10",

package/public/ai-hub/script.js

@@ -8515,6 +8515,12 @@ function convNeedsPolling(conv) {
 }
 
 function switchToConversation(id) {
+  const conv = findConversation(id);
+  const scope = convScope(conv);
+  const targetArea = scope === 'manager' || scope === 'company' ? scope : 'projects';
+  if (conv && tf.area !== targetArea) {
+    tfShowArea(targetArea);
+  }
   state.activeId = id;
   persistActiveConversationSelection(id);
   // Issue #1065: a find session belongs to one thread. srchOpenResult re-opens it with the search
@@ -8522,23 +8528,23 @@ function switchToConversation(id) {
   if (typeof convFindClose === 'function') convFindClose();
   // For Company/Manager: move the shared .page into this area's conv-host and
   // switch from the info view to the full coaching panel.
-  if (tf.area === 'company' || tf.area === 'manager') {
-    tfEnsurePageInArea(tf.area);
-    const host = document.getElementById(tf.area + '-conv-host');
-    const info = document.getElementById(tf.area + '-info-view');
+  if (targetArea === 'company' || targetArea === 'manager') {
+    tfEnsurePageInArea(targetArea);
+    const host = document.getElementById(targetArea + '-conv-host');
+    const info = document.getElementById(targetArea + '-info-view');
     if (host) host.hidden = false;
     if (info) info.hidden = true;
     // #1397: an area selection represents every explicit destination, not only
     // the Info view. Poll-driven renders must preserve this conversation until
     // the user chooses another destination or the conversation disappears.
-    if (tf.areaSelection) tf.areaSelection[tf.area] = id;
+    if (tf.areaSelection) tf.areaSelection[targetArea] = id;
   }
   renderRail();
   renderActive();
-  hydrateConversationBody(state.projectPath, id).catch((error) =>
+  hydrateConversationBody(conv ? convBucketKey(conv) : state.projectPath, id).catch((error) =>
     console.warn('Could not hydrate switched conversation body:', error));
-  const conv = activeConversation();
-  if (convNeedsPolling(conv)) {
+  const active = activeConversation();
+  if (convNeedsPolling(active)) {
     startPolling();
   } else if (state.pollHandle) {
     window.clearInterval(state.pollHandle);
@@ -11050,7 +11056,9 @@ async function tfSelectProjectView(view, projectId) {
     if (tab.id === 'ptab-add') continue;
     const isOverview = tab.id === 'ptab-overview';
     const matchesProj = tab.dataset.projectId === tf.activeProjectId;
-    tab.classList.toggle('on', view === 'overview' ? isOverview : matchesProj);
+    const isOn = view === 'overview' ? isOverview : matchesProj;
+    tab.classList.toggle('on', isOn);
+    if (isOn && matchesProj) tab.scrollIntoView({ behavior: 'instant', block: 'nearest', inline: 'nearest' });
   }
   if (view === 'overview') {
     tfRenderOverview();
@@ -11187,6 +11195,8 @@ function tfRenderProjectTabs() {
     btn.addEventListener('click', () => tfSelectProjectView('workspace', proj.id));
     host.appendChild(btn);
   }
+  const activeTab = host.querySelector('.ptab.on');
+  if (activeTab) activeTab.scrollIntoView({ behavior: 'instant', block: 'nearest', inline: 'nearest' });
 }
 
 function tfRenderOverview() {