fraim-hub 2.0.271 → 2.0.272

package/bin/fraim-hub-2.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 try {
   const { createFraimHub2Program } = require('../dist/src/cli/fraim-hub-2.js');
   createFraimHub2Program().parseAsync(process.argv).catch((error) => {

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

@@ -43,6 +43,9 @@ function conversationScopeKey(scope, projectPath) {
         return exports.MANAGER_SCOPE_KEY;
     if (scope === 'company')
         return exports.COMPANY_SCOPE_KEY;
+    if (typeof projectPath !== 'string' || projectPath.trim().length === 0) {
+        throw new Error('conversationScopeKey: empty project path');
+    }
     return normalizeConversationKey(projectPath);
 }
 const emptyProjectState = () => ({
@@ -67,7 +70,10 @@ function normalizeConversationKey(key) {
     if (typeof key === 'string' && (key === exports.MANAGER_SCOPE_KEY || key === exports.COMPANY_SCOPE_KEY)) {
         return key;
     }
-    return path_1.default.resolve(key || process.cwd());
+    if (typeof key !== 'string' || key.trim().length === 0) {
+        throw new Error('normalizeConversationKey: empty project path');
+    }
+    return path_1.default.resolve(key);
 }
 function normalizeProjectPath(projectPath) {
     return normalizeConversationKey(projectPath);

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

@@ -10,33 +10,34 @@ exports.getOsShortcutPaths = getOsShortcutPaths;
 exports.writeMacosLaunchAgent = writeMacosLaunchAgent;
 exports.writeLinuxDesktopEntry = writeLinuxDesktopEntry;
 exports.runHubInstall = runHubInstall;
-// #921: `fraim hub install` — register the FRAIM Hub as an OS application so users
+// #921/#1179: `fraim-hub install` — register the FRAIM Hub as an OS application so users
 // can launch it without a terminal or npx command.
 //
-// This is an interim mitigation. Full packaged installers (electron-builder, code
-// signing, .msi/.dmg) are a separate effort requiring signing infrastructure.
+// #921 shipped this as a downloader: it fetched a packaged Electron app from the repository's
+// latest GitHub Release and pointed the shortcut at it. That never worked. The lookup is
+// unauthenticated and `mathursrus/FRAIM` is private (GitHub answers 404, not 403), and no release
+// has ever been published, so every run ended in `GitHub release lookup failed with HTTP 404`.
+//
+// #1179 replaces the download with a generated launcher that runs the Hub through
+// `npx fraim-hub@latest` (see `./hub-launcher`). That needs no release feed and no signing
+// infrastructure, and it matches the shape of the macOS installer that already ships:
+// `scripts/build-macos-installer.sh` builds a `pkgbuild --nopayload` package whose entire payload
+// is a script that runs `npx -y fraim@latest first-run`.
 const commander_1 = require("commander");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const child_process_1 = require("child_process");
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
-const hub_release_download_1 = require("./hub-release-download");
+const hub_launcher_1 = require("./hub-launcher");
 // Stable install directory under ~/.fraim/bin/fraim-hub-electron/
 function resolveHubInstallDir() {
     return path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), 'bin', 'fraim-hub-electron');
 }
-// The binary that OS shortcuts should point at. On Windows this is the Electron .exe;
-// on POSIX systems it is the unpacked Electron binary or a shell wrapper.
+// The file OS shortcuts point at: the generated launcher, `fraim-hub.cmd` on Windows and
+// `fraim-hub` elsewhere. Before #1179 this named a downloaded Electron binary that never arrived.
 function resolveShortcutTarget() {
-    const installDir = resolveHubInstallDir();
-    if (process.platform === 'win32') {
-        return path_1.default.join(installDir, 'fraim-hub.exe');
-    }
-    if (process.platform === 'darwin') {
-        return path_1.default.join(installDir, 'FRAIM Hub.app', 'Contents', 'MacOS', 'FRAIM Hub');
-    }
-    return path_1.default.join(installDir, 'fraim-hub');
+    return (0, hub_launcher_1.resolveLauncherPath)(resolveHubInstallDir());
 }
 // Platform-correct locations for OS launcher entries.
 function getOsShortcutPaths(home) {
@@ -48,7 +49,10 @@ function getOsShortcutPaths(home) {
     }
     if (process.platform === 'darwin') {
         return {
+            // The LaunchAgent starts the Hub headless at login; the .app is what Launchpad and Finder
+            // show. Neither substitutes for the other, so both are installed.
             launchAgent: path_1.default.join(home, 'Library', 'LaunchAgents', 'ai.fraim.hub.plist'),
+            appBundle: path_1.default.join(home, 'Applications', 'FRAIM Hub.app'),
         };
     }
     return {
@@ -81,11 +85,21 @@ function writeMacosLaunchAgent(plistPath, target) {
     fs_1.default.mkdirSync(path_1.default.dirname(plistPath), { recursive: true });
     fs_1.default.writeFileSync(plistPath, content, 'utf8');
 }
-function writeLinuxDesktopEntry(desktopPath, target) {
+function writeLinuxDesktopEntry(desktopPath, target, workingDir = os_1.default.homedir()) {
+    // No `--no-open` here. A .desktop entry is something the user clicks, and `--no-open` would start
+    // the server without ever showing the Hub. Only the macOS LaunchAgent, which runs at login with
+    // no click behind it, wants the headless form.
+    //
+    // `Path=` is not decoration. #646 lost a whole release to the same class of bug on macOS: the
+    // installer ran its bootstrap from a temp directory that no longer existed, so `npx`'s
+    // `process.cwd()` threw `ENOENT: uv_cwd` and first-run never launched (fixed in d680d2a6 by
+    // cd-ing to the user's home). A launcher started by a desktop environment inherits whatever
+    // working directory that environment had, so name one that is guaranteed to exist.
     const content = `[Desktop Entry]
 Name=FRAIM Hub
 Comment=FRAIM AI Workforce Hub
-Exec=${target} --no-open
+Exec=${target}
+Path=${workingDir}
 Icon=fraim-hub
 Terminal=false
 Type=Application
@@ -99,13 +113,26 @@ StartupNotify=true
     }
     catch { /* non-fatal */ }
 }
-function writeWindowsShortcutScript(lnkPath, target) {
+function writeWindowsShortcutScript(lnkPath, target, workingDir = os_1.default.homedir()) {
     // PowerShell WScript.Shell creates a real .lnk shortcut.
+    //
+    // WindowStyle 7 (minimized), not 1 (normal): the target is a .cmd, so Windows creates a console
+    // host for the length of the launch. `src/ai-hub/cli.ts` detaches and unrefs the Electron child,
+    // so npx returns once the Hub is ready and that console closes on its own; minimized keeps it
+    // from taking focus in front of the Hub window while it is up. Hiding it outright would need a
+    // wscript/VBS shim, which this repo has no precedent for.
+    //
+    // WorkingDirectory is set rather than left empty. #646 lost a release to the same class of bug:
+    // the macOS installer ran its bootstrap from a temp directory that no longer existed, `npx`'s
+    // `process.cwd()` threw `ENOENT: uv_cwd`, and first-run never launched (fixed in d680d2a6 by
+    // cd-ing to the user's home). A shortcut with no WorkingDirectory hands npx whatever directory
+    // the shell that launched it happened to be in.
     const ps = [
         '$ws = New-Object -ComObject WScript.Shell',
         `$sc = $ws.CreateShortcut('${lnkPath.replace(/'/g, "''")}')`,
         `$sc.TargetPath = '${target.replace(/'/g, "''")}'`,
-        "$sc.WindowStyle = 1",
+        `$sc.WorkingDirectory = '${workingDir.replace(/'/g, "''")}'`,
+        "$sc.WindowStyle = 7",
         '$sc.Save()',
     ].join('; ');
     try {
@@ -113,8 +140,10 @@ function writeWindowsShortcutScript(lnkPath, target) {
     }
     catch {
         // PowerShell unavailable (e.g. minimal CI image) — write a plain .cmd launcher as fallback.
+        // Same working-directory guarantee the .lnk gets above, for the same #646 reason.
         const safeTarget = target.replace(/"/g, '""');
-        const cmd = `@echo off\r\nstart "" "${safeTarget}"\r\n`;
+        const safeWorkingDir = workingDir.replace(/"/g, '""');
+        const cmd = `@echo off\r\ncd /d "${safeWorkingDir}"\r\nstart "" "${safeTarget}"\r\n`;
         const cmdPath = lnkPath.replace(/\.lnk$/i, '.cmd');
         fs_1.default.mkdirSync(path_1.default.dirname(cmdPath), { recursive: true });
         fs_1.default.writeFileSync(cmdPath, cmd, 'utf8');
@@ -127,14 +156,18 @@ async function runHubInstall() {
     const home = os_1.default.homedir();
     const shortcuts = getOsShortcutPaths(home);
     fs_1.default.mkdirSync(installDir, { recursive: true });
-    const downloaded = await (0, hub_release_download_1.downloadLatestHubBinary)(installDir, target);
-    console.log(`  Downloaded release asset: ${downloaded.assetName}`);
+    (0, hub_launcher_1.writeHubLauncher)({ installDir });
+    console.log(`  Launcher: ${target}`);
     if (process.platform === 'win32' && shortcuts.startMenu) {
         fs_1.default.mkdirSync(path_1.default.dirname(shortcuts.startMenu), { recursive: true });
-        writeWindowsShortcutScript(shortcuts.startMenu, target);
+        writeWindowsShortcutScript(shortcuts.startMenu, target, home);
         console.log(`  Start Menu shortcut: ${shortcuts.startMenu}`);
     }
     else if (process.platform === 'darwin' && shortcuts.launchAgent) {
+        if (shortcuts.appBundle) {
+            (0, hub_launcher_1.writeMacosAppBundle)(shortcuts.appBundle, target);
+            console.log(`  Application: ${shortcuts.appBundle}`);
+        }
         writeMacosLaunchAgent(shortcuts.launchAgent, target);
         // Load the agent so it is active immediately without a logout/login.
         try {
@@ -144,7 +177,7 @@ async function runHubInstall() {
         console.log(`  LaunchAgent: ${shortcuts.launchAgent}`);
     }
     else if (shortcuts.desktopEntry) {
-        writeLinuxDesktopEntry(shortcuts.desktopEntry, target);
+        writeLinuxDesktopEntry(shortcuts.desktopEntry, target, home);
         // Notify the desktop environment to refresh its app database.
         try {
             (0, child_process_1.execFileSync)('update-desktop-database', [path_1.default.dirname(shortcuts.desktopEntry)], { stdio: 'ignore' });
@@ -155,6 +188,7 @@ async function runHubInstall() {
     console.log('');
     console.log('FRAIM Hub is registered as an OS application.');
     console.log('Launch it from your Start Menu / Launchpad / application launcher.');
+    console.log('Each launch resolves the latest published fraim-hub, so there is nothing to reinstall.');
 }
 exports.hubInstallCommand = new commander_1.Command('install')
     .description('Register FRAIM Hub as an OS application (Start Menu / Launchpad entry)')

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

@@ -0,0 +1,184 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveLauncherPath = resolveLauncherPath;
+exports.writeHubLauncher = writeHubLauncher;
+exports.writeMacosAppBundle = writeMacosAppBundle;
+// #1179: the launcher an OS shortcut points at.
+//
+// `fraim-hub install` used to download a packaged Electron app from
+// `https://api.github.com/repos/mathursrus/FRAIM/releases/latest`. That call is unauthenticated and
+// `mathursrus/FRAIM` is private, so GitHub answered 404 rather than 403; and no release has ever
+// been published, because `.github/workflows/fraim-hub-release.yml` fires only on `release:
+// published`. The command therefore failed for every user and never produced anything launchable.
+//
+// The Hub does not need a packaged binary to be double-clickable. `npx fraim-hub@latest` already
+// resolves a shared Electron dist from `~/.fraim/bin/electron/<version>/` (#1112) and detaches the
+// desktop child (`src/ai-hub/cli.ts`), and the shipped macOS installer is the same shape: a
+// `pkgbuild --nopayload` package whose whole job is to run `npx -y fraim@latest first-run`. So the
+// shortcut target is a small generated script that runs the Hub through npx.
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * What the launcher runs.
+ *
+ * `@latest` and not a pinned version, because an npx-launched Hub has no self-update path:
+ * `configureAutoUpdater()` in `desktop-main.ts` returns immediately unless `app.isPackaged` (never
+ * true under npx), it reads from the same absent release feed, and `/api/ai-hub/version` only
+ * reports `updateAvailable` without acting on it. Resolving `@latest` at launch is the update
+ * mechanism; pinning here would strand users on the version they installed.
+ */
+const HUB_LAUNCH_SPEC = 'fraim-hub@latest';
+/**
+ * No `--restart`: it replaces a running Hub unconditionally, so double-clicking the icon while the
+ * Hub is up would kill it and pay a cold relaunch (~20s in #1110). The default already replaces
+ * only an older or stale instance and re-focuses a current one (`src/cli/fraim-hub.ts`).
+ *
+ * No `--no-open` either: that belongs to the background LaunchAgent, not to a clicked app entry.
+ */
+const NPX_ARGS = `-y ${HUB_LAUNCH_SPEC}`;
+/**
+ * Shown when no `npx` can be resolved. Worth a real sentence because the failure surface is a
+ * double-clicked icon with no terminal behind it, where the alternative is cmd's
+ * `'npx' is not recognized` flashing past.
+ *
+ * Emitted by a batch `echo`, so this string must stay free of `& | < > ^`, which cmd interprets
+ * rather than prints.
+ */
+const MISSING_NODE_MESSAGE = 'FRAIM Hub needs Node.js. Install it from https://nodejs.org/ and open FRAIM Hub again.';
+/**
+ * Quote a value for a POSIX shell script.
+ *
+ * The launcher interpolates filesystem paths into a script it then executes. Inside double quotes a
+ * shell still expands `$(...)`, backticks, and `$VAR`, so a path carrying any of those would be
+ * evaluated rather than used. Single quotes suppress all of it, and `'\''` is the standard way to
+ * carry a literal single quote through.
+ *
+ * These paths derive from `process.execPath` and `getUserFraimDirPath()` (which honours
+ * `FRAIM_USER_DIR`), so an attacker who controls them can already run code as this user. This is
+ * not a privilege boundary; it is a write-boundary guard kept next to the construction it protects,
+ * so a future caller passing a less trustworthy path does not turn this into one.
+ */
+function posixSingleQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Escape a value for literal use inside a batch file.
+ *
+ * `%` is the variable sigil, and a Windows path may legally contain it, so `C:\%TEMP%\node` would
+ * expand at parse time instead of naming the directory. In a batch file `%%` yields a literal `%`.
+ * `"` needs no handling: it is not a legal character in a Windows path.
+ */
+function batchEscape(value) {
+    return value.replace(/%/g, '%%');
+}
+/** `fraim-hub.cmd` on Windows, `fraim-hub` elsewhere. */
+function launcherFileName(platform = process.platform) {
+    return platform === 'win32' ? 'fraim-hub.cmd' : 'fraim-hub';
+}
+function resolveLauncherPath(installDir, platform = process.platform) {
+    return path_1.default.join(installDir, launcherFileName(platform));
+}
+/**
+ * The Node directory recorded into the launcher is *appended* to PATH, never prepended.
+ *
+ * Appended, because prepending would pin every future launch to whichever Node ran the install and
+ * shadow a later system upgrade indefinitely. A system `npx` should keep winning; this directory is
+ * the fallback for the case that made recording it necessary at all: a GUI shortcut inherits no
+ * shell PATH, and the portable-Node bootstrap in `scripts/installer/fraim-install-win.template.cmd`
+ * puts Node under `~/.fraim/node/...` where the system PATH never points.
+ */
+function renderWindowsLauncher(nodeDir) {
+    return [
+        '@echo off',
+        'rem FRAIM Hub launcher - generated by `fraim-hub install` (issue #1179). Safe to delete;',
+        'rem re-running `npx fraim-hub@latest install` recreates it.',
+        'setlocal',
+        `set "PATH=%PATH%;${batchEscape(nodeDir)}"`,
+        'where npx >nul 2>nul',
+        'if errorlevel 1 (',
+        `  echo ${MISSING_NODE_MESSAGE}`,
+        '  pause',
+        '  exit /b 1',
+        ')',
+        `call npx ${NPX_ARGS} %*`,
+        '',
+    ].join('\r\n');
+}
+function renderPosixLauncher(nodeDir) {
+    return [
+        '#!/bin/sh',
+        '# FRAIM Hub launcher - generated by `fraim-hub install` (issue #1179). Safe to delete;',
+        '# re-running `npx fraim-hub@latest install` recreates it.',
+        `FRAIM_NODE_DIR=${posixSingleQuote(nodeDir)}`,
+        'PATH="$PATH:$FRAIM_NODE_DIR"',
+        'export PATH',
+        'if ! command -v npx >/dev/null 2>&1; then',
+        `  echo "${MISSING_NODE_MESSAGE}" >&2`,
+        '  exit 1',
+        'fi',
+        `exec npx ${NPX_ARGS} "$@"`,
+        '',
+    ].join('\n');
+}
+/**
+ * Write the launcher and return its path. Idempotent: the contents depend only on the platform and
+ * the Node directory, so a repeat install rewrites the same bytes.
+ */
+function writeHubLauncher(options) {
+    const platform = options.platform ?? process.platform;
+    const nodeDir = options.nodeDir ?? path_1.default.dirname(process.execPath);
+    const launcherPath = resolveLauncherPath(options.installDir, platform);
+    fs_1.default.mkdirSync(options.installDir, { recursive: true });
+    fs_1.default.writeFileSync(launcherPath, platform === 'win32' ? renderWindowsLauncher(nodeDir) : renderPosixLauncher(nodeDir), 'utf8');
+    if (platform !== 'win32') {
+        fs_1.default.chmodSync(launcherPath, 0o755);
+    }
+    return launcherPath;
+}
+/**
+ * A minimal `.app` around the launcher, so macOS has something to show in Launchpad and Finder.
+ *
+ * The LaunchAgent `runHubInstall` already writes is a login item, not an application: it starts the
+ * Hub headless at login and produces no clickable entry. The two are complementary and both are
+ * installed.
+ *
+ * `CFBundleIdentifier` is deliberately `ai.fraim.hub.launcher`, not the `ai.fraim.hub` that
+ * `packages/fraim-hub/package.json` declares as electron-builder's `appId`. If a packaged Hub is
+ * ever installed alongside this one, two bundles sharing an identifier would leave LaunchServices
+ * to guess which is which.
+ */
+function writeMacosAppBundle(appDir, launcherPath) {
+    const executableName = 'FRAIM Hub';
+    const macosDir = path_1.default.join(appDir, 'Contents', 'MacOS');
+    fs_1.default.mkdirSync(macosDir, { recursive: true });
+    const infoPlist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleName</key>
+  <string>FRAIM Hub</string>
+  <key>CFBundleDisplayName</key>
+  <string>FRAIM Hub</string>
+  <key>CFBundleIdentifier</key>
+  <string>ai.fraim.hub.launcher</string>
+  <key>CFBundleExecutable</key>
+  <string>${executableName}</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  <key>CFBundleInfoDictionaryVersion</key>
+  <string>6.0</string>
+  <key>CFBundleVersion</key>
+  <string>1</string>
+  <key>CFBundleShortVersionString</key>
+  <string>1.0</string>
+</dict>
+</plist>
+`;
+    fs_1.default.writeFileSync(path_1.default.join(appDir, 'Contents', 'Info.plist'), infoPlist, 'utf8');
+    const executablePath = path_1.default.join(macosDir, executableName);
+    fs_1.default.writeFileSync(executablePath, `#!/bin/sh\nexec ${posixSingleQuote(launcherPath)} "$@"\n`, 'utf8');
+    fs_1.default.chmodSync(executablePath, 0o755);
+}

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

@@ -22,7 +22,10 @@ const defaultPreferences = (projectPath) => ({
     removedProjectPaths: [],
 });
 function normalizeProjectPath(projectPath) {
-    return path_1.default.resolve(projectPath || process.cwd());
+    if (typeof projectPath !== 'string' || projectPath.trim().length === 0) {
+        throw new Error('normalizeProjectPath: empty project path');
+    }
+    return path_1.default.resolve(projectPath);
 }
 function canonicalProjectPath(projectPath) {
     const normalized = normalizeProjectPath(projectPath);

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

@@ -1468,6 +1468,8 @@ const HUB_TO_FIRST_RUN_ID = {
     codex: 'codex',
     gemini: 'gemini-cli',
     copilot: 'copilot-cli',
+    // Issue #1205: antigravity (agy) has no npm package; wire it so the install route can handle it
+    antigravity: 'antigravity-cli',
 };
 function hubAgentOption(hubId) {
     const frId = HUB_TO_FIRST_RUN_ID[hubId];
@@ -1483,7 +1485,7 @@ function hubAgentOption(hubId) {
  * `runAddIDE` reads the FRAIM key from ~/.fraim/config.json (written by setup/first-run) and
  * `process.exit(1)`s when it is missing. We guard on that here via the exported `loadGlobalConfig`
  * so a missing key degrades to a logged no-op instead of terminating the long-running Hub server.
- * `skipTokenPrompts` keeps the run fully non-interactive.
+ * Base IDE setup does not collect third-party provider credentials.
  */
 async function configureFraimForHubAgent(hubId) {
     const frId = HUB_TO_FIRST_RUN_ID[hubId];
@@ -1497,7 +1499,7 @@ async function configureFraimForHubAgent(hubId) {
         }
         // `frId` (e.g. 'claude-code', 'codex', 'gemini-cli', 'copilot-cli') is a valid add-ide
         // `--ide` name/alias; runAddIDE resolves and configures it even when not yet detected.
-        await runAddIDE({ ide: frId, skipTokenPrompts: true });
+        await runAddIDE({ ide: frId });
         return { configured: true, ideName: frId };
     }
     catch (e) {
@@ -1698,7 +1700,13 @@ function isPathInsideDirectory(candidatePath, parentPath) {
 function isLikelyTemporaryProjectPath(projectPath) {
     if (!projectPath)
         return false;
-    return isPathInsideDirectory(projectPath, os_1.default.tmpdir());
+    if (isPathInsideDirectory(projectPath, os_1.default.tmpdir()))
+        return true;
+    const resolved = path_1.default.resolve(projectPath);
+    const home = os_1.default.homedir();
+    const commonLaunchDirectories = [home, path_1.default.join(home, 'Desktop'), path_1.default.join(home, 'Downloads')];
+    return commonLaunchDirectories.some((candidate) => sameDirectoryPath(resolved, candidate))
+        && !directoryExists(path_1.default.join(resolved, 'fraim'));
 }
 function isRelatedTemporaryProjectPath(projectPath, activeProjectPath) {
     if (!isLikelyTemporaryProjectPath(projectPath))
@@ -2430,7 +2438,7 @@ class AiHubServer {
         const managerTeam = personasResolved
             ? await this.withFirstPaintBudget(managerTeamPromise, [], 'manager team')
             : [];
-        const { personas, subscriptionActive, workspaceId, userKey } = personaProjection;
+        const { personas, subscriptionActive, workspaceId, userKey, identityAuthoritative } = personaProjection;
         void personaProjectionPromise.catch(() => undefined);
         void managerTeamPromise.catch(() => undefined);
         const resolvedUserEmail = userKey ?? null;
@@ -2478,6 +2486,10 @@ class AiHubServer {
             // 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,
+            // Issue #1185: lets the client tell a definitive "signed out" from "we could not
+            // reach the authority yet", so it neither latches the placeholder nor keeps showing
+            // a signed-out user's stale identity.
+            identityAuthoritative,
             // #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),
@@ -2759,6 +2771,13 @@ class AiHubServer {
         return record;
     }
     persistRunConversationNow(run, activeId) {
+        if ((run.scope ?? 'project') === 'project' && !run.projectPath.trim()) {
+            console.warn('[ai-hub] skipped project-scoped conversation write with no project path', {
+                runId: run.id,
+                conversationId: run.conversationId || run.id,
+            });
+            return;
+        }
         try {
             // Issue #708: route the record to its scope bucket (manager/company runs get a
             // project-independent home); project runs continue to key by project path.
@@ -3839,6 +3858,12 @@ class AiHubServer {
         // blip does not sign the user out; a definitive 401/no-key (reachable, null state)
         // yields null with no local-guess fallback (#750 contract).
         const userKey = this.resolveResilientUserKey(apiKey, state, reachable);
+        // Issue #1185: tell the client WHY the identity is what it is. A resolved identity is
+        // always authoritative. A null one is authoritative only when the authority actually
+        // answered — no key at all, or a reachable authority returning no state (401 /
+        // feature-off). When the authority could not be reached and nothing was cached, "not
+        // connected" is a guess, and the client must neither latch it nor sign the user out.
+        const identityAuthoritative = userKey !== null || !apiKey || reachable;
         // A null state means the Hub makes its ONLY self-owned access decision — render the
         // locked "not-signed-in" fallback. When a state IS returned, its per-persona
         // `status` is authoritative and rendered verbatim: the hired/locked decision
@@ -3847,7 +3872,7 @@ class AiHubServer {
         // re-derive it.
         const customPersonas = (0, custom_employees_1.readCustomEmployees)(projectPath).map(custom_employees_1.buildCustomEmployeePersona);
         if (!state) {
-            return { ...fallbackProjection, userKey };
+            return { ...fallbackProjection, userKey, identityAuthoritative };
         }
         try {
             const verdictByKey = new Map((state.personas || []).map((p) => [p.personaKey, p]));
@@ -3876,12 +3901,12 @@ class AiHubServer {
             });
             // Issue #945: union custom employees — they are always 'hired' and carry no
             // entitlement. Custom personas are appended so catalog order is unchanged.
-            return { personas: [...personas, ...customPersonas], subscriptionActive: state.subscriptionActive, workspaceId: state.workspaceId, userKey };
+            return { personas: [...personas, ...customPersonas], subscriptionActive: state.subscriptionActive, workspaceId: state.workspaceId, userKey, identityAuthoritative };
         }
         catch (err) {
             console.error('[ai-hub] persona lookup failed:', err);
             // Keep the (already-resolved) identity even if per-persona accounting fails.
-            return { ...fallbackProjection, userKey };
+            return { ...fallbackProjection, userKey, identityAuthoritative };
         }
     }
     fallbackPersonaProjection(apiKey, 
@@ -3900,11 +3925,16 @@ class AiHubServer {
             origin: 'catalog',
         }));
         const customPersonas = (0, custom_employees_1.readCustomEmployees)(projectPath).map(custom_employees_1.buildCustomEmployeePersona);
+        const userKey = apiKey ? this.lastResolvedIdentityByApiKey.get(apiKey) ?? null : null;
         return {
             personas: [...fallbackPersonas, ...customPersonas],
             subscriptionActive: false,
             workspaceId: null,
-            userKey: apiKey ? this.lastResolvedIdentityByApiKey.get(apiKey) ?? null : null,
+            userKey,
+            // Issue #1185: this projection is the first-paint placeholder. A null identity here
+            // means "the budget ran out before we knew", never "signed out". A cached identity
+            // IS authoritative — it came from a real prior resolve for this exact key.
+            identityAuthoritative: userKey !== null,
         };
     }
     async withFirstPaintBudget(promise, fallback, label) {
@@ -4071,7 +4101,7 @@ class AiHubServer {
             });
             // Issue #1005: pass the requested project so custom employees are scoped to it,
             // not to the directory the Hub launched from.
-            const { personas, subscriptionActive, workspaceId, userKey } = await this.computePersonas(apiKey, managerTeamPromise, projectPath);
+            const { personas, subscriptionActive, workspaceId, userKey, identityAuthoritative } = await this.computePersonas(apiKey, managerTeamPromise, projectPath);
             const managerTeam = await managerTeamPromise;
             const jobCount = (0, catalog_1.discoverEmployeeJobs)(projectPath, { includeRegistry: true })
                 .filter((job) => !FRAIM_INTERNAL_JOB_IDS.has(job.id))
@@ -4081,6 +4111,7 @@ class AiHubServer {
                 subscriptionActive,
                 workspaceId,
                 userEmail: userKey ?? null,
+                identityAuthoritative,
                 managerTeam,
                 firstRun: this.computeFirstRun(projectPath, jobCount, personas),
             });
@@ -4186,14 +4217,22 @@ class AiHubServer {
             const scope = scopeParam(req.query.scope);
             const key = scope
                 ? (0, conversation_store_1.conversationScopeKey)(scope, '')
-                : (typeof req.query.projectPath === 'string' && req.query.projectPath.length > 0
+                : (typeof req.query.projectPath === 'string' && req.query.projectPath.trim().length > 0
                     ? path_1.default.resolve(req.query.projectPath)
                     : this.defaultProjectPath());
+            const conversationId = typeof req.query.conversationId === 'string' ? req.query.conversationId : '';
+            if (!scope && !key) {
+                if (conversationId)
+                    return res.status(404).json({ error: 'conversation not found' });
+                if (req.query.headersOnly === '1' || req.query.headersOnly === 'true') {
+                    return res.json({ projectPath: '', scope: 'project', headersOnly: true, conversations: [], source: 'disk' });
+                }
+                return res.json({ projectPath: '', scope: 'project', activeId: null, conversations: [], source: 'disk' });
+            }
             // Issue #820: lazy read surfaces so the UI never has to parse the whole store.
             // ?conversationId=<id> -> one full body (lazy load on open).
             // ?headersOnly=1 -> newest-first headers, no bodies (fast list / first paint).
             // (default) -> full project (backwards compatible).
-            const conversationId = typeof req.query.conversationId === 'string' ? req.query.conversationId : '';
             if (conversationId) {
                 const conversation = this.conversationStore.loadConversation(key, conversationId);
                 if (!conversation)
@@ -4902,6 +4941,16 @@ class AiHubServer {
                         fraimConfigured: mcp.configured,
                     });
                 }
+                // Issue #1205: agents with no npm package (e.g. antigravity/agy) must be installed manually.
+                if (!option.installPackage) {
+                    return res.json({
+                        ok: true,
+                        manualInstall: true,
+                        installUrl: option.installUrl || '',
+                        message: `Install ${option.label} from the vendor site, then click "Download / Install" again to activate it.`,
+                        loginHint: `Once installed, click "Check if Ready" to verify ${option.label} is on your PATH.`,
+                    });
+                }
                 let standardInstallError = null;
                 try {
                     await hubRunProcess('npm', ['install', '-g', option.installPackage], {
@@ -6388,6 +6437,7 @@ class AiHubServer {
         // Pre-register before startRun so synchronous onEvent calls (e.g. FakeHostRuntime)
         // can call runRegistry.update without "Run not found" throws.
         this.runRegistry.create(run, {});
+        this.deploymentStore.update(deployment.id, (d) => { d.activeRunId = run.id; });
         const child = this.hostRuntime.startRun(hostId, deployment.projectPath, instructions, {
             onEvent: (event, channel) => {
                 this.runRegistry.update(run.id, (current) => {
@@ -6424,7 +6474,6 @@ class AiHubServer {
             },
         }, startSessionSeedForHost(hostId, run.id), launchContext);
         this.runRegistry.create(run, child);
-        this.deploymentStore.update(deployment.id, (d) => { d.activeRunId = run.id; });
         return run;
     }
     // ─── End Issue #578 helpers ───────────────────────────────────────────────

package/dist/src/cli/commands/add-ide.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.saveProviderTokenToConfig = exports.loadGlobalConfig = exports.addIDECommand = exports.runAddIDE = void 0;
+exports.loadGlobalConfig = exports.addIDECommand = exports.runAddIDE = void 0;
 const commander_1 = require("commander");
 const chalk_1 = __importDefault(require("chalk"));
 const prompts_1 = __importDefault(require("prompts"));
@@ -48,9 +48,6 @@ const mcp_config_generator_1 = require("../setup/mcp-config-generator");
 const claude_code_telemetry_1 = require("../setup/claude-code-telemetry");
 const script_sync_utils_1 = require("../utils/script-sync-utils");
 const mcp_server_registry_1 = require("../mcp/mcp-server-registry");
-const get_provider_client_1 = require("../api/get-provider-client");
-const provider_prompts_1 = require("../setup/provider-prompts");
-const provider_registry_1 = require("../providers/provider-registry");
 const user_config_1 = require("../utils/user-config");
 const resolveGlobalConfigPath = () => {
     const primary = path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'config.json');
@@ -84,41 +81,9 @@ const loadGlobalConfig = async () => {
         const config = JSON.parse(fs_1.default.readFileSync(globalConfigPath, 'utf8'));
         if (!config.apiKey)
             return null;
-        // Support both old and new token format
-        const tokens = config.tokens || {};
-        // Backward compatibility: map old format to new
-        // Only try to fetch provider IDs if we have a valid FRAIM key
-        if (config.apiKey) {
-            try {
-                const client = (0, get_provider_client_1.getProviderClient)();
-                const providerIds = await client.getAllProviderIds();
-                for (const id of providerIds) {
-                    const oldKey = `${id}Token`;
-                    if (config[oldKey] && !tokens[id]) {
-                        tokens[id] = config[oldKey];
-                    }
-                }
-            }
-            catch (e) {
-                // If provider client fails (network error, invalid key, etc.), 
-                // skip backward compatibility mapping and use local fallback
-                // This is fine - the config will still work with the new format
-            }
-        }
-        // Load all provider configs
-        const providerConfigs = {};
-        // New format: providerConfigs object
-        if (config.providerConfigs) {
-            Object.entries(config.providerConfigs).forEach(([key, value]) => {
-                const providerId = key.replace('Config', '');
-                providerConfigs[providerId] = value;
-            });
-        }
         return {
             fraimKey: config.apiKey,
-            tokens,
             mode: config.mode,
-            providerConfigs
         };
     }
     catch (e) {
@@ -126,65 +91,7 @@ const loadGlobalConfig = async () => {
     }
 };
 exports.loadGlobalConfig = loadGlobalConfig;
-const promptForProviderTokenIfNeeded = async (providerId, isOptional = false) => {
-    const client = (0, get_provider_client_1.getProviderClient)();
-    const provider = await client.getProvider(providerId);
-    if (!provider)
-        return '';
-    if (isOptional) {
-        console.log(chalk_1.default.yellow(`\n🔑 ${provider.displayName} token (optional for conversational mode)`));
-        console.log(chalk_1.default.gray(`${provider.displayName} token enables ${provider.displayName}-specific MCP features.\n`));
-        const wantsToken = await (0, prompts_1.default)({
-            type: 'confirm',
-            name: 'addToken',
-            message: `Do you want to add a ${provider.displayName} token?`,
-            initial: false
-        });
-        if (!wantsToken.addToken) {
-            console.log(chalk_1.default.blue(`ℹ️  Skipping ${provider.displayName} token - ${provider.displayName} MCP server will not be configured`));
-            return '';
-        }
-    }
-    else {
-        console.log(chalk_1.default.yellow(`\n🔑 ${provider.displayName} token needed for MCP configuration`));
-        console.log(chalk_1.default.gray(`This is required for ${provider.displayName} MCP servers to function properly.\n`));
-    }
-    try {
-        return await (0, provider_prompts_1.promptForProviderToken)(client, providerId);
-    }
-    catch (error) {
-        if (isOptional) {
-            console.log(chalk_1.default.blue(`ℹ️  No ${provider.displayName} token provided - ${provider.displayName} MCP server will not be configured`));
-            return '';
-        }
-        console.log(chalk_1.default.red(`${provider.displayName} token is required. Exiting.`));
-        process.exit(1);
-    }
-};
-const saveProviderTokenToConfig = async (providerId, token) => {
-    const globalConfigPath = resolveGlobalConfigPath();
-    if (fs_1.default.existsSync(globalConfigPath)) {
-        try {
-            const config = JSON.parse(fs_1.default.readFileSync(globalConfigPath, 'utf8'));
-            // Use new tokens structure
-            if (!config.tokens) {
-                config.tokens = {};
-            }
-            config.tokens[providerId] = token;
-            fs_1.default.writeFileSync(globalConfigPath, JSON.stringify(config, null, 2));
-            const { getProvider } = await Promise.resolve().then(() => __importStar(require('../providers/provider-registry')));
-            const provider = await getProvider(providerId);
-            console.log(chalk_1.default.green(`✅ ${provider?.displayName || providerId} token saved to global config`));
-        }
-        catch (e) {
-            const { getProvider } = await Promise.resolve().then(() => __importStar(require('../providers/provider-registry')));
-            const provider = await getProvider(providerId);
-            console.log(chalk_1.default.yellow(`⚠️ Could not save ${provider?.displayName || providerId} token to config`));
-        }
-    }
-};
-exports.saveProviderTokenToConfig = saveProviderTokenToConfig;
-const configureIDEMCP = async (ide, fraimKey, tokens, providerConfigs) => {
+const configureIDEMCP = async (ide, fraimKey) => {
     const configPath = (0, ide_detector_1.expandPath)(ide.configPath);
     console.log(chalk_1.default.blue(`🔧 Configuring ${ide.name}...`));
     // Create backup if config exists
@@ -219,13 +126,10 @@ const configureIDEMCP = async (ide, fraimKey, tokens, providerConfigs) => {
             existingTomlContent = fs_1.default.readFileSync(configPath, 'utf8');
             console.log(chalk_1.default.gray(`  📋 Found existing TOML config`));
         }
-        const newTomlContent = await (0, mcp_config_generator_1.generateMCPConfig)(ide.configType, fraimKey, tokens, providerConfigs);
+        const newTomlContent = await (0, mcp_config_generator_1.generateMCPConfig)(ide.configType, fraimKey, {});
         const { getAllMCPServerIds } = await Promise.resolve().then(() => __importStar(require('../mcp/mcp-server-registry')));
         const baseServerIds = getAllMCPServerIds();
-        // Add provider server IDs from tokens
-        const providerServerIds = Object.keys(tokens).filter(id => tokens[id]);
-        const serversToAdd = [...baseServerIds, ...providerServerIds];
-        const mergeResult = (0, mcp_config_generator_1.mergeTomlMCPServers)(existingTomlContent, newTomlContent, serversToAdd);
+        const mergeResult = (0, mcp_config_generator_1.mergeTomlMCPServers)(existingTomlContent, newTomlContent, baseServerIds);
         fs_1.default.writeFileSync(configPath, mergeResult.content);
         mergeResult.addedServers.forEach(server => {
             console.log(chalk_1.default.green(`  ✅ Added ${server} MCP server`));
@@ -239,14 +143,14 @@ const configureIDEMCP = async (ide, fraimKey, tokens, providerConfigs) => {
     }
     else {
         // For JSON configs - intelligent merging
-        const newConfig = await (0, mcp_config_generator_1.generateMCPConfig)(ide.configType, fraimKey, tokens, providerConfigs);
+        const newConfig = await (0, mcp_config_generator_1.generateMCPConfig)(ide.configType, fraimKey, {});
         const newMCPServers = newConfig[serversKey] || newConfig.mcpServers || {};
         // Merge MCP servers intelligently
         const mergedMCPServers = { ...existingMCPServers };
         const addedServers = [];
         const updatedServers = [];
         const skippedServers = [];
-        const alwaysUpdateServers = new Set(['fraim', 'github', 'gitlab', 'jira', 'ado', 'linear']);
+        const alwaysUpdateServers = new Set(['fraim']);
         for (const [serverName, serverConfig] of Object.entries(newMCPServers)) {
             if (!existingMCPServers[serverName]) {
                 mergedMCPServers[serverName] = serverConfig;
@@ -302,7 +206,7 @@ const listSupportedIDEs = () => {
     console.log(chalk_1.default.yellow('   Gemini aliases: gemini, gemini-cli, gemini cli'));
     console.log(chalk_1.default.yellow('   GitHub Copilot CLI aliases: copilot, copilot-cli, github copilot cli'));
 };
-const promptForIDESelection = async (availableIDEs, tokens) => {
+const promptForIDESelection = async (availableIDEs) => {
     console.log(chalk_1.default.green(`✅ Found ${availableIDEs.length} IDEs that can be configured:\n`));
     availableIDEs.forEach((ide, index) => {
         const configExists = fs_1.default.existsSync((0, ide_detector_1.expandPath)(ide.configPath));
@@ -315,14 +219,6 @@ const promptForIDESelection = async (availableIDEs, tokens) => {
     for (const server of mcp_server_registry_1.BASE_MCP_SERVERS) {
         console.log(chalk_1.default.gray(`   • ${server.id} (${server.description})`));
     }
-    // Show provider servers (only if tokens exist)
-    const allProviders = await (0, provider_registry_1.getAllProviders)();
-    for (const provider of allProviders) {
-        const hasToken = tokens?.[provider.id];
-        if (hasToken && provider.mcpServer) {
-            console.log(chalk_1.default.gray(`   - ${provider.id} (${provider.description})`));
-        }
-    }
     const response = await (0, prompts_1.default)({
         type: 'text',
         name: 'selection',
@@ -360,25 +256,8 @@ const runAddIDE = async (options) => {
         console.log(chalk_1.default.yellow('💡 Please run "fraim setup" first to configure your FRAIM keys.'));
         process.exit(1);
     }
-    const platformTokens = globalConfig.tokens || {};
     const isConversationalMode = globalConfig.mode === 'conversational';
-    // Check if any provider tokens exist
-    const allProviderIds = await (0, provider_registry_1.getAllProviderIds)();
-    const hasAnyToken = allProviderIds.some(id => platformTokens[id]);
-    if (!hasAnyToken && !isConversationalMode && !options.skipTokenPrompts) {
-        console.log(chalk_1.default.yellow('⚠️ No provider tokens found in configuration.'));
-        // Prompt for first integrated provider as default
-        const integratedProviders = await (0, provider_registry_1.getProvidersWithCapability)('integrated');
-        const defaultProviderId = integratedProviders[0]?.id;
-        if (defaultProviderId) {
-            const token = await promptForProviderTokenIfNeeded(defaultProviderId, false);
-            if (token) {
-                await saveProviderTokenToConfig(defaultProviderId, token);
-                platformTokens[defaultProviderId] = token;
-            }
-        }
-    }
-    if (isConversationalMode && !hasAnyToken) {
+    if (isConversationalMode) {
         console.log(chalk_1.default.blue('ℹ️  Conversational mode: Configuring MCP without platform integration\n'));
     }
     else {
@@ -415,7 +294,7 @@ const runAddIDE = async (options) => {
         }
         else {
             // Interactive selection
-            idesToConfigure = await promptForIDESelection(detectedIDEs, platformTokens);
+            idesToConfigure = await promptForIDESelection(detectedIDEs);
         }
     }
     if (idesToConfigure.length === 0) {
@@ -429,7 +308,7 @@ const runAddIDE = async (options) => {
     };
     for (const ide of idesToConfigure) {
         try {
-            await configureIDEMCP(ide, globalConfig.fraimKey, platformTokens, globalConfig.providerConfigs);
+            await configureIDEMCP(ide, globalConfig.fraimKey);
             results.successful.push(ide.name);
             (0, user_config_1.addInstalledIde)((0, ide_detector_1.getAdapterConfigType)(ide));
         }

package/dist/src/cli/mcp/ide-formats.js

@@ -257,7 +257,7 @@ class CodexFormat {
                 const escapedUrl = this.escapeToml(server.url);
                 sections.push(`[mcp_servers.${key}]`);
                 sections.push(`url = "${escapedUrl}"`);
-                // OAuth-first providers (e.g. GitHub) have no Authorization header — IDE manages auth
+                // URL-only provider metadata serializes without a synthesized Authorization header.
                 if (authHeader) {
                     sections.push(`http_headers = { Authorization = "${this.escapeToml(authHeader)}" }`);
                 }

package/dist/src/cli/mcp/mcp-server-registry.js

@@ -81,9 +81,9 @@ async function buildProviderMCPServer(providerId, token, config) {
     }
 }
 /**
- * Build an HTTP MCP server.
- * When authHeaderTemplate is absent the provider uses IDE-native OAuth (e.g. GitHub);
- * write a URL-only entry so the IDE handles the OAuth flow on first tool use.
+ * Serialize an HTTP MCP server from explicit provider metadata.
+ * A missing authHeaderTemplate produces a URL-only shape; it does not establish
+ * authentication compatibility for any agent host.
  */
 function buildHTTPServer(mcpConfig, token) {
     if (!mcpConfig.url) {

package/dist/src/cli/providers/local-provider-registry.js

@@ -22,7 +22,7 @@ const LOCAL_PROVIDERS = [
         description: 'GitHub repository and issue management',
         capabilities: ['code', 'issues', 'integrated'],
         docsUrl: 'https://docs.github.com',
-        setupInstructions: 'Run "fraim add-provider github" — your IDE handles OAuth automatically on first use',
+        setupInstructions: 'Ask your agent to use the FRAIM connect-mcp skill and follow current GitHub and host guidance',
         hasAdditionalConfig: false,
         mcpServer: {
             type: 'http',
@@ -35,7 +35,7 @@ const LOCAL_PROVIDERS = [
         description: 'GitLab repository and issue management',
         capabilities: ['code', 'issues', 'integrated'],
         docsUrl: 'https://docs.gitlab.com',
-        setupInstructions: 'Create a Personal Access Token in your GitLab settings',
+        setupInstructions: 'Ask your agent to use the FRAIM connect-mcp skill and follow current GitLab and host guidance',
         hasAdditionalConfig: false,
         mcpServer: {
             type: 'http',
@@ -49,7 +49,7 @@ const LOCAL_PROVIDERS = [
         description: 'Azure DevOps repository and issue management',
         capabilities: ['code', 'issues', 'integrated'],
         docsUrl: 'https://docs.microsoft.com/azure/devops',
-        setupInstructions: 'Create a Personal Access Token in Azure DevOps',
+        setupInstructions: 'Ask your agent to use the FRAIM connect-mcp skill and follow current Azure DevOps and host guidance',
         hasAdditionalConfig: true,
         mcpServer: {
             type: 'stdio',
@@ -66,7 +66,7 @@ const LOCAL_PROVIDERS = [
         description: 'Jira issue tracking and project management',
         capabilities: ['issues'],
         docsUrl: 'https://support.atlassian.com/jira',
-        setupInstructions: 'Create an API token at https://id.atlassian.com/manage-profile/security/api-tokens',
+        setupInstructions: 'Ask your agent to use the FRAIM connect-mcp skill and follow current Jira and host guidance',
         hasAdditionalConfig: true,
         mcpServer: {
             type: 'stdio',

package/dist/src/first-run/types.js

@@ -64,8 +64,8 @@ exports.FIRST_RUN_AGENT_OPTIONS = [
         detectAliases: ['agy', 'antigravity', 'antigravity-cli'],
         loginCommand: 'agy auth login',
         launchCommand: 'agy',
-        // agy has no npm package — install via https://antigravity.google/cli/
         installPackage: '',
+        installUrl: 'https://antigravity.google/cli/',
     },
 ];
 /**

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

@@ -139,8 +139,8 @@ function emptyStore() {
  * The shallow `record.offered && record.fired` this replaced was not enough. A
  * record whose sub-objects exist but are empty passed it and then threw in
  * `buildUsageReport` (`record.offered.log is not iterable`),
- * `findRetirementCandidates` and `deriveStanding`, so `fraim learning-usage
- * report` and `candidates` failed outright instead of degrading. That state is
+ * `findRetirementCandidates` and `deriveStanding`, so usage reports and
+ * candidate analysis failed outright instead of degrading. That state is
  * reachable: the store is a JSON file inside the manager home, which is commonly
  * a synced folder, so an interrupted write or a partial sync produces valid JSON
  * with a hollow record.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-hub",
-  "version": "2.0.271",
+  "version": "2.0.272",
   "description": "FRAIM Hub local companion package.",
   "bin": {
     "fraim-hub": "bin/fraim-hub.js",
@@ -168,7 +168,7 @@
     "electron-updater": "^6.8.9",
     "express": "^5.2.1",
     "extract-zip": "^2.0.1",
-    "fraim": "2.0.271",
+    "fraim": "2.0.272",
     "mongodb": "^7.0.0",
     "node-cron": "4.2.1",
     "node-edge-tts": "^1.2.10",

package/public/ai-hub/script.js

@@ -230,6 +230,36 @@ function cacheBootstrapPayload(bootstrap, docUrl) {
 // carrying the previous project's across would re-create the cross-project leak.
 const PERSONA_AUTHORITY_FIELDS = ['subscriptionActive', 'workspaceId', 'userEmail', 'managerTeam'];
 
+// Issue #1185: identity is the one authority field where "previous always wins" is wrong.
+// The other three describe the roster, which the placeholder genuinely does not know. But
+// bootstrap resolves `userEmail` from a SEPARATE, cheaper source — the server's resilient
+// identity cache — which warms after the first request even while the persona projection
+// keeps missing its 250ms budget. So an unresolved bootstrap routinely carries a correct
+// email alongside a placeholder roster, and copying `previous.userEmail` over it discarded
+// the real answer. Preferring whichever side actually has an identity keeps the roster
+// preservation of #1005 intact while letting the account menu recover.
+//
+// `authoritative` is the server's answer to "is this null a real answer?" (bootstrap /
+// personas `identityAuthoritative`). An authoritative null is a genuine sign-out and MUST
+// clear — otherwise a user who signed out, or whose ~/.fraim key changed, would keep seeing
+// the previous account's name and initials. A non-authoritative null is "we could not reach
+// the authority yet", and the last known identity stands.
+function preferResolvedIdentity(preferred, fallback, authoritative) {
+  if (preferred !== null && preferred !== undefined) return preferred;
+  if (authoritative) return preferred ?? null;
+  return fallback;
+}
+
+// Bootstrap projection merges are intentionally different from a fresh authority answer:
+// the incoming projection is explicitly unresolved, so its null can never clear a known
+// identity. Whichever side is non-null wins, independent of arrival order. A fresh personas
+// response still uses preferResolvedIdentity above, where an authoritative null clears.
+function mergeKnownIdentity(incoming, previous) {
+  if (incoming !== null && incoming !== undefined) return incoming;
+  if (previous !== null && previous !== undefined) return previous;
+  return null;
+}
+
 function mergePersonaProjection(incoming, previous) {
   if (!incoming || incoming.personasResolved !== false) return incoming;
   // Nothing trustworthy to fall back on (cold start, or the previous payload was itself a
@@ -243,6 +273,10 @@ function mergePersonaProjection(incoming, previous) {
   for (const field of PERSONA_AUTHORITY_FIELDS) {
     if (previous[field] !== undefined) merged[field] = previous[field];
   }
+  merged.userEmail = mergeKnownIdentity(incoming.userEmail, previous.userEmail);
+  merged.identityAuthoritative = merged.userEmail !== null
+    ? true
+    : Boolean(previous.identityAuthoritative && incoming.identityAuthoritative);
   return merged;
 }
 
@@ -337,6 +371,41 @@ async function refreshBootstrapInBackground(projectPath, docUrl) {
 
 let tfPersonaRefreshInFlight = null;
 
+// Issue #1185: the single tfInitShell lookup was the only thing standing between a cold
+// start and a permanently signed-out-looking Hub. When it comes back with no identity —
+// because the hosted authority was briefly unreachable while the server's resilient cache
+// was still cold — nothing used to try again until the user switched projects. These retries
+// close that gap. The schedule is exponential and finite: a user who really is signed out
+// gets a handful of extra requests over ~1 minute, then silence.
+const PERSONA_IDENTITY_RETRY_DELAYS_MS = [1000, 2000, 4000, 8000, 16000, 30000];
+let tfPersonaIdentityRetryCount = 0;
+let tfPersonaIdentityRetryTimer = null;
+
+// Called once an identity resolves. Resetting the counter as well as clearing the timer
+// means a LATER outage in the same long-lived window gets a fresh budget — without it, a
+// session that healed once would never retry again, which is the same permanent-latch
+// failure this issue is about, just deferred.
+function tfCancelPersonaIdentityRetry() {
+  if (tfPersonaIdentityRetryTimer !== null) {
+    clearTimeout(tfPersonaIdentityRetryTimer);
+    tfPersonaIdentityRetryTimer = null;
+  }
+  tfPersonaIdentityRetryCount = 0;
+}
+
+// Schedule the next attempt when a lookup produced no identity. Resolving an identity (or
+// exhausting the schedule) stops the chain; a retry already pending is never doubled up.
+function tfSchedulePersonaIdentityRetry() {
+  if (tfPersonaIdentityRetryTimer !== null) return;
+  const delay = PERSONA_IDENTITY_RETRY_DELAYS_MS[tfPersonaIdentityRetryCount];
+  if (delay === undefined) return;
+  tfPersonaIdentityRetryCount += 1;
+  tfPersonaIdentityRetryTimer = setTimeout(() => {
+    tfPersonaIdentityRetryTimer = null;
+    void tfRefreshPersonasFromServerInBackground();
+  }, delay);
+}
+
 function tfRefreshPersonaDependentSurfaces() {
   tfPopulateAccountMenu();
   renderPersonaGrid();
@@ -359,25 +428,42 @@ async function tfRefreshPersonasFromServerInBackground() {
   tfPersonaRefreshInFlight = requestJson('/api/ai-hub/personas' + query)
     .then((payload) => {
       if (!payload || !state.bootstrap) return;
+      const resolvedEmail = payload.userEmail ?? null;
+      // Issue #1185: only a response the server vouches for is the resolved projection.
+      // An identity-less answer from an unreachable authority is a guess; recording it as
+      // resolved is what latched the "not connected" avatar for the life of the window —
+      // it froze the null identity into every later merge AND switched off
+      // tfRefreshAfterBootstrap's re-request. A definitive sign-out IS resolved, and still
+      // clears, so signing out remains immediate.
+      const identityAuthoritative = Boolean(payload.identityAuthoritative);
+      const identityResolved = resolvedEmail !== null || identityAuthoritative;
       state.bootstrap = {
         ...state.bootstrap,
         personas: Array.isArray(payload.personas) ? payload.personas : state.bootstrap.personas,
         // Issue #1005: GET /api/ai-hub/personas awaits the authority with no first-paint
-        // budget, so a successful response IS the resolved projection. Marking it lets
-        // applyBootstrap preserve it against a later unresolved bootstrap, and stops
-        // tfRefreshAfterBootstrap from re-requesting a lookup that already succeeded.
-        personasResolved: true,
+        // budget, so a response that carries an identity IS the resolved projection.
+        // Marking it lets applyBootstrap preserve it against a later unresolved bootstrap,
+        // and stops tfRefreshAfterBootstrap re-requesting a lookup that already succeeded.
+        personasResolved: identityResolved,
         subscriptionActive: Boolean(payload.subscriptionActive),
         workspaceId: payload.workspaceId ?? null,
-        userEmail: payload.userEmail ?? null,
+        // Never trade a known identity for an unknown one, UNLESS the server says the
+        // unknown is definitive — a real sign-out has to take effect immediately.
+        userEmail: preferResolvedIdentity(resolvedEmail, state.bootstrap.userEmail, identityAuthoritative),
+        identityAuthoritative,
         managerTeam: Array.isArray(payload.managerTeam) ? payload.managerTeam : state.bootstrap.managerTeam,
         firstRun: payload.firstRun || state.bootstrap.firstRun,
       };
       cacheBootstrapPayload(state.bootstrap, new URLSearchParams(window.location.search).get('docUrl') || '');
       tfRefreshPersonaDependentSurfaces();
+      // Retry only while the "not connected" state is still a guess. A definitive
+      // sign-out is a final answer and must not be polled.
+      if (state.bootstrap.userEmail === null && !identityAuthoritative) tfSchedulePersonaIdentityRetry();
+      else tfCancelPersonaIdentityRetry();
     })
     .catch((error) => {
       console.warn('Could not refresh Hub personas:', error);
+      tfSchedulePersonaIdentityRetry();
     })
     .finally(() => {
       tfPersonaRefreshInFlight = null;
@@ -1049,6 +1135,7 @@ const SERVER_OWNED_CONV_FIELDS = ['messages', 'events', 'artifacts', 'run', 'del
 // any inbound value. That is what preserves issue #913: a marker arriving over
 // the wire is never trusted, only one this client set after a real fetch.
 const CLIENT_ONLY_CONV_FIELDS = ['_bodyLoaded', '_bodyFetched', '_stopping'];
+const FULL_BODY_CONV_FIELDS = ['messages', 'events', 'artifacts', 'run', 'handoffSummary'];
 function slimConversationForPersist(conv) {
   if (!conv || typeof conv !== 'object') return conv;
   const slim = { ...conv };
@@ -1067,7 +1154,7 @@ function conversationHasBody(conv) {
   // instead of looping. Issue #913 stays satisfied because `_bodyFetched` is
   // client-only and stripped from every inbound header.
   if (conv._bodyFetched === true) return true;
-  return SERVER_OWNED_CONV_FIELDS.some((field) => Object.prototype.hasOwnProperty.call(conv, field));
+  return FULL_BODY_CONV_FIELDS.some((field) => Object.prototype.hasOwnProperty.call(conv, field));
 }
 
 function cleanConversationHeader(header) {
@@ -2646,22 +2733,22 @@ function statusLabel(s) {
 
 function conversationUiState(conv) {
   if (!conv) return 'idle';
-  if (conv.blocked) return 'blocked';
-  // Issue #1081: a submit-phase review handoff is a manager gate even if the
-  // employee process is still alive for post-submit bookkeeping.
-  if (conv.pauseReason === 'awaiting_review') return 'waiting';
-  // Issue #550: recovered legacy freeform conversations can be persisted as
-  // "running" even though there is no FRAIM employee owner and no conversation
-  // body to indicate live work. Surface these as manager-attention items so the
-  // rail dot and label agree.
-  if (
-    conv.status === 'running'
-    && conv.jobId === '__freeform__'
-    && !conversationHasFraimEmployee(conv)
-    && !(conv.messages || []).length
-    && !(conv.events || []).length
-  ) return 'waiting';
-  if (conv.status === 'running') return 'working';
+  if (conv.blocked) return 'blocked';
+  // Issue #1081: a submit-phase review handoff is a manager gate even if the
+  // employee process is still alive for post-submit bookkeeping.
+  if (conv.pauseReason === 'awaiting_review') return 'waiting';
+  // Issue #550: recovered legacy freeform conversations can be persisted as
+  // "running" even though there is no FRAIM employee owner and no conversation
+  // body to indicate live work. Surface these as manager-attention items so the
+  // rail dot and label agree.
+  if (
+    conv.status === 'running'
+    && conv.jobId === '__freeform__'
+    && !conversationHasFraimEmployee(conv)
+    && !(conv.messages || []).length
+    && !(conv.events || []).length
+  ) return 'waiting';
+  if (conv.status === 'running') return 'working';
   // Issue #904: read pauseReason first for non-running records so the pill
   // reflects the exit classification rather than mapping all completed -> 'waiting'.
   if (conv.pauseReason === 'working') return 'working';
@@ -7423,7 +7510,10 @@ async function startAgentInstall(hubId) {
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ hubId }),
     });
-    if (result.ok) {
+    if (result.ok && result.manualInstall) {
+      if (result.installUrl) window.open(result.installUrl, '_blank');
+      setInstallState(hubId, 'login-triggered', result.loginHint || `Install from the vendor site, then click "Check if Ready".`);
+    } else if (result.ok) {
       setInstallState(hubId, 'needs-login', result.loginHint || 'Installed. Sign in to activate.');
     } else {
       setInstallState(hubId, 'error', result.message || 'Install failed.');