fraim-hub 2.0.283 → 2.0.284

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

@@ -2156,7 +2156,8 @@ class FakeHostRuntime {
     }
     startRun(hostId, _projectPath, message, handlers, _sessionId) {
         this.lastStartMessage = message;
-        return this.fakeProcess(hostId, this.fakeEmployeeReply('start', message), handlers);
+        const reply = this.startReply ?? this.fakeEmployeeReply('start', message);
+        return this.fakeProcess(hostId, reply, handlers);
     }
     continueRun(hostId, _projectPath, sessionId, message, handlers) {
         this.lastContinueMessage = message;

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

@@ -9,9 +9,16 @@ exports.refreshLatestPublishedVersionInBackground = refreshLatestPublishedVersio
 exports.__resetLatestVersionCache = __resetLatestVersionCache;
 const https_1 = __importDefault(require("https"));
 // Issue #755: best-effort "latest published fraim version" for the Hub's
-// update-available nudge. Cached in-process (1h TTL) and never throws — returns
+// update-available nudge. Cached in-process (5m TTL) and never throws — returns
 // null when offline or the registry is unreachable, so the nudge simply hides.
-const TTL_MS = 60 * 60 * 1000;
+// Issue #1379: TTL_MS was 1 hour, so a real npm publish could take up to an hour to
+// ever show up in a running Hub server's own cache, confirmed live (one process still
+// reporting a stale "latest" long after a newer version had been on the registry for
+// several minutes, while a freshly-started process reported the correct one). The
+// client only calls GET /api/ai-hub/version on page load, bootstrap refresh, and
+// persona-identity retry (not a fast poll loop), so 5 minutes cuts worst-case
+// staleness by 12x with no meaningful increase in registry request volume.
+const TTL_MS = 5 * 60 * 1000;
 const FAILED_RETRY_MS = 5 * 60 * 1000;
 const REGISTRY_URL = 'https://registry.npmjs.org/fraim/latest';
 let cache = { value: null, at: 0 };

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

@@ -18,6 +18,7 @@ exports.writeMacosAppBundle = writeMacosAppBundle;
 // `fraim-hub install` from the npm package.
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const windows_shim_path_search_1 = require("../core/utils/windows-shim-path-search");
 /**
  * What the launcher runs.
  *
@@ -94,13 +95,16 @@ function renderWindowsLauncher(nodeDir) {
         'rem re-running `npx fraim-hub@latest install` recreates it.',
         'setlocal',
         `set "PATH=%PATH%;${batchEscape(nodeDir)}"`,
-        'where npx >nul 2>nul',
-        'if errorlevel 1 (',
+        // Issue #1375: `where npx` depends on `where.exe` (C:\Windows\System32), which is
+        // unresolvable when the launching process's PATH omits System32. The PATH-search below
+        // needs no external binary and resolves an absolute path we can invoke directly.
+        ...(0, windows_shim_path_search_1.windowsPathSearchLines)('NPX_CMD', 'npx'),
+        'if not defined NPX_CMD (',
         `  echo ${MISSING_NODE_MESSAGE}`,
         '  pause',
         '  exit /b 1',
         ')',
-        `call npx ${NPX_ARGS} %*`,
+        `call "%NPX_CMD%" ${NPX_ARGS} %*`,
         '',
     ].join('\r\n');
 }

package/dist/src/ai-hub/server.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.findAvailablePortExcluding = exports.findAvailablePort = exports.AiHubServer = exports.HostConfigStore = exports.DeploymentStore = void 0;
+exports.findAvailablePortExcluding = exports.findAvailablePort = exports.AiHubServer = exports.HubConnectorStatusStore = exports.HostConfigStore = exports.DeploymentStore = void 0;
 exports.configureFraimForHubAgent = configureFraimForHubAgent;
 exports.hubCommandVersion = hubCommandVersion;
 exports.buildOpenFileInvocation = buildOpenFileInvocation;
@@ -48,6 +48,7 @@ const crypto_1 = require("crypto");
 const child_process_1 = require("child_process");
 const https_1 = __importDefault(require("https"));
 const types_1 = require("../first-run/types");
+const local_provider_registry_1 = require("../cli/providers/local-provider-registry");
 const learning_context_builder_1 = require("../local-mcp-server/learning-context-builder");
 const brand_store_1 = require("../core/brand-store");
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
@@ -604,6 +605,227 @@ class HostConfigStore {
     }
 }
 exports.HostConfigStore = HostConfigStore;
+class HubConnectorStatusStore {
+    constructor(filePath) {
+        this.filePath = filePath ?? path_1.default.join(getUserHubDir(), 'hub-connectors.json');
+    }
+    load() {
+        try {
+            if (!fs_1.default.existsSync(this.filePath))
+                return [];
+            const parsed = JSON.parse(fs_1.default.readFileSync(this.filePath, 'utf8'));
+            if (!Array.isArray(parsed))
+                return [];
+            return parsed.map((entry) => normalizeStoredConnectorStatus(entry)).filter(Boolean);
+        }
+        catch {
+            return [];
+        }
+    }
+    saveStatus(status) {
+        const list = this.load();
+        const next = list.filter((entry) => entry.id !== status.id);
+        next.push(status);
+        fs_1.default.mkdirSync(path_1.default.dirname(this.filePath), { recursive: true });
+        fs_1.default.writeFileSync(this.filePath, JSON.stringify(next.sort((a, b) => a.id.localeCompare(b.id)), null, 2));
+        return status;
+    }
+}
+exports.HubConnectorStatusStore = HubConnectorStatusStore;
+function normalizeConnectorId(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const id = raw.trim().toLowerCase();
+    return /^[a-z0-9][a-z0-9._-]{0,63}$/.test(id) ? id : null;
+}
+function connectorReadiness(configured, authenticated) {
+    if (!configured)
+        return 'missing_config';
+    if (!authenticated)
+        return 'needs_auth';
+    return 'ready';
+}
+function normalizeStoredConnectorStatus(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const value = raw;
+    const id = normalizeConnectorId(value.id);
+    if (!id)
+        return null;
+    const configured = Boolean(value.configured);
+    const authenticated = Boolean(value.authenticated);
+    const label = typeof value.label === 'string' && value.label.trim() ? value.label.trim() : id;
+    const transport = value.transport === 'stdio' || value.transport === 'http' ? value.transport : undefined;
+    const authMode = value.authMode === 'none' ||
+        value.authMode === 'env' ||
+        value.authMode === 'oauth' ||
+        value.authMode === 'api-token' ||
+        value.authMode === 'host-managed' ||
+        value.authMode === 'unknown'
+        ? value.authMode
+        : undefined;
+    return {
+        id,
+        label,
+        configured,
+        authenticated,
+        readiness: connectorReadiness(configured, authenticated),
+        source: 'configured',
+        ...(transport ? { transport } : {}),
+        ...(authMode ? { authMode } : {}),
+        ...(typeof value.detail === 'string' && value.detail.trim() ? { detail: value.detail.trim() } : {}),
+        ...(typeof value.updatedAt === 'string' && value.updatedAt.trim() ? { updatedAt: value.updatedAt.trim() } : {}),
+    };
+}
+function hasSecretLikeField(raw) {
+    if (!raw || typeof raw !== 'object')
+        return false;
+    if (Array.isArray(raw))
+        return raw.some((entry) => hasSecretLikeField(entry));
+    return Object.entries(raw).some(([key, value]) => /token|secret|password|apikey|api_key|credential/i.test(key) || hasSecretLikeField(value));
+}
+function readFraimApiKeyConfigured() {
+    if (process.env.FRAIM_API_KEY && process.env.FRAIM_API_KEY.trim())
+        return true;
+    try {
+        const configPath = path_1.default.join(os_1.default.homedir(), '.fraim', 'config.json');
+        if (!fs_1.default.existsSync(configPath))
+            return false;
+        const parsed = JSON.parse(fs_1.default.readFileSync(configPath, 'utf8'));
+        return typeof parsed.apiKey === 'string' && parsed.apiKey.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function providerConnectorStatus(provider) {
+    if (!provider.mcpServer)
+        return null;
+    const mcpServer = provider.mcpServer;
+    const needsAuth = Boolean(mcpServer.authHeaderTemplate || mcpServer.envTemplate);
+    return {
+        id: provider.id,
+        label: provider.displayName,
+        configured: false,
+        authenticated: false,
+        readiness: 'missing_config',
+        source: 'derived',
+        transport: mcpServer.type,
+        authMode: needsAuth ? 'unknown' : 'host-managed',
+        detail: 'External provider readiness is supplied by an agent-guided setup on this Hub machine, then recorded with non-secret connector status.',
+    };
+}
+function genericConnectorStatus(id) {
+    const provider = (0, local_provider_registry_1.getAllLocalProviders)().find((entry) => entry.id === id);
+    const providerStatus = provider ? providerConnectorStatus(provider) : null;
+    if (providerStatus)
+        return providerStatus;
+    return {
+        id,
+        label: id,
+        configured: false,
+        authenticated: false,
+        readiness: 'missing_config',
+        source: 'derived',
+        authMode: 'unknown',
+        detail: 'No connector status has been configured for this machine.',
+    };
+}
+function buildStoredConnectorStatusFromDerived(status) {
+    return normalizeStoredConnectorStatus({
+        ...status,
+        source: 'configured',
+        updatedAt: new Date().toISOString(),
+    });
+}
+function connectorSetupResponseForStatus(status, setupStatus, message, action) {
+    return {
+        connectorId: status.id,
+        status: setupStatus,
+        connector: status,
+        ...(action ? { action } : {}),
+        checkUrl: `/api/ai-hub/connectors/${status.id}/setup/check`,
+        message,
+    };
+}
+function buildDerivedConnectorStatuses() {
+    const fraimReady = readFraimApiKeyConfigured();
+    const base = [
+        {
+            id: 'fraim',
+            label: 'FRAIM',
+            configured: fraimReady,
+            authenticated: fraimReady,
+            readiness: connectorReadiness(fraimReady, fraimReady),
+            source: 'derived',
+            transport: 'stdio',
+            authMode: 'api-token',
+            detail: fraimReady ? 'FRAIM credential is available on this machine.' : 'Run fraim setup on this machine.',
+        },
+        {
+            id: 'git',
+            label: 'Git',
+            configured: true,
+            authenticated: true,
+            readiness: 'ready',
+            source: 'derived',
+            transport: 'stdio',
+            authMode: 'none',
+            detail: 'Base local Git MCP server is available in the generated FRAIM MCP set.',
+        },
+        {
+            id: 'playwright',
+            label: 'Playwright',
+            configured: true,
+            authenticated: true,
+            readiness: 'ready',
+            source: 'derived',
+            transport: 'stdio',
+            authMode: 'none',
+            detail: 'Base local Playwright MCP server is available in the generated FRAIM MCP set.',
+        },
+    ];
+    const providers = (0, local_provider_registry_1.getAllLocalProviders)()
+        .map((provider) => providerConnectorStatus(provider))
+        .filter(Boolean);
+    return [...base, ...providers];
+}
+function mergeConnectorStatuses(stored) {
+    const merged = new Map();
+    for (const status of buildDerivedConnectorStatuses())
+        merged.set(status.id, status);
+    for (const status of stored) {
+        const derived = merged.get(status.id);
+        if (derived?.readiness === 'ready' && status.readiness !== 'ready')
+            continue;
+        merged.set(status.id, status);
+    }
+    return [...merged.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+function missingRequiredConnectors(required, connectors) {
+    if (!Array.isArray(required) || required.length === 0)
+        return [];
+    const byId = new Map(connectors.map((connector) => [connector.id, connector]));
+    const missing = [];
+    for (const raw of required) {
+        const id = normalizeConnectorId(raw);
+        if (!id)
+            continue;
+        const connector = byId.get(id) || {
+            id,
+            label: id,
+            configured: false,
+            authenticated: false,
+            readiness: 'missing_config',
+            source: 'derived',
+            authMode: 'unknown',
+            detail: 'No connector status has been configured for this machine.',
+        };
+        if (connector.readiness !== 'ready')
+            missing.push(connector);
+    }
+    return missing;
+}
 async function pingHost(host) {
     const start = Date.now();
     try {
@@ -1530,6 +1752,31 @@ function hubCommandVersion(command, extraBinDirs, basePath) {
     const raw = (result.stdout || result.stderr || '').trim();
     return raw || null;
 }
+function hubRunSync(command, args, env) {
+    const resolvedCommand = (0, command_resolution_1.getSystemCommandPath)(command, process.env.PATH) || command;
+    const executable = process.platform === 'win32' ? 'cmd.exe' : resolvedCommand;
+    const realArgs = process.platform === 'win32'
+        ? ['/d', '/s', '/c', [resolvedCommand, ...args].map(hosts_1.escapeWindowsArg).join(' ')]
+        : args;
+    const childEnv = { ...process.env };
+    for (const [key, value] of Object.entries(env || {})) {
+        if (value === undefined)
+            delete childEnv[key];
+        else
+            childEnv[key] = value;
+    }
+    const result = (0, child_process_1.spawnSync)(executable, realArgs, {
+        encoding: 'utf8',
+        timeout: 10_000,
+        env: childEnv,
+    });
+    return {
+        status: result.status,
+        stdout: result.stdout || '',
+        stderr: result.stderr || '',
+        ...(result.error ? { error: result.error } : {}),
+    };
+}
 function hubRunProcess(command, args, env) {
     if (process.env.NODE_ENV === 'test' && command === 'npm' && process.env.FRAIM_TEST_HUB_NPM_ERROR) {
         return Promise.reject(new Error(process.env.FRAIM_TEST_HUB_NPM_ERROR));
@@ -2200,6 +2447,7 @@ class AiHubServer {
         this.deploymentStoreProvided = Boolean(options.deploymentStore);
         this.deploymentStore = options.deploymentStore ?? new DeploymentStore();
         this.hostConfigStore = options.hostConfigStore ?? new HostConfigStore();
+        this.connectorStatusStore = options.connectorStatusStore ?? new HubConnectorStatusStore();
         this.restartRecoveryPolicy = new restart_recovery_policy_1.RestartRecoveryPolicy({ machineLevelJobIds: MACHINE_LEVEL_JOB_IDS });
         this.app.use(express_1.default.json({ limit: '10mb' }));
         // CORS + Chrome Private Network Access for browser extensions and Office add-in task panes
@@ -5446,6 +5694,16 @@ class AiHubServer {
                 if (!instructions && !legacyMessage) {
                     throw new Error('Coach your employee before starting the run.');
                 }
+                const missingConnectors = missingRequiredConnectors(req.body.requiredConnectors, mergeConnectorStatuses(this.connectorStatusStore.load()));
+                if (missingConnectors.length > 0) {
+                    return res.status(409).json({
+                        error: 'Remote Hub connector preflight failed.',
+                        code: 'missing_remote_connectors',
+                        missingConnectors,
+                        capabilitiesUrl: '/api/ai-hub/capabilities',
+                        setupHint: 'Configure the connector on this Hub machine through the agent-guided setup workflow, then update non-secret connector status and retry.',
+                    });
+                }
                 const employees = this.hostRuntime.detectEmployees();
                 const { hostId, agent: configuredAgent, launchContext } = this.resolveLaunchAgent(req.body.configuredAgentId, requestedHostId, employees);
                 const prepared = instructions
@@ -6551,6 +6809,120 @@ class AiHubServer {
         });
         // ─── End Issue #945 ───────────────────────────────────────────────────────
         // GET /api/ai-hub/hosts — list registered remote hosts with health status.
+        this.app.get('/api/ai-hub/capabilities', (_req, res) => {
+            const employees = this.hostRuntime.detectEmployees();
+            const response = {
+                host: {
+                    id: 'local',
+                    label: os_1.default.hostname(),
+                    url: this.hubBase,
+                },
+                generatedAt: new Date().toISOString(),
+                agents: this.configuredAgentsForCurrentMachine(employees).map((agent) => (0, configured_agents_1.projectConfiguredAgent)(agent, employees)),
+                connectors: mergeConnectorStatuses(this.connectorStatusStore.load()),
+            };
+            return res.json(response);
+        });
+        this.app.put('/api/ai-hub/connectors/:id/status', (req, res) => {
+            if (!this.requireTrustedHubOrigin(req, res))
+                return;
+            const id = normalizeConnectorId(req.params.id);
+            if (!id)
+                return res.status(400).json({ error: 'Invalid connector id.' });
+            if (hasSecretLikeField(req.body)) {
+                console.warn('[ai-hub] connector status rejected secret-shaped payload', { connectorId: id });
+                return res.status(400).json({ error: 'Connector status must not include tokens, passwords, API keys, or credentials.' });
+            }
+            const configured = Boolean(req.body?.configured);
+            const authenticated = Boolean(req.body?.authenticated);
+            const candidate = normalizeStoredConnectorStatus({
+                id,
+                label: typeof req.body?.label === 'string' ? req.body.label : id,
+                configured,
+                authenticated,
+                transport: req.body?.transport,
+                authMode: req.body?.authMode,
+                detail: req.body?.detail,
+                updatedAt: new Date().toISOString(),
+            });
+            if (!candidate)
+                return res.status(400).json({ error: 'Invalid connector status.' });
+            const saved = this.connectorStatusStore.saveStatus(candidate);
+            console.log('[ai-hub] connector status updated', {
+                connectorId: saved.id,
+                readiness: saved.readiness,
+                configured: saved.configured,
+                authenticated: saved.authenticated,
+            });
+            return res.json(saved);
+        });
+        this.app.post('/api/ai-hub/connectors/:id/setup/start', (req, res) => {
+            if (!this.requireTrustedHubOrigin(req, res))
+                return;
+            const id = normalizeConnectorId(req.params.id);
+            if (!id)
+                return res.status(400).json({ error: 'Invalid connector id.' });
+            if (hasSecretLikeField(req.body)) {
+                console.warn('[ai-hub] connector setup rejected secret-shaped payload', { connectorId: id, action: 'start' });
+                return res.status(400).json({ error: 'Connector setup must not include tokens, passwords, API keys, or credentials.' });
+            }
+            const current = mergeConnectorStatuses(this.connectorStatusStore.load()).find((status) => status.id === id) || genericConnectorStatus(id);
+            if (current.readiness === 'ready') {
+                const saved = this.connectorStatusStore.saveStatus(buildStoredConnectorStatusFromDerived(current));
+                console.log('[ai-hub] connector setup status updated', {
+                    connectorId: saved.id,
+                    action: 'start',
+                    setupStatus: 'verified',
+                    readiness: saved.readiness,
+                });
+                return res.json(connectorSetupResponseForStatus(saved, 'verified', `${saved.label} is verified on this Hub machine.`));
+            }
+            const saved = this.connectorStatusStore.saveStatus(buildStoredConnectorStatusFromDerived(current));
+            console.log('[ai-hub] connector setup status updated', {
+                connectorId: saved.id,
+                action: 'start',
+                setupStatus: 'action_required',
+                readiness: saved.readiness,
+            });
+            return res.json(connectorSetupResponseForStatus(saved, 'action_required', `${saved.label} must be configured on this Hub machine before the remote run can start.`, {
+                type: 'manual',
+                label: `Configure ${saved.label} on the remote Hub machine`,
+                detail: 'Use the appropriate provider or MCP setup flow for the selected remote machine. Do not assume a CLI dependency from the Hub API; after verification, record non-secret readiness with PUT /api/ai-hub/connectors/{id}/status.',
+            }));
+        });
+        this.app.post('/api/ai-hub/connectors/:id/setup/check', (req, res) => {
+            if (!this.requireTrustedHubOrigin(req, res))
+                return;
+            const id = normalizeConnectorId(req.params.id);
+            if (!id)
+                return res.status(400).json({ error: 'Invalid connector id.' });
+            if (hasSecretLikeField(req.body)) {
+                console.warn('[ai-hub] connector setup rejected secret-shaped payload', { connectorId: id, action: 'check' });
+                return res.status(400).json({ error: 'Connector setup check must not include tokens, passwords, API keys, or credentials.' });
+            }
+            const current = mergeConnectorStatuses(this.connectorStatusStore.load()).find((status) => status.id === id) || genericConnectorStatus(id);
+            const saved = this.connectorStatusStore.saveStatus(buildStoredConnectorStatusFromDerived(current));
+            if (saved.readiness === 'ready') {
+                console.log('[ai-hub] connector setup status updated', {
+                    connectorId: saved.id,
+                    action: 'check',
+                    setupStatus: 'verified',
+                    readiness: saved.readiness,
+                });
+                return res.json(connectorSetupResponseForStatus(saved, 'verified', `${saved.label} is verified on this Hub machine.`));
+            }
+            console.log('[ai-hub] connector setup status updated', {
+                connectorId: saved.id,
+                action: 'check',
+                setupStatus: 'action_required',
+                readiness: saved.readiness,
+            });
+            return res.json(connectorSetupResponseForStatus(saved, 'action_required', `${saved.label} is not ready on this Hub machine.`, {
+                type: 'manual',
+                label: `Verify ${saved.label} on the remote Hub machine`,
+                detail: 'The agent-guided setup must verify the provider on the remote machine and then PUT a non-secret ready status. The Hub does not infer provider-specific auth state.',
+            }));
+        });
         this.app.get('/api/ai-hub/hosts', async (_req, res) => {
             const hosts = this.hostConfigStore.load();
             const healthResults = await Promise.allSettled(hosts.map((h) => pingHost(h)));

package/dist/src/cli/mcp/fraim-mcp-latest-launcher.js

@@ -14,6 +14,7 @@ exports.ensureFraimMcpLatestLauncher = ensureFraimMcpLatestLauncher;
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
+const windows_shim_path_search_1 = require("../../core/utils/windows-shim-path-search");
 const LAUNCHER_VERSION = 1;
 const PACKAGED_RUNTIME_VERSION = 1;
 const launcherSource = `#!/usr/bin/env node
@@ -194,9 +195,9 @@ function packagedFraimShimSource(command, runtime) {
 const windowsFraimMcpShimSource = `@echo off
 setlocal
 for %%I in ("%~dp0..") do set "FRAIM_USER_DIR_VALUE=%%~fI"
-where node >nul 2>nul
-if not errorlevel 1 (
-  node "%FRAIM_USER_DIR_VALUE%\\bin\\fraim-mcp-latest.js" %*
+${(0, windows_shim_path_search_1.windowsPathSearchLines)('NODE_EXE', 'node').join('\n')}
+if defined NODE_EXE (
+  "%NODE_EXE%" "%FRAIM_USER_DIR_VALUE%\\bin\\fraim-mcp-latest.js" %*
   exit /b %ERRORLEVEL%
 )
 if exist "%FRAIM_USER_DIR_VALUE%\\node\\node.exe" (
@@ -217,9 +218,9 @@ exit /b 1
 const windowsFraimNpxShimSource = `@echo off
 setlocal
 for %%I in ("%~dp0..") do set "FRAIM_USER_DIR_VALUE=%%~fI"
-where npx >nul 2>nul
-if not errorlevel 1 (
-  npx %*
+${(0, windows_shim_path_search_1.windowsPathSearchLines)('NPX_CMD', 'npx').join('\n')}
+if defined NPX_CMD (
+  "%NPX_CMD%" %*
   exit /b %ERRORLEVEL%
 )
 if exist "%FRAIM_USER_DIR_VALUE%\\node\\npx.cmd" (

package/dist/src/core/utils/windows-shim-path-search.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * Shared Windows batch-script primitive for resolving an executable on `PATH` without
+ * depending on `where.exe`.
+ *
+ * Issue #1375: every generated `.cmd` launcher in this repo used to probe for `node`/`npx`
+ * with `where <name> >nul 2>nul`. `where.exe` itself lives in `C:\Windows\System32`, so on a
+ * launching process whose `PATH` omits `System32` — the normal case for a shell started from
+ * the VS Code integrated Git Bash terminal — the probe is unresolvable and falsely reports the
+ * target missing even when it is on `PATH`. cmd.exe's own command dispatch resolves external
+ * commands strictly through `PATH` (not the OS's default `CreateProcess` search order, which
+ * would fall back to the system directory automatically), so this is a real, reproducible gap,
+ * not a theoretical one.
+ *
+ * `for %%X in (<name>) do set "VAR=%%~$PATH:X"` is cmd.exe's native argument-expansion PATH
+ * search. It needs no external binary — the direct analogue of a POSIX shell's `command -v`
+ * builtin — and resolves to an absolute path the caller can invoke directly. Unlike `where`, it
+ * needs an exact filename (no `%PATHEXT%` extension search of its own), so this module tries
+ * `.exe` then `.cmd` in turn to match `where`'s original extension-agnostic behavior.
+ *
+ * Every `.cmd` generator in this repo that needs to resolve node/npx/git on Windows should call
+ * this instead of hand-rolling its own `where` probe: three independent reimplementations of this
+ * exact check (`src/cli/mcp/fraim-mcp-latest-launcher.ts`, `src/ai-hub/hub-launcher.ts`, and
+ * `scripts/installer/fraim-install-win.template.cmd`) is exactly how the `where`-based bug shipped
+ * on Windows only while the POSIX shim's single `command -v` call stayed correct.
+ *
+ * `scripts/installer/fraim-install-win.template.cmd` is a static text file, not generated from
+ * this module (it is read verbatim and two tokens substituted, not built from TypeScript), so it
+ * cannot import this function. It re-implements the identical pattern as literal batch text —
+ * keep both in sync when this logic changes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.windowsPathSearchLines = windowsPathSearchLines;
+/**
+ * Extensions tried, in order, when resolving a bare command name — mirrors the two extensions
+ * every tool this repo probes for actually ships as: `node.exe`/`git.exe`/`winget.exe` are native
+ * PE binaries, `npx.cmd` is npm's batch shim. `%%~$PATH:X` needs an exact filename (unlike `where`,
+ * it does not consult `%PATHEXT%` itself), so trying each extension in turn is what restores
+ * `where`'s original extension-agnostic behavior.
+ */
+const WINDOWS_EXECUTABLE_EXTENSIONS = ['.exe', '.cmd'];
+/**
+ * Returns the batch-script lines that resolve `targetBaseName` (no extension) on `PATH` into
+ * `varName`, trying each of `WINDOWS_EXECUTABLE_EXTENSIONS` in turn, or leave `varName` undefined
+ * if none match. Caller decides line joining (`\n` vs `\r\n`) and what to do with the result —
+ * typically `if defined <varName> ( "%<varName>%" ... )`.
+ *
+ * @param varName Batch variable to receive the resolved absolute path, e.g. `NODE_EXE`.
+ * @param targetBaseName Command name without extension, e.g. `node`, `npx`, `git`, `winget`.
+ */
+function windowsPathSearchLines(varName, targetBaseName) {
+    return [
+        `set "${varName}="`,
+        ...WINDOWS_EXECUTABLE_EXTENSIONS.map((ext) => `if not defined ${varName} for %%X in (${targetBaseName}${ext}) do set "${varName}=%%~$PATH:X"`),
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-hub",
-  "version": "2.0.283",
+  "version": "2.0.284",
   "description": "FRAIM Hub local companion package.",
   "author": "Sid Mathur <sid.mathur@gmail.com>",
   "homepage": "https://github.com/mathursrus/FRAIM#readme",
@@ -75,6 +75,7 @@
     "dist/src/core/utils/ports.js",
     "dist/src/core/utils/project-fraim-paths.js",
     "dist/src/core/utils/setup-preferences.js",
+    "dist/src/core/utils/windows-shim-path-search.js",
     "dist/src/db/payment-repository.js",
     "dist/src/fraim/db-service.js",
     "dist/src/first-run/",
@@ -209,7 +210,7 @@
     "electron-updater": "^6.8.9",
     "express": "^5.2.1",
     "extract-zip": "^2.0.1",
-    "fraim": "2.0.283",
+    "fraim": "2.0.284",
     "mongodb": "^7.0.0",
     "node-cron": "4.2.1",
     "node-edge-tts": "^1.2.10",

package/public/ai-hub/excel-taskpane/index.html

@@ -121,7 +121,7 @@
 
     function emptyContext() {
       var meta = docMeta();
-      return { docUrl: meta.docUrl, docTitle: meta.docTitle, selection: '', hasSelection: true, bodyPreview: '', wordCount: 0, comments: [] };
+      return { docUrl: meta.docUrl, docTitle: meta.docTitle, selection: '', hasSelection: true, bodyPreview: '', wordCount: 0, comments: [], hostApp: 'Excel' };
     }
 
     function readFullContext(cb) {
@@ -150,6 +150,7 @@
             bodyPreview: body.slice(0, 800),
             wordCount: body ? body.split(/\s+/).filter(Boolean).length : 0,
             comments: commentList,
+            hostApp: 'Excel',
           });
         });
       }).catch(function() { cb(emptyContext()); });
@@ -198,20 +199,42 @@
 
     // ── Write-back (R4) ─────────────────────────────────────────────────────────
     // Never overwrites the cell that was selected when the job started: if that
-    // selection was meaningful (anything but the sheet's bare A1 default),
-    // write into the cell immediately adjacent to it (same row, next column).
-    // Otherwise append a new row at the end of the used range. Either way, add
-    // a cell comment noting the write for audit/undo-by-review (R4's own
-    // recommended default) and rely on Excel's native Ctrl+Z for reject.
+    // selection was meaningful (anything but the sheet's bare A1 default) AND the
+    // output is plain text (not a table), write into the cell immediately adjacent
+    // to it (same row, next column). For markdown-table output, or when only a
+    // default A1 was selected, append a new block at the end of the used range.
+    // Either way, add a cell comment on the first written cell for audit/undo-by-
+    // review (R4) and rely on Excel's native Ctrl+Z for the reject path.
+
+    // Parse a markdown table into a 2D string array. Returns null when the text
+    // contains no recognisable table. Separator rows (| --- |) are skipped.
+    function parseMarkdownTable(text) {
+      var rows = [];
+      var lines = String(text || '').split('\n');
+      for (var i = 0; i < lines.length; i++) {
+        var line = lines[i].trim();
+        if (!line.startsWith('|')) continue;
+        var cells = line.replace(/^\||\|$/g, '').split('|');
+        var isSep = cells.every(function(c) { return /^\s*:?-+:?\s*$/.test(c); });
+        if (isSep) continue;
+        rows.push(cells.map(function(c) { return c.trim(); }));
+      }
+      return rows.length >= 1 ? rows : null;
+    }
+
     function writeBackNonDestructive(text, jobLabel, cb) {
       if (typeof Excel === 'undefined' || !Excel.run) { cb(false, 'Excel API 1.10+ not available'); return; }
       var info = lastSelectionInfo;
       var meaningful = !!(info && !isDefaultA1(info));
       var note = 'Written by FRAIM' + (jobLabel ? ' (' + jobLabel + ')' : '') + ' - ' + new Date().toISOString();
+      var tableData = parseMarkdownTable(text);
       try {
         Excel.run(function(ctx) {
           var sheet = ctx.workbook.worksheets.getActiveWorksheet();
-          if (meaningful) {
+          // Plain-text adjacent write only when the selection was meaningful AND
+          // the output is not a multi-row table (tables always land at end of range
+          // because they span rows and would clobber data if placed mid-sheet).
+          if (meaningful && !tableData) {
             var addr = String(info.address).split('!').pop();
             var selRange = sheet.getRange(addr);
             var target = selRange.getOffsetRange(0, 1);
@@ -222,10 +245,23 @@
           var used = sheet.getUsedRangeOrNullObject();
           used.load('rowCount,rowIndex,isNullObject');
           return ctx.sync().then(function() {
-            var nextRow = used.isNullObject ? 0 : (used.rowIndex + used.rowCount);
-            var target = sheet.getRangeByIndexes(nextRow, 0, 1, 1);
-            target.values = [[text]];
-            sheet.comments.add(target, note);
+            var nextRow = used.isNullObject ? 1 : (used.rowIndex + used.rowCount);
+            if (tableData) {
+              var numRows = tableData.length;
+              var numCols = tableData.reduce(function(mx, r) { return Math.max(mx, r.length); }, 0);
+              var padded = tableData.map(function(row) {
+                var r = row.slice(0, numCols);
+                while (r.length < numCols) r.push('');
+                return r;
+              });
+              var tableRange = sheet.getRangeByIndexes(nextRow, 0, numRows, numCols);
+              tableRange.values = padded;
+              sheet.comments.add(sheet.getRangeByIndexes(nextRow, 0, 1, 1), note);
+            } else {
+              var target = sheet.getRangeByIndexes(nextRow, 0, 1, 1);
+              target.values = [[text]];
+              sheet.comments.add(target, note);
+            }
             return ctx.sync();
           });
         }).then(function() { cb(true); }).catch(function(e) { cb(false, (e && e.message) || String(e)); });

package/public/ai-hub/index.html

@@ -50,6 +50,10 @@
     <div class="nav-right">
       <!-- #744: FRAIM co-mark (co-branding, not white-label) shown when a brand is set. -->
       <span class="hub-cobrand" id="hub-cobrand" hidden></span>
+      <!-- #1379: persistent top-bar update indicator, driven by tfPopulateVersionInfo() alongside
+           the #am-update account-menu nudge below. Hidden until an update is actually available;
+           the `title` attribute (set in JS) carries the version + action-to-take hover text. -->
+      <button class="hub-update-badge" id="hub-update-badge" type="button" hidden>⬆️ Updates available</button>
       <button class="avatar-btn" id="avatar-btn" type="button" title="Account &amp; settings">SM</button>
       <div id="account-menu" class="account-menu">
         <div class="am-header">

package/public/ai-hub/script.js

@@ -576,6 +576,13 @@ function buildWordContextBlock(wc) {
     const lines = wc.comments.slice(0, 5).map(c => `- ${c.author || 'Author'}: ${c.text}`).join('\n');
     parts.push(`Document comments (${wc.comments.length}):\n${lines}`);
   }
+  if (wc.hostApp === 'Excel') {
+    parts.push(
+      'Host: Excel add-in. Your final text response is written automatically into this workbook.\n' +
+      'For structured output (tables, schedules, amortization calculators, grids): format your response as a Markdown table (| Header | Header | / | value | value |) so each cell is written to the correct row and column in the sheet.\n' +
+      'Do NOT use Python, openpyxl, or any file-creation tool to produce a standalone .xlsx file — all output goes directly into the currently open workbook.'
+    );
+  }
   if (parts.length === 0) return '';
   return `[Word Document Context]\n${parts.join('\n\n')}`;
 }
@@ -15861,6 +15868,11 @@ function tfWireShell() {
   }
   const avatar = document.getElementById('avatar-btn');
   if (avatar) avatar.addEventListener('click', tfToggleAccountMenu);
+  // #1379: clicking the top-bar badge opens the same account menu that already carries
+  // the full update-available detail, rather than duplicating that content into a
+  // second popover.
+  const updateBadge = document.getElementById('hub-update-badge');
+  if (updateBadge) updateBadge.addEventListener('click', tfToggleAccountMenu);
   tfWireThemeToggle();
   const accountItem = document.getElementById('am-account');
   if (accountItem) accountItem.addEventListener('click', (e) => {
@@ -16080,24 +16092,36 @@ function tfPopulateAccountMenu() {
 // #755: show the running Hub build version and, when a newer version is published,
 // an update-available nudge. Running version is cheap (from bootstrap); the latest
 // check hits the server's cached /api/ai-hub/version (best-effort, hidden on failure).
+// #1379: the account-menu nudge above is only visible once the manager opens that menu,
+// so a persistent top-bar indicator (#hub-update-badge, in .nav-right before #avatar-btn)
+// surfaces the same info without requiring the click. Both surfaces are driven from the
+// same response and use the same copy; #am-update is kept as-is (not removed) per #1379's
+// own "implementer's call, as long as the information isn't lost."
 function tfPopulateVersionInfo() {
   const versionEl = document.getElementById('am-version');
   const running = (state.bootstrap && state.bootstrap.version) || '';
   if (versionEl) versionEl.textContent = running ? `FRAIM Hub v${running}` : '';
   const updateEl = document.getElementById('am-update');
   const updateSub = document.getElementById('am-update-sub');
-  if (!updateEl) return;
+  const badgeEl = document.getElementById('hub-update-badge');
+  if (!updateEl && !badgeEl) return;
   fetch('/api/ai-hub/version')
     .then((r) => (r.ok ? r.json() : null))
     .then((info) => {
       if (info && info.updateAvailable && info.latest) {
-        if (updateSub) updateSub.textContent = `v${info.latest} is available. Quit the Hub (tray → Quit) and relaunch to update.`;
-        updateEl.hidden = false;
+        const actionText = `v${info.latest} is available. Quit the Hub (tray → Quit) and relaunch to update.`;
+        if (updateSub) updateSub.textContent = actionText;
+        if (updateEl) updateEl.hidden = false;
+        if (badgeEl) {
+          badgeEl.title = actionText;
+          badgeEl.hidden = false;
+        }
       } else {
-        updateEl.hidden = true;
+        if (updateEl) updateEl.hidden = true;
+        if (badgeEl) badgeEl.hidden = true;
       }
     })
-    .catch(() => { /* offline / best-effort: leave the nudge hidden */ });
+    .catch(() => { /* offline / best-effort: leave both surfaces hidden */ });
 }
 
 function tfRequestedConnectedSurface() {

package/public/ai-hub/styles.css

@@ -4419,6 +4419,22 @@ body.hub-shell { display: flex; flex-direction: column; height: 100vh; overflow:
 }
 .avatar-btn:hover { opacity: .85; box-shadow: 0 2px 8px rgba(0,0,0,.22); }
 
+/* Issue #1379: persistent top-bar update indicator, sits in .nav-right just before
+   .avatar-btn. Pill sizing/radius matches the established .run-state-pill convention;
+   accent-colored (not warn) since a new version is a nudge, not a problem. */
+.hub-update-badge {
+  display: inline-flex; align-items: center; gap: 5px;
+  padding: 7px 12px; border-radius: 999px;
+  font-size: 11px; font-weight: 700; letter-spacing: .02em; white-space: nowrap;
+  background: var(--accent); color: #fff; border: none;
+  cursor: pointer; flex-shrink: 0; margin-left: 8px;
+  box-shadow: 0 1px 4px rgba(0,0,0,.18);
+  transition: opacity .12s, box-shadow .12s;
+}
+.hub-update-badge:hover { opacity: .85; box-shadow: 0 2px 8px rgba(0,0,0,.22); }
+.hub-update-badge:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+.hub-update-badge[hidden] { display: none; }
+
 /* Suppress the old Hub's header and rail when inside the workspace-conv */
 .workspace-conv .header { display: none !important; }
 .workspace-conv .rail { display: none !important; }
@@ -5400,6 +5416,12 @@ body.hub-shell { display: flex; flex-direction: column; height: 100vh; overflow:
   .hub-brand { padding: 0 2px 0 10px; }
   .hub-brand-divider { margin: 0 4px 0 8px; }
   .hub-tab { padding: 10px 12px; }
+  /* #1379: the badge's own text ("Updates available") is exactly what forced the same
+     horizontal-scroll problem this block already exists to prevent - measured at 375px:
+     95px of overflow with the badge shown, none without it. Same treatment as the
+     co-mark above: the update is still reachable via #avatar-btn -> #am-update at this
+     width, just not duplicated in the top bar where there's no room for it. */
+  .hub-update-badge { display: none; }
 }
 
 /* Brand editor (Company tab → Brand accordion). */