fraim-hub 2.0.310 → 2.0.311

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

@@ -24,6 +24,8 @@ const fraim_mcp_latest_launcher_1 = require("../cli/mcp/fraim-mcp-latest-launche
 const desktop_auto_updater_1 = require("./desktop-auto-updater");
 const hub_app_materializer_1 = require("./hub-app-materializer");
 const hub_instance_reconciliation_1 = require("./hub-instance-reconciliation");
+const hub_main_diagnostics_1 = require("./hub-main-diagnostics");
+const devtools_window_1 = require("./devtools-window");
 // Keep installed, running, and user-pinned Windows shortcuts grouped under the
 // stable identity declared in packages/fraim-hub/package.json.
 electron_1.app.setAppUserModelId('ai.fraim.hub');
@@ -163,7 +165,7 @@ async function resolveLatestHubAppVersion() {
         bundledVersion: runningVersion,
         bundledEntryPath: __filename,
     });
-    return { upgradable: resolved.version !== runningVersion, latest: resolved.version };
+    return { upgradable: resolved.version !== runningVersion, latest: resolved.version, error: resolved.materializationError };
 }
 // Issue #1415: a second-instance activation (the user re-clicking the icon while the Hub is
 // already running) is the common case once login-item autostart + hide-to-tray keep the Hub
@@ -189,9 +191,12 @@ async function checkForHubAppUpdateOnSecondInstance() {
 // response reaches the browser (which uses it to start polling for the new instance) before this
 // process starts tearing down.
 async function restartToLatestNow() {
-    const { upgradable, latest } = await resolveLatestHubAppVersion();
-    if (!upgradable)
-        return { restarting: false, latest };
+    const { upgradable, latest, error } = await resolveLatestHubAppVersion();
+    if (!upgradable) {
+        if (error)
+            console.warn(`[fraim] manual restart requested but could not complete: ${error}`);
+        return { restarting: false, latest, error };
+    }
     console.log(`[fraim] manual restart requested; relaunching to FRAIM Hub ${latest}`);
     setTimeout(() => {
         electron_1.app.relaunch();
@@ -274,6 +279,14 @@ function shouldConfigureOfficeSideload() {
 function displayName(runtimeId = process.env.FRAIM_HUB_RUNTIME_ID || 'hub') {
     return process.env.FRAIM_HUB_DISPLAY_NAME || (runtimeId === 'hub2' ? 'FRAIM Hub 2' : 'FRAIM Hub');
 }
+async function openMainWindowDevTools(hubUrl) {
+    await (0, devtools_window_1.openHubWindowDevTools)({
+        hubUrl,
+        getWindow: () => mainWindow,
+        createWindow,
+        recordOpenRequested: () => (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('hub.devtools.open_requested'),
+    });
+}
 function buildTrayMenu(hubUrl, runtimeId) {
     const name = displayName(runtimeId);
     return electron_1.Menu.buildFromTemplate([
@@ -289,6 +302,14 @@ function buildTrayMenu(hubUrl, runtimeId) {
                 }
             },
         },
+        {
+            label: 'Open DevTools',
+            click: () => {
+                void openMainWindowDevTools(hubUrl).catch((error) => {
+                    console.warn('[fraim] could not open Hub DevTools:', error);
+                });
+            },
+        },
         {
             // #755: surface the running build version so staleness is diagnosable at a glance.
             label: `About ${name}`,
@@ -345,6 +366,36 @@ function createTray(hubUrl, runtimeId) {
 // ---------------------------------------------------------------------------
 // BrowserWindow
 // ---------------------------------------------------------------------------
+function buildDesktopDebugSnapshot(runtimeId) {
+    const win = mainWindow;
+    const windowPresent = Boolean(win);
+    const isDestroyed = win ? win.isDestroyed() : null;
+    const canReadWindow = Boolean(win && !isDestroyed);
+    const safeRead = (reader) => {
+        if (!canReadWindow)
+            return null;
+        try {
+            return reader();
+        }
+        catch {
+            return null;
+        }
+    };
+    return {
+        runtimeId,
+        windowPresent,
+        isDestroyed,
+        isFocused: safeRead(() => win.isFocused()),
+        isVisible: safeRead(() => win.isVisible()),
+        isMinimized: safeRead(() => win.isMinimized()),
+        bounds: safeRead(() => win.getBounds()),
+        title: safeRead(() => win.getTitle()),
+        url: safeRead(() => win.webContents.getURL()),
+        webContentsDestroyed: win ? safeRead(() => win.webContents.isDestroyed()) : null,
+        devToolsOpened: safeRead(() => win.webContents.isDevToolsOpened()),
+        gpuFeatureStatus: electron_1.app.getGPUFeatureStatus(),
+    };
+}
 async function createWindow(url, runtimeId = process.env.FRAIM_HUB_RUNTIME_ID || 'hub') {
     const { width, height } = preferredWindowSize();
     const isMac = process.platform === 'darwin';
@@ -374,6 +425,32 @@ async function createWindow(url, runtimeId = process.env.FRAIM_HUB_RUNTIME_ID ||
         webPreferences: { contextIsolation: true, nodeIntegration: false, sandbox: true },
     });
     electron_1.Menu.setApplicationMenu(null);
+    mainWindow.on('focus', () => (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('window.focus'));
+    mainWindow.on('blur', () => (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('window.blur'));
+    mainWindow.on('show', () => (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('window.show'));
+    mainWindow.on('hide', () => (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('window.hide'));
+    mainWindow.on('close', () => (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('window.close', { isQuitting }));
+    mainWindow.webContents.on('render-process-gone', (_event, details) => {
+        (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('webcontents.render_process_gone', details);
+    });
+    mainWindow.webContents.on('unresponsive', () => (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('webcontents.unresponsive'));
+    mainWindow.webContents.on('responsive', () => (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('webcontents.responsive'));
+    mainWindow.webContents.on('did-finish-load', () => {
+        (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('webcontents.did_finish_load', {
+            url: mainWindow?.webContents.getURL() || '',
+            title: mainWindow?.getTitle() || '',
+        });
+    });
+    mainWindow.webContents.on('did-fail-load', (_event, errorCode, errorDescription, validatedURL, isMainFrame) => {
+        (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('webcontents.did_fail_load', {
+            errorCode,
+            errorDescription,
+            validatedURL,
+            isMainFrame,
+        });
+    });
+    mainWindow.webContents.on('devtools-opened', () => (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('webcontents.devtools_opened'));
+    mainWindow.webContents.on('devtools-closed', () => (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('webcontents.devtools_closed'));
     try {
         await mainWindow.webContents.session.clearCache();
     }
@@ -448,7 +525,10 @@ async function createWindow(url, runtimeId = process.env.FRAIM_HUB_RUNTIME_ID ||
             mainWindow?.hide();
         }
     });
-    mainWindow.on('closed', () => { mainWindow = null; });
+    mainWindow.on('closed', () => {
+        (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('window.closed');
+        mainWindow = null;
+    });
     await mainWindow.loadURL(url);
     mainWindow.webContents.setZoomFactor(1);
 }
@@ -499,6 +579,9 @@ async function launchDesktopShell(options) {
             return result.canceled || result.filePaths.length === 0 ? null : result.filePaths[0];
         },
         restartToLatest: restartToLatestNow,
+        hubMainDiagnostics: {
+            snapshot: () => (0, hub_main_diagnostics_1.getHubMainDiagnosticsSnapshot)(buildDesktopDebugSnapshot(runtimeId)),
+        },
     });
     await server.start(httpPort);
     const resolvedProjectPath = server.getProjectPath();
@@ -566,6 +649,16 @@ async function launchDesktopShell(options) {
 async function bootstrap() {
     const options = parseArgs(process.argv.slice(2));
     applyUserDataOverride();
+    (0, hub_main_diagnostics_1.installHubMainConsoleTee)();
+    (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('hub.startup', {
+        runtimeId: options.runtimeId,
+        preferredPort: options.preferredPort,
+        hasProjectPath: Boolean(options.projectPath),
+    });
+    electron_1.app.on('child-process-gone', (_event, details) => {
+        (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('app.child_process_gone', details);
+    });
+    electron_1.app.on('gpu-info-update', () => (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('app.gpu_info_update'));
     // Single-instance lock — if another instance is already running, focus it
     // and exit rather than spawning a second server + window.
     // Skip when FRAIM_AI_HUB_FAKE_HOST=1 (test mode) so Playwright can launch
@@ -577,6 +670,7 @@ async function bootstrap() {
         return;
     }
     electron_1.app.on('second-instance', () => {
+        (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('hub.second_instance');
         void electron_1.app.whenReady().then(checkForRelaunchAttemptUpdate);
         if (mainWindow) {
             mainWindow.show();
@@ -624,6 +718,7 @@ async function bootstrap() {
         // macOS: clicking dock icon re-shows the window. Unlike Windows/Linux, this never spawns a
         // second process (so 'second-instance' never fires here) — it is macOS's equivalent
         // relaunch-attempt event, so it gets the same npm-latest re-check (#1415).
+        (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('hub.activate');
         checkForRelaunchAttemptUpdate();
         if (mainWindow) {
             mainWindow.show();
@@ -632,6 +727,7 @@ async function bootstrap() {
     });
     electron_1.app.on('before-quit', () => {
         isQuitting = true;
+        (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('hub.shutdown');
         // #755: clear the runtime file so a later `fraim hub` doesn't treat a
         // cleanly-exited instance as live.
         try {

package/dist/src/ai-hub/devtools-window.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openHubWindowDevTools = openHubWindowDevTools;
+async function openHubWindowDevTools(options) {
+    options.recordOpenRequested?.();
+    let window = options.getWindow();
+    if (!window || window.isDestroyed()) {
+        await options.createWindow(options.hubUrl);
+        window = options.getWindow();
+    }
+    if (!window || window.isDestroyed())
+        return 'unavailable';
+    window.show();
+    window.focus();
+    window.webContents.openDevTools({ mode: 'detach' });
+    return 'opened';
+}

package/dist/src/ai-hub/hub-app-materializer.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HUB_APP_ENTRY_RELATIVE = exports.HUB_APP_PACKAGE_NAME = void 0;
+exports.redactCredentialLikeSubstrings = redactCredentialLikeSubstrings;
 exports.resolvePackagedCliScriptPath = resolvePackagedCliScriptPath;
 exports.planHubAppMaterialization = planHubAppMaterialization;
 exports.resolveHubAppCacheDir = resolveHubAppCacheDir;
@@ -33,6 +34,23 @@ const managed_node_runtime_1 = require("../cli/utils/managed-node-runtime");
 // offline matrix is unit-testable without touching npm, disk, or Electron — the same separation
 // `hub-launch-decision.ts` (#755) and `desktop-auto-updater.ts` (#1387) already established for
 // this exact class of problem.
+// Issue #1627 (security review): the raw materialization failure text below is now surfaced to a
+// new, wider audience than before this issue — a persisted log file and the manual restart-to-
+// latest HTTP response/UI — where previously it was silently discarded. `npm install` output does
+// not normally echo credentials, but a misconfigured corporate registry (a literal token in a
+// `.npmrc` URL, verbose proxy auth errors) is a real enough edge case that this new, wider surface
+// should not forward it as-is. Defense-in-depth only: redact credential-shaped substrings before
+// this text reaches either destination.
+const CREDENTIAL_LIKE_PATTERNS = [
+    /:\/\/[^\s/@]+:[^\s/@]+@/g, // scheme://user:pass@ basic-auth-in-URL
+    /\b(?:_authToken|authToken|Authorization|api[_-]?key|password)\s*[:=]\s*\S+/gi,
+    /\bnpm_[A-Za-z0-9]{20,}\b/g, // npm access-token shape
+    /\bBearer\s+[A-Za-z0-9._-]{10,}\b/gi,
+];
+/** Strip anything that looks like a credential from text before it is logged or surfaced. */
+function redactCredentialLikeSubstrings(text) {
+    return CREDENTIAL_LIKE_PATTERNS.reduce((acc, pattern) => acc.replace(pattern, '[redacted]'), text);
+}
 exports.HUB_APP_PACKAGE_NAME = 'fraim-hub';
 /** Relative path, from a materialized (or bundled) package root, to the Electron main entry. */
 exports.HUB_APP_ENTRY_RELATIVE = path_1.default.join('dist', 'src', 'ai-hub', 'desktop-main.js');
@@ -68,12 +86,14 @@ function planHubAppMaterialization(input) {
                 action: 'use-cached',
                 version: newestCached,
                 reason: 'npm registry unreachable; reusing the newest complete cached version',
+                degraded: false,
             };
         }
         return {
             action: 'use-bundled',
             version: bundledVersion,
             reason: 'npm registry unreachable and no cached version available; falling back to the version bundled with this installer',
+            degraded: true,
         };
     }
     if (latestPublishedVersion === bundledVersion) {
@@ -81,6 +101,7 @@ function planHubAppMaterialization(input) {
             action: 'use-bundled',
             version: bundledVersion,
             reason: 'the installed shell already matches the latest published version',
+            degraded: false,
         };
     }
     const alreadyMaterialized = cachedVersions.some((entry) => entry.complete && entry.version === latestPublishedVersion);
@@ -89,12 +110,14 @@ function planHubAppMaterialization(input) {
             action: 'use-cached',
             version: latestPublishedVersion,
             reason: 'latest published version is already materialized on disk',
+            degraded: false,
         };
     }
     return {
         action: 'materialize',
         version: latestPublishedVersion,
         reason: `latest published version ${latestPublishedVersion} is not yet materialized`,
+        degraded: false,
     };
 }
 // ---------------------------------------------------------------------------
@@ -265,7 +288,11 @@ async function resolveHubAppEntry(options) {
         cachedVersions,
     });
     if (plan.action === 'use-bundled') {
-        return { entryPath: options.bundledEntryPath, source: 'bundled', version: plan.version };
+        const materializationError = plan.degraded ? plan.reason : undefined;
+        if (materializationError) {
+            console.error(`[fraim] FRAIM Hub update check could not complete: ${materializationError}`);
+        }
+        return { entryPath: options.bundledEntryPath, source: 'bundled', version: plan.version, materializationError };
     }
     if (plan.action === 'use-cached') {
         return {
@@ -279,7 +306,10 @@ async function resolveHubAppEntry(options) {
         const entryPath = await ensureMaterializedHubApp(plan.version, { fraimDir, installPackage: options.installPackage });
         return { entryPath, source: 'cached', version: plan.version };
     }
-    catch {
-        return { entryPath: options.bundledEntryPath, source: 'bundled', version: options.bundledVersion };
+    catch (error) {
+        const rawMessage = error instanceof Error ? error.message : String(error);
+        const materializationError = redactCredentialLikeSubstrings(rawMessage);
+        console.error(`[fraim] failed to materialize FRAIM Hub ${plan.version}; falling back to bundled ${options.bundledVersion}: ${materializationError}`);
+        return { entryPath: options.bundledEntryPath, source: 'bundled', version: options.bundledVersion, materializationError };
     }
 }

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

@@ -0,0 +1,278 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HubMainDiagnostics = void 0;
+exports.getHubMainDiagnostics = getHubMainDiagnostics;
+exports.resetHubMainDiagnosticsForTest = resetHubMainDiagnosticsForTest;
+exports.recordHubMainDiagnostic = recordHubMainDiagnostic;
+exports.getHubMainDiagnosticsSnapshot = getHubMainDiagnosticsSnapshot;
+exports.installHubMainConsoleTee = installHubMainConsoleTee;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_util_1 = __importDefault(require("node:util"));
+const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
+const version_utils_1 = require("../cli/utils/version-utils");
+const DEFAULT_MAX_EVENTS = 100;
+const DEFAULT_MAX_CURRENT_BYTES = 1024 * 1024;
+const DEFAULT_MAX_RETAINED_CHUNKS = 20;
+const DEFAULT_MAX_RETAINED_BYTES = 50 * 1024 * 1024;
+const MAX_STRING_LENGTH = 1000;
+const SENSITIVE_KEY_PATTERN = /token|secret|password|api[-_]?key|credential|authorization/i;
+const EMAIL_PATTERN = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi;
+const SENSITIVE_TEXT_PATTERNS = [
+    /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g,
+    /\bsk-[A-Za-z0-9]{48,}\b/g,
+    /\bgh[pousr]_[A-Za-z0-9]{36,}\b/g,
+    /\bAKIA[0-9A-Z]{16}\b/g,
+    /\bSG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}\b/g,
+    /\bsk_live_[A-Za-z0-9]{24,}\b/g,
+    /(?:authorization|api[-_]?key|token|secret|password|credential)(["'\s:=]+)([^"',\s]{8,})/gi,
+];
+function resolveDefaultLogDir() {
+    try {
+        return node_path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), 'logs');
+    }
+    catch {
+        return node_path_1.default.join(node_os_1.default.homedir(), '.fraim', 'logs');
+    }
+}
+function redactSensitiveText(value) {
+    let redacted = value.replace(EMAIL_PATTERN, '[redacted-email]');
+    for (const pattern of SENSITIVE_TEXT_PATTERNS) {
+        redacted = redacted.replace(pattern, (match, separator) => {
+            if (typeof separator === 'string' && match.includes(separator)) {
+                return match.replace(new RegExp(`${separator.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}.*$`), `${separator}[redacted]`);
+            }
+            return '[redacted-secret]';
+        });
+    }
+    return redacted;
+}
+function boundedString(value, max = MAX_STRING_LENGTH) {
+    const redacted = redactSensitiveText(value);
+    return redacted.length > max ? `${redacted.slice(0, max)}...[truncated ${redacted.length - max} chars]` : redacted;
+}
+function safeFileSegment(value) {
+    const sanitized = value.replace(/[^a-z0-9._-]+/gi, '-').replace(/^-+|-+$/g, '');
+    return sanitized || 'hub';
+}
+function sanitizeDetail(value, depth = 0) {
+    if (value == null || typeof value === 'boolean' || typeof value === 'number')
+        return value;
+    if (typeof value === 'string')
+        return boundedString(value);
+    if (value instanceof Error)
+        return { name: value.name, message: boundedString(value.message) };
+    if (depth >= 4)
+        return '[truncated-depth]';
+    if (Array.isArray(value))
+        return value.slice(0, 20).map((item) => sanitizeDetail(item, depth + 1));
+    if (typeof value === 'object') {
+        const out = {};
+        for (const [key, item] of Object.entries(value).slice(0, 40)) {
+            out[key] = SENSITIVE_KEY_PATTERN.test(key) ? '[redacted]' : sanitizeDetail(item, depth + 1);
+        }
+        return out;
+    }
+    return boundedString(String(value));
+}
+function toDetails(details) {
+    if (!details)
+        return undefined;
+    const sanitized = sanitizeDetail(details);
+    return sanitized && typeof sanitized === 'object' && !Array.isArray(sanitized)
+        ? sanitized
+        : { value: sanitized };
+}
+function safeStat(filePath) {
+    try {
+        return node_fs_1.default.statSync(filePath);
+    }
+    catch {
+        return null;
+    }
+}
+function buildVersions() {
+    return {
+        node: process.versions.node,
+        ...(process.versions.electron ? { electron: process.versions.electron } : {}),
+        ...(process.versions.chrome ? { chrome: process.versions.chrome } : {}),
+    };
+}
+class HubMainDiagnostics {
+    constructor(options = {}) {
+        this.events = [];
+        this.rotationSequence = 0;
+        this.lastWriteError = null;
+        this.lastRenderProcessGone = null;
+        this.lastChildProcessGone = null;
+        this.lastUnresponsiveAt = null;
+        this.lastResponsiveAt = null;
+        this.runtimeId = options.runtimeId || process.env.FRAIM_HUB_RUNTIME_ID || 'hub';
+        this.now = options.now || (() => new Date());
+        this.maxEvents = options.maxEvents || DEFAULT_MAX_EVENTS;
+        this.maxCurrentBytes = options.maxCurrentBytes || DEFAULT_MAX_CURRENT_BYTES;
+        this.maxRetainedChunks = options.maxRetainedChunks || DEFAULT_MAX_RETAINED_CHUNKS;
+        this.maxRetainedBytes = options.maxRetainedBytes || DEFAULT_MAX_RETAINED_BYTES;
+        this.logDir = node_path_1.default.resolve(options.logDir || resolveDefaultLogDir());
+        this.logPath = node_path_1.default.join(this.logDir, 'hub-main.log');
+    }
+    record(type, details) {
+        const event = {
+            type,
+            timestamp: this.now().toISOString(),
+            runtimeId: this.runtimeId,
+            pid: process.pid,
+            appVersion: (0, version_utils_1.getFraimVersion)(),
+            ...(details ? { details: toDetails(details) } : {}),
+        };
+        this.events.push(event);
+        if (this.events.length > this.maxEvents)
+            this.events.splice(0, this.events.length - this.maxEvents);
+        if (type === 'webcontents.render_process_gone')
+            this.lastRenderProcessGone = event;
+        if (type === 'app.child_process_gone')
+            this.lastChildProcessGone = event;
+        if (type === 'webcontents.unresponsive')
+            this.lastUnresponsiveAt = event.timestamp;
+        if (type === 'webcontents.responsive')
+            this.lastResponsiveAt = event.timestamp;
+        this.persist(event);
+        return event;
+    }
+    snapshot(window = null) {
+        const current = safeStat(this.logPath);
+        return {
+            ok: true,
+            process: {
+                pid: process.pid,
+                platform: process.platform,
+                versions: buildVersions(),
+                uptimeSeconds: Math.round(process.uptime()),
+            },
+            log: {
+                path: this.logPath,
+                directory: this.logDir,
+                exists: Boolean(current),
+                bytes: current?.size || 0,
+                maxCurrentBytes: this.maxCurrentBytes,
+                retainedChunks: this.retainedChunks(),
+                lastWriteError: this.lastWriteError,
+            },
+            window,
+            lastEvents: [...this.events],
+            lastRenderProcessGone: this.lastRenderProcessGone,
+            lastChildProcessGone: this.lastChildProcessGone,
+            lastUnresponsiveAt: this.lastUnresponsiveAt,
+            lastResponsiveAt: this.lastResponsiveAt,
+            capturedAt: this.now().toISOString(),
+        };
+    }
+    persist(event) {
+        try {
+            node_fs_1.default.mkdirSync(this.logDir, { recursive: true });
+            const line = `${JSON.stringify(event)}\n`;
+            const current = safeStat(this.logPath);
+            if (current && current.size > 0 && current.size + Buffer.byteLength(line, 'utf8') > this.maxCurrentBytes) {
+                this.rotateCurrentLog();
+            }
+            node_fs_1.default.appendFileSync(this.logPath, line, 'utf8');
+            this.lastWriteError = null;
+        }
+        catch (error) {
+            this.lastWriteError = error instanceof Error ? boundedString(error.message, 500) : boundedString(String(error), 500);
+        }
+    }
+    rotateCurrentLog() {
+        if (!node_fs_1.default.existsSync(this.logPath))
+            return;
+        const timestamp = this.now().toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+        const chunkPath = node_path_1.default.join(this.logDir, `hub-main-${timestamp}-${safeFileSegment(this.runtimeId)}-${String(this.rotationSequence).padStart(4, '0')}.log`);
+        this.rotationSequence += 1;
+        node_fs_1.default.renameSync(this.logPath, chunkPath);
+        this.pruneRetainedChunks();
+    }
+    retainedChunks() {
+        try {
+            return node_fs_1.default.readdirSync(this.logDir)
+                .filter((name) => /^hub-main-.+\.log$/.test(name))
+                .map((name) => {
+                const filePath = node_path_1.default.join(this.logDir, name);
+                const stat = node_fs_1.default.statSync(filePath);
+                return { path: filePath, bytes: stat.size, modifiedAt: stat.mtime.toISOString() };
+            })
+                .sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt));
+        }
+        catch {
+            return [];
+        }
+    }
+    pruneRetainedChunks() {
+        const chunks = this.retainedChunks();
+        let retainedBytes = 0;
+        chunks.forEach((chunk, index) => {
+            retainedBytes += chunk.bytes;
+            if (index < this.maxRetainedChunks && retainedBytes <= this.maxRetainedBytes)
+                return;
+            try {
+                node_fs_1.default.unlinkSync(chunk.path);
+            }
+            catch {
+                // Best effort pruning; endpoint still reports remaining chunks.
+            }
+        });
+    }
+}
+exports.HubMainDiagnostics = HubMainDiagnostics;
+let singleton = null;
+let consoleTeeInstalled = false;
+let inConsoleTee = false;
+function getHubMainDiagnostics() {
+    if (!singleton)
+        singleton = new HubMainDiagnostics();
+    return singleton;
+}
+function resetHubMainDiagnosticsForTest(options = {}) {
+    singleton = new HubMainDiagnostics(options);
+    return singleton;
+}
+function recordHubMainDiagnostic(type, details) {
+    return getHubMainDiagnostics().record(type, details);
+}
+function getHubMainDiagnosticsSnapshot(window = null) {
+    return getHubMainDiagnostics().snapshot(window);
+}
+function installHubMainConsoleTee() {
+    if (consoleTeeInstalled)
+        return;
+    consoleTeeInstalled = true;
+    const originals = {
+        log: console.log.bind(console),
+        warn: console.warn.bind(console),
+        error: console.error.bind(console),
+    };
+    const wrap = (level, type) => {
+        return (...args) => {
+            originals[level](...args);
+            if (inConsoleTee)
+                return;
+            inConsoleTee = true;
+            try {
+                getHubMainDiagnostics().record(type, { message: node_util_1.default.format(...args) });
+            }
+            catch (error) {
+                originals.warn('[fraim] hub main diagnostic console tee failed:', error);
+            }
+            finally {
+                inConsoleTee = false;
+            }
+        };
+    };
+    console.log = wrap('log', 'log.info');
+    console.warn = wrap('warn', 'log.warn');
+    console.error = wrap('error', 'log.error');
+    getHubMainDiagnostics().record('hub.log_tee_installed');
+}

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

@@ -69,6 +69,7 @@ const manager_turns_1 = require("./manager-turns");
 const preferences_1 = require("./preferences");
 const conversation_store_1 = require("./conversation-store");
 const raw_event_log_store_1 = require("./raw-event-log-store");
+const hub_main_diagnostics_1 = require("./hub-main-diagnostics");
 const run_working_directory_1 = require("./run-working-directory");
 const conversation_search_1 = require("./conversation-search");
 const conversation_search_index_1 = require("./conversation-search-index");
@@ -3005,6 +3006,7 @@ class AiHubServer {
             userDataDir: process.env.FRAIM_BROWSER_USER_DATA_DIR || undefined,
             explicitPath: process.env.FRAIM_BROWSER_PATH || undefined,
         });
+        this.hubMainDiagnostics = options.hubMainDiagnostics || { snapshot: () => (0, hub_main_diagnostics_1.getHubMainDiagnosticsSnapshot)(null) };
         this.hostRuntime = options.hostRuntime || (process.env.FRAIM_AI_HUB_FAKE_HOST === '1' ? new hosts_1.FakeHostRuntime() : new hosts_1.CliHostRuntime());
         // 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
@@ -6122,6 +6124,17 @@ class AiHubServer {
         this.app.get('/api/ai-hub/pid', (_req, res) => {
             return res.json({ pid: process.pid });
         });
+        this.app.get('/api/ai-hub/debug/window-state', (_req, res) => {
+            try {
+                (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('debug.window_state_requested');
+                return res.json(this.hubMainDiagnostics.snapshot());
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                (0, hub_main_diagnostics_1.recordHubMainDiagnostic)('debug.window_state_failed', { error: message });
+                return res.status(500).json({ error: message });
+            }
+        });
         // Issue #1415/#1379: the update badge's click handler POSTs here instead of just telling the
         // user to quit and relaunch by hand. `restartToLatest` (the Electron shell's
         // restartToLatestNow) responds before it actually tears the process down, so the client can
@@ -6485,10 +6498,25 @@ class AiHubServer {
                 return res.status(404).json({ error: 'Configured agent not found or cannot be deleted.' });
             return res.json({ ok: true });
         });
-        this.app.post('/api/ai-hub/configured-agents/:id/check', (req, res) => {
+        this.app.post('/api/ai-hub/configured-agents/:id/check', async (req, res) => {
             if (!this.requireTrustedHubOrigin(req, res))
                 return;
-            const employees = this.hostRuntime.detectEmployees();
+            // Issue #1618: this is the manager's explicit "check now" action, so it must reflect
+            // reality immediately rather than serving the up-to-5-minute-stale detection cache -
+            // the same reasoning installAgentAndRefreshDetection() already applies after install
+            // (see the comment above that function, server.ts:~2430).
+            (0, hosts_1.invalidateEmployeeDetectionCache)();
+            // Security review (implement-security-review, issue #1618): prefer the non-blocking
+            // parallel probe here for the same reason bootstrapResponse() does (server.ts:~3939) -
+            // invalidating the cache on every click means this route now pays the full re-probe
+            // cost every time instead of at most once per TTL window, so the synchronous form
+            // would let a manager repeatedly clicking Check block the single-threaded Hub event
+            // loop for ~1-3s per click, reintroducing the exact issue-#1010 unresponsiveness this
+            // route previously avoided only by accident (via the cache). Falls back to the sync
+            // form for HostRuntime stubs that do not implement the async variant.
+            const employees = this.hostRuntime.detectEmployeesAsync
+                ? await this.hostRuntime.detectEmployeesAsync()
+                : this.hostRuntime.detectEmployees();
             const agent = this.configuredAgentsForCurrentMachine(employees).find((entry) => entry.id === req.params.id);
             if (!agent)
                 return res.status(404).json({ error: 'Configured agent not found.' });

package/package.json

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

package/public/ai-hub/script.js

@@ -7642,11 +7642,20 @@ function renderCpAgentPicker() {
   if (!picker) return;
   picker.innerHTML = '';
   const list = hubConfiguredAgents();
+  const hasAvailable = list.some((e) => e.available !== false && e.enabled !== false);
+  const footer = picker.closest('.cp-employee-footer');
+  if (footer) footer.hidden = !hasAvailable;
   const curOk = list.some((e) => e.id === state.cpEmployee && e.available !== false && e.enabled !== false);
   if (!curOk) {
     const firstAvail = list.find((e) => e.available !== false && e.enabled !== false);
     state.cpEmployee = firstAvail ? firstAvail.id : null;
   }
+  if (!hasAvailable) {
+    renderCpAgentInstallPanel();
+    const startBtn = document.getElementById('cp-start-btn');
+    if (startBtn) startBtn.disabled = true;
+    return;
+  }
   for (const e of list) {
     const pill = document.createElement('button');
     pill.type = 'button';
@@ -7808,6 +7817,12 @@ function rerunLastJob() {
 function showRerunToast(msg) {
   const t = document.createElement('div');
   t.className = 'cp-rerun-toast';
+  // Issue #1627: matches this app's own convention for transient status text (#be-status,
+  // #status-line, etc.) so a screen reader announces the message instead of it being silently
+  // visual-only - relevant beyond the original re-run case now that this toast also carries the
+  // real reason a restart-to-latest attempt failed.
+  t.setAttribute('role', 'status');
+  t.setAttribute('aria-live', 'polite');
   t.textContent = msg;
   document.body.appendChild(t);
   setTimeout(() => { if (t.parentNode) t.parentNode.removeChild(t); }, 5000);
@@ -8079,11 +8094,122 @@ function renderCpAgentInstallPanel() {
     panel.innerHTML = '';
     return;
   }
-  renderAgentInstallPanelInto(panel, {
-    heading: 'Set up a CLI agent before starting',
-    intro: 'Install, sign in, and verify one Hub agent to enable Start.',
-    testPrefix: 'cp-agent',
+  // Keep setup guidance centralized in Manager -> AI Agents.
+  panel.hidden = false;
+  panel.innerHTML = '';
+
+  const heading = document.createElement('div');
+  heading.className = 'install-panel-heading';
+  heading.textContent = 'No AI agent is set up yet';
+  panel.appendChild(heading);
+
+  const intro = document.createElement('p');
+  intro.className = 'install-panel-copy';
+  intro.textContent = 'Install, sign in, and verify a CLI agent in Manager -> AI Agents, then come back here to start.';
+  panel.appendChild(intro);
+
+  const link = document.createElement('button');
+  link.type = 'button';
+  link.className = 'secondary small';
+  link.textContent = 'Go to Manager -> AI Agents';
+  link.setAttribute('data-testid', 'cp-cli-setup-goto-manager');
+  link.addEventListener('click', () => {
+    closePalette();
+    if (typeof tfShowArea === 'function') tfShowArea('manager');
+    const acc = document.getElementById('manager-agents-acc');
+    if (acc) {
+      acc.open = true;
+      acc.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    }
   });
+  panel.appendChild(link);
+}
+
+// Issue #1618 (R3): the single shared install/sign-in row builder. Used both by the job
+// composer's standalone panels (renderAgentInstallPanelInto's loop below) and by the
+// Manager AI Agents panel's per-card mount (renderConfiguredAgentsPanel), so the two
+// surfaces share one state machine and cannot drift out of sync. `options.testPrefix`
+// namespaces testids per mount point (e.g. 'hub-agent' vs 'manager-agent').
+// PR feedback (#1620): `options.showLabel` (default true) and `options.resetLabel`
+// (default 'Choose another agent') let a mount point adapt wording/labeling without a
+// second implementation. `options.buttonClass`/`options.secondaryButtonClass` (default
+// 'secondary small'/'ghost small', the job composer's own standalone-panel button style)
+// let a mount point match its own surrounding card/button language instead. The job
+// composer's 3 mounts pass none of these and are unchanged.
+function buildAgentInstallRow(emp, options) {
+  const buttonClass = options.buttonClass || 'secondary small';
+  const secondaryButtonClass = options.secondaryButtonClass || 'ghost small';
+
+  const row = document.createElement('div');
+  row.className = 'install-row';
+  row.id = `install-row-${emp.id}`;
+
+  if (options.showLabel !== false) {
+    const label = document.createElement('span');
+    label.className = 'install-label';
+    label.textContent = emp.label;
+    row.appendChild(label);
+  }
+
+  const status = document.createElement('span');
+  status.className = 'install-status';
+  status.id = `install-status-${emp.id}`;
+  status.textContent = agentInstallState[emp.id]?.statusText || '';
+  row.appendChild(status);
+
+  const btn = document.createElement('button');
+  btn.className = buttonClass;
+  btn.id = `install-btn-${emp.id}`;
+  btn.dataset.hubId = emp.id;
+
+  const st = agentInstallState[emp.id] || {};
+  if (!st.phase) {
+    btn.textContent = `Download / Install ${emp.label}`;
+    btn.setAttribute('data-testid', `${options.testPrefix || 'hub-agent'}-install-${emp.id}`);
+    btn.addEventListener('click', () => startAgentInstall(emp.id));
+  } else if (st.phase === 'installing') {
+    btn.textContent = 'Installing...';
+    btn.disabled = true;
+  } else if (st.phase === 'needs-login') {
+    btn.textContent = 'Sign In';
+    btn.addEventListener('click', () => triggerAgentLogin(emp.id));
+  } else if (st.phase === 'login-triggered') {
+    const checkBtn = document.createElement('button');
+    checkBtn.className = buttonClass;
+    checkBtn.textContent = 'Check if Ready';
+    checkBtn.setAttribute('data-testid', `${options.testPrefix || 'hub-agent'}-check-${emp.id}`);
+    checkBtn.addEventListener('click', () => checkAgentReady(emp.id));
+    row.appendChild(checkBtn);
+
+    const skipBtn = document.createElement('button');
+    skipBtn.className = secondaryButtonClass;
+    // PR feedback (#1620): "Choose another agent" describes the job composer's picker
+    // context (abandon this one, pick a different employee/tool). The Manager panel has
+    // no picker to return to — clicking this just resets THIS card's install phase — so
+    // that mount passes a clearer label via options.resetLabel.
+    skipBtn.textContent = options.resetLabel || 'Choose another agent';
+    skipBtn.setAttribute('data-testid', `${options.testPrefix || 'hub-agent'}-reset-${emp.id}`);
+    skipBtn.style.marginLeft = '6px';
+    skipBtn.addEventListener('click', () => {
+      delete agentInstallState[emp.id];
+      renderAgentInstallPanel();
+      renderHubAgentSetupPanel();
+      renderCpAgentInstallPanel();
+      renderConfiguredAgentsPanel();
+    });
+    row.appendChild(skipBtn);
+    return row;
+  } else if (st.phase === 'ready') {
+    btn.textContent = 'Ready';
+    btn.disabled = true;
+    btn.style.color = 'var(--accent)';
+  } else if (st.phase === 'error') {
+    btn.textContent = 'Retry';
+    btn.addEventListener('click', () => startAgentInstall(emp.id));
+  }
+
+  row.appendChild(btn);
+  return row;
 }
 
 function renderAgentInstallPanelInto(panel, options) {
@@ -8113,70 +8239,7 @@ function renderAgentInstallPanelInto(panel, options) {
   }
 
   for (const emp of unavailable) {
-    const row = document.createElement('div');
-    row.className = 'install-row';
-    row.id = `install-row-${emp.id}`;
-
-    const label = document.createElement('span');
-    label.className = 'install-label';
-    label.textContent = emp.label;
-    row.appendChild(label);
-
-    const status = document.createElement('span');
-    status.className = 'install-status';
-    status.id = `install-status-${emp.id}`;
-    status.textContent = agentInstallState[emp.id]?.statusText || '';
-    row.appendChild(status);
-
-    const btn = document.createElement('button');
-    btn.className = 'secondary small';
-    btn.id = `install-btn-${emp.id}`;
-    btn.dataset.hubId = emp.id;
-
-    const st = agentInstallState[emp.id] || {};
-    if (!st.phase) {
-      btn.textContent = `Download / Install ${emp.label}`;
-      btn.setAttribute('data-testid', `${options.testPrefix || 'hub-agent'}-install-${emp.id}`);
-      btn.addEventListener('click', () => startAgentInstall(emp.id));
-    } else if (st.phase === 'installing') {
-      btn.textContent = 'Installing...';
-      btn.disabled = true;
-    } else if (st.phase === 'needs-login') {
-      btn.textContent = 'Sign In';
-      btn.addEventListener('click', () => triggerAgentLogin(emp.id));
-    } else if (st.phase === 'login-triggered') {
-      const checkBtn = document.createElement('button');
-      checkBtn.className = 'secondary small';
-      checkBtn.textContent = 'Check if Ready';
-      checkBtn.setAttribute('data-testid', `${options.testPrefix || 'hub-agent'}-check-${emp.id}`);
-      checkBtn.addEventListener('click', () => checkAgentReady(emp.id));
-      row.appendChild(checkBtn);
-
-      const skipBtn = document.createElement('button');
-      skipBtn.className = 'ghost small';
-      skipBtn.textContent = 'Choose another agent';
-      skipBtn.setAttribute('data-testid', `${options.testPrefix || 'hub-agent'}-reset-${emp.id}`);
-      skipBtn.style.marginLeft = '6px';
-      skipBtn.addEventListener('click', () => {
-        delete agentInstallState[emp.id];
-        renderAgentInstallPanel();
-        renderHubAgentSetupPanel();
-        renderCpAgentInstallPanel();
-      });
-      row.appendChild(skipBtn);
-      panel.appendChild(row);
-      continue;
-    } else if (st.phase === 'ready') {
-      btn.textContent = 'Ready';
-      btn.disabled = true;
-      btn.style.color = 'var(--accent)';
-    } else if (st.phase === 'error') {
-      btn.textContent = 'Retry';
-      btn.addEventListener('click', () => startAgentInstall(emp.id));
-    }
-
-    row.appendChild(btn);
-    panel.appendChild(row);
+    panel.appendChild(buildAgentInstallRow(emp, options));
   }
 }
 
@@ -8186,6 +8249,10 @@ function setInstallState(hubId, phase, statusText) {
   renderHubAgentSetupPanel();
   renderCpAgentInstallPanel();
   renderCpAgentPicker();
+  // Issue #1618: the Manager AI Agents panel's per-card install row shares this same
+  // agentInstallState, so it must refresh at the same choke point as the job composer's
+  // three panels or it drifts out of sync with them.
+  renderConfiguredAgentsPanel();
 }
 
 // Issue #1256 (slice c, AC-C4): backstop above the server's own AGENT_INSTALL_TIMEOUT_MS
@@ -8257,6 +8324,9 @@ async function refreshEmployees() {
     renderAgentInstallPanel();
     renderHubAgentSetupPanel();
     renderCpAgentInstallPanel();
+    // Issue #1618: the Manager AI Agents panel's per-card install row depends on the same
+    // refreshed employee roster (e.g. after "Check if Ready" confirms a host is now available).
+    renderConfiguredAgentsPanel();
   } catch { /* best-effort */ }
 }
 
@@ -9166,6 +9236,26 @@ function renderConfiguredAgentsPanel() {
       const renderedAvailable = latestCheck ? latestCheck.available !== false : agent.available !== false;
       const renderedEnabled = agent.enabled !== false;
       const renderedReasons = latestCheck?.reasons || agent.reasons || [];
+
+      // Issue #1618 (R2/R3), moved up (PR feedback #1620): computed before the actions
+      // row so the redundant top-of-card "Check" button can be omitted whenever the
+      // install row itself is about to render — the install row's own state machine
+      // (Download/Install -> Sign In -> Check if Ready) already provides a live-check
+      // path once installed, and "Check" against a not-yet-installed host communicates
+      // nothing the status pill/status pill text does not already say.
+      //
+      // Gated strictly on the underlying host CLI's own readiness (`emp.available ===
+      // false`), never on the configured-agent's `enabled` flag or any other not-ready
+      // reason (PR feedback #1620: an earlier, broader formula also showed the row for a
+      // profile that was merely disabled, or one with a good host but a broken/missing
+      // setup script -- neither of which installing/signing-in the CLI would fix; Edit
+      // is the correct path for both). `renderedAvailable` already prefers a fresh
+      // `latestCheck` result over the possibly-stale roster snapshot, so clicking "Check
+      // if Ready" inside the row hides the row (and restores the top Check button)
+      // immediately once ready.
+      const emp = hubEmployees().find((e) => e.id === agent.baseHostId);
+      const showInstallRow = emp ? emp.available === false : false;
+
       const card = document.createElement('div');
       card.className = 'configured-agent-card';
       card.dataset.testid = 'configured-agent-card';
@@ -9181,21 +9271,23 @@ function renderConfiguredAgentsPanel() {
 
       const actions = document.createElement('div');
       actions.className = 'configured-agent-card-actions';
-      const check = document.createElement('button');
-      check.type = 'button';
-      check.className = 'configured-agent-icon-action';
-      check.textContent = 'Check';
-      check.addEventListener('click', async () => {
-        try {
-          const result = await requestJson(`/api/ai-hub/configured-agents/${encodeURIComponent(agent.id)}/check`, { method: 'POST' });
-          state.configuredAgentCheckResults[agent.id] = result;
-          showStatus(result.available ? `${agent.label} is ready.` : `${agent.label}: ${(result.reasons || []).join(' ') || 'Check setup.'}`, !result.available);
-          renderConfiguredAgentsPanel();
-        } catch (err) {
-          showStatus(err.message || 'Agent check failed.', true);
-        }
-      });
-      actions.appendChild(check);
+      if (!showInstallRow) {
+        const check = document.createElement('button');
+        check.type = 'button';
+        check.className = 'configured-agent-icon-action';
+        check.textContent = 'Check';
+        check.addEventListener('click', async () => {
+          try {
+            const result = await requestJson(`/api/ai-hub/configured-agents/${encodeURIComponent(agent.id)}/check`, { method: 'POST' });
+            state.configuredAgentCheckResults[agent.id] = result;
+            showStatus(result.available ? `${agent.label} is ready.` : `${agent.label}: ${(result.reasons || []).join(' ') || 'Check setup.'}`, !result.available);
+            renderConfiguredAgentsPanel();
+          } catch (err) {
+            showStatus(err.message || 'Agent check failed.', true);
+          }
+        });
+        actions.appendChild(check);
+      }
 
       const edit = document.createElement('button');
       edit.type = 'button';
@@ -9243,6 +9335,38 @@ function renderConfiguredAgentsPanel() {
       card.appendChild(head);
       card.appendChild(meta);
       card.appendChild(detail);
+
+      // Issue #1618 (R2/R3/R4): a per-card install/sign-in affordance for an agent
+      // that isn't ready, reusing the job composer's shared row builder rather than a
+      // second parallel implementation. `showInstallRow` is computed above (it also
+      // gates the top "Check" button). The buttons are styled with the card's own
+      // `.configured-agent-icon-action` class (PR feedback #1620: the job composer's
+      // `.secondary small`/`.ghost small` classes read as a visually different, duller
+      // button style next to Check/Edit/Delete) instead of the job composer's own
+      // standalone-panel button classes.
+      if (showInstallRow) {
+        const installWrap = document.createElement('div');
+        installWrap.className = 'configured-agent-install-row';
+        installWrap.appendChild(buildAgentInstallRow(
+          emp || { id: agent.baseHostId, label: agent.label, available: false },
+          // PR feedback (#1620): the card's own title already names this configured
+          // agent, so the row's own `emp.label` line (the underlying host's label,
+          // which can legitimately differ from a custom configured-agent label) is
+          // suppressed here to avoid reading as a second, unrelated agent name.
+          // "Choose another agent" is replaced with "Start over" since there is no
+          // agent picker on this panel to return to -- the button only resets this
+          // card's own install phase.
+          {
+            testPrefix: 'manager-agent',
+            showLabel: false,
+            resetLabel: 'Start over',
+            buttonClass: 'configured-agent-icon-action',
+            secondaryButtonClass: 'configured-agent-icon-action',
+          },
+        ));
+        card.appendChild(installWrap);
+      }
+
       panel.appendChild(card);
     }
   }
@@ -16994,23 +17118,42 @@ function tfRestartHubToLatest(event) {
     badgeEl.textContent = '⬆️ Restarting…';
   }
   fetch('/api/ai-hub/restart-to-latest', { method: 'POST' })
-    .then((r) => (r.ok ? r.json() : Promise.reject(new Error(`status ${r.status}`))))
-    .then((info) => {
-      if (info && info.restarting) {
-        tfPollForHubRestart(info.latest || null, 0);
-      } else if (badgeEl) {
-        badgeEl.disabled = false;
-        badgeEl.textContent = '⬆️ Updates available';
+    .then((r) => r.json().catch(() => ({})).then((body) => ({ ok: r.ok, body })))
+    .then(({ ok, body }) => {
+      if (!ok) throw new Error((body && body.error) || 'Could not update FRAIM Hub.');
+      if (body && body.restarting) {
+        tfPollForHubRestart(body.latest || null, 0);
+        return;
       }
+      // Issue #1627: restarting:false used to be treated as "nothing to do" unconditionally, so a
+      // genuine materialization failure looked identical to "already current" and the badge just
+      // silently reverted with no explanation. An `error` here means the restart was attempted and
+      // failed - show the real reason instead of pretending the click did nothing.
+      tfShowHubRestartFailure(badgeEl, body && body.error);
     })
-    .catch(() => {
-      if (badgeEl) {
-        badgeEl.disabled = false;
-        badgeEl.textContent = '⬆️ Updates available';
-      }
+    .catch((err) => {
+      tfShowHubRestartFailure(badgeEl, err && err.message);
     });
 }
 
+// Issue #1627: how long the badge shows "Restart failed" before settling back to its steady
+// "an update is still available, click to try again" state.
+const HUB_RESTART_FAILURE_DISPLAY_MS = 8000;
+
+function tfShowHubRestartFailure(badgeEl, reason) {
+  const message = reason
+    ? `Could not update FRAIM Hub: ${reason}. Check your network or npm access, then click to try again.`
+    : 'Could not update FRAIM Hub. Check your network or npm access, then click to try again.';
+  showRerunToast(message);
+  if (!badgeEl) return;
+  badgeEl.disabled = false;
+  badgeEl.textContent = '⬆️ Restart failed';
+  badgeEl.title = message;
+  setTimeout(() => {
+    if (badgeEl.textContent === '⬆️ Restart failed') badgeEl.textContent = '⬆️ Updates available';
+  }, HUB_RESTART_FAILURE_DISPLAY_MS);
+}
+
 const HUB_RESTART_POLL_MS = 1000;
 const HUB_RESTART_POLL_MAX_ATTEMPTS = 45; // ~45s: generous for a fresh materialize-from-npm relaunch
 

package/public/ai-hub/styles.css

@@ -6198,6 +6198,32 @@ img.eh-av { object-fit: cover; background: var(--surface); }
   overflow-wrap: anywhere;
 }
 
+/* Issue #1618 (R4): the per-card install/sign-in row is a continuation of the existing
+   card, not a second panel — a dashed top border separates it from Check/Edit/Delete
+   above, matching the mock (docs/feature-specs/mocks/1618-view.html). The shared
+   .install-row/.install-label/.install-status/button.secondary.small/.ghost.small rules
+   above are reused, scoped-overridden only where the card's ~750px width behaves
+   differently than the job composer's ~340px standalone panel (PR #1620 feedback):
+   `.install-status`'s `flex:1` is designed to fill a narrow panel; at card width an
+   empty status span balloons into a large, unstyled-looking blank gap before the
+   action button. Capping it to content width and right-aligning the button instead
+   (matching the Check/Edit/Delete row's own right-aligned actions) keeps the same
+   information, without a wide accidental gap. Only `.configured-agent-install-row`
+   is affected; the 3 job-composer mounts keep their original layout unchanged. */
+.configured-agent-install-row {
+  margin-top: 8px;
+  padding-top: 8px;
+  border-top: 1px dashed var(--line);
+}
+
+.configured-agent-install-row .install-status {
+  flex: 0 1 auto;
+}
+
+.configured-agent-install-row .install-row button:first-of-type {
+  margin-left: auto;
+}
+
 .configured-agents-empty {
   margin: 0;
   color: var(--muted);