genexus-mcp 3.9.0 → 3.9.1

package/cli/commands/axi.js

@@ -818,42 +818,55 @@ function buildRuntimeStagingCheck() {
         const {
             resolveDefaultRuntimeRoot,
             listStagedRuntimes,
-            getRunningGxMcpProcesses,
+            probeRunningGxMcpProcesses,
+            getRuntimeProcessUsage,
             classifyProcessRuntime,
             shouldStage
         } = require('../lib/runtime-stager');
 
         const runtimeRoot = resolveDefaultRuntimeRoot();
         const stagedList = listStagedRuntimes(runtimeRoot);
-        const runningProcs = getRunningGxMcpProcesses();
+        const processProbe = probeRunningGxMcpProcesses();
+        const runningProcs = processProbe.processes || [];
+        if (processProbe.ok === false) {
+            return {
+                id: 'runtime_staging',
+                status: 'warn',
+                detail: `Runtime process inspection was incomplete; GC is fail-closed. ${processProbe.error || 'The process probe did not return executable paths.'}`
+            };
+        }
         const npxProcs = runningProcs.filter((p) => classifyProcessRuntime(p.exePath, runtimeRoot) === 'npx-cache');
         const stagedProcs = runningProcs.filter((p) => classifyProcessRuntime(p.exePath, runtimeRoot) === 'staged');
+        const inUseRuntimes = getRuntimeProcessUsage(runtimeRoot, runningProcs);
+        const inUseDetail = inUseRuntimes.length > 0
+            ? ` Retained in-use runtime(s): ${inUseRuntimes.map((entry) => `${entry.name} (PIDs: ${entry.pids.join(', ')})`).join('; ')}.`
+            : '';
 
         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.`
+                detail: `${npxProcs.length} process(es) running directly from npx cache (PIDs: ${npxProcs.map((p) => p.pid).join(', ')}). Terminate them to prevent EBUSY during upgrades.${inUseDetail}`
             };
         }
         if (shouldStage()) {
             return {
                 id: 'runtime_staging',
                 status: 'pass',
-                detail: `Staging active at ${runtimeRoot}. ${stagedList.length} staged version(s) found, ${stagedProcs.length} active process(es).`
+                detail: `Staging active at ${runtimeRoot}. ${stagedList.length} staged version(s) found, ${stagedProcs.length} active process(es).${inUseDetail}`
             };
         }
         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.`
+                detail: `Fixed-path runtime override active via GENEXUS_MCP_GATEWAY_EXE (${process.env.GENEXUS_MCP_GATEWAY_EXE}). Staging bypassed.${inUseDetail}`
             };
         }
         return {
             id: 'runtime_staging',
             status: 'pass',
-            detail: 'Development checkout active. Runtime staging bypassed.'
+            detail: `Development checkout active. Runtime staging bypassed.${inUseDetail}`
         };
     } catch {
         return {

package/cli/index.js

@@ -455,6 +455,15 @@ async function launchGateway(passthroughArgs, options) {
         const { ensureStagedGateway } = require('./lib/runtime-stager');
         const staged = ensureStagedGateway();
         gatewayExePath = staged.gatewayExePath;
+        const cleanup = staged.cleanup;
+        if (cleanup && (cleanup.skipped?.length || cleanup.failed?.length || cleanup.processProbeAvailable === false)) {
+            const summary = [
+                cleanup.processProbeAvailable === false ? 'process probe unavailable' : null,
+                cleanup.skipped?.length ? `${cleanup.skipped.length} skipped` : null,
+                cleanup.failed?.length ? `${cleanup.failed.length} failed` : null
+            ].filter(Boolean).join(', ');
+            if (!options.quiet) launcherStderr.write(`[genexus-mcp] Runtime cleanup incomplete: ${summary}.\n`);
+        }
     } catch (stageErr) {
         if (!options.quiet) {
             launcherStderr.write(`[genexus-mcp] Warning: Runtime staging failed (${stageErr.message}), falling back to direct binary.\n`);

package/cli/lib/runtime-stager.js

@@ -96,75 +96,353 @@ function verifyManifest(stagedDir, manifestPath) {
     }
 }
 
-function cleanOldRuntimes(runtimeRoot, currentTargetDir, keepCount = 2) {
+function isPathWithin(candidatePath, rootPath) {
+    if (!candidatePath || !rootPath) return false;
+    const relative = path.relative(path.resolve(rootPath), path.resolve(candidatePath));
+    return relative === '' || (
+        relative !== '..'
+        && !relative.startsWith(`..${path.sep}`)
+        && !path.isAbsolute(relative)
+    );
+}
+
+function getRuntimeProcessUsage(runtimeRoot, processes, runtimeDirectories = null) {
+    const runtimes = Array.isArray(runtimeDirectories)
+        ? runtimeDirectories
+        : listStagedRuntimes(runtimeRoot);
+    const usage = new Map();
+
+    for (const runtime of runtimes) {
+        const pids = (Array.isArray(processes) ? processes : [])
+            .filter((proc) => proc && isPathWithin(proc.exePath, runtime.path))
+            .map((proc) => Number(proc.pid))
+            .filter((pid) => Number.isInteger(pid) && pid > 0)
+            .sort((a, b) => a - b);
+        if (pids.length > 0) {
+            usage.set(path.resolve(runtime.path).toLowerCase(), {
+                name: runtime.name,
+                path: runtime.path,
+                pids
+            });
+        }
+    }
+
+    return Array.from(usage.values()).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function createRuntimeCleanupResult() {
+    return {
+        deleted: [],
+        skipped: [],
+        failed: [],
+        processProbeAvailable: true
+    };
+}
+
+function readRuntimeProcessSnapshot(processProvider) {
+    let snapshot = processProvider();
+    if (snapshot && !Array.isArray(snapshot) && Array.isArray(snapshot.processes)) {
+        if (snapshot.ok === false) throw new Error(snapshot.error || 'runtime process probe failed');
+        snapshot = snapshot.processes;
+    }
+    if (!Array.isArray(snapshot)) throw new Error('runtime process probe returned no process list');
+    if (snapshot.some((proc) => !proc || !proc.exePath)) {
+        throw new Error('runtime process probe returned a process without an executable path');
+    }
+    return snapshot;
+}
+
+function processPidsUnder(directory, processes) {
+    return (Array.isArray(processes) ? processes : [])
+        .filter((proc) => proc && isPathWithin(proc.exePath, directory))
+        .map((proc) => Number(proc.pid))
+        .filter((pid) => Number.isInteger(pid) && pid > 0)
+        .sort((a, b) => a - b);
+}
+
+function processPidsUnderAny(directories, processes) {
+    const paths = Array.isArray(directories) ? directories.filter(Boolean) : [directories].filter(Boolean);
+    return [...new Set(paths.flatMap((directory) => processPidsUnder(directory, processes)))]
+        .sort((a, b) => a - b);
+}
+
+function originalPathForTombstone(tombstonePath) {
+    if (typeof tombstonePath !== 'string') return null;
+    const marker = tombstonePath.lastIndexOf('.deleting-');
+    return marker > 0 ? tombstonePath.slice(0, marker) : null;
+}
+
+function cleanupRuntimeDirectory(directory, options = {}) {
+    const result = createRuntimeCleanupResult();
+    if (!directory || !fs.existsSync(directory)) return result;
+
+    const processProvider = typeof options.getRunningProcesses === 'function'
+        ? options.getRunningProcesses
+        : probeRunningGxMcpProcesses;
+    const rmSync = typeof options.rmSync === 'function' ? options.rmSync : fs.rmSync;
+    const removeOptions = { recursive: true, force: true, maxRetries: 3, retryDelay: 100 };
+    const probePaths = [
+        directory,
+        ...(Array.isArray(options.additionalProbePaths) ? options.additionalProbePaths : [])
+    ].filter(Boolean);
+
+    let initialSnapshot;
     try {
-        if (!fs.existsSync(runtimeRoot)) return;
-        const entries = fs.readdirSync(runtimeRoot, { withFileTypes: true });
+        initialSnapshot = readRuntimeProcessSnapshot(processProvider);
+    } catch (err) {
+        result.processProbeAvailable = false;
+        result.skipped.push({
+            path: directory,
+            reason: 'process-probe-unavailable',
+            pids: [],
+            error: err && err.message ? err.message : String(err)
+        });
+        return result;
+    }
 
-        // 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
-                }
-            }
+    const initialPids = processPidsUnderAny(probePaths, initialSnapshot);
+    if (initialPids.length > 0) {
+        result.skipped.push({ path: directory, reason: 'in-use', pids: initialPids });
+        return result;
+    }
+
+    let finalSnapshot;
+    try {
+        finalSnapshot = readRuntimeProcessSnapshot(processProvider);
+    } catch (err) {
+        result.processProbeAvailable = false;
+        result.skipped.push({
+            path: directory,
+            reason: 'process-probe-unavailable-before-delete',
+            pids: [],
+            error: err && err.message ? err.message : String(err)
+        });
+        return result;
+    }
+
+    const finalPids = processPidsUnderAny(probePaths, finalSnapshot);
+    if (finalPids.length > 0) {
+        result.skipped.push({ path: directory, reason: 'in-use-before-delete', pids: finalPids });
+        return result;
+    }
+
+    try {
+        rmSync(directory, removeOptions);
+        result.deleted.push(directory);
+    } catch (err) {
+        result.failed.push({ path: directory, error: err && err.message ? err.message : String(err) });
+    }
+    return result;
+}
+
+function mergeRuntimeCleanupResults(target, additional) {
+    if (!additional) return target;
+    target.deleted.push(...additional.deleted);
+    target.skipped.push(...additional.skipped);
+    target.failed.push(...additional.failed);
+    target.processProbeAvailable = target.processProbeAvailable && additional.processProbeAvailable;
+    return target;
+}
+
+function cleanOldRuntimes(runtimeRoot, currentTargetDir, keepCount = 2, options = {}) {
+    const result = createRuntimeCleanupResult();
+
+    const processProvider = typeof options.getRunningProcesses === 'function'
+        ? options.getRunningProcesses
+        : probeRunningGxMcpProcesses;
+    const renameSync = typeof options.renameSync === 'function' ? options.renameSync : fs.renameSync;
+    const rmSync = typeof options.rmSync === 'function' ? options.rmSync : fs.rmSync;
+    const removeOptions = { recursive: true, force: true, maxRetries: 3, retryDelay: 100 };
+
+    const readProcessSnapshot = () => readRuntimeProcessSnapshot(processProvider);
+
+    const probeImmediatelyBeforeDelete = (directory) => {
+        try {
+            const snapshot = readProcessSnapshot();
+            return { ok: true, pids: processPidsUnder(directory, snapshot) };
+        } catch (err) {
+            return { ok: false, pids: [], error: err && err.message ? err.message : String(err) };
         }
+    };
 
-        // Gather valid version directories
+    try {
+        if (!fs.existsSync(runtimeRoot)) return result;
+        const entries = fs.readdirSync(runtimeRoot, { withFileTypes: true });
+        const now = Date.now();
         const versionDirs = [];
+        const tmpDirs = [];
+        const tombstoneDirs = [];
+
         for (const entry of entries) {
-            if (!entry.isDirectory() || entry.name.includes('.tmp-')) continue;
+            if (!entry.isDirectory()) continue;
             const fullPath = path.join(runtimeRoot, entry.name);
+            if (entry.name.includes('.tmp-')) {
+                tmpDirs.push(fullPath);
+                continue;
+            }
+            if (entry.name.includes('.deleting-')) {
+                tombstoneDirs.push(fullPath);
+                continue;
+            }
             try {
                 const stat = fs.statSync(fullPath);
-                versionDirs.push({
-                    name: entry.name,
-                    path: fullPath,
-                    mtimeMs: stat.mtimeMs
-                });
+                versionDirs.push({ name: entry.name, path: fullPath, mtimeMs: stat.mtimeMs });
             } catch {
-                // Ignore stat errors
+                // Ignore an entry that disappeared during enumeration.
             }
         }
 
-        // 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();
+        const keep = Number.isFinite(Number(keepCount)) ? Math.max(0, Number(keepCount)) : 2;
         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);
+            if (path.resolve(vdir.path).toLowerCase() === normalizedCurrent) continue;
+            if (kept < keep) kept++;
+            else toDelete.push(vdir.path);
+        }
+
+        const staleTmpDirs = tmpDirs.filter((dir) => {
+            try { return now - fs.statSync(dir).mtimeMs > 10 * 60 * 1000; } catch { return false; }
+        });
+        if (toDelete.length === 0 && staleTmpDirs.length === 0 && tombstoneDirs.length === 0) {
+            return result;
+        }
+
+        // Finish tombstones and stale staging directories with the same
+        // fail-closed process protection used by immediate staging cleanup.
+        for (const tombstone of tombstoneDirs) {
+            const originalPath = originalPathForTombstone(tombstone);
+            mergeRuntimeCleanupResults(result, cleanupRuntimeDirectory(tombstone, {
+                ...options,
+                additionalProbePaths: originalPath ? [originalPath] : []
+            }));
+        }
+        for (const tmpDir of staleTmpDirs) {
+            mergeRuntimeCleanupResults(result, cleanupRuntimeDirectory(tmpDir, options));
+        }
+
+        if (toDelete.length === 0) return result;
+        let processSnapshot;
+        try {
+            processSnapshot = readProcessSnapshot();
+        } catch (err) {
+            result.processProbeAvailable = false;
+            const error = err && err.message ? err.message : String(err);
+            for (const dir of toDelete) {
+                result.skipped.push({ path: dir, reason: 'process-probe-unavailable', pids: [], error });
             }
+            return result;
         }
 
+        const initialUsage = new Map(
+            getRuntimeProcessUsage(runtimeRoot, processSnapshot, versionDirs)
+                .map((entry) => [path.resolve(entry.path).toLowerCase(), entry])
+        );
+
         for (const dirToDelete of toDelete) {
+            let freshSnapshot;
             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.
+                freshSnapshot = readProcessSnapshot();
+            } catch (err) {
+                result.skipped.push({
+                    path: dirToDelete,
+                    reason: 'process-probe-unavailable',
+                    pids: [],
+                    error: err && err.message ? err.message : String(err)
+                });
+                continue;
+            }
+
+            const freshUsage = getRuntimeProcessUsage(runtimeRoot, freshSnapshot, versionDirs)
+                .find((entry) => path.resolve(entry.path).toLowerCase() === path.resolve(dirToDelete).toLowerCase());
+            if (freshUsage || initialUsage.has(path.resolve(dirToDelete).toLowerCase())) {
+                const usage = freshUsage || initialUsage.get(path.resolve(dirToDelete).toLowerCase());
+                result.skipped.push({ path: dirToDelete, reason: 'in-use', pids: usage.pids });
+                continue;
+            }
+
+            // Rename first. The post-rename probe below closes the normal
+            // TOCTOU window; a process that appears while retiring is restored
+            // to its original name before any recursive removal is attempted.
+            const deletingPath = `${dirToDelete}.deleting-${process.pid}-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
+            try {
+                renameSync(dirToDelete, deletingPath);
+            } catch (err) {
+                result.failed.push({ path: dirToDelete, error: err && err.message ? err.message : String(err) });
+                continue;
+            }
+
+            let postSnapshot;
+            try {
+                postSnapshot = readProcessSnapshot();
+            } catch (err) {
+                try { renameSync(deletingPath, dirToDelete); } catch { }
+                result.skipped.push({
+                    path: dirToDelete,
+                    reason: 'process-probe-unavailable-after-rename',
+                    pids: [],
+                    error: err && err.message ? err.message : String(err)
+                });
+                continue;
+            }
+            const postPids = [
+                ...processPidsUnder(dirToDelete, postSnapshot),
+                ...processPidsUnder(deletingPath, postSnapshot)
+            ].filter((pid, index, all) => all.indexOf(pid) === index).sort((a, b) => a - b);
+            if (postPids.length > 0) {
+                let restored = true;
+                try { renameSync(deletingPath, dirToDelete); } catch { restored = false; }
+                result.skipped.push({
+                    path: dirToDelete,
+                    reason: 'in-use-after-rename',
+                    pids: postPids,
+                    restored
+                });
+                continue;
+            }
+            const finalDeletingProbe = probeImmediatelyBeforeDelete(deletingPath);
+            if (!finalDeletingProbe.ok) {
+                let restored = true;
+                try { renameSync(deletingPath, dirToDelete); } catch { restored = false; }
+                result.skipped.push({
+                    path: dirToDelete,
+                    reason: 'process-probe-unavailable-before-delete',
+                    pids: [],
+                    error: finalDeletingProbe.error,
+                    restored
+                });
+                continue;
+            }
+            if (finalDeletingProbe.pids.length > 0) {
+                let restored = true;
+                try { renameSync(deletingPath, dirToDelete); } catch { restored = false; }
+                result.skipped.push({
+                    path: dirToDelete,
+                    reason: 'in-use-before-delete',
+                    pids: finalDeletingProbe.pids,
+                    restored
+                });
+                continue;
+            }
+
+            try {
+                rmSync(deletingPath, removeOptions);
+                result.deleted.push(dirToDelete);
+            } catch (err) {
+                result.failed.push({
+                    path: dirToDelete,
+                    deletingPath,
+                    error: err && err.message ? err.message : String(err)
+                });
             }
         }
-    } catch {
-        // Garbage collection is best-effort
+    } catch (err) {
+        result.failed.push({ path: runtimeRoot, error: err && err.message ? err.message : String(err) });
     }
+
+    return result;
 }
 
 function ensureStagedGateway(options = {}) {
@@ -177,7 +455,8 @@ function ensureStagedGateway(options = {}) {
             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')
+            reason: process.env.GENEXUS_MCP_GATEWAY_EXE ? 'GENEXUS_MCP_GATEWAY_EXE' : (process.env.GENEXUS_MCP_NO_STAGING === '1' ? 'NO_STAGING' : 'checkout'),
+            cleanup: null
         };
     }
 
@@ -195,12 +474,13 @@ function ensureStagedGateway(options = {}) {
     const stagedGatewayExe = path.join(targetDir, 'GxMcp.Gateway.exe');
 
     if (fs.existsSync(stagedGatewayExe)) {
-        cleanOldRuntimes(runtimeRoot, targetDir);
+        const cleanup = cleanOldRuntimes(runtimeRoot, targetDir, 2, options);
         return {
             staged: true,
             gatewayExePath: stagedGatewayExe,
             runtimeDir: targetDir,
-            fresh: false
+            fresh: false,
+            cleanup
         };
     }
 
@@ -211,6 +491,7 @@ function ensureStagedGateway(options = {}) {
     fs.mkdirSync(runtimeRoot, { recursive: true });
     const tmpDir = `${targetDir}.tmp-${process.pid}-${Date.now()}`;
     fs.mkdirSync(tmpDir, { recursive: true });
+    let temporaryCleanup = null;
 
     try {
         fs.cpSync(publishDir, tmpDir, { recursive: true });
@@ -222,31 +503,45 @@ function ensureStagedGateway(options = {}) {
         } 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
-                }
+                temporaryCleanup = cleanupRuntimeDirectory(tmpDir, options);
             } else {
                 throw renameErr;
             }
         }
     } catch (err) {
-        try {
-            fs.rmSync(tmpDir, { recursive: true, force: true });
-        } catch {
-            // Ignore tmp cleanup error
+        const failure = err instanceof Error ? err : new Error(String(err));
+        const cleanup = cleanupRuntimeDirectory(tmpDir, options);
+        failure.runtimeCleanup = cleanup;
+        const notes = [];
+        if (cleanup.skipped.length > 0) {
+            const reasons = cleanup.skipped
+                .map((entry) => `${entry.reason}${entry.pids?.length ? ` (PIDs: ${entry.pids.join(', ')})` : ''}`)
+                .join(', ');
+            notes.push(`skipped ${cleanup.skipped.length} path(s): ${reasons}`);
+        }
+        if (cleanup.failed.length > 0) {
+            notes.push(`failed ${cleanup.failed.length} path(s)`);
+        }
+        if (!cleanup.processProbeAvailable) {
+            notes.push('process probe unavailable');
+        }
+        if (notes.length > 0) {
+            failure.message = `${failure.message} Runtime cleanup ${notes.join('; ')}.`;
         }
-        throw err;
+        throw failure;
     }
 
-    cleanOldRuntimes(runtimeRoot, targetDir);
+    const cleanup = mergeRuntimeCleanupResults(
+        cleanOldRuntimes(runtimeRoot, targetDir, 2, options),
+        temporaryCleanup
+    );
 
     return {
         staged: true,
         gatewayExePath: stagedGatewayExe,
         runtimeDir: targetDir,
-        fresh: true
+        fresh: true,
+        cleanup
     };
 }
 
@@ -255,7 +550,7 @@ function listStagedRuntimes(runtimeRoot = resolveDefaultRuntimeRoot()) {
     try {
         const entries = fs.readdirSync(runtimeRoot, { withFileTypes: true });
         return entries
-            .filter((e) => e.isDirectory() && !e.name.includes('.tmp-'))
+            .filter((e) => e.isDirectory() && !e.name.includes('.tmp-') && !e.name.includes('.deleting-'))
             .map((e) => {
                 const dirPath = path.join(runtimeRoot, e.name);
                 let stat = null;
@@ -276,10 +571,14 @@ function listStagedRuntimes(runtimeRoot = resolveDefaultRuntimeRoot()) {
     }
 }
 
-function getRunningGxMcpProcesses() {
-    if (process.platform !== 'win32') return [];
+function probeRunningGxMcpProcesses() {
+    if (process.platform !== 'win32') {
+        return { ok: true, processes: [] };
+    }
     try {
-        // Query CIM Win32_Process for GxMcp processes
+        // Query CIM Win32_Process for GxMcp processes. Keep the probe result
+        // distinguishable from a successful empty result: GC must fail closed
+        // when Windows denies the query.
         const output = execFileSync('powershell.exe', [
             '-NoProfile',
             '-NonInteractive',
@@ -287,31 +586,43 @@ function getRunningGxMcpProcesses() {
             `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 [];
+        if (!output) return { ok: true, processes: [] };
         let data;
         try {
             data = JSON.parse(output);
-        } catch {
-            return [];
+        } catch (err) {
+            return { ok: false, processes: [], error: `invalid process probe JSON: ${err.message}` };
         }
         const rows = Array.isArray(data) ? data : [data];
-        return rows.map((r) => ({
+        const processes = rows.filter(Boolean).map((r) => ({
             pid: r.ProcessId,
             exePath: r.ExecutablePath || '',
             commandLine: r.CommandLine || ''
         }));
-    } catch {
-        return [];
+        const unresolved = processes.filter((proc) => !proc.exePath);
+        if (unresolved.length > 0) {
+            return {
+                ok: false,
+                processes,
+                error: `${unresolved.length} GxMcp process record(s) had no executable path; runtime GC is fail-closed.`
+            };
+        }
+        return { ok: true, processes };
+    } catch (err) {
+        return { ok: false, processes: [], error: err && err.message ? err.message : String(err) };
     }
 }
 
+function getRunningGxMcpProcesses() {
+    return probeRunningGxMcpProcesses().processes;
+}
+
 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)) {
+    if (isPathWithin(exePath, runtimeRoot)) {
         return 'staged';
     }
+    const norm = path.resolve(exePath).toLowerCase();
     if (norm.includes('npm-cache') || norm.includes('_npx') || norm.includes('node_modules')) {
         return 'npx-cache';
     }
@@ -328,5 +639,7 @@ module.exports = {
     ensureStagedGateway,
     listStagedRuntimes,
     getRunningGxMcpProcesses,
+    probeRunningGxMcpProcesses,
+    getRuntimeProcessUsage,
     classifyProcessRuntime
 };