genexus-mcp 3.5.3 → 3.6.0

package/README.md

@@ -57,7 +57,7 @@ needed. Existing tool names, arguments, and MCP client configuration formats do
 not change.
 
 <!-- BEGIN GENERATED: gx-compatibility -->
-Supported SDK majors: **GeneXus 17, GeneXus 18**.
+Supported SDK majors: **GeneXus 16, GeneXus 17, GeneXus 18**.
 Primary SDK: **GeneXus 18**.
 Source of truth: `config/gx-versions.json`.
 <!-- END GENERATED: gx-compatibility -->
@@ -67,6 +67,13 @@ catalog only after compiling the Worker with that SDK and passing the focused
 tests plus a live KB smoke. This prevents the server from claiming compatibility
 based only on a version string.
 
+### Legacy GeneXus compatibility (GX8 to GX15)
+
+The server also includes best-effort dynamic compatibility for legacy installations:
+- **GeneXus Evolution 1 (10.1), Evolution 2 (10.2), Evolution 3 (10.3), and GeneXus 15**: Driven via runtime reflection (`dotnet-reflection`), dynamically adapting to missing types or structural differences (such as module-less KBs without `QualifiedName`).
+- **GeneXus 8.0 and GeneXus 9.0**: Driven via classic Win32 COM automation (`com-gxpublic`), late-binding to `GXPublic.GXPublic` on an STA thread to open, inspect, and read objects from classic `.gxi` Knowledge Bases.
+- **Graceful degradation**: Modern tools that require features introduced in newer GeneXus versions (such as `genexus_api`, `genexus_gam`, or `genexus_module`) return structured `UNSUPPORTED_IN_GENEXUS_VERSION` errors indicating the required minimum version rather than failing ungracefully.
+
 ---
 
 ## What you can do with it

package/cli/commands/axi.js

@@ -59,7 +59,9 @@ function validateClientIds(ids) {
 
 function isSupportedCatalogMajor(catalog, major) {
     if (!major) return true;
-    return catalog.supportedMajors.some((entry) => String(entry.major) === String(major));
+    const inSupported = catalog.supportedMajors && catalog.supportedMajors.some((entry) => String(entry.major) === String(major));
+    if (inSupported) return true;
+    return Array.isArray(catalog.legacyMajors) && catalog.legacyMajors.some((entry) => String(entry.major) === String(major));
 }
 
 function parseFieldSelection(raw) {
@@ -176,6 +178,37 @@ function buildStatusData(cwd) {
     return { ready, configFound, gatewayExeFound, kbLooksValid, configPath, gatewayExePath, kbPath, gxPath, configSource };
 }
 
+const PROBE_EXIT_GRACE_MS = 2000;
+
+// Stop a probe child and wait for it to actually exit. On Windows child.kill()
+// only signals the direct process and returns before the OS releases the
+// executable image, so reporting success right after kill() left the exe file
+// handle open (Issue #211: the shared gateway stub in cli/run.test.js made the
+// suite teardown fail with EPERM while every assertion passed). Resolves true
+// once the child exited, false when it did not within the bounded grace.
+function stopProbeChild(child, graceMs = PROBE_EXIT_GRACE_MS) {
+    return new Promise((resolve) => {
+        if (!child || child.exitCode !== null || child.signalCode !== null) {
+            resolve(true);
+            return;
+        }
+        let settled = false;
+        const finish = (exited) => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(exited);
+        };
+        const timer = setTimeout(() => finish(false), graceMs);
+        child.once('exit', () => finish(true));
+        try {
+            child.kill();
+        } catch {
+            finish(true);
+        }
+    });
+}
+
 async function spawnGatewayProbe({ env = process.env, spawnHoldMs, timeoutMs, label, successDetail }) {
     const gatewayExePath = getGatewayExePath();
 
@@ -209,17 +242,25 @@ async function spawnGatewayProbe({ env = process.env, spawnHoldMs, timeoutMs, la
             });
 
             child.once('spawn', () => {
-                setTimeout(() => {
-                    try { child.kill(); } catch { }
-                    finish({ status: 'pass', detail: successDetail });
+                setTimeout(async () => {
+                    const exited = await stopProbeChild(child);
+                    if (exited) {
+                        finish({ status: 'pass', detail: successDetail });
+                    } else {
+                        finish({ status: 'warn', detail: `${label}: process did not exit after the stop signal; it may still hold the gateway exe.` });
+                    }
                 }, spawnHoldMs);
             });
 
-            setTimeout(() => {
-                if (!done) {
-                    try { child.kill(); } catch { }
-                    finish({ status: 'warn', detail: `${label} timed out; process was force-stopped.` });
-                }
+            setTimeout(async () => {
+                if (done) return;
+                const exited = await stopProbeChild(child);
+                finish({
+                    status: 'warn',
+                    detail: exited
+                        ? `${label} timed out; process was force-stopped.`
+                        : `${label} timed out and did not exit after the stop signal; it may still hold the gateway exe.`
+                });
             }, timeoutMs);
         } catch (err) {
             finish({ status: 'fail', detail: `${label} threw: ${err.message}` });
@@ -562,6 +603,50 @@ function buildInProcessBuildAssemblyLoadCheck(gxPath) {
     };
 }
 
+function buildGxPublicComCheck(gxMajor, gxPath) {
+    if (gxMajor !== '8' && gxMajor !== '9') {
+        return { id: 'gxpublic_com_registration', status: 'not_applicable', detail: 'Not a GeneXus 8.0/9.0 installation.' };
+    }
+    const child_process = require('child_process');
+    let isRegistered = false;
+    try {
+        const res = child_process.spawnSync('reg', ['query', 'HKCR\\GXPublic.GXPublic'], { encoding: 'utf8', timeout: 2000 });
+        isRegistered = res.status === 0;
+    } catch { }
+
+    if (isRegistered) {
+        return { id: 'gxpublic_com_registration', status: 'pass', detail: 'GXPublic COM automation server (GXPublic.GXPublic) is registered.' };
+    }
+    const dllHint = gxPath ? path.join(gxPath, 'GxPublic.dll') : 'GxPublic.dll';
+    return {
+        id: 'gxpublic_com_registration',
+        status: 'warn',
+        detail: `GXPublic COM component is not registered. Run 'regsvr32 "${dllHint}"' to enable GeneXus ${gxMajor}.0 COM automation.`
+    };
+}
+
+function buildLegacyIdeLockCheck(gxMajor) {
+    if (gxMajor !== '8' && gxMajor !== '9' && gxMajor !== '10.1' && gxMajor !== '10.2') {
+        return { id: 'legacy_ide_lock', status: 'not_applicable', detail: 'Lock check not applicable for modern GeneXus versions.' };
+    }
+    const child_process = require('child_process');
+    let ideRunning = false;
+    try {
+        const res = child_process.spawnSync('tasklist', ['/FI', 'IMAGENAME eq gx.exe', '/NH'], { encoding: 'utf8', timeout: 2000 });
+        if (res.stdout && res.stdout.toLowerCase().includes('gx.exe')) {
+            ideRunning = true;
+        }
+    } catch { }
+    if (ideRunning) {
+        return {
+            id: 'legacy_ide_lock',
+            status: 'warn',
+            detail: 'GeneXus IDE (gx.exe) process is currently running. Legacy engines hold exclusive file locks on the KB.'
+        };
+    }
+    return { id: 'legacy_ide_lock', status: 'pass', detail: 'No conflicting GeneXus IDE process (gx.exe) detected.' };
+}
+
 function redactConfig(cfg) {
     // Replace absolute paths with `<redacted:hash8>` so the structure is preserved
     // but filesystem layout, usernames, and KB names are not leaked. Hash is stable
@@ -710,7 +795,7 @@ async function handleDoctor(options, ctx) {
     const kbPath = data.kbPath;
     const gxPath = data.gxPath;
     const kbExists = !!(kbPath && fs.existsSync(kbPath));
-    const gxExeExists = !!(gxPath && fs.existsSync(path.join(gxPath, 'genexus.exe')));
+    const gxExeExists = !!(gxPath && (fs.existsSync(path.join(gxPath, 'genexus.exe')) || fs.existsSync(path.join(gxPath, 'gx.exe'))));
     const kbSdkCompatibility = kbExists && gxExeExists
         ? compareGeneXusKbAndInstallation(kbPath, gxPath)
         : null;
@@ -731,15 +816,18 @@ async function handleDoctor(options, ctx) {
             compatibilityDetail = `${unsupportedCompatibilityMajor} is not supported by this MCP distribution. Supported majors: ${catalog.supportedMajors.map((entry) => entry.major).join(', ')}.`;
         } else if (kbSdkCompatibility.status === 'mismatch') {
             compatibilityStatus = 'fail';
-            compatibilityDetail = `KB major ${kbSdkCompatibility.kb.major} does not match GeneXus SDK major ${kbSdkCompatibility.gx.major}. Re-run init with the matching --gx path.`;
+            compatibilityDetail = `KB major ${kbSdkCompatibility.kb.major} does not match GeneXus SDK major ${kbSdkCompatibility.gx.major}${kbSdkCompatibility.gx.version ? ` (${kbSdkCompatibility.gx.version})` : ''}. Re-run init with the matching --gx path.`;
         } else if (kbSdkCompatibility.status === 'match') {
             compatibilityStatus = 'pass';
-            compatibilityDetail = `KB major ${kbSdkCompatibility.kb.major} matches GeneXus SDK major ${kbSdkCompatibility.gx.major}.`;
+            compatibilityDetail = `KB major ${kbSdkCompatibility.kb.major} matches GeneXus SDK major ${kbSdkCompatibility.gx.major}${kbSdkCompatibility.gx.version ? ` (${kbSdkCompatibility.gx.version})` : ''}.`;
         } else {
             compatibilityDetail = `KB/SDK major compatibility could not be verified (KB: ${kbSdkCompatibility.kb.source}; SDK: ${kbSdkCompatibility.gx.source}).`;
         }
     }
 
+    const gxIdent = gxPath ? readGeneXusInstallationIdentity(gxPath) : null;
+    const gxVersionLabel = gxIdent && gxIdent.version ? ` (GeneXus ${gxIdent.major || ''} version ${gxIdent.version})` : (gxIdent && gxIdent.major ? ` (GeneXus ${gxIdent.major})` : '');
+
     const riskyZone = isPathLikelyAppLockerBlocked(gatewayExePath);
     const clientCrossCheck = buildClientExeCrossCheck(gatewayExePath);
 
@@ -767,7 +855,7 @@ async function handleDoctor(options, ctx) {
         // Same logic for the GeneXus install: missing genexus.exe at a configured path
         // guarantees a worker crash on first MCP call. Promote from warn to fail so init
         // exits non-zero and the caller (install.ps1, AI client) actually sees the problem.
-        { id: 'gx_installation', status: gxExeExists ? 'pass' : (gxPath ? 'fail' : 'warn'), detail: gxExeExists ? 'GeneXus installation has genexus.exe.' : (gxPath ? `Configured GeneXus installation is missing genexus.exe at: ${gxPath}` : 'No GeneXus installation path is configured.') },
+        { id: 'gx_installation', status: gxExeExists ? 'pass' : (gxPath ? 'fail' : 'warn'), detail: gxExeExists ? `GeneXus installation has ${gxPath && fs.existsSync(path.join(gxPath, 'gx.exe')) && !fs.existsSync(path.join(gxPath, 'genexus.exe')) ? 'gx.exe' : 'genexus.exe'}${gxVersionLabel}.` : (gxPath ? `Configured GeneXus installation is missing executable at: ${gxPath}` : 'No GeneXus installation path is configured.') },
         {
             id: 'kb_sdk_compatibility',
             status: compatibilityStatus,
@@ -784,6 +872,13 @@ async function handleDoctor(options, ctx) {
     const inProcessLoad = buildInProcessBuildAssemblyLoadCheck(gxPath);
     checks.push({ id: 'in_process_build_assembly_load', status: inProcessLoad.status, detail: inProcessLoad.detail });
 
+    // Legacy GeneXus checks (GX 8.0, 9.0, Ev1, Ev2)
+    const gxMajor = (gxIdent && gxIdent.major) || (kbSdkCompatibility && kbSdkCompatibility.gx && kbSdkCompatibility.gx.major) || null;
+    const comCheck = buildGxPublicComCheck(gxMajor, gxPath);
+    checks.push({ id: 'gxpublic_com_registration', status: comCheck.status, detail: comCheck.detail });
+    const ideLockCheck = buildLegacyIdeLockCheck(gxMajor);
+    checks.push({ id: 'legacy_ide_lock', status: ideLockCheck.status, detail: ideLockCheck.detail });
+
     // Client registration summary — one line answering "are my AI agents wired up?".
     const clientRows = clientsStatus();
     const installedRows = clientRows.filter((r) => r.installed);
@@ -1344,6 +1439,7 @@ function buildClientLauncherHelp(patchResult) {
     }
     if (patched.length > 0 && process.platform === 'win32' && !process.env.GENEXUS_MCP_GATEWAY_EXE) {
         help.push('Windows launcher paths may resolve under the npm cache and be blocked by AppLocker/SRP. Use scripts/install.ps1 for a stable whitelisted path.');
+        help.push('Working from a local checkout? Register the clients with the checkout gateway from the repo root instead: `$env:GENEXUS_MCP_GATEWAY_EXE="<repoRoot>\\publish\\GxMcp.Gateway.exe"; node cli\\run.js clients add --clients <ids>` (or re-run `.\\install.ps1`). Avoid `npx @latest clients add` there, because it rewrites the registration to this npm package\'s launcher; validate with the same checkout CLI (`node cli\\run.js clients` / `doctor`).');
     }
     return help;
 }
@@ -1939,6 +2035,7 @@ async function probeWorkerStartup({ configPath, observeMs = 2500 }) {
         };
 
         let child;
+        let stopping = false;
         try {
             child = spawn(gatewayExePath, [], {
                 stdio: ['ignore', 'pipe', 'pipe'],
@@ -1957,6 +2054,9 @@ async function probeWorkerStartup({ configPath, observeMs = 2500 }) {
         });
 
         child.once('exit', (code) => {
+            // The observation timeout stops the gateway itself; that deliberate
+            // signal is reported by the timeout branch, not as a crash.
+            if (stopping) return;
             if (code === 0) {
                 finish({ status: 'pass', detail: 'Worker smoke: gateway exited cleanly during observation window.' });
             } else {
@@ -1970,10 +2070,15 @@ async function probeWorkerStartup({ configPath, observeMs = 2500 }) {
             }
         });
 
-        setTimeout(() => {
-            try { child.kill(); } catch { }
-            // Still alive after observeMs → worker bootstrapped without crashing.
-            finish({ status: 'pass', detail: `Worker smoke: gateway stayed alive for ${observeMs}ms with KB and GX configured.` });
+        setTimeout(async () => {
+            stopping = true;
+            const exited = await stopProbeChild(child);
+            if (exited) {
+                // Still alive after observeMs → worker bootstrapped without crashing.
+                finish({ status: 'pass', detail: `Worker smoke: gateway stayed alive for ${observeMs}ms with KB and GX configured.` });
+            } else {
+                finish({ status: 'warn', detail: 'Worker smoke: gateway did not exit after the stop signal; it may still hold the gateway exe.' });
+            }
         }, observeMs);
     });
 }
@@ -2150,11 +2255,12 @@ async function handleClients(subcommand, options, ctx) {
         if (invalidLaunchers.length > 0) {
             help.push(`These clients have a known-invalid MCP launcher (check command and args) — re-register: genexus-mcp clients add --clients ${invalidLaunchers.map((r) => r.id).join(',')}${serverName !== DEFAULT_MCP_SERVER_NAME ? ` --server-name ${serverName}` : ''}`);
         }
-        const otherStale = stale.filter((r) =>
-            r.launcherStructuralState !== 'missing' && r.launcherSemanticState !== 'invalid'
-        );
-        if (otherStale.length > 0) {
-            help.push(`These clients have a stale launcher — re-register: genexus-mcp clients add --clients ${otherStale.map((r) => r.id).join(',')}${serverName !== DEFAULT_MCP_SERVER_NAME ? ` --server-name ${serverName}` : ''}`);
+        // A launcher that exists but is not this CLI's gateway is a different working
+        // install (checkout, fixed-path, other package cache), so it is reported as
+        // informational drift instead of a stale registration that needs repair.
+        const driftedLaunchers = rows.filter((r) => r.launcherPathDrift && !r.commandStale);
+        if (driftedLaunchers.length > 0) {
+            help.push(`Note: ${driftedLaunchers.map((r) => r.name).join(', ')} point at a gateway that is not this CLI's (informational — the launcher exists and is valid). Re-register with this CLI only if you want them to track it: genexus-mcp clients add --clients ${driftedLaunchers.map((r) => r.id).join(',')}${serverName !== DEFAULT_MCP_SERVER_NAME ? ` --server-name ${serverName}` : ''}`);
         }
         const semanticValidCount = rows.filter((r) => r.launcherSemanticState === 'valid').length;
         const semanticInvalidCount = rows.filter((r) => r.launcherSemanticState === 'invalid').length;

package/cli/lib/client-adapters.js

@@ -78,10 +78,16 @@ class OpenCodeJsoncAdapter extends BaseClientAdapter {
         this.config = configModule || require('./config');
     }
     apply(client, launcher, targetConfigPath, opts = {}) {
-        return this.config.applyOpenCodeJson(client.path, launcher, targetConfigPath, opts);
+        return this.config.applyOpenCodeJson(client.path, launcher, targetConfigPath, {
+            ...opts,
+            alternatePaths: client.alternatePaths || []
+        });
     }
     remove(client, opts = {}) {
-        return this.config.removeOpenCodeJson(client.path, opts);
+        return this.config.removeOpenCodeJson(client.path, {
+            ...opts,
+            alternatePaths: client.alternatePaths || []
+        });
     }
     read(client, serverName) {
         if (!fs.existsSync(client.path)) return null;

package/cli/lib/config.js

@@ -88,9 +88,12 @@ function getGeneXusVersionCatalog() {
             const catalog = JSON.parse(fs.readFileSync(candidate, 'utf8'));
             if (!catalog || !catalog.primaryMajor || !Array.isArray(catalog.supportedMajors)) continue;
             const entries = catalog.supportedMajors.filter((entry) => entry && /^\d+$/.test(String(entry.major)));
+            const legacyEntries = Array.isArray(catalog.legacyMajors)
+                ? catalog.legacyMajors.filter((entry) => entry && /^(?:10\.[1-3]|\d+)$/.test(String(entry.major)))
+                : [];
             const primary = entries.find((entry) => String(entry.major) === String(catalog.primaryMajor));
             if (entries.length > 0 && primary?.defaultInstallPath) {
-                return { ...catalog, supportedMajors: entries };
+                return { ...catalog, supportedMajors: entries, legacyMajors: legacyEntries };
             }
         } catch {
         }
@@ -101,13 +104,19 @@ function getGeneXusVersionCatalog() {
             { major: '17', displayName: 'GeneXus 17', defaultInstallPath: 'C:\\Program Files (x86)\\GeneXus\\GeneXus17Trial' },
             { major: '18', displayName: 'GeneXus 18', defaultInstallPath: 'C:\\Program Files (x86)\\GeneXus\\GeneXus18' }
         ],
+        legacyMajors: [
+            { major: '10.3', displayName: 'GeneXus Evolution 3', defaultInstallPath: 'C:\\Program Files (x86)\\GeneXus\\GeneXusXEv3' },
+            { major: '9', displayName: 'GeneXus 9.0', defaultInstallPath: 'C:\\Program Files (x86)\\ARTech\\GeneXus\\GeneXus 9.0' },
+            { major: '8', displayName: 'GeneXus 8.0', defaultInstallPath: 'C:\\Program Files (x86)\\ARTech\\GeneXus\\GeneXus 8.0' }
+        ],
         source: 'built-in-fallback'
     };
 }
 
 function getGeneXusCatalogEntries(preferredMajor = null) {
     const catalog = getGeneXusVersionCatalog();
-    return [...catalog.supportedMajors].sort((left, right) => {
+    const all = [...catalog.supportedMajors, ...(catalog.legacyMajors || [])];
+    return all.sort((left, right) => {
         const leftPreferred = preferredMajor !== null && String(left.major) === String(preferredMajor);
         const rightPreferred = preferredMajor !== null && String(right.major) === String(preferredMajor);
         if (leftPreferred !== rightPreferred) return Number(rightPreferred) - Number(leftPreferred);
@@ -708,6 +717,12 @@ function resolveOpenCodeConfigPath(xdgConfig) {
     return path.join(xdgConfig, 'opencode', 'opencode.json');
 }
 
+function alternateOpenCodeConfigPath(filePath) {
+    return path.extname(filePath).toLowerCase() === '.jsonc'
+        ? filePath.slice(0, -1)
+        : filePath.replace(/\.json$/i, '.jsonc');
+}
+
 // VS Code stores its user profile (and native MCP mcp.json) in a per-platform
 // location. `variant` is 'Code' (stable) or 'Code - Insiders'.
 function vscodeUserDir(variant, { appData, macAppSupport, xdgConfig }) {
@@ -807,6 +822,7 @@ function getClientConfigTargets() {
             name: 'OpenCode (CLI)',
             format: 'opencode',
             path: resolveOpenCodeConfigPath(xdgConfig),
+            alternatePaths: [alternateOpenCodeConfigPath(resolveOpenCodeConfigPath(xdgConfig))],
             installMarkers: [
                 path.join(xdgConfig, 'opencode'),
                 path.join(home, '.local', 'share', 'opencode')
@@ -826,6 +842,7 @@ function getClientConfigTargets() {
             name: 'OpenCode Desktop',
             format: 'opencode',
             path: resolveOpenCodeConfigPath(xdgConfig),
+            alternatePaths: [alternateOpenCodeConfigPath(resolveOpenCodeConfigPath(xdgConfig))],
             detectByMarkerOnly: true,
             installMarkers: [
                 path.join(localAppData, 'Programs', '@opencode-aidesktop'),
@@ -937,21 +954,27 @@ function clientCommandHealth(entry, client = null, { fs: fileSystem = fs } = {})
         reason: null,
         structuralState: 'indeterminate',
         semanticState: 'unknown',
-        semanticReason: null
+        semanticReason: null,
+        pathDrift: false,
+        pathDriftReason: null
     };
     const invalid = (reason, structuralState = 'present') => ({
         stale: true,
         reason,
         structuralState,
         semanticState: 'invalid',
-        semanticReason: reason
+        semanticReason: reason,
+        pathDrift: false,
+        pathDriftReason: null
     });
     const valid = (structuralState = 'present') => ({
         stale: false,
         reason: null,
         structuralState,
         semanticState: 'valid',
-        semanticReason: null
+        semanticReason: null,
+        pathDrift: false,
+        pathDriftReason: null
     });
     const missingLauncherReason = 'configured launcher does not exist on disk';
 
@@ -961,7 +984,9 @@ function clientCommandHealth(entry, client = null, { fs: fileSystem = fs } = {})
             reason: null,
             structuralState: 'not-registered',
             semanticState: 'not-applicable',
-            semanticReason: null
+            semanticReason: null,
+            pathDrift: false,
+            pathDriftReason: null
         };
     }
     if (typeof entry !== 'object') {
@@ -973,7 +998,9 @@ function clientCommandHealth(entry, client = null, { fs: fileSystem = fs } = {})
             reason: null,
             structuralState: 'not-applicable',
             semanticState: 'not-applicable',
-            semanticReason: null
+            semanticReason: null,
+            pathDrift: false,
+            pathDriftReason: null
         };
     }
 
@@ -1004,13 +1031,21 @@ function clientCommandHealth(entry, client = null, { fs: fileSystem = fs } = {})
             };
         }
         if (!exists) return invalid(missingLauncherReason, 'missing');
+        // A gateway exe that exists at a different absolute path is a *different,
+        // working* install — a local checkout's publish/ copy, a fixed-path install,
+        // or another package cache — not a broken registration. Reporting it as
+        // `stale` made `npx genexus-mcp clients` tell a checkout operator to
+        // re-register, which rewrote the harness away from the checkout gateway
+        // (Issue #210). The drift is still surfaced (as `pathDrift`, never `stale`)
+        // and doctor's `client_config_sync` check keeps the "not this CLI's packaged
+        // gateway" warning with its own remediation.
         if (client && client.preferDirectGateway) {
             const currentPackageGateway = getGatewayExePath();
-            if (fs.existsSync(currentPackageGateway) && normalizeExePath(command) !== normalizeExePath(currentPackageGateway)) {
+            if (fileSystem.existsSync(currentPackageGateway) && normalizeExePath(command) !== normalizeExePath(currentPackageGateway)) {
                 return {
                     ...valid('present'),
-                    stale: true,
-                    reason: 'configured launcher points at a different package gateway; re-register the client'
+                    pathDrift: true,
+                    pathDriftReason: `configured gateway differs from this CLI's gateway (${currentPackageGateway})`
                 };
             }
         }
@@ -1131,13 +1166,16 @@ function clientsStatus(opts = {}) {
             serverName,
             isThirdParty: Boolean(isThirdParty),
             writeSupported: client.writeSupported !== false,
-            configPath: client.path,
+            configPath: entry && entry.configPath ? entry.configPath : client.path,
+            configPaths: entry && entry.configPath ? [entry.configPath] : [client.path],
             command: entry && entry.command ? entry.command : null,
             args: entry && Array.isArray(entry.args) ? entry.args : [],
             url: entry && entry.url ? entry.url : null,
             launcherStructuralState: health.structuralState,
             launcherSemanticState: health.semanticState,
             launcherSemanticReason: health.semanticReason,
+            launcherPathDrift: health.pathDrift,
+            launcherPathDriftReason: health.pathDriftReason,
             commandStale: health.stale,
             commandStaleReason: health.reason || (isThirdParty ? 'configured as third-party / HTTP MCP server (e.g. official GeneXus MCP)' : null),
             detectedAt: det.markerHit || (det.hasConfig ? client.path : null),
@@ -1426,7 +1464,7 @@ function getOpenCodeMcpContainer(cfgObj) {
     };
 }
 
-function applyOpenCodeJson(filePath, launcher, targetConfigPath, { serverName = DEFAULT_MCP_SERVER_NAME, force = false, globalConfig = false, fs: fileSystem = fs } = {}) {
+function applyOpenCodeJson(filePath, launcher, targetConfigPath, { serverName = DEFAULT_MCP_SERVER_NAME, force = false, globalConfig = false, alternatePaths = [], fs: fileSystem = fs } = {}) {
     const parsed = fileSystem.existsSync(filePath) ? readJsonFileSafe(filePath, fileSystem) : {};
     if (parsed === null) throw new Error('Invalid JSON');
     const cfgObj = parsed || {};
@@ -1470,10 +1508,20 @@ function applyOpenCodeJson(filePath, launcher, targetConfigPath, { serverName =
         }
     }
     writeClientJson(filePath, cfgObj, fileSystem);
+    for (const alternatePath of alternatePaths || []) {
+        if (!fileSystem.existsSync(alternatePath)) continue;
+        applyOpenCodeJson(alternatePath, launcher, targetConfigPath, {
+            serverName,
+            force,
+            globalConfig,
+            alternatePaths: [],
+            fs: fileSystem
+        });
+    }
 }
 
-function removeOpenCodeJson(filePath, { serverName = DEFAULT_MCP_SERVER_NAME, fs: fileSystem = fs } = {}) {
-    const parsed = readJsonFileSafe(filePath);
+function removeOpenCodeJson(filePath, { serverName = DEFAULT_MCP_SERVER_NAME, alternatePaths = [], fs: fileSystem = fs } = {}) {
+    const parsed = readJsonFileSafe(filePath, fileSystem);
     if (parsed === null) throw new Error('Invalid JSON');
     const cfgObj = parsed || {};
     if (!cfgObj.mcp || typeof cfgObj.mcp !== 'object') return false;
@@ -1503,9 +1551,17 @@ function removeOpenCodeJson(filePath, { serverName = DEFAULT_MCP_SERVER_NAME, fs
             }
         }
     }
-    if (!removedAny) return false;
-    writeClientJson(filePath, cfgObj, fileSystem);
-    return true;
+    if (removedAny) writeClientJson(filePath, cfgObj, fileSystem);
+    let removedAlternate = false;
+    for (const alternatePath of alternatePaths || []) {
+        if (!fileSystem.existsSync(alternatePath)) continue;
+        removedAlternate = removeOpenCodeJson(alternatePath, {
+            serverName,
+            alternatePaths: [],
+            fs: fileSystem
+        }) || removedAlternate;
+    }
+    return removedAny || removedAlternate;
 }
 
 function extractCodexTomlEntry(content, serverName = DEFAULT_MCP_SERVER_NAME) {
@@ -1650,8 +1706,49 @@ function normalizeExePath(p) {
     return s;
 }
 
+function readOpenCodeCommandEntry(filePath, serverName, fileSystem) {
+    if (!fileSystem.existsSync(filePath)) return null;
+    const parsed = readJsonFileSafe(filePath, fileSystem);
+    if (!parsed || typeof parsed !== 'object') return null;
+    let entry = parsed.mcp?.servers?.[serverName] || parsed.mcp?.[serverName];
+    if (!entry && serverName === DEFAULT_MCP_SERVER_NAME) {
+        const legacyGx = parsed.mcp?.servers?.genexus || parsed.mcp?.genexus;
+        if (legacyGx && !isThirdPartyMcpEntry(legacyGx)) entry = legacyGx;
+        else entry = parsed.mcp?.servers?.genexus18 || parsed.mcp?.genexus18;
+    }
+    if (!entry) return null;
+    if (Array.isArray(entry.command) && entry.command.length > 0) {
+        return {
+            command: entry.command[0],
+            args: entry.command.slice(1),
+            url: entry.url || null,
+            type: entry.type || null,
+            environment: entry.environment || null,
+            raw: entry,
+            configPath: filePath
+        };
+    }
+    return {
+        command: null,
+        args: [],
+        url: entry.url || null,
+        type: entry.type || null,
+        environment: entry.environment || null,
+        raw: entry,
+        configPath: filePath
+    };
+}
+
 function readClientCommandEntry(client, serverName = DEFAULT_MCP_SERVER_NAME, { fs: fileSystem = fs } = {}) {
     if (client.writeSupported === false) return null;
+    if (client.format === 'opencode') {
+        const paths = [client.path, ...(client.alternatePaths || [])];
+        for (const configPath of paths) {
+            const entry = readOpenCodeCommandEntry(configPath, serverName, fileSystem);
+            if (entry) return entry;
+        }
+        return null;
+    }
     if (!fileSystem.existsSync(client.path)) return null;
     try {
         if (client.format === 'mcpServers') {
@@ -1752,7 +1849,7 @@ function getLocalAppDataCacheDir() {
 }
 
 function getGeneXusMajor(version) {
-    const match = String(version || '').match(/^\s*(\d+)/);
+    const match = String(version || '').match(/^\s*(10\.[1-3](?!\d)|\d+)/);
     return match ? match[1] : null;
 }
 
@@ -1809,7 +1906,10 @@ function readGeneXusInstallationIdentity(gxPath, options = {}) {
     const readExecutableVersion = typeof options.readExecutableVersion === 'function'
         ? options.readExecutableVersion
         : readExecutableProductVersion;
-    const executableVersion = readExecutableVersion(path.join(gxPath, 'GeneXus.exe'));
+    let executableVersion = readExecutableVersion(path.join(gxPath, 'GeneXus.exe'));
+    if (!executableVersion) {
+        executableVersion = readExecutableVersion(path.join(gxPath, 'gx.exe'));
+    }
     if (executableVersion) {
         return {
             version: executableVersion,
@@ -1895,14 +1995,24 @@ function readGeneXusKbIdentity(kbPath) {
     if (!kbPath) return { version: null, major: null, source: 'unavailable', reason: 'missing-kb-path' };
 
     let gxwFiles;
+    let gxiFiles = [];
     try {
-        gxwFiles = fs.readdirSync(kbPath)
+        const allFiles = fs.readdirSync(kbPath);
+        gxwFiles = allFiles
             .filter((fileName) => fileName.toLowerCase().endsWith('.gxw'))
             .map((fileName) => path.join(kbPath, fileName));
+        gxiFiles = allFiles
+            .filter((fileName) => fileName.toLowerCase().endsWith('.gxi'))
+            .map((fileName) => path.join(kbPath, fileName));
     } catch {
         return { version: null, major: null, source: 'unavailable', reason: 'unreadable-kb-path' };
     }
-    if (gxwFiles.length === 0) return { version: null, major: null, source: 'unavailable', reason: 'no-gxw' };
+    if (gxwFiles.length === 0) {
+        if (gxiFiles.length > 0) {
+            return { version: '9.0', major: '9', source: 'gxi-classic', reason: null };
+        }
+        return { version: null, major: null, source: 'unavailable', reason: 'no-gxw' };
+    }
     if (gxwFiles.length > 1) return { version: null, major: null, source: 'unavailable', reason: 'multiple-gxw' };
 
     try {