fraim-framework 2.0.199 → 2.0.201

package/dist/src/ai-hub/conversation-store.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AiHubConversationStore = exports.COMPANY_SCOPE_KEY = exports.MANAGER_SCOPE_KEY = void 0;
 exports.conversationScopeKey = conversationScopeKey;
+exports.migrateConversationStore = migrateConversationStore;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
@@ -93,6 +94,103 @@ function migrateScopeBuckets(store) {
     }
     return { version: 1, projects };
 }
+// Canonical comparison key for a project path (case-insensitive on win32), matching the
+// convention used by removeProject and the preferences store.
+function canonicalProjectPathKey(value) {
+    const resolved = path_1.default.resolve(value);
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+// How much run history a record carries. Used to decide the winner when the same conversation id
+// exists in two buckets: the copy with real history must never be overwritten by a header-only
+// shell (which is exactly what a mis-filed slim PUT produces).
+function conversationRichness(conv) {
+    const value = conv;
+    const messages = Array.isArray(value?.messages) ? value.messages.length : 0;
+    const events = Array.isArray(value?.events) ? value.events.length : 0;
+    return messages + events;
+}
+// Place a raw conversation into a bucket, deduping by id. When the id already exists, keep the
+// richer copy (more run history); tie-break on newer lastUpdatedAt. Order-independent.
+function placeConversationInBucket(bucket, conv) {
+    const value = conv;
+    const id = value && typeof value.id === 'string' ? value.id : '';
+    if (!id) {
+        bucket.conversations.push(conv);
+        return;
+    }
+    const idx = bucket.conversations.findIndex((entry) => entry && entry.id === id);
+    if (idx < 0) {
+        bucket.conversations.push(conv);
+        return;
+    }
+    const existing = bucket.conversations[idx];
+    const existingScore = conversationRichness(existing);
+    const incomingScore = conversationRichness(conv);
+    if (incomingScore > existingScore) {
+        bucket.conversations[idx] = conv;
+    }
+    else if (incomingScore === existingScore
+        && timestampValue(value?.lastUpdatedAt) > timestampValue(existing.lastUpdatedAt)) {
+        bucket.conversations[idx] = conv;
+    }
+}
+// A conversation's identity is unique only WITHIN a bucket, and a bucket key is a project path.
+// The buggy client PUT path could file a conversation whose own projectPath points at project B
+// into project A's bucket (see docs/rca/hub-conversation-cross-project-leak.md), so the same run
+// appeared under two projects and the mis-filed copy was a header-only shell. This one-time,
+// idempotent, read-time migration relocates every project-scoped record back to the bucket that
+// matches its own projectPath, deduping so the copy with real run history wins. A bucket activeId
+// that pointed at a relocated record is cleared. Sentinel scope buckets (@manager/@company)
+// legitimately hold records whose projectPath points at a project, so they are left untouched.
+function migrateProjectBuckets(store) {
+    const projects = {};
+    const ensure = (key) => {
+        if (!projects[key])
+            projects[key] = { activeId: null, conversations: [] };
+        return projects[key];
+    };
+    // Preserve every existing bucket key and its activeId up front.
+    for (const [key, state] of Object.entries(store.projects || {})) {
+        ensure(key).activeId = state.activeId ?? null;
+    }
+    for (const [bucketKey, state] of Object.entries(store.projects || {})) {
+        const isSentinel = bucketKey === exports.MANAGER_SCOPE_KEY || bucketKey === exports.COMPANY_SCOPE_KEY;
+        for (const conv of (state.conversations || [])) {
+            if (!conv || typeof conv !== 'object')
+                continue;
+            const scope = conv.scope
+                ?? conv.invokedArea;
+            const ownPath = typeof conv.projectPath === 'string'
+                ? conv.projectPath
+                : '';
+            const mismatched = !isSentinel
+                && scope !== 'manager' && scope !== 'company'
+                && ownPath.length > 0
+                && canonicalProjectPathKey(ownPath) !== canonicalProjectPathKey(bucketKey);
+            if (!mismatched) {
+                placeConversationInBucket(ensure(bucketKey), conv);
+                continue;
+            }
+            // Relocate to the record's own project bucket.
+            placeConversationInBucket(ensure(path_1.default.resolve(ownPath)), conv);
+        }
+    }
+    // Any activeId that no longer resolves to a conversation in its bucket (because that record was
+    // relocated out) is stale — clear it so a project never points at another project's run.
+    for (const state of Object.values(projects)) {
+        if (state.activeId && !state.conversations.some((entry) => entry && entry.id === state.activeId)) {
+            state.activeId = null;
+        }
+    }
+    return { version: 1, projects };
+}
+// The full on-read migration pipeline, exported so a one-off maintenance/cleanup pass can heal an
+// existing store file through the EXACT same code path the store uses at runtime (rather than a
+// duplicated, drift-prone reimplementation). Operates on raw records, so it never drops a record
+// via normalization.
+function migrateConversationStore(store) {
+    return migrateProjectBuckets(migrateScopeBuckets(store));
+}
 function normalizeConversation(projectPath, raw) {
     if (!raw || typeof raw !== 'object')
         return null;
@@ -242,8 +340,10 @@ class AiHubConversationStore {
             if (raw.version !== 1 || !raw.projects || typeof raw.projects !== 'object') {
                 return { version: 1, projects: {} };
             }
-            // Issue #708: fold legacy manager/company-invoked runs into scope buckets on read.
-            return migrateScopeBuckets({ version: 1, projects: raw.projects });
+            // Issue #708: fold legacy manager/company-invoked runs into scope buckets on read, then
+            // relocate any project-scoped record mis-filed under the wrong project bucket back to its
+            // own project (see docs/rca/hub-conversation-cross-project-leak.md).
+            return migrateProjectBuckets(migrateScopeBuckets({ version: 1, projects: raw.projects }));
         }
         catch {
             return { version: 1, projects: {} };

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

@@ -11,6 +11,9 @@ const server_1 = require("./server");
 const cert_store_1 = require("./cert-store");
 const office_sideload_1 = require("./office-sideload");
 const remote_hub_gateway_1 = require("./remote-hub-gateway");
+const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
+const version_utils_1 = require("../cli/utils/version-utils");
+const hub_runtime_file_1 = require("./hub-runtime-file");
 // ---------------------------------------------------------------------------
 // State
 // ---------------------------------------------------------------------------
@@ -176,6 +179,19 @@ function buildTrayMenu(hubUrl) {
                 }
             },
         },
+        {
+            // #755: surface the running build version so staleness is diagnosable at a glance.
+            label: 'About FRAIM Hub',
+            click: () => {
+                void electron_1.dialog.showMessageBox({
+                    type: 'info',
+                    title: 'About FRAIM Hub',
+                    message: 'FRAIM Hub',
+                    detail: `Version ${(0, version_utils_1.getFraimVersion)()}\nIdentity: ~/.fraim/config.json\nLocal server: ${hubUrl}`,
+                    buttons: ['OK'],
+                });
+            },
+        },
         { type: 'separator' },
         {
             label: 'Word Add-in',
@@ -354,6 +370,19 @@ async function launchDesktopShell(options) {
         },
     });
     await server.start(httpPort);
+    // #755: record the live instance so `fraim hub` can detect a stale build and
+    // replace it instead of re-focusing an outdated process.
+    try {
+        (0, hub_runtime_file_1.writeHubRuntimeFile)((0, project_fraim_paths_1.getUserFraimDirPath)(), {
+            pid: process.pid,
+            port: httpPort,
+            version: (0, version_utils_1.getFraimVersion)(),
+            startedAt: new Date().toISOString(),
+        });
+    }
+    catch (err) {
+        console.warn('[fraim] could not write hub-runtime.json:', err);
+    }
     ensureWordSideload(options.projectPath, httpPort);
     const hubUrl = `http://127.0.0.1:${httpPort}/ai-hub/`;
     createTray(hubUrl);
@@ -394,6 +423,12 @@ async function bootstrap() {
     });
     electron_1.app.on('before-quit', () => {
         isQuitting = true;
+        // #755: clear the runtime file so a later `fraim hub` doesn't treat a
+        // cleanly-exited instance as live.
+        try {
+            (0, hub_runtime_file_1.removeHubRuntimeFile)((0, project_fraim_paths_1.getUserFraimDirPath)());
+        }
+        catch { /* best-effort */ }
         void stopServerOnce();
     });
     // Keep app alive when all windows are closed — server must keep serving

package/dist/src/ai-hub/hub-latest-version.js

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLatestPublishedVersion = getLatestPublishedVersion;
+exports.__resetLatestVersionCache = __resetLatestVersionCache;
+const https_1 = __importDefault(require("https"));
+// Issue #755: best-effort "latest published fraim version" for the Hub's
+// update-available nudge. Cached in-process (1h TTL) and never throws — returns
+// null when offline or the registry is unreachable, so the nudge simply hides.
+const TTL_MS = 60 * 60 * 1000;
+const REGISTRY_URL = 'https://registry.npmjs.org/fraim/latest';
+let cache = { value: null, at: 0 };
+async function getLatestPublishedVersion() {
+    const now = Date.now();
+    if (cache.at !== 0 && now - cache.at < TTL_MS)
+        return cache.value;
+    const value = await fetchNpmLatest();
+    // Only cache successful lookups; a failed fetch retries next call rather than
+    // caching a null for an hour.
+    if (value !== null)
+        cache = { value, at: now };
+    return value ?? cache.value;
+}
+/** Test-only: reset the module cache. */
+function __resetLatestVersionCache() {
+    cache = { value: null, at: 0 };
+}
+function fetchNpmLatest() {
+    return new Promise((resolve) => {
+        const req = https_1.default.get(REGISTRY_URL, { timeout: 4000 }, (res) => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                return resolve(null);
+            }
+            let body = '';
+            res.on('data', (chunk) => { body += chunk; });
+            res.on('end', () => {
+                try {
+                    const version = JSON.parse(body).version;
+                    resolve(typeof version === 'string' ? version : null);
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+        });
+        req.on('error', () => resolve(null));
+        req.on('timeout', () => { req.destroy(); resolve(null); });
+    });
+}

package/dist/src/ai-hub/hub-launch-decision.js

@@ -0,0 +1,57 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decideHubLaunch = decideHubLaunch;
+const semver = __importStar(require("semver"));
+function decideHubLaunch(input) {
+    const { running, pidAlive, cliVersion, restart, noRestart } = input;
+    if (!running || !pidAlive) {
+        return { action: 'launch-fresh', reason: 'no live Hub instance is running' };
+    }
+    if (noRestart) {
+        return { action: 'focus-existing', reason: '--no-restart: keeping the running instance' };
+    }
+    if (restart) {
+        return { action: 'replace', reason: '--restart: replacing the running instance' };
+    }
+    // Only treat as stale when BOTH versions are valid semver and the running one is
+    // strictly older. On any uncertainty (unknown/unparseable version) do not kill —
+    // conservative default is to focus the existing instance.
+    const comparable = !!semver.valid(running.version) && !!semver.valid(cliVersion);
+    if (comparable && semver.lt(running.version, cliVersion)) {
+        return { action: 'replace', reason: `running ${running.version} is older than ${cliVersion}; replacing with the newer build` };
+    }
+    return { action: 'focus-existing', reason: `running ${running.version} is current or not comparable to ${cliVersion}` };
+}

package/dist/src/ai-hub/hub-runtime-file.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hubRuntimeFilePath = hubRuntimeFilePath;
+exports.writeHubRuntimeFile = writeHubRuntimeFile;
+exports.readHubRuntimeFile = readHubRuntimeFile;
+exports.removeHubRuntimeFile = removeHubRuntimeFile;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+// Issue #755: the running desktop Hub writes ~/.fraim/hub-runtime.json so the
+// `fraim hub` CLI can discover a live instance (pid/port/version) before deciding
+// whether to replace a stale build. `fraimDir` is injected (never hard-coded to
+// the real ~/.fraim) so tests isolate via a temp directory.
+const RUNTIME_FILE = 'hub-runtime.json';
+function hubRuntimeFilePath(fraimDir) {
+    return path_1.default.join(fraimDir, RUNTIME_FILE);
+}
+function writeHubRuntimeFile(fraimDir, info) {
+    fs_1.default.mkdirSync(fraimDir, { recursive: true });
+    fs_1.default.writeFileSync(hubRuntimeFilePath(fraimDir), JSON.stringify(info, null, 2));
+}
+function readHubRuntimeFile(fraimDir) {
+    try {
+        const parsed = JSON.parse(fs_1.default.readFileSync(hubRuntimeFilePath(fraimDir), 'utf8'));
+        if (typeof parsed.pid !== 'number' || typeof parsed.port !== 'number' || typeof parsed.version !== 'string') {
+            return null;
+        }
+        return { pid: parsed.pid, port: parsed.port, version: parsed.version, startedAt: String(parsed.startedAt ?? '') };
+    }
+    catch {
+        return null;
+    }
+}
+function removeHubRuntimeFile(fraimDir) {
+    try {
+        fs_1.default.rmSync(hubRuntimeFilePath(fraimDir), { force: true });
+    }
+    catch {
+        /* no-op: absent file is fine */
+    }
+}

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

@@ -140,7 +140,9 @@ class AiHubPreferencesStore {
                     ? raw.recentJobInstructions
                     : {},
                 personaKey: typeof raw.personaKey === 'string' ? raw.personaKey : null,
-                apiKey: typeof raw.apiKey === 'string' && raw.apiKey.length > 0 ? raw.apiKey : undefined,
+                // Issue #750: apiKey is no longer a persisted field here at all — any
+                // legacy apiKey left over from a pre-#750 ai-hub-state.json is silently
+                // dropped, never read back. Identity comes from ~/.fraim/config.json only.
                 projects: normalizeAiHubProjectList(Array.isArray(raw.projects) ? raw.projects : [], projectPath, { removedProjectPaths }),
                 removedProjectPaths,
             };

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

@@ -38,6 +38,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AiHubServer = exports.HostConfigStore = exports.DeploymentStore = void 0;
 exports.configureFraimForHubAgent = configureFraimForHubAgent;
+exports.buildOpenFileInvocation = buildOpenFileInvocation;
 exports.findAvailablePort = findAvailablePort;
 exports.findAvailablePortExcluding = findAvailablePortExcluding;
 const express_1 = __importDefault(require("express"));
@@ -61,6 +62,10 @@ const conversation_store_1 = require("./conversation-store");
 const remote_hub_gateway_1 = require("./remote-hub-gateway");
 const managed_browser_1 = require("./managed-browser");
 const managed_agent_paths_1 = require("../cli/utils/managed-agent-paths");
+const user_config_1 = require("../cli/utils/user-config");
+const version_utils_1 = require("../cli/utils/version-utils");
+const hub_latest_version_1 = require("./hub-latest-version");
+const semver = __importStar(require("semver"));
 let personaHiringModule;
 let managerHiringModule;
 function loadPersonaHiringModule() {
@@ -973,28 +978,43 @@ function resolveSafeArtifactPath(rawPath, projectPath) {
     ];
     return safeRoots.some((root) => pathWithin(root, resolved)) ? resolved : null;
 }
-function hubOpenFile(filePath) {
-    return new Promise((resolve, reject) => {
-        const args = process.platform === 'win32'
-            ? [
+// Builds the OS "open this file with its default app" invocation. Exported for regression
+// testing (see tests/isolated/test-ai-hub-open-file.ts).
+//
+// Windows contract: the path travels via an ENVIRONMENT VARIABLE, never as a trailing `-Command`
+// argument. PowerShell re-parses trailing args on its own command line and mangles Windows paths —
+// it strips backslashes and truncates at the first space — so `Invoke-Item -LiteralPath $p`
+// received a broken path (e.g. `C:UserssidmaOneDriveCodeDrug`) and failed for every real artifact
+// path, which is why the Hub's "open file" button did nothing. `$env:FRAIM_OPEN_PATH` is read
+// directly from the environment and is not re-parsed, so the path arrives intact (verified against
+// paths containing spaces and backslashes).
+function buildOpenFileInvocation(filePath, platform = process.platform) {
+    if (platform === 'win32') {
+        return {
+            command: 'powershell.exe',
+            args: [
                 '-NoProfile',
                 '-ExecutionPolicy',
                 'Bypass',
                 '-Command',
-                '& { param($p) try { Invoke-Item -LiteralPath $p; exit 0 } catch { Write-Error $_; exit 1 } }',
-                filePath,
-            ]
-            : process.platform === 'darwin'
-                ? [filePath]
-                : [filePath];
-        const command = process.platform === 'win32'
-            ? 'powershell.exe'
-            : process.platform === 'darwin'
-                ? 'open'
-                : 'xdg-open';
+                'try { Invoke-Item -LiteralPath $env:FRAIM_OPEN_PATH; exit 0 } catch { Write-Error $_; exit 1 }',
+            ],
+            envPatch: { FRAIM_OPEN_PATH: filePath },
+        };
+    }
+    return {
+        command: platform === 'darwin' ? 'open' : 'xdg-open',
+        args: [filePath],
+        envPatch: {},
+    };
+}
+function hubOpenFile(filePath) {
+    return new Promise((resolve, reject) => {
+        const { command, args, envPatch } = buildOpenFileInvocation(filePath);
         const child = (0, child_process_1.spawn)(command, args, {
             stdio: ['ignore', 'ignore', 'pipe'],
             windowsHide: process.platform === 'win32',
+            env: { ...process.env, ...envPatch },
         });
         let stderr = '';
         child.stderr?.on('data', (chunk) => {
@@ -1051,53 +1071,15 @@ function deploymentBelongsToProject(deployment, projectPath, fallbackProjectPath
 // ---------------------------------------------------------------------------
 // Issue #512 (S3) — Hub bootstrap projection helpers.
 // ---------------------------------------------------------------------------
-// Resolve the user email used to key personal (L1) learnings. Reads
-// ~/.fraim/preferences.json (the existing user-prefs file) when present so the
-// Brain counts match the auto-load context; falls back to a sensible default
-// that resolveLearningUserId can refine against on-disk files.
-function getHubUserEmail() {
-    try {
-        const prefsPath = path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), 'preferences.json');
-        if (fs_1.default.existsSync(prefsPath)) {
-            const raw = JSON.parse(fs_1.default.readFileSync(prefsPath, 'utf8'));
-            if (typeof raw.userEmail === 'string' && raw.userEmail.length > 0)
-                return raw.userEmail;
-        }
-    }
-    catch {
-        // fall through to default
-    }
-    // #533: preferences.json may not carry the email yet — the proxy persists it on
-    // fraim_connect (see stdio-server). Until then, personal learnings are ALWAYS
-    // stamped `<email>-<type>.md`, so a single-user machine resolves deterministically
-    // from the on-disk files. This is what makes the avatar + personal learnings work.
-    const stamped = resolveSingleStampedUser();
-    if (stamped)
-        return stamped;
-    return 'fraim-user';
-}
-// Return the one user prefix stamped on the global learning files, or null if
-// there is not exactly one (so we never guess between multiple accounts).
-function resolveSingleStampedUser() {
-    try {
-        const dir = (0, project_fraim_paths_1.getUserFraimLearningsDir)();
-        if (!fs_1.default.existsSync(dir))
-            return null;
-        const prefixes = new Set();
-        for (const f of fs_1.default.readdirSync(dir)) {
-            if (f.startsWith('org-'))
-                continue;
-            const m = f.match(/^(.*)-(preferences|manager-coaching|mistake-patterns|validated-patterns)\.md$/);
-            if (m)
-                prefixes.add(m[1]);
-        }
-        if (prefixes.size === 1)
-            return Array.from(prefixes)[0];
-    }
-    catch {
-        // ignore unreadable dir
-    }
-    return null;
+// Issue #750: the Hub's identity — for persona/entitlement resolution, the
+// displayed "signed in as" email, and personal (L1) learnings keying — comes
+// from ~/.fraim/config.json's apiKey (architecture.md §4.3.4's "Global config
+// stores only identity"), the same credential every other FRAIM CLI/MCP
+// surface already reads via readUserFraimConfig(). There is no fallback: a
+// missing or invalid apiKey resolves to null (rendered as a "not connected"
+// state), never a guess from another local file.
+function resolveApiKey() {
+    return (0, user_config_1.readUserFraimConfig)().apiKey;
 }
 // Read persisted Get-started step states from ~/.fraim/install-state.json
 // (architecture §3.5) and ~/.fraim/preferences.json. Returns a partial — any
@@ -1177,21 +1159,13 @@ class AiHubServer {
             explicitPath: process.env.FRAIM_BROWSER_PATH || undefined,
         });
         this.hostRuntime = options.hostRuntime || (process.env.FRAIM_AI_HUB_FAKE_HOST === '1' ? new hosts_1.FakeHostRuntime() : new hosts_1.CliHostRuntime());
-        // Issue #701: the AI Hub is a loopback companion that never touches MongoDB directly —
-        // on every machine (dev, CI, prod) it resolves persona/manager-team state from the hosted
-        // server through the same code path. The hosted server is the sole owner of DB access.
-        // A dbService is used ONLY when explicitly injected (e.g. the hosted server embedding the
-        // Hub, or a test); it is never auto-created, so there is no dev/prod divergence.
-        this.dbService = options.dbService;
-        this.ownsDbService = false;
+        // Issue #701 / #749: the AI Hub is a loopback companion that runs on user machines and
+        // never touches a database. Persona and manager-team state resolve from the hosted server
+        // through the remote gateway; the hosted server is the sole owner of DB access.
         this.remoteGateway = options.remoteGateway ?? new remote_hub_gateway_1.HttpHubRemoteGateway();
         this.deploymentStore = options.deploymentStore ?? new DeploymentStore();
         this.hostConfigStore = options.hostConfigStore ?? new HostConfigStore();
         this.app.use(express_1.default.json({ limit: '10mb' }));
-        if (this.dbService) {
-            const { registerPaymentRoutes } = require('../routes/payment-routes');
-            registerPaymentRoutes(this.app, () => this.paymentRepo ?? null, this.dbService);
-        }
         // CORS + Chrome Private Network Access for browser extensions and Office add-in task panes
         // calling the Hub from a public origin (word-edit.officeapps.live.com, etc.).
         this.app.use((_req, res, next) => {
@@ -1207,8 +1181,7 @@ class AiHubServer {
         });
         // Payment success redirect: sync entitlement then bounce to the hub.
         // Stripe redirects here after a completed persona-hire checkout.
-        this.app.get('/ai-hub/payment-success', async (req, res) => {
-            const sessionId = req.query['session_id'];
+        this.app.get('/ai-hub/payment-success', (req, res) => {
             const email = req.query['email'];
             // Persist the buyer's email so bootstrap can look up entitlements by userId.
             if (email) {
@@ -1223,17 +1196,8 @@ class AiHubServer {
                     console.warn('[ai-hub] could not persist userEmail:', err);
                 }
             }
-            if (sessionId && this.dbService) {
-                try {
-                    const { syncPersonaEntitlementFromCheckoutSession } = await Promise.resolve().then(() => __importStar(require('../services/persona-entitlement-service')));
-                    const { stripe } = await Promise.resolve().then(() => __importStar(require('../config/stripe')));
-                    const session = await stripe.checkout.sessions.retrieve(sessionId);
-                    await syncPersonaEntitlementFromCheckoutSession(this.dbService, session, 'dashboard-link');
-                }
-                catch (err) {
-                    console.warn('[ai-hub] payment-success entitlement sync failed:', err);
-                }
-            }
+            // Issue #749: the Hub holds no DB. Entitlement is synced authoritatively by the backend
+            // Stripe webhook; the Hub re-reads status via the remote gateway on the next bootstrap.
             res.redirect('/ai-hub/?hired=1');
         });
         this.app.use('/ai-hub', express_1.default.static(resolveAiHubPublicDir()));
@@ -1322,20 +1286,6 @@ class AiHubServer {
     }
     async start(port) {
         this.httpPort = port;
-        if (this.dbService) {
-            try {
-                await this.dbService.connect();
-                const mongoClient = this.dbService.getClient();
-                if (mongoClient) {
-                    const PaymentRepositoryImpl = require('../db/payment-repository').PaymentRepository;
-                    this.paymentRepo = new PaymentRepositoryImpl(mongoClient);
-                }
-            }
-            catch (err) {
-                console.warn('[ai-hub] DB connect failed — personas will show as locked:', err);
-                this.dbService = undefined;
-            }
-        }
         await new Promise((resolve, reject) => {
             this.httpServer = this.app.listen(port, '127.0.0.1');
             this.httpServer.once('listening', () => resolve());
@@ -1406,10 +1356,6 @@ class AiHubServer {
         // #521: tear down the shared browser if WE launched it (stop() no-ops on a
         // browser the manager owns).
         this.managedBrowser.stop();
-        if (this.ownsDbService && this.dbService) {
-            await this.dbService.close();
-            this.dbService = undefined;
-        }
     }
     getHttpsPort() { return this.httpsPort; }
     knownProjects(projectPath, extras = []) {
@@ -1422,7 +1368,7 @@ class AiHubServer {
             ...extras,
         ], normalizedProjectPath, { removedProjectPaths: preferences.removedProjectPaths || [] });
     }
-    async bootstrapResponse(projectPath, apiKey) {
+    async bootstrapResponse(projectPath) {
         const normalizedProjectPath = path_1.default.resolve(projectPath || this.projectPath);
         const employees = this.hostRuntime.detectEmployees();
         let preferences = this.preferencesStore.load(normalizedProjectPath);
@@ -1449,9 +1395,12 @@ class AiHubServer {
             requiredPersonaKey: getProtectedPersonaForHubJob(job.id),
         }));
         const managerTemplates = (0, catalog_1.discoverManagerTemplates)(normalizedProjectPath, catalogOptions);
-        const resolvedApiKey = apiKey || preferences.apiKey;
+        // Issue #750: the apiKey always comes from ~/.fraim/config.json — no header
+        // override, no ai-hub-state.json copy, no fallback chain.
+        const resolvedApiKey = resolveApiKey();
         const { personas, subscriptionActive, workspaceId, userKey } = await this.computePersonas(resolvedApiKey);
         const managerTeam = await this.computeManagerTeam(resolvedApiKey);
+        const resolvedUserEmail = userKey ?? null;
         const projects = this.knownProjects(normalizedProjectPath);
         preferences = { ...preferences, projectPath: normalizedProjectPath, projects };
         this.preferencesStore.save(preferences);
@@ -1463,8 +1412,15 @@ class AiHubServer {
         return {
             title: 'AI Hub',
             remoteBaseUrl: (0, remote_hub_gateway_1.resolveFraimRemoteUrl)(),
+            // #755: the running build version, so the account menu can show it and flag
+            // when a newer version is available (see GET /api/ai-hub/version for `latest`).
+            version: (0, version_utils_1.getFraimVersion)(),
             project,
-            preferences,
+            // Issue #750: `apiKey` is no longer a persisted AiHubPreferences field —
+            // it is overlaid on the wire response only, freshly resolved from
+            // ~/.fraim/config.json, so public/ai-hub/script.js's existing
+            // tfConnectedApiKey()/tfConnectedSurfaceUrl read path needs no changes.
+            preferences: { ...preferences, apiKey: resolvedApiKey },
             categories: (0, catalog_1.getAiHubCategories)(normalizedProjectPath, catalogOptions),
             jobs,
             managerTemplates,
@@ -1476,10 +1432,11 @@ class AiHubServer {
             // Issue #512 (S3) — additive manager-flow projections.
             firstRun: this.computeFirstRun(normalizedProjectPath, jobs.length, personas),
             teamContext: this.computeTeamContext(normalizedProjectPath),
-            brain: this.computeBrain(normalizedProjectPath, jobs.length + managerTemplates.length),
-            // #533: the resolved account email, so the profile card shows the real
-            // identity (not a hardcoded placeholder) and the client can display it.
-            userEmail: getHubUserEmail(),
+            brain: this.computeBrain(normalizedProjectPath, jobs.length + managerTemplates.length, resolvedUserEmail),
+            // #533/#750: the resolved account email (from the same ~/.fraim/config.json
+            // apiKey used for personas above), or null when not connected — so the
+            // profile card and personas can never disagree about who's signed in.
+            userEmail: resolvedUserEmail,
             // #744: the org cobrand identity (name/color/logo) from the org context
             // storage, or null when unset so the Hub falls back to FRAIM identity.
             orgBrand: (0, learning_context_builder_1.readOrgBrand)(normalizedProjectPath),
@@ -1866,8 +1823,19 @@ class AiHubServer {
     }
     // Issue #512 (S3, R14) — Brain summary: preserved-learning counts by scope +
     // registry catalog counts. A read projection; no new storage.
-    computeBrain(projectPath, jobCount) {
-        const learnings = (0, learning_context_builder_1.countPreservedLearnings)(projectPath, getHubUserEmail());
+    // Issue #750: `userEmail` is the config.json-resolved identity, or `null` when
+    // not connected. `organization`/`rawSignals` are identity-independent (org-*
+    // files and repo-level raw signals) and must always be counted regardless of
+    // connection state — only `manager`/`project` (L1, individual-keyed) are
+    // zeroed when not connected, rather than guessing an identity via
+    // resolveLearningUserId's single-stamped-user fallback (a legitimate
+    // convenience for MCP auto-load context, but not appropriate here).
+    computeBrain(projectPath, jobCount, userEmail) {
+        const learnings = (0, learning_context_builder_1.countPreservedLearnings)(projectPath, userEmail || '');
+        if (!userEmail) {
+            learnings.manager = 0;
+            learnings.project = 0;
+        }
         return {
             learnings,
             catalog: {
@@ -1970,15 +1938,7 @@ class AiHubServer {
         // passes raw invocation syntax.
         const explicit = (0, manager_turns_1.extractExplicitFraimInvocation)(instructions);
         const effectiveJobId = explicit?.jobId || coachingJobId || run.jobId;
-        // #730: the manager thread shows the coaching turn with high fidelity — the
-        // correct FRAIM command in front plus what the manager actually said — built
-        // from the shared normalizer, exactly like the start path. With no
-        // instructions (e.g. a plain coaching-template click) buildManagerMessage
-        // collapses to just the invocation. The employee additionally receives the
-        // communication-style note (and, per #732 below, a lighter same-job payload);
-        // those operational details stay out of the visible bubble.
         const userText = (explicit?.remainder || instructions || '').trim();
-        const display = (0, manager_turns_1.buildManagerMessage)(run.hostId, effectiveJobId, 'continue', instructions);
         // Issue #732: a plain continue of the SAME active real job must not re-load
         // the job via get_fraim_job on every coaching turn — the host session is
         // resumed with the job already in context, so re-fetching is wasted latency
@@ -1987,9 +1947,26 @@ class AiHubServer {
         // template or an explicit /fraim <other>). Freeform/adhoc runs keep the
         // existing buildManagerMessage path (which already emits no invocation).
         const switchesJob = effectiveJobId !== run.jobId;
-        const message = (switchesJob || run.jobId === '__freeform__')
-            ? (0, manager_turns_1.buildManagerMessage)(run.hostId, effectiveJobId, 'continue', instructions) + (0, manager_turns_1.buildCommunicationStyleNote)()
-            : (0, manager_turns_1.buildSameJobContinueMessage)(userText) + (0, manager_turns_1.buildCommunicationStyleNote)();
+        const showsInvocation = switchesJob || run.jobId === '__freeform__';
+        // Issue #756: the manager bubble must MIRROR what actually happens. A
+        // same-job coaching continue resumes the active job WITHOUT re-invoking it
+        // (the `message` below carries no `/fraim`), so the bubble shows only what
+        // the manager SAID — never a `/fraim <same-job>` line, which reads as a full
+        // re-run of the active job Y and misled managers into thinking coaching
+        // restarts the workflow. Only a real job SWITCH actually issues an
+        // invocation, so only then does the bubble lead with the command. This still
+        // upholds the #730 guarantee: the manager's coaching text is never dropped,
+        // and when a command IS issued it appears in front of that text.
+        // The invocation form (`/fraim <job>` + words) is built once and reused for
+        // both the bubble and the agent payload when a command is actually issued.
+        const invocationForm = showsInvocation
+            ? (0, manager_turns_1.buildManagerMessage)(run.hostId, effectiveJobId, 'continue', instructions)
+            : null;
+        // Bubble: the command form for a real switch, else the manager's own words.
+        const display = invocationForm ?? userText;
+        // Agent payload: the same command form for a switch, else a lightweight
+        // same-job continue; the communication-style note is agent-only.
+        const message = (invocationForm ?? (0, manager_turns_1.buildSameJobContinueMessage)(userText)) + (0, manager_turns_1.buildCommunicationStyleNote)();
         return { message, display };
     }
     async computePersonas(apiKey) {
@@ -2053,51 +2030,48 @@ class AiHubServer {
         // Issue #701: manager team comes from the hosted server, not local Mongo.
         return this.remoteGateway.listManagerTeam(apiKey);
     }
+    // Issue #750: identity for routes that don't already call computePersonas()
+    // (which fetches this same hosted state for personas/manager-team). Always
+    // sources the apiKey from ~/.fraim/config.json; null means "not connected" —
+    // no local-guess fallback.
+    async resolveHubIdentity() {
+        const apiKey = resolveApiKey();
+        if (!apiKey)
+            return null;
+        const state = await this.remoteGateway.getPersonaState(apiKey);
+        return state?.userId ?? null;
+    }
+    // Issue #750: shared by the two learnings routes below. 'org' scope never
+    // needs identity (readPreservedLearnings/applyLearningEntryChange ignore the
+    // userId param for it); every other scope resolves through resolveHubIdentity,
+    // returning '' (not a guess) when not connected — callers distinguish
+    // "org" from "not connected" via the scope check they already have to make.
+    async resolveLearningIdentity(scope) {
+        if (scope === 'org')
+            return '';
+        return (await this.resolveHubIdentity()) || '';
+    }
     registerRoutes() {
-        // Issue #512: Serve the account and analytics pages from public/.
-        // These live outside of /ai-hub so they need explicit routes.
-        const publicDir = resolveAiHubPublicDir().replace(/[\\/]ai-hub$/, '');
-        if (!this.dbService) {
-            this.app.get(/^\/auth(\/.*)?$/, (req, res) => {
-                const parsed = new URL(req.originalUrl, 'http://127.0.0.1');
-                if (parsed.pathname === '/auth/sign-in.html' && !parsed.searchParams.has('hub_return')) {
-                    const rawSurface = parsed.searchParams.get('surface');
-                    const surface = rawSurface === 'account' || rawSurface === 'brain' || rawSurface === 'analytics'
-                        ? rawSurface
-                        : 'analytics';
-                    parsed.searchParams.set('hub_return', buildLocalHubReturnUrl(req, surface));
-                }
-                res.redirect(buildHostedPathUrl(parsed.pathname, parsed.search));
-            });
-            this.app.get(['/account', '/account/'], (req, res) => {
-                res.redirect(buildHostedAuthUrl('account', '/account/', buildLocalHubReturnUrl(req, 'account')));
-            });
-            this.app.get(['/analytics', '/analytics/'], (req, res) => {
-                res.redirect(buildHostedAuthUrl('analytics', '/analytics/', buildLocalHubReturnUrl(req, 'analytics')));
-            });
-        }
-        else {
-            this.app.get('/account', (_req, res) => {
-                const filePath = path_1.default.join(publicDir, 'account', 'index.html');
-                if (fs_1.default.existsSync(filePath)) {
-                    res.sendFile(filePath);
-                }
-                else {
-                    res.status(404).send('Account page not found.');
-                }
-            });
-            this.app.use('/account', express_1.default.static(path_1.default.join(publicDir, 'account')));
-            this.app.get('/analytics', (_req, res) => {
-                const filePath = path_1.default.join(publicDir, 'analytics', 'index.html');
-                if (fs_1.default.existsSync(filePath)) {
-                    res.sendFile(filePath);
-                }
-                else {
-                    res.status(404).send('Analytics page not found.');
-                }
-            });
-            this.app.use('/analytics', express_1.default.static(path_1.default.join(publicDir, 'analytics')));
-        }
+        // Issue #512 / #749: the account and analytics surfaces live outside /ai-hub. The
+        // on-machine Hub holds no DB, so it always redirects these (and /auth) to the hosted
+        // server, which owns the authenticated, DB-backed pages.
+        this.app.get(/^\/auth(\/.*)?$/, (req, res) => {
+            const parsed = new URL(req.originalUrl, 'http://127.0.0.1');
+            if (parsed.pathname === '/auth/sign-in.html' && !parsed.searchParams.has('hub_return')) {
+                const rawSurface = parsed.searchParams.get('surface');
+                const surface = rawSurface === 'account' || rawSurface === 'brain' || rawSurface === 'analytics'
+                    ? rawSurface
+                    : 'analytics';
+                parsed.searchParams.set('hub_return', buildLocalHubReturnUrl(req, surface));
+            }
+            res.redirect(buildHostedPathUrl(parsed.pathname, parsed.search));
+        });
+        this.app.get(['/account', '/account/'], (req, res) => {
+            res.redirect(buildHostedAuthUrl('account', '/account/', buildLocalHubReturnUrl(req, 'account')));
+        });
+        this.app.get(['/analytics', '/analytics/'], (req, res) => {
+            res.redirect(buildHostedAuthUrl('analytics', '/analytics/', buildLocalHubReturnUrl(req, 'analytics')));
+        });
         // Issue #478: Serve the PowerPoint task pane HTML and manifest.
         // Office JS appends query strings (?_host_Info=PowerPoint$Win32$...) to every
         // request, so we must strip them before resolving the file path. Use a custom
@@ -2149,8 +2123,6 @@ class AiHubServer {
                 }
                 catch { }
             }
-            // Read API key from header — query-param API keys are prohibited (§3.14)
-            const apiKey = typeof req.headers['x-fraim-api-key'] === 'string' ? req.headers['x-fraim-api-key'] : undefined;
             // #719: a bare reload (no projectPath query) must land on the last-recorded
             // workspace project, not the launch folder. The bootstrap saves its resolved
             // current path back into the projects list, so defaulting to the launch
@@ -2164,17 +2136,18 @@ class AiHubServer {
                     projectPath = recorded;
                 }
             }
-            res.json(await this.bootstrapResponse(projectPath || this.projectPath, apiKey));
+            res.json(await this.bootstrapResponse(projectPath || this.projectPath));
         });
         // Issue #512 (S3, R14) — Brain summary as a standalone route, returning the
         // same projection folded into bootstrap. Useful for the avatar→Brain view
         // without re-fetching the whole bootstrap payload.
-        this.app.get('/api/ai-hub/brain', (req, res) => {
+        this.app.get('/api/ai-hub/brain', async (req, res) => {
             const projectPath = typeof req.query.projectPath === 'string' && req.query.projectPath.length > 0
                 ? path_1.default.resolve(req.query.projectPath)
                 : this.projectPath;
             const jobCount = (0, catalog_1.discoverEmployeeJobs)(projectPath).length + (0, catalog_1.discoverManagerTemplates)(projectPath).length;
-            return res.json(this.computeBrain(projectPath, jobCount));
+            const userEmail = await this.resolveHubIdentity();
+            return res.json(this.computeBrain(projectPath, jobCount, userEmail));
         });
         // #533: read the PRESERVED learnings for a section + storage level so the
         // Company/Manager sections (machine level) and the project workspace (project
@@ -2187,7 +2160,7 @@ class AiHubServer {
             : (typeof (req.body && req.body.projectPath) === 'string' && req.body.projectPath.length > 0
                 ? path_1.default.resolve(req.body.projectPath)
                 : this.projectPath);
-        this.app.get('/api/ai-hub/learnings', (req, res) => {
+        this.app.get('/api/ai-hub/learnings', async (req, res) => {
             const scope = req.query.scope;
             if (typeof scope !== 'string' || !VALID_SCOPES.includes(scope)) {
                 return res.status(400).json({ error: `scope must be one of: ${VALID_SCOPES.join(', ')}` });
@@ -2195,7 +2168,11 @@ class AiHubServer {
             const level = (typeof req.query.level === 'string' && VALID_LEVELS.includes(req.query.level))
                 ? req.query.level : 'machine';
             try {
-                const entries = (0, learning_context_builder_1.readPreservedLearnings)(resolveProjectPath(req), getHubUserEmail(), scope, level);
+                const userEmail = await this.resolveLearningIdentity(scope);
+                if (scope !== 'org' && !userEmail) {
+                    return res.json({ scope, level, entries: [] });
+                }
+                const entries = (0, learning_context_builder_1.readPreservedLearnings)(resolveProjectPath(req), userEmail, scope, level);
                 return res.json({ scope, level, entries });
             }
             catch (error) {
@@ -2205,7 +2182,7 @@ class AiHubServer {
         // #533 §3: add / edit / delete a single learning entry — writes the real file
         // at the section's level (machine for the Manager/Company tabs, project for the
         // project workspace). The action targets exactly the card's file.
-        this.app.post('/api/ai-hub/learnings/entry', (req, res) => {
+        this.app.post('/api/ai-hub/learnings/entry', async (req, res) => {
             const b = (req.body || {});
             if (!['add', 'edit', 'delete'].includes(b.action || '')) {
                 return res.status(400).json({ error: 'action must be one of: add, edit, delete' });
@@ -2216,8 +2193,14 @@ class AiHubServer {
                 return res.status(400).json({ error: `category must be one of: ${VALID_CATEGORIES.join(', ')}` });
             const level = (b.level && VALID_LEVELS.includes(b.level)) ? b.level : 'machine';
             const ref = { scope: b.scope, level, category: b.category };
+            // Issue #750: writes to a personal-scope file need a resolved identity —
+            // fail explicitly rather than writing to a guessed or empty-string file.
+            const userEmail = await this.resolveLearningIdentity(b.scope);
+            if (b.scope !== 'org' && !userEmail) {
+                return res.status(400).json({ error: 'not_connected', message: 'No FRAIM identity resolved. Run `fraim setup` first.' });
+            }
             try {
-                const result = (0, learning_context_builder_1.applyLearningEntryChange)(resolveProjectPath(req), getHubUserEmail(), ref, b.action, {
+                const result = (0, learning_context_builder_1.applyLearningEntryChange)(resolveProjectPath(req), userEmail, ref, b.action, {
                     originalTitle: b.originalTitle,
                     severity: b.severity,
                     title: b.title,
@@ -2229,24 +2212,22 @@ class AiHubServer {
                 return res.status(400).json({ error: error instanceof Error ? error.message : 'Could not write learning.' });
             }
         });
-        // Issue #540/#701: POST /api/ai-hub/manager-team/assign
-        // Proxies to the hosted server (which owns the DB + seat enforcement). The Hub
-        // accepts the local X-Fraim-Api-Key header and forwards it as the hosted x-api-key.
+        // Issue #540/#701/#750: POST /api/ai-hub/manager-team/assign
+        // Proxies to the hosted server (which owns the DB + seat enforcement), using
+        // the Hub's own ~/.fraim/config.json apiKey — not a caller-supplied header.
         // Hosted returns 404 no_company_seat / 409 out_of_stock; those are passed through.
         this.app.post('/api/ai-hub/manager-team/assign', async (req, res) => {
-            const apiKey = typeof req.headers['x-fraim-api-key'] === 'string' ? req.headers['x-fraim-api-key'] : undefined;
             const { personaKey } = (req.body ?? {});
             if (!personaKey)
                 return res.status(400).json({ error: 'personaKey required' });
-            const result = await this.remoteGateway.assignManagerTeam(apiKey, personaKey);
+            const result = await this.remoteGateway.assignManagerTeam(resolveApiKey(), personaKey);
             return res.status(result.status).json(result.body);
         });
-        // Issue #540/#701: DELETE /api/ai-hub/manager-team/assign/:personaKey
+        // Issue #540/#701/#750: DELETE /api/ai-hub/manager-team/assign/:personaKey
         // Proxies the seat release to the hosted server.
         this.app.delete('/api/ai-hub/manager-team/assign/:personaKey', async (req, res) => {
-            const apiKey = typeof req.headers['x-fraim-api-key'] === 'string' ? req.headers['x-fraim-api-key'] : undefined;
             const { personaKey } = req.params;
-            await this.remoteGateway.removeManagerTeam(apiKey, personaKey);
+            await this.remoteGateway.removeManagerTeam(resolveApiKey(), personaKey);
             return res.status(204).end();
         });
         // Issue #708: manager/company scopes resolve to a project-independent sentinel bucket
@@ -2277,7 +2258,27 @@ class AiHubServer {
                 // deletes are honored (a conversation absent here is dropped).
                 const prior = this.conversationStore.loadProject(key);
                 const priorById = new Map(prior.conversations.map((entry) => [entry.id, entry]));
-                const conversations = body.conversations.map((incoming) => {
+                // Write-boundary guard for the cross-project leak (docs/rca/hub-conversation-cross-project-leak.md):
+                // a project PUT persists the client's current-project list, but that list can transiently
+                // include a conversation belonging to ANOTHER project (e.g. the just-finished run of the
+                // project the user switched away from). Never file such a record into this project bucket —
+                // its authoritative home is its own project bucket. Scope (manager/company) PUTs are exempt:
+                // their sentinel buckets legitimately hold records whose projectPath points at a project.
+                const belongsInBucket = (incoming) => {
+                    if (scope)
+                        return true;
+                    const incomingScope = incoming.scope
+                        ?? incoming.invokedArea;
+                    if (incomingScope === 'manager' || incomingScope === 'company')
+                        return false;
+                    const own = incoming && typeof incoming.projectPath === 'string' ? incoming.projectPath : '';
+                    if (!own)
+                        return true;
+                    return normalizedDirectoryPath(own) === normalizedDirectoryPath(key);
+                };
+                const conversations = body.conversations
+                    .filter((incoming) => belongsInBucket(incoming))
+                    .map((incoming) => {
                     const existing = incoming && incoming.id ? priorById.get(incoming.id) : undefined;
                     return existing ? { ...existing, ...incoming } : incoming;
                 });
@@ -2375,20 +2376,24 @@ class AiHubServer {
             const projects = this.preferencesStore.removeProject(projectPath, known.filter((project) => project.id !== entry.id), entry.folderPath);
             return res.json({ ok: true, projects });
         });
-        this.app.post('/api/ai-hub/api-key', (req, res) => {
-            const { apiKey } = req.body;
-            if (!apiKey || typeof apiKey !== 'string')
-                return res.status(400).json({ error: 'apiKey required' });
-            const prefs = this.preferencesStore.load(this.projectPath);
-            this.preferencesStore.save({ ...prefs, apiKey });
-            return res.json({ ok: true });
-        });
+        // Issue #750: POST /api/ai-hub/api-key is removed — there is no Hub-local
+        // apiKey to persist. Identity always comes from ~/.fraim/config.json
+        // (set by `fraim setup`), read fresh via resolveApiKey() on every request.
         this.app.post('/api/ai-hub/preferences', (req, res) => {
             const { personaKey } = req.body;
             const prefs = this.preferencesStore.load(this.projectPath);
             this.preferencesStore.save({ ...prefs, personaKey: personaKey ?? null });
             return res.json({ ok: true });
         });
+        // #755: running build version + best-effort latest published version, so the
+        // account menu can show the version and flag when an update is available. The
+        // `fraim hub` CLI also queries this to confirm a running instance's version.
+        this.app.get('/api/ai-hub/version', async (_req, res) => {
+            const version = (0, version_utils_1.getFraimVersion)();
+            const latest = await (0, hub_latest_version_1.getLatestPublishedVersion)();
+            const updateAvailable = !!(latest && semver.valid(version) && semver.valid(latest) && semver.gt(latest, version));
+            return res.json({ version, latest, updateAvailable });
+        });
         this.app.post('/api/ai-hub/project-path/pick', async (_req, res) => {
             try {
                 const projectPath = await this.folderPicker();

package/dist/src/cli/commands/hub.js

@@ -45,6 +45,14 @@ const git_utils_1 = require("../../core/utils/git-utils");
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const fs_1 = __importDefault(require("fs"));
+const net_1 = __importDefault(require("net"));
+const http_1 = __importDefault(require("http"));
+// #755: light, server-free modules — safe to import eagerly in the packed client
+// (unlike ai-hub/server, which is lazy-required per #422).
+const hub_launch_decision_1 = require("../../ai-hub/hub-launch-decision");
+const hub_runtime_file_1 = require("../../ai-hub/hub-runtime-file");
+const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
+const version_utils_1 = require("../utils/version-utils");
 function resolveElectronBinary() {
     try {
         // eslint-disable-next-line @typescript-eslint/no-var-requires
@@ -97,18 +105,116 @@ function openBrowser(url) {
     const child = (0, child_process_1.spawn)('xdg-open', [url], { detached: true, stdio: 'ignore' });
     child.unref();
 }
+// #755: version-aware kill-and-replace. Electron's single-instance lock otherwise
+// re-focuses a stale running build instead of launching a newly-released one.
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        // EPERM => the process exists but we can't signal it (still "alive").
+        return !!(e && e.code === 'EPERM');
+    }
+}
+function killPid(pid) {
+    try {
+        if (process.platform === 'win32') {
+            (0, child_process_1.execFileSync)('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' });
+        }
+        else {
+            process.kill(pid, 'SIGTERM');
+        }
+    }
+    catch {
+        /* already gone */
+    }
+}
+function isPortFree(port, timeoutMs = 500) {
+    return new Promise((resolve) => {
+        const sock = net_1.default.connect({ host: '127.0.0.1', port }, () => { sock.destroy(); resolve(false); });
+        sock.on('error', () => resolve(true));
+        sock.setTimeout(timeoutMs, () => { sock.destroy(); resolve(true); });
+    });
+}
+async function waitForPortFree(port, totalMs = 5000) {
+    const start = Date.now();
+    while (Date.now() - start < totalMs) {
+        if (await isPortFree(port))
+            return;
+        await new Promise((r) => setTimeout(r, 200));
+    }
+}
+/**
+ * Reconcile a running desktop Hub with the version about to launch. Replaces a
+ * stale/older instance (or any instance under --restart) so the new build takes
+ * over; keeps the running instance under --keep-running.
+ */
+/** Confirm the recorded port actually serves a FRAIM Hub, returning its authoritative version. */
+function fetchRunningHubVersion(port) {
+    return new Promise((resolve) => {
+        const req = http_1.default.get({ host: '127.0.0.1', port, path: '/api/ai-hub/version', timeout: 1000 }, (res) => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                return resolve(null);
+            }
+            let body = '';
+            res.on('data', (c) => { body += c; });
+            res.on('end', () => { try {
+                resolve(JSON.parse(body).version ?? null);
+            }
+            catch {
+                resolve(null);
+            } });
+        });
+        req.on('error', () => resolve(null));
+        req.on('timeout', () => { req.destroy(); resolve(null); });
+    });
+}
+async function reconcileRunningHub(flags) {
+    const running = (0, hub_runtime_file_1.readHubRuntimeFile)((0, project_fraim_paths_1.getUserFraimDirPath)());
+    // Confirm the recorded port genuinely serves a FRAIM Hub before trusting the file.
+    // This (a) prevents killing an unrelated process that reused a crashed Hub's pid,
+    // and (b) yields the authoritative running version (the file may be stale).
+    const confirmedVersion = running ? await fetchRunningHubVersion(running.port) : null;
+    const live = !!(running && confirmedVersion && isProcessAlive(running.pid));
+    const effective = live && running ? { ...running, version: confirmedVersion } : null;
+    const decision = (0, hub_launch_decision_1.decideHubLaunch)({
+        running: effective,
+        pidAlive: live,
+        cliVersion: (0, version_utils_1.getFraimVersion)(),
+        restart: flags.restart,
+        noRestart: flags.keepRunning,
+    });
+    if (decision.action === 'replace' && effective) {
+        console.log(`Replacing running Hub (v${effective.version}, pid ${effective.pid}) — ${decision.reason}`);
+        killPid(effective.pid);
+        await waitForPortFree(effective.port);
+    }
+    else if (decision.action === 'focus-existing' && effective) {
+        console.log(`A Hub (v${effective.version}) is already running — focusing it. Use --restart to replace it.`);
+    }
+}
 exports.hubCommand = new commander_1.Command('hub')
     .description('Start the AI Hub local companion for running FRAIM jobs through Codex or Claude Code')
     .option('--port <port>', 'Preferred local port for the hub', (value) => Number(value), 43091)
     .option('--project-path <path>', 'Initial project path for job discovery', process.cwd())
     .option('--no-open', 'Do not open the hub after startup')
     .option('--browser', 'Open in the default browser instead of the desktop shell')
+    .option('--restart', 'Replace any running Hub instance with this build (even at the same version)')
+    .option('--keep-running', 'Do not replace a running Hub; keep single-instance focus (default replaces only an older/stale instance)')
     .action(async (options) => {
     const { AiHubServer, findAvailablePort } = await Promise.resolve().then(() => __importStar(require('../../ai-hub/server')));
     const preferredPort = options.port || (0, git_utils_1.getPort)() + 100;
     const projectPath = path_1.default.resolve(options.projectPath || process.cwd());
     if (options.open) {
-        const openedDesktop = !options.browser && openDesktopWindow(projectPath, preferredPort);
+        const wantDesktop = !options.browser;
+        // #755: before spawning Electron (whose single-instance lock would re-focus a
+        // stale build), replace an older/forced running instance so the new build wins.
+        if (wantDesktop) {
+            await reconcileRunningHub({ restart: !!options.restart, keepRunning: !!options.keepRunning });
+        }
+        const openedDesktop = wantDesktop && openDesktopWindow(projectPath, preferredPort);
         if (!openedDesktop) {
             const port = await findAvailablePort(preferredPort);
             const server = new AiHubServer({ projectPath });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.199",
+  "version": "2.0.201",
   "description": "FRAIM: AI Workforce Infrastructure — the organizational capability that turns AI agents into an accountable workforce, their operators into capable AI managers, and executives into leaders with clear optics on AI proficiency.",
   "main": "index.js",
   "bin": {

package/public/ai-hub/index.html

@@ -59,7 +59,12 @@
           <span class="am-switch" aria-hidden="true"><span class="am-switch-knob"></span></span>
         </button>
         <div class="am-div"></div>
+        <div class="am-update" id="am-update" hidden>
+          <span class="am-ico">⬆️</span>
+          <div><div class="am-label">Update available</div><div class="am-sub" id="am-update-sub"></div></div>
+        </div>
         <button class="am-foot" id="am-signout" type="button"><span class="am-ico">⏻</span><span>Sign out</span></button>
+        <div class="am-version" id="am-version" title="Running FRAIM Hub build"></div>
       </div>
     </div>
   </nav>

package/public/ai-hub/script.js

@@ -9631,23 +9631,15 @@ async function tfHandleConnectedAuthMessage(event) {
   }
 }
 
+// Issue #750: the Hub's identity comes from ~/.fraim/config.json (set by
+// `fraim setup`), not a Hub-local copy — there is nothing to persist here.
+// A key recovered via embedded sign-in is used for the rest of this browser
+// session only (in-memory); it does not survive a Hub restart, by design.
 async function tfRememberConnectedApiKey(apiKey) {
-  const changed = apiKey !== state.storedApiKey;
   state.storedApiKey = apiKey;
   if (state.bootstrap && state.bootstrap.preferences) {
     state.bootstrap.preferences.apiKey = apiKey;
   }
-  if (changed) {
-    try {
-      await requestJson('/api/ai-hub/api-key', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ apiKey }),
-      });
-    } catch (error) {
-      console.warn('[ai-hub] Could not persist connected auth key:', error);
-    }
-  }
 }
 
 // ---------------------------------------------------------------------------
@@ -10352,6 +10344,12 @@ async function tfSwitchProjectFolder(folderPath) {
     return;
   }
   state.projectPath = normalized.folderPath;
+  // Cross-project leak fix (docs/rca/hub-conversation-cross-project-leak.md): drop the previous
+  // project's active conversation on switch. Otherwise the just-finished run stays state.activeId
+  // while state.projectPath is the new project, and a debounced conversation PUT during the
+  // cached-bucket fast render below would flush that foreign conversation into the new project's
+  // bucket. hydrateConversationsFromServer recomputes the correct activeId for this project.
+  state.activeId = null;
   // #521 fix: the context cache (state._ctxCache) is keyed by context key only
   // (projectContext/projectBrief/projectRules), NOT by project — so without this
   // the new project's Brief section would render the PREVIOUS project's content
@@ -10850,6 +10848,12 @@ function tfWireShell() {
 // replacing the hardcoded "SM" placeholder. Falls back gracefully when the email
 // isn't known yet (e.g. before the proxy has persisted it).
 function tfAccountIdentity() {
+  // Issue #750: bootstrap.userEmail is `null` (not just missing) once the server
+  // has definitively resolved "no ~/.fraim/config.json apiKey" — distinct from
+  // the transient pre-bootstrap window where state.bootstrap doesn't exist yet.
+  if (state.bootstrap && state.bootstrap.userEmail === null) {
+    return { email: '', name: 'You', initials: '·', notConnected: true };
+  }
   const email = (state.bootstrap && state.bootstrap.userEmail) || '';
   if (!email || !email.includes('@')) {
     return { email: '', name: 'You', initials: '·' };
@@ -10869,9 +10873,33 @@ function tfPopulateAccountMenu() {
   const avEl = document.getElementById('am-av');
   const avatarBtn = document.getElementById('avatar-btn');
   if (nameEl) nameEl.textContent = id.name;
-  if (emailEl) emailEl.textContent = id.email;
+  if (emailEl) emailEl.textContent = id.notConnected ? 'Not connected — run `fraim setup`' : id.email;
   if (avEl) avEl.textContent = id.initials;
   if (avatarBtn) avatarBtn.textContent = id.initials;
+  tfPopulateVersionInfo(); // #755
+}
+
+// #755: show the running Hub build version and, when a newer version is published,
+// an update-available nudge. Running version is cheap (from bootstrap); the latest
+// check hits the server's cached /api/ai-hub/version (best-effort, hidden on failure).
+function tfPopulateVersionInfo() {
+  const versionEl = document.getElementById('am-version');
+  const running = (state.bootstrap && state.bootstrap.version) || '';
+  if (versionEl) versionEl.textContent = running ? `FRAIM Hub v${running}` : '';
+  const updateEl = document.getElementById('am-update');
+  const updateSub = document.getElementById('am-update-sub');
+  if (!updateEl) return;
+  fetch('/api/ai-hub/version')
+    .then((r) => (r.ok ? r.json() : null))
+    .then((info) => {
+      if (info && info.updateAvailable && info.latest) {
+        if (updateSub) updateSub.textContent = `v${info.latest} is available — quit the Hub (tray → Quit) and relaunch to update.`;
+        updateEl.hidden = false;
+      } else {
+        updateEl.hidden = true;
+      }
+    })
+    .catch(() => { /* offline / best-effort: leave the nudge hidden */ });
 }
 
 function tfRequestedConnectedSurface() {

package/public/ai-hub/styles.css

@@ -2783,6 +2783,13 @@ body.hub-shell { display: flex; flex-direction: column; height: 100vh; overflow:
 .am-div { height: 1px; background: var(--line); margin: 4px 0; }
 .am-foot { padding: 8px 16px; font-size: 13px; color: var(--muted); cursor: pointer; }
 .am-foot:hover { background: var(--bg); }
+/* #755: running-version footer + update-available nudge in the account menu */
+.am-version { padding: 6px 16px 10px; font-size: 10px; color: var(--muted); text-align: center; }
+#account-menu .am-update:not([hidden]) { display: grid; grid-template-columns: 30px 1fr; column-gap: 12px; align-items: start; }
+#account-menu .am-update { padding: 9px 16px; margin: 2px 8px 4px; background: var(--bg); border: 1px solid var(--line); border-radius: 8px; }
+#account-menu .am-update .am-ico { width: 30px; margin: 0; text-align: center; font-size: 16px; }
+.am-update .am-label { font-size: 13px; font-weight: 700; color: var(--text); }
+.am-update .am-sub { font-size: 11px; color: var(--muted); margin-top: 1px; }
 /* #700: theme toggle row + iOS-style switch */
 .am-theme { align-items: center; width: 100%; border: none; background: none; text-align: left; font: inherit; color: var(--text); }
 .am-theme .am-switch { box-sizing: border-box; margin-left: auto; align-self: center; width: 38px; height: 22px; border-radius: 999px; background: var(--soft); border: 1px solid var(--line); position: relative; flex-shrink: 0; transition: background .18s ease, border-color .18s ease; }