fraim-hub 2.0.283 → 2.0.285

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/doctor/checks/agent-cli-health-checks.js

@@ -15,11 +15,12 @@ const child_process_1 = require("child_process");
 const path_1 = __importDefault(require("path"));
 const managed_agent_paths_1 = require("../../utils/managed-agent-paths");
 const command_resolution_1 = require("../../mcp/command-resolution");
-// Codex is FRAIM's first Hub-compatible CLI with a managed-install fallback
-// (npm install -g into FRAIM's portable Node when no system install is
-// found). Extend this list as claude/gemini/copilot gain the same fallback.
+// CLIs with a managed-install fallback (npm install -g into FRAIM's portable
+// Node when no system install is found). Add gemini/copilot here when their
+// installManagedAgent wiring lands.
 const MANAGED_CLIS = [
     { id: 'codex', label: 'Codex', command: 'codex' },
+    { id: 'claude-code', label: 'Claude Code', command: 'claude' },
 ];
 // Windows cannot CreateProcess a `.cmd`/`.bat` file directly (spawnSync on a
 // resolved absolute `.cmd` path throws EINVAL) — it must go through cmd.exe,

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/cli/utils/managed-agent-paths.js

@@ -83,6 +83,13 @@ function cleanupOrphanedManagedShims() {
     const removed = [];
     for (const basename of basenames) {
         const candidate = path_1.default.join(nodeRoot, basename);
+        // Guard: only delete the flat-dir shim once the versioned dir already has
+        // an equivalent. Without this, upgrading users lose their shims before a
+        // reinstall has had a chance to place them in the versioned dir — the
+        // agent CLI disappears entirely until the next explicit reinstall.
+        const versionedEquiv = path_1.default.join(versionedDir, basename);
+        if (!fs_1.default.existsSync(versionedEquiv))
+            continue;
         try {
             if (fs_1.default.statSync(candidate).isFile()) {
                 fs_1.default.unlinkSync(candidate);

package/dist/src/config/persona-capability-bundles.js

@@ -63,7 +63,7 @@ exports.PERSONA_CAPABILITY_BUNDLES = {
         personaKey: 'swen',
         bundleId: 'persona-swen-core',
         catalogMetadata: buildCatalogMetadata('swen', ['feature-implementation', 'technical-design', 'code-refactoring']),
-        protectedJobs: ['feature-implementation', 'technical-design', 'implementation-design-review', 'code-refactoring', 'pr-iteration', 'mobile-app-development', 'mcp-server-creation', 'cloud-application-deployment', 'cloud-cost-optimization', 'cloud-performance-diagnosis', 'route-llm-spend-to-cloud-credits', 'set-up-cloud-cost-alerts', 'gitlabs-to-github', 'system-migration', 'cross-cloud-migration', 'data-pipeline-design', 'data-quality-monitoring', 'data-platform-architecture', 'write-dev-docs', 'database-schema-design', 'create-architecture', 'project-scaffolding', 'codebase-analysis-and-ideation', 'github-org-setup', 'google-workspace-setup', 'mobile-app-rejection-response', 'mobile-app-submission', 'publish-mcp-app', 'application-replication-workflow'],
+        protectedJobs: ['feature-implementation', 'technical-design', 'implementation-design-review', 'code-refactoring', 'pr-iteration', 'mobile-app-development', 'cloud-application-deployment', 'cloud-cost-optimization', 'cloud-performance-diagnosis', 'route-llm-spend-to-cloud-credits', 'set-up-cloud-cost-alerts', 'gitlabs-to-github', 'system-migration', 'cross-cloud-migration', 'data-pipeline-design', 'data-quality-monitoring', 'data-platform-architecture', 'write-dev-docs', 'database-schema-design', 'create-architecture', 'project-scaffolding', 'codebase-analysis-and-ideation', 'github-org-setup', 'google-workspace-setup', 'mobile-app-rejection-response', 'mobile-app-submission', 'application-replication-workflow'],
         protectedAliases: ['software-engineering', 'implementation'],
         defaultHireMode: 'job',
         lockCopy: 'Hire SWEn to unlock software-engineering delivery for this request.'
@@ -262,6 +262,23 @@ exports.PERSONA_CAPABILITY_BUNDLES = {
         protectedAliases: ['banking-audit', 'kyc-audit', 'audit'],
         defaultHireMode: 'job',
         lockCopy: 'Hire AUDITya to unlock banking evidence audit work for this request.'
+    },
+    aida: {
+        personaKey: 'aida',
+        bundleId: 'persona-aida-core',
+        catalogMetadata: buildCatalogMetadata('aida', ['create-ai-agent', 'author-ai-evals', 'enable-web-mcp']),
+        protectedJobs: [
+            'create-ai-agent',
+            'author-ai-evals',
+            'enable-web-mcp',
+            'evaluate-ai-agent',
+            'mcp-server-creation',
+            'publish-mcp-app',
+            'create-hub-configured-agent',
+        ],
+        protectedAliases: ['ai-engineering', 'agent-engineering', 'ai-agents'],
+        defaultHireMode: 'job',
+        lockCopy: 'Hire AIda to unlock AI agent design, MCP enablement, eval authoring, and agent evaluation work for this request.'
     }
 };
 const PROTECTED_JOB_TO_PERSONA = new Map();
@@ -275,7 +292,6 @@ for (const bundle of Object.values(exports.PERSONA_CAPABILITY_BUNDLES)) {
 // as "free") so the Hub attributes them to FRAIMworker, but they are never
 // hire-gated because FRAIMworker is not a purchasable persona.
 const GENERIC_WORKER_OWNED_JOBS = new Set([
-    'create-hub-configured-agent',
     'contribute-to-fraim',
     'file-fraim-issue',
     'praise-fraim',