genexus-mcp 3.7.2 → 3.9.0

package/cli/commands/axi.js

@@ -813,6 +813,57 @@ function buildLegacyIdeLockCheck(gxMajor) {
     return { id: 'legacy_ide_lock', status: 'pass', detail: 'No conflicting GeneXus IDE process (gx.exe) detected.' };
 }
 
+function buildRuntimeStagingCheck() {
+    try {
+        const {
+            resolveDefaultRuntimeRoot,
+            listStagedRuntimes,
+            getRunningGxMcpProcesses,
+            classifyProcessRuntime,
+            shouldStage
+        } = require('../lib/runtime-stager');
+
+        const runtimeRoot = resolveDefaultRuntimeRoot();
+        const stagedList = listStagedRuntimes(runtimeRoot);
+        const runningProcs = getRunningGxMcpProcesses();
+        const npxProcs = runningProcs.filter((p) => classifyProcessRuntime(p.exePath, runtimeRoot) === 'npx-cache');
+        const stagedProcs = runningProcs.filter((p) => classifyProcessRuntime(p.exePath, runtimeRoot) === 'staged');
+
+        if (npxProcs.length > 0) {
+            return {
+                id: 'runtime_staging',
+                status: 'warn',
+                detail: `${npxProcs.length} process(es) running directly from npx cache (PIDs: ${npxProcs.map((p) => p.pid).join(', ')}). Terminate them to prevent EBUSY during upgrades.`
+            };
+        }
+        if (shouldStage()) {
+            return {
+                id: 'runtime_staging',
+                status: 'pass',
+                detail: `Staging active at ${runtimeRoot}. ${stagedList.length} staged version(s) found, ${stagedProcs.length} active process(es).`
+            };
+        }
+        if (process.env.GENEXUS_MCP_GATEWAY_EXE) {
+            return {
+                id: 'runtime_staging',
+                status: 'pass',
+                detail: `Fixed-path runtime override active via GENEXUS_MCP_GATEWAY_EXE (${process.env.GENEXUS_MCP_GATEWAY_EXE}). Staging bypassed.`
+            };
+        }
+        return {
+            id: 'runtime_staging',
+            status: 'pass',
+            detail: 'Development checkout active. Runtime staging bypassed.'
+        };
+    } catch {
+        return {
+            id: 'runtime_staging',
+            status: 'not_applicable',
+            detail: 'Runtime staging inspection unavailable.'
+        };
+    }
+}
+
 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
@@ -1124,6 +1175,7 @@ async function handleDoctor(options, ctx) {
     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 });
+    checks.push(buildRuntimeStagingCheck());
 
     // Client registration summary — one line answering "are my AI agents wired up?".
     const installedRows = clientRows.filter((r) => r.installed);

package/cli/index.js

@@ -450,7 +450,16 @@ async function launchGateway(passthroughArgs, options) {
         return EXIT_CODES.ERROR;
     }
 
-    const gatewayExePath = getGatewayExePath();
+    let gatewayExePath = getGatewayExePath();
+    try {
+        const { ensureStagedGateway } = require('./lib/runtime-stager');
+        const staged = ensureStagedGateway();
+        gatewayExePath = staged.gatewayExePath;
+    } catch (stageErr) {
+        if (!options.quiet) {
+            launcherStderr.write(`[genexus-mcp] Warning: Runtime staging failed (${stageErr.message}), falling back to direct binary.\n`);
+        }
+    }
     if (!require('fs').existsSync(gatewayExePath)) {
         const message = `[genexus-mcp] ERROR: Gateway executable not found at ${gatewayExePath}`;
         launcherStderr.write(`${message}\n`);

package/cli/lib/client-adapters.test.js

@@ -151,6 +151,7 @@ test('generateNeutralConfig produces valid shape without KB fields', () => {
     assert.equal(cfg.GeneXus.InstallationPath, 'C:\\GeneXus18');
     assert.ok(cfg.GeneXus.WorkerExecutable.endsWith(path.join('worker', 'GxMcp.Worker.exe')));
     assert.equal(cfg.Server.McpStdio, true);
+    assert.equal(cfg.Server.ToolProfile, 'standard');
     assert.equal(cfg.Server.TransportMode, undefined);
     assert.equal(cfg.Server.HttpPort, 0);
     assert.equal(cfg.Environment.ResolutionPolicy, 'strict');

package/cli/lib/config.js

@@ -8,6 +8,7 @@ function generateConfig(gxPath, kbPath) {
         Server: {
             HttpPort: 5000,
             McpStdio: true,
+            ToolProfile: 'standard',
             SessionIdleTimeoutMinutes: 10,
             WorkerIdleTimeoutMinutes: 5,
             // Lean + terse defaults: the MCP client is an LLM agent that reads
@@ -33,6 +34,7 @@ function generateNeutralConfig(gxPath, { workerPath, gatewayMode = 'stdio-isolat
         Server: {
             HttpPort: 0,
             McpStdio: true,
+            ToolProfile: 'standard',
             WorkerSharingMode: 'isolated',
             SessionIdleTimeoutMinutes: 10,
             WorkerIdleTimeoutMinutes: 5,
@@ -657,9 +659,18 @@ function createConfigFile(kbPath, gxPath) {
     }
     const nextConfig = {
         ...baseConfig,
+        Server: { ...baseConfig.Server },
         Environment: { ...baseConfig.Environment, ...preservedEnv }
     };
 
+    if (existing) {
+        if (existing.Server && Object.prototype.hasOwnProperty.call(existing.Server, 'ToolProfile')) {
+            nextConfig.Server.ToolProfile = existing.Server.ToolProfile;
+        } else {
+            delete nextConfig.Server.ToolProfile;
+        }
+    }
+
     const changed = !existing || JSON.stringify(existing) !== JSON.stringify(nextConfig);
     if (changed) {
         writeFileAtomic(targetConfigPath, JSON.stringify(nextConfig, null, 2));

package/cli/lib/runtime-stager.js

@@ -0,0 +1,332 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+
+function resolveDefaultRuntimeRoot() {
+    if (process.env.GENEXUS_MCP_RUNTIME_DIR) {
+        return process.env.GENEXUS_MCP_RUNTIME_DIR;
+    }
+    const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    return path.join(localAppData, 'GenexusMCP', 'runtime');
+}
+
+function isCheckoutMode(packageRoot) {
+    try {
+        const gitMarker = fs.statSync(path.join(packageRoot, '.git'));
+        return gitMarker.isDirectory() || gitMarker.isFile();
+    } catch {
+        return false;
+    }
+}
+
+function shouldStage(packageRoot = path.resolve(__dirname, '..', '..')) {
+    if (process.env.GENEXUS_MCP_GATEWAY_EXE) {
+        return false;
+    }
+    if (process.env.GENEXUS_MCP_NO_STAGING === '1') {
+        return false;
+    }
+    if (process.env.GENEXUS_MCP_FORCE_STAGING === '1') {
+        return true;
+    }
+    return !isCheckoutMode(packageRoot);
+}
+
+function computeFileSha256(filePath) {
+    const hash = crypto.createHash('sha256');
+    const buffer = fs.readFileSync(filePath);
+    hash.update(buffer);
+    return hash.digest('hex');
+}
+
+function computePublishFingerprint(publishDir) {
+    const manifestPath = path.join(publishDir, 'gxmcp-manifest.json');
+    if (fs.existsSync(manifestPath)) {
+        try {
+            return computeFileSha256(manifestPath).slice(0, 8);
+        } catch {
+            // fallback
+        }
+    }
+    const gatewayExe = path.join(publishDir, 'GxMcp.Gateway.exe');
+    if (fs.existsSync(gatewayExe)) {
+        try {
+            return computeFileSha256(gatewayExe).slice(0, 8);
+        } catch {
+            // fallback
+        }
+    }
+    return '00000000';
+}
+
+function verifyManifest(stagedDir, manifestPath) {
+    if (!fs.existsSync(manifestPath)) {
+        return;
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    } catch (err) {
+        throw new Error(`Failed to parse manifest at ${manifestPath}: ${err.message}`);
+    }
+
+    const artifacts = Array.isArray(manifest.artifacts) ? manifest.artifacts : [];
+    for (const artifact of artifacts) {
+        if (!artifact || !artifact.path) continue;
+        const fullPath = path.join(stagedDir, artifact.path);
+        if (!fs.existsSync(fullPath)) {
+            throw new Error(`Manifest verification failed: missing artifact '${artifact.path}'`);
+        }
+        if (typeof artifact.size === 'number') {
+            const stat = fs.statSync(fullPath);
+            if (stat.size !== artifact.size) {
+                throw new Error(`Manifest verification failed: size mismatch for '${artifact.path}' (expected ${artifact.size}, got ${stat.size})`);
+            }
+        }
+        if (artifact.sha256) {
+            const actualSha = computeFileSha256(fullPath);
+            if (actualSha.toLowerCase() !== artifact.sha256.toLowerCase()) {
+                throw new Error(`Manifest verification failed: sha256 mismatch for '${artifact.path}'`);
+            }
+        }
+    }
+}
+
+function cleanOldRuntimes(runtimeRoot, currentTargetDir, keepCount = 2) {
+    try {
+        if (!fs.existsSync(runtimeRoot)) return;
+        const entries = fs.readdirSync(runtimeRoot, { withFileTypes: true });
+
+        // Clean up stale tmp directories older than 10 minutes
+        const now = Date.now();
+        for (const entry of entries) {
+            if (entry.isDirectory() && entry.name.includes('.tmp-')) {
+                const fullTmpPath = path.join(runtimeRoot, entry.name);
+                try {
+                    const stat = fs.statSync(fullTmpPath);
+                    if (now - stat.mtimeMs > 10 * 60 * 1000) {
+                        fs.rmSync(fullTmpPath, { recursive: true, force: true });
+                    }
+                } catch {
+                    // Ignore removal failures on locked tmp dirs
+                }
+            }
+        }
+
+        // Gather valid version directories
+        const versionDirs = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.includes('.tmp-')) continue;
+            const fullPath = path.join(runtimeRoot, entry.name);
+            try {
+                const stat = fs.statSync(fullPath);
+                versionDirs.push({
+                    name: entry.name,
+                    path: fullPath,
+                    mtimeMs: stat.mtimeMs
+                });
+            } catch {
+                // Ignore stat errors
+            }
+        }
+
+        // Sort newest first
+        versionDirs.sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+        // Keep current targetDir always, plus up to keepCount newest
+        const normalizedCurrent = path.resolve(currentTargetDir).toLowerCase();
+        let kept = 0;
+        const toDelete = [];
+
+        for (const vdir of versionDirs) {
+            const normalized = path.resolve(vdir.path).toLowerCase();
+            if (normalized === normalizedCurrent) {
+                continue;
+            }
+            if (kept < keepCount) {
+                kept++;
+            } else {
+                toDelete.push(vdir.path);
+            }
+        }
+
+        for (const dirToDelete of toDelete) {
+            try {
+                fs.rmSync(dirToDelete, { recursive: true, force: true });
+            } catch {
+                // EBUSY or EPERM means another running process has loaded DLLs from this runtime.
+                // Keep it for later cleanup.
+            }
+        }
+    } catch {
+        // Garbage collection is best-effort
+    }
+}
+
+function ensureStagedGateway(options = {}) {
+    const packageRoot = options.packageRoot || path.resolve(__dirname, '..', '..');
+    const publishDir = options.publishDir || path.join(packageRoot, 'publish');
+    const defaultGatewayExe = options.defaultGatewayExe || path.join(publishDir, 'GxMcp.Gateway.exe');
+
+    if (!options.forceStaging && !shouldStage(packageRoot)) {
+        return {
+            staged: false,
+            gatewayExePath: process.env.GENEXUS_MCP_GATEWAY_EXE || defaultGatewayExe,
+            runtimeDir: path.dirname(process.env.GENEXUS_MCP_GATEWAY_EXE || defaultGatewayExe),
+            reason: process.env.GENEXUS_MCP_GATEWAY_EXE ? 'GENEXUS_MCP_GATEWAY_EXE' : (process.env.GENEXUS_MCP_NO_STAGING === '1' ? 'NO_STAGING' : 'checkout')
+        };
+    }
+
+    let version = '0.0.0';
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+        if (pkg.version) version = pkg.version;
+    } catch {
+        // Fallback
+    }
+
+    const sha8 = computePublishFingerprint(publishDir);
+    const runtimeRoot = options.runtimeRoot || resolveDefaultRuntimeRoot();
+    const targetDir = path.join(runtimeRoot, `${version}-${sha8}`);
+    const stagedGatewayExe = path.join(targetDir, 'GxMcp.Gateway.exe');
+
+    if (fs.existsSync(stagedGatewayExe)) {
+        cleanOldRuntimes(runtimeRoot, targetDir);
+        return {
+            staged: true,
+            gatewayExePath: stagedGatewayExe,
+            runtimeDir: targetDir,
+            fresh: false
+        };
+    }
+
+    if (!fs.existsSync(publishDir)) {
+        throw new Error(`Cannot stage runtime: publish directory not found at ${publishDir}`);
+    }
+
+    fs.mkdirSync(runtimeRoot, { recursive: true });
+    const tmpDir = `${targetDir}.tmp-${process.pid}-${Date.now()}`;
+    fs.mkdirSync(tmpDir, { recursive: true });
+
+    try {
+        fs.cpSync(publishDir, tmpDir, { recursive: true });
+        const manifestPath = path.join(tmpDir, 'gxmcp-manifest.json');
+        verifyManifest(tmpDir, manifestPath);
+
+        try {
+            fs.renameSync(tmpDir, targetDir);
+        } catch (renameErr) {
+            // Concurrent launcher might have completed the rename first
+            if (fs.existsSync(stagedGatewayExe)) {
+                try {
+                    fs.rmSync(tmpDir, { recursive: true, force: true });
+                } catch {
+                    // Ignore tmp cleanup error
+                }
+            } else {
+                throw renameErr;
+            }
+        }
+    } catch (err) {
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        } catch {
+            // Ignore tmp cleanup error
+        }
+        throw err;
+    }
+
+    cleanOldRuntimes(runtimeRoot, targetDir);
+
+    return {
+        staged: true,
+        gatewayExePath: stagedGatewayExe,
+        runtimeDir: targetDir,
+        fresh: true
+    };
+}
+
+function listStagedRuntimes(runtimeRoot = resolveDefaultRuntimeRoot()) {
+    if (!fs.existsSync(runtimeRoot)) return [];
+    try {
+        const entries = fs.readdirSync(runtimeRoot, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isDirectory() && !e.name.includes('.tmp-'))
+            .map((e) => {
+                const dirPath = path.join(runtimeRoot, e.name);
+                let stat = null;
+                try {
+                    stat = fs.statSync(dirPath);
+                } catch {
+                    // Ignore
+                }
+                return {
+                    name: e.name,
+                    path: dirPath,
+                    hasGateway: fs.existsSync(path.join(dirPath, 'GxMcp.Gateway.exe')),
+                    mtime: stat ? stat.mtime : null
+                };
+            });
+    } catch {
+        return [];
+    }
+}
+
+function getRunningGxMcpProcesses() {
+    if (process.platform !== 'win32') return [];
+    try {
+        // Query CIM Win32_Process for GxMcp processes
+        const output = execFileSync('powershell.exe', [
+            '-NoProfile',
+            '-NonInteractive',
+            '-Command',
+            `Get-CimInstance Win32_Process -Filter "name like 'GxMcp%'" | Select-Object ProcessId, ExecutablePath, CommandLine | ConvertTo-Json -Compress`
+        ], { encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+
+        if (!output) return [];
+        let data;
+        try {
+            data = JSON.parse(output);
+        } catch {
+            return [];
+        }
+        const rows = Array.isArray(data) ? data : [data];
+        return rows.map((r) => ({
+            pid: r.ProcessId,
+            exePath: r.ExecutablePath || '',
+            commandLine: r.CommandLine || ''
+        }));
+    } catch {
+        return [];
+    }
+}
+
+function classifyProcessRuntime(exePath, runtimeRoot = resolveDefaultRuntimeRoot()) {
+    if (!exePath) return 'unknown';
+    const norm = path.resolve(exePath).toLowerCase();
+    const normRuntime = path.resolve(runtimeRoot).toLowerCase();
+    if (norm.startsWith(normRuntime)) {
+        return 'staged';
+    }
+    if (norm.includes('npm-cache') || norm.includes('_npx') || norm.includes('node_modules')) {
+        return 'npx-cache';
+    }
+    return 'other';
+}
+
+module.exports = {
+    resolveDefaultRuntimeRoot,
+    isCheckoutMode,
+    shouldStage,
+    computePublishFingerprint,
+    verifyManifest,
+    cleanOldRuntimes,
+    ensureStagedGateway,
+    listStagedRuntimes,
+    getRunningGxMcpProcesses,
+    classifyProcessRuntime
+};

package/cli/lib/runtime-stager.test.js

@@ -0,0 +1,221 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+const {
+    resolveDefaultRuntimeRoot,
+    shouldStage,
+    ensureStagedGateway,
+    cleanOldRuntimes,
+    verifyManifest,
+    classifyProcessRuntime
+} = require('./runtime-stager');
+
+function sha256(content) {
+    return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+test('runtime-stager: resolveDefaultRuntimeRoot uses GENEXUS_MCP_RUNTIME_DIR or LocalAppData', (t) => {
+    const orig = process.env.GENEXUS_MCP_RUNTIME_DIR;
+    t.after(() => {
+        if (orig !== undefined) process.env.GENEXUS_MCP_RUNTIME_DIR = orig;
+        else delete process.env.GENEXUS_MCP_RUNTIME_DIR;
+    });
+    process.env.GENEXUS_MCP_RUNTIME_DIR = 'C:\\custom\\runtime';
+    assert.equal(resolveDefaultRuntimeRoot(), 'C:\\custom\\runtime');
+});
+
+test('runtime-stager: verifyManifest succeeds on valid files', () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gx-verify-'));
+    try {
+        const file = path.join(tmp, 'test.txt');
+        fs.writeFileSync(file, 'hello');
+        const manifest = path.join(tmp, 'manifest.json');
+        fs.writeFileSync(manifest, JSON.stringify({
+            artifacts: [{ path: 'test.txt', size: 5, sha256: sha256('hello') }]
+        }));
+        assert.doesNotThrow(() => verifyManifest(tmp, manifest));
+    } finally {
+        try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* ignore */ }
+    }
+});
+
+test('runtime-stager: shouldStage respects env overrides and checkout markers', (t) => {
+    const origEnv = { ...process.env };
+    t.after(() => {
+        process.env = origEnv;
+    });
+
+    const tmpPkg = fs.mkdtempSync(path.join(os.tmpdir(), 'gx-pkg-'));
+    t.after(() => {
+        try { fs.rmSync(tmpPkg, { recursive: true, force: true }); } catch { /* ignore */ }
+    });
+
+    // Case 1: GENEXUS_MCP_GATEWAY_EXE set -> false
+    process.env.GENEXUS_MCP_GATEWAY_EXE = 'C:\\custom\\GxMcp.Gateway.exe';
+    delete process.env.GENEXUS_MCP_NO_STAGING;
+    delete process.env.GENEXUS_MCP_FORCE_STAGING;
+    assert.equal(shouldStage(tmpPkg), false);
+
+    // Case 2: GENEXUS_MCP_NO_STAGING === '1' -> false
+    delete process.env.GENEXUS_MCP_GATEWAY_EXE;
+    process.env.GENEXUS_MCP_NO_STAGING = '1';
+    assert.equal(shouldStage(tmpPkg), false);
+
+    // Case 3: In packaged mode (no .git) -> true
+    delete process.env.GENEXUS_MCP_NO_STAGING;
+    assert.equal(shouldStage(tmpPkg), true);
+
+    // Case 4: With .git marker -> false
+    fs.mkdirSync(path.join(tmpPkg, '.git'));
+    assert.equal(shouldStage(tmpPkg), false);
+
+    // Case 5: With .git marker but GENEXUS_MCP_FORCE_STAGING === '1' -> true
+    process.env.GENEXUS_MCP_FORCE_STAGING = '1';
+    assert.equal(shouldStage(tmpPkg), true);
+});
+
+test('runtime-stager: ensureStagedGateway stages publish folder, verifies manifest and reuses staged runtime', (t) => {
+    const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'gx-stage-test-'));
+    t.after(() => {
+        try { fs.rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+    });
+
+    const fakePkg = path.join(tmpRoot, 'package');
+    const fakePublish = path.join(fakePkg, 'publish');
+    fs.mkdirSync(fakePublish, { recursive: true });
+
+    fs.writeFileSync(path.join(fakePkg, 'package.json'), JSON.stringify({ version: '3.9.0' }));
+    const fakeExeContent = 'fake gateway binary';
+    fs.writeFileSync(path.join(fakePublish, 'GxMcp.Gateway.exe'), fakeExeContent);
+
+    const manifestContent = JSON.stringify({
+        schemaVersion: 'gxmcp-release-manifest/1',
+        artifacts: [
+            {
+                path: 'GxMcp.Gateway.exe',
+                size: Buffer.byteLength(fakeExeContent),
+                sha256: sha256(fakeExeContent)
+            }
+        ]
+    });
+    fs.writeFileSync(path.join(fakePublish, 'gxmcp-manifest.json'), manifestContent);
+
+    const runtimeRoot = path.join(tmpRoot, 'runtime');
+
+    // First run: stages fresh
+    const result1 = ensureStagedGateway({
+        packageRoot: fakePkg,
+        publishDir: fakePublish,
+        runtimeRoot,
+        forceStaging: true
+    });
+
+    assert.equal(result1.staged, true);
+    assert.equal(result1.fresh, true);
+    assert.equal(fs.existsSync(result1.gatewayExePath), true);
+    assert.equal(fs.readFileSync(result1.gatewayExePath, 'utf8'), fakeExeContent);
+
+    // Second run: reuses already staged
+    const result2 = ensureStagedGateway({
+        packageRoot: fakePkg,
+        publishDir: fakePublish,
+        runtimeRoot,
+        forceStaging: true
+    });
+
+    assert.equal(result2.staged, true);
+    assert.equal(result2.fresh, false);
+    assert.equal(result2.gatewayExePath, result1.gatewayExePath);
+});
+
+test('runtime-stager: ensureStagedGateway fails closed and cleans tmp on manifest corruption', (t) => {
+    const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'gx-corrupt-test-'));
+    t.after(() => {
+        try { fs.rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+    });
+
+    const fakePkg = path.join(tmpRoot, 'package');
+    const fakePublish = path.join(fakePkg, 'publish');
+    fs.mkdirSync(fakePublish, { recursive: true });
+
+    fs.writeFileSync(path.join(fakePkg, 'package.json'), JSON.stringify({ version: '3.9.0' }));
+    const fakeExeContent = 'tampered gateway binary';
+    fs.writeFileSync(path.join(fakePublish, 'GxMcp.Gateway.exe'), fakeExeContent);
+
+    const manifestContent = JSON.stringify({
+        schemaVersion: 'gxmcp-release-manifest/1',
+        artifacts: [
+            {
+                path: 'GxMcp.Gateway.exe',
+                size: 9999, // mismatched size
+                sha256: 'deadbeef'
+            }
+        ]
+    });
+    fs.writeFileSync(path.join(fakePublish, 'gxmcp-manifest.json'), manifestContent);
+
+    const runtimeRoot = path.join(tmpRoot, 'runtime');
+
+    assert.throws(() => {
+        ensureStagedGateway({
+            packageRoot: fakePkg,
+            publishDir: fakePublish,
+            runtimeRoot,
+            forceStaging: true
+        });
+    }, /Manifest verification failed/);
+
+    // Assert that target dir was not created and no tmp dir left behind
+    assert.equal(fs.readdirSync(runtimeRoot).length, 0);
+});
+
+test('runtime-stager: cleanOldRuntimes retains current version plus keepCount newest versions', (t) => {
+    const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'gx-gc-test-'));
+    t.after(() => {
+        try { fs.rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+    });
+
+    const v1 = path.join(tmpRoot, '3.6.0-aaaa1111');
+    const v2 = path.join(tmpRoot, '3.7.0-bbbb2222');
+    const v3 = path.join(tmpRoot, '3.8.0-cccc3333');
+    const v4 = path.join(tmpRoot, '3.9.0-dddd4444');
+
+    fs.mkdirSync(v1);
+    fs.utimesSync(v1, 1000, 1000);
+    fs.mkdirSync(v2);
+    fs.utimesSync(v2, 2000, 2000);
+    fs.mkdirSync(v3);
+    fs.utimesSync(v3, 3000, 3000);
+    fs.mkdirSync(v4);
+    fs.utimesSync(v4, 4000, 4000);
+
+    // Current is v4. Keep count = 2 -> keep v4, v3, v2. v1 should be deleted.
+    cleanOldRuntimes(tmpRoot, v4, 2);
+
+    assert.equal(fs.existsSync(v4), true, 'current version must be kept');
+    assert.equal(fs.existsSync(v3), true, 'newest previous version must be kept');
+    assert.equal(fs.existsSync(v2), true, 'second previous version must be kept');
+    assert.equal(fs.existsSync(v1), false, 'oldest version beyond keepCount must be deleted');
+});
+
+test('runtime-stager: classifyProcessRuntime identifies staged vs npx-cache', () => {
+    const runtimeRoot = 'C:\\Users\\user\\AppData\\Local\\GenexusMCP\\runtime';
+    assert.equal(
+        classifyProcessRuntime('C:\\Users\\user\\AppData\\Local\\GenexusMCP\\runtime\\3.8.0-abcd\\GxMcp.Gateway.exe', runtimeRoot),
+        'staged'
+    );
+    assert.equal(
+        classifyProcessRuntime('C:\\Users\\user\\AppData\\Local\\npm-cache\\_npx\\12345\\node_modules\\genexus-mcp\\publish\\GxMcp.Gateway.exe', runtimeRoot),
+        'npx-cache'
+    );
+    assert.equal(
+        classifyProcessRuntime('C:\\Projetos\\Genexus18MCP\\publish\\GxMcp.Gateway.exe', runtimeRoot),
+        'other'
+    );
+});