genexus-mcp 2.6.5 → 2.6.6

package/cli/commands/axi.js

@@ -18,6 +18,7 @@ const {
     readGeneXusVersionFromInstall,
     discoverGeneXusInstallation,
     discoverKnowledgeBase,
+    discoverKnowledgeBases,
     readKbCatalog,
     addKbToConfig,
     removeKbFromConfig,
@@ -419,6 +420,234 @@ function buildClientExeCrossCheck(packageExePath) {
     };
 }
 
+// v2.6.6 — probe Stream B's per-KB worker lock. The worker writes
+// `.worker-<hash>.lock` into TempPath (or the configured lockDir); the file
+// holds the live PID. We list every matching file, classify it as live /
+// stale, and surface stale ones so the user can clean them up.
+function buildWorkerSingleInstanceLockCheck() {
+    const tempDir = require('os').tmpdir();
+    let entries;
+    try {
+        entries = fs.readdirSync(tempDir).filter((n) => /^\.worker-[0-9a-f]{16}\.lock$/i.test(n));
+    } catch (err) {
+        return { status: 'warn', detail: `Unable to scan ${tempDir} for worker lock files: ${err.message || err}` };
+    }
+
+    if (!entries || entries.length === 0) {
+        return { status: 'pass', detail: 'No worker single-instance lock files found (no worker currently registered).' };
+    }
+
+    const live = [];
+    const stale = [];
+    for (const name of entries) {
+        const full = path.join(tempDir, name);
+        let pid = null;
+        try {
+            const txt = fs.readFileSync(full, 'utf8').trim();
+            const parsed = Number.parseInt(txt, 10);
+            if (Number.isFinite(parsed) && parsed > 0) pid = parsed;
+        } catch {
+            // Lock file holds a delete-on-close handle on the owning worker —
+            // if reading fails with EBUSY/EACCES it's almost certainly live.
+            live.push({ name, pid: null, note: 'file is locked (owner alive)' });
+            continue;
+        }
+
+        if (pid === null) {
+            stale.push({ name, pid: null, note: 'pid file unreadable / empty' });
+            continue;
+        }
+
+        let alive = false;
+        try {
+            process.kill(pid, 0);
+            alive = true;
+        } catch (err) {
+            alive = err.code === 'EPERM'; // EPERM => process exists but we can't signal it
+        }
+
+        if (alive) live.push({ name, pid, note: null });
+        else stale.push({ name, pid, note: 'pid not running' });
+    }
+
+    if (stale.length === 0) {
+        const desc = live.map((l) => l.pid ? `pid=${l.pid}` : (l.note || 'locked')).join(', ');
+        return {
+            status: 'pass',
+            detail: `Worker single-instance lock healthy (${live.length} live owner${live.length === 1 ? '' : 's'}: ${desc}).`
+        };
+    }
+
+    const livePart = live.length ? `live: ${live.map((l) => l.pid || '?').join(', ')}` : 'no live owners';
+    const stalePart = `stale: ${stale.map((s) => path.join(tempDir, s.name)).join('; ')}`;
+    return {
+        status: 'warn',
+        detail: `Worker lock files include ${stale.length} stale entr${stale.length === 1 ? 'y' : 'ies'} (${livePart}; ${stalePart}). Delete the stale .lock file(s) to clear; Stream B's lock will recreate on next worker start.`
+    };
+}
+
+// v2.6.6 — probe Stream D's in-process build path. Confirms
+// `Genexus.MsBuild.Tasks.dll` is reachable under GX_PROGRAM_DIR / configured
+// GeneXus install. If missing, the worker falls back to spawning MSBuild.exe
+// (the slow path) — that still works but loses the IDE-parity build daemon.
+function buildInProcessBuildAssemblyLoadCheck(gxPath) {
+    const dllName = 'Genexus.MsBuild.Tasks.dll';
+    const candidates = [];
+    if (process.env.GX_PROGRAM_DIR) candidates.push(path.join(process.env.GX_PROGRAM_DIR, dllName));
+    if (gxPath) candidates.push(path.join(gxPath, dllName));
+
+    if (candidates.length === 0) {
+        return {
+            status: 'warn',
+            detail: `In-process build assembly check skipped: GX_PROGRAM_DIR not set and no configured GeneXus path. Build will fall back to MSBuild.exe spawn (the slow path).`
+        };
+    }
+
+    for (const candidate of candidates) {
+        try {
+            const stat = fs.statSync(candidate);
+            if (stat && stat.isFile() && stat.size > 0) {
+                return {
+                    status: 'pass',
+                    detail: `In-process build assembly is loadable from ${candidate} (${Math.round(stat.size / 1024)} KB). Stream D's build daemon is ready.`
+                };
+            }
+        } catch {
+            // try next candidate
+        }
+    }
+
+    return {
+        status: 'warn',
+        detail: `In-process build assembly ${dllName} not found at: ${candidates.join('; ')}. The worker will fall back to spawning MSBuild.exe (the slow path) — set GXMCP_INPROCESS_BUILD=0 to silence, or install/repair GeneXus.`
+    };
+}
+
+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
+    // across the dump so the support engineer can still correlate "this redacted KB
+    // is the same as that one in worker logs."
+    if (!cfg || typeof cfg !== 'object') return cfg;
+    const crypto = require('crypto');
+    const hash = (s) => crypto.createHash('sha256').update(s).digest('hex').slice(0, 8);
+    const looksLikePath = (s) => typeof s === 'string' && /[\\/]/.test(s) && (s.length > 3);
+    const walk = (node) => {
+        if (Array.isArray(node)) return node.map(walk);
+        if (node && typeof node === 'object') {
+            const out = {};
+            for (const k of Object.keys(node)) out[k] = walk(node[k]);
+            return out;
+        }
+        if (looksLikePath(node)) return `<redacted:${hash(node)}>`;
+        return node;
+    };
+    return walk(cfg);
+}
+
+async function buildSupportDump({ checks, summary, data, gatewayExePath, ctx }) {
+    const os = require('os');
+    const crypto = require('crypto');
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const tmpBase = path.join(os.tmpdir(), `genexus-mcp-dump-${stamp}`);
+    fs.mkdirSync(tmpBase, { recursive: true });
+
+    const entries = [];
+
+    const writeEntry = (relPath, content) => {
+        const full = path.join(tmpBase, relPath);
+        fs.mkdirSync(path.dirname(full), { recursive: true });
+        fs.writeFileSync(full, typeof content === 'string' ? content : JSON.stringify(content, null, 2));
+        entries.push(relPath);
+    };
+
+    writeEntry('doctor.json', { summary, checks, generatedAt: new Date().toISOString() });
+
+    if (data.configPath && fs.existsSync(data.configPath)) {
+        const cfg = readJsonFileSafe(data.configPath);
+        writeEntry('config.redacted.json', redactConfig(cfg));
+    }
+
+    let gxVersion = null;
+    try { gxVersion = readGeneXusVersionFromInstall(data.gxPath); } catch { }
+
+    writeEntry('environment.json', {
+        platform: process.platform,
+        arch: process.arch,
+        nodeVersion: process.version,
+        osRelease: os.release(),
+        cwdHash: crypto.createHash('sha256').update(ctx.cwd || '').digest('hex').slice(0, 8),
+        gatewayExePath,
+        gatewayExeExists: fs.existsSync(gatewayExePath),
+        configSource: data.configSource,
+        kbConfigured: !!data.kbPath,
+        gxConfigured: !!data.gxPath,
+        gxVersion,
+        envFlags: {
+            GX_CONFIG_PATH: !!process.env.GX_CONFIG_PATH,
+            GENEXUS_MCP_GATEWAY_EXE: !!process.env.GENEXUS_MCP_GATEWAY_EXE,
+            GXMCP_INPROCESS_BUILD: process.env.GXMCP_INPROCESS_BUILD || null,
+            HTTPS_PROXY: !!process.env.HTTPS_PROXY,
+            HTTP_PROXY: !!process.env.HTTP_PROXY
+        }
+    });
+
+    // Worker logs: scan the standard log dir (LocalAppData) for recent worker logs,
+    // grab the tail of each. Keep it bounded so the zip stays small.
+    const logRoots = [];
+    if (process.env.LOCALAPPDATA) logRoots.push(path.join(process.env.LOCALAPPDATA, 'GenexusMCP', 'logs'));
+    logRoots.push(path.join(os.tmpdir(), 'GenexusMCP', 'logs'));
+
+    let logCount = 0;
+    for (const root of logRoots) {
+        if (logCount >= 5) break;
+        try {
+            if (!fs.existsSync(root)) continue;
+            const files = fs.readdirSync(root)
+                .filter((f) => /\.log$/i.test(f))
+                .map((f) => ({ f, full: path.join(root, f), mtime: fs.statSync(path.join(root, f)).mtimeMs }))
+                .sort((a, b) => b.mtime - a.mtime)
+                .slice(0, 5 - logCount);
+            for (const entry of files) {
+                try {
+                    const stat = fs.statSync(entry.full);
+                    const tailBytes = 64 * 1024;
+                    const start = Math.max(0, stat.size - tailBytes);
+                    const fd = fs.openSync(entry.full, 'r');
+                    try {
+                        const buf = Buffer.alloc(stat.size - start);
+                        fs.readSync(fd, buf, 0, buf.length, start);
+                        writeEntry(`logs/${entry.f}.tail.txt`, buf.toString('utf8'));
+                    } finally {
+                        fs.closeSync(fd);
+                    }
+                    logCount += 1;
+                } catch { }
+            }
+        } catch { }
+    }
+
+    // Zip via PowerShell's built-in Compress-Archive on Windows; tar elsewhere.
+    const { execFileSync } = require('child_process');
+    let zipPath;
+    if (process.platform === 'win32') {
+        zipPath = `${tmpBase}.zip`;
+        execFileSync('powershell.exe', ['-NoProfile', '-Command', `Compress-Archive -Path '${tmpBase}\\*' -DestinationPath '${zipPath}' -Force`], { windowsHide: true });
+    } else {
+        zipPath = `${tmpBase}.tar.gz`;
+        execFileSync('tar', ['-czf', zipPath, '-C', path.dirname(tmpBase), path.basename(tmpBase)]);
+    }
+
+    // Clean up the staging dir; the zip is the artifact.
+    try { fs.rmSync(tmpBase, { recursive: true, force: true }); } catch { }
+
+    return {
+        zipPath,
+        sizeBytes: fs.statSync(zipPath).size,
+        entries
+    };
+}
+
 async function handleDoctor(options, ctx) {
     const data = buildStatusData(ctx.cwd);
     const toolDefPath = getToolDefinitionsPath();
@@ -453,14 +682,25 @@ async function handleDoctor(options, ctx) {
                 ? `Gateway exe is under %${riskyZone}%, which is commonly blocked by AppLocker/SRP in Windows domains. If clients show "Failed to connect" / "Access denied", reinstall to a whitelisted path via scripts/install.ps1 (defaults to C:\\Tools\\GenexusMCP or %LOCALAPPDATA%\\Programs\\GenexusMCP).`
                 : 'Gateway exe is in a path unlikely to be blocked by AppLocker/SRP.'
         },
-        { id: 'kb_path_exists', status: kbExists ? 'pass' : 'warn', detail: kbExists ? 'Configured KB path exists.' : 'Configured KB path does not exist.' },
+        // A KB path configured but absent on disk is fatal — the worker can't open a KB
+        // that doesn't exist. Only when no KB is configured at all do we soften to warn.
+        { id: 'kb_path_exists', status: kbExists ? 'pass' : (kbPath ? 'fail' : 'warn'), detail: kbExists ? 'Configured KB path exists.' : (kbPath ? `Configured KB path does not exist: ${kbPath}` : 'No KB path is configured.') },
         { id: 'kb_shape', status: data.kbLooksValid ? 'pass' : 'warn', detail: data.kbLooksValid ? 'KB folder shape looks valid.' : 'KB markers were not found in configured KB path.' },
-        { id: 'gx_installation', status: gxExeExists ? 'pass' : 'warn', detail: gxExeExists ? 'GeneXus installation has genexus.exe.' : 'Configured GeneXus installation is missing genexus.exe.' },
+        // 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: 'tool_definitions', status: toolDefsExists ? 'pass' : 'warn', detail: toolDefsExists ? `Tool definition file found (${toolCount} tools).` : 'tool_definitions.json is missing.' },
         { id: 'gx_env', status: process.env.GX_CONFIG_PATH ? 'pass' : 'warn', detail: process.env.GX_CONFIG_PATH ? 'GX_CONFIG_PATH env var is set.' : 'GX_CONFIG_PATH env var is not set for this process.' },
         { id: 'client_config_sync', status: clientCrossCheck.status, detail: clientCrossCheck.detail }
     ];
 
+    // v2.6.6 — Stream B / Stream D doctor checks.
+    const lockCheck = buildWorkerSingleInstanceLockCheck();
+    checks.push({ id: 'worker_single_instance_lock', status: lockCheck.status, detail: lockCheck.detail });
+    const inProcessLoad = buildInProcessBuildAssemblyLoadCheck(gxPath);
+    checks.push({ id: 'in_process_build_assembly_load', status: inProcessLoad.status, detail: inProcessLoad.detail });
+
     if (data.gatewayExeFound) {
         const probe = await probeGatewaySpawn();
         checks.push({ id: 'gateway_spawn_probe', status: probe.status, detail: probe.detail });
@@ -478,6 +718,34 @@ async function handleDoctor(options, ctx) {
         return acc;
     }, { pass: 0, warn: 0, fail: 0 });
 
+    // Support bundle for handing off to support: doctor output + config (with paths
+    // anonymized by hash so we don't leak filesystem layout) + recent worker logs +
+    // version info, all zipped under TempPath. Far simpler than asking the operator
+    // to send 5 separate things over chat.
+    if (options.dump) {
+        try {
+            const dumpResult = await buildSupportDump({ checks, summary, data, gatewayExePath, ctx });
+            return {
+                exitCode: ctx.EXIT_CODES.OK,
+                envelope: {
+                    ok: {
+                        action: 'doctor.dump',
+                        zipPath: dumpResult.zipPath,
+                        sizeBytes: dumpResult.sizeBytes,
+                        entries: dumpResult.entries,
+                        summary
+                    },
+                    help: ['Attach the zip to your support ticket. Paths inside config.json have been redacted; sensitive values may still appear in worker logs — review before sharing if needed.']
+                }
+            };
+        } catch (err) {
+            return {
+                exitCode: ctx.EXIT_CODES.ERROR,
+                envelope: operationalErrorEnvelope(`Failed to build doctor dump: ${err && err.message ? err.message : 'unknown error'}`, ctx.EXIT_CODES.ERROR)
+            };
+        }
+    }
+
     const defaultFields = ['id', 'status', 'detail'];
     const allowedFields = ['id', 'status', 'detail'];
     const fieldSelection = validateFieldSelection(options.fields, allowedFields, 'doctor', ctx);
@@ -890,6 +1158,34 @@ async function runInteractiveInit(ctx) {
         const gxAnswer = await question(`\n2) GeneXus installation path (default: ${defaultGx}):\n> `);
         const finalGx = String(gxAnswer || '').trim() || defaultGx;
 
+        if (!fs.existsSync(path.join(finalGx, 'genexus.exe'))) {
+            const suggested = discoverGeneXusInstallation();
+            const help = [`Path checked: ${finalGx}`];
+            if (suggested && suggested.toLowerCase() !== finalGx.toLowerCase()) {
+                help.push(`Detected a working GeneXus install at: ${suggested}`);
+                help.push('Re-run `genexus-mcp init --interactive` and accept the detected path, or pass --gx explicitly.');
+            }
+            return {
+                exitCode: ctx.EXIT_CODES.ERROR,
+                envelope: operationalErrorEnvelope(
+                    `GeneXus path does not contain genexus.exe. Aborted before writing config to avoid silent worker crashes.`,
+                    ctx.EXIT_CODES.ERROR,
+                    help
+                )
+            };
+        }
+
+        if (!fs.existsSync(finalKb)) {
+            return {
+                exitCode: ctx.EXIT_CODES.ERROR,
+                envelope: operationalErrorEnvelope(
+                    `KB path does not exist on disk. Aborted before writing config.`,
+                    ctx.EXIT_CODES.ERROR,
+                    [`Path checked: ${finalKb}`, 'Create the KB in GeneXus first, then re-run init.']
+                )
+            };
+        }
+
         const allTargets = getClientConfigTargets();
         const platformTargets = filterClientTargets(allTargets, { platform: process.platform });
         ctx.stderr.write('\n3) Select AI agents to register (y/N per agent; Enter accepts default):\n');
@@ -971,6 +1267,18 @@ async function handleInit(options, ctx) {
         }
     }
 
+    // Broaden the search: walk-up from cwd and scan common KB roots. If exactly one
+    // candidate exists, use it; if many, surface them so the operator can pass --kb
+    // explicitly instead of seeing the bare "missing --kb" error.
+    let kbCandidates = null;
+    if (!resolution.kb.value) {
+        kbCandidates = discoverKnowledgeBases(ctx.cwd);
+        if (kbCandidates.length === 1) {
+            resolution.kb.value = kbCandidates[0].path;
+            resolution.kb.source = `auto-discovery:${kbCandidates[0].source}`;
+        }
+    }
+
     if (!resolution.gx.value) {
         const fromDisco = discoverGeneXusInstallation();
         if (fromDisco) {
@@ -981,13 +1289,69 @@ async function handleInit(options, ctx) {
 
     if (!resolution.kb.value || !resolution.gx.value) {
         const missing = [];
-        if (!resolution.kb.value) missing.push('--kb (and current directory is not a GeneXus KB)');
+        const help = [];
+        if (!resolution.kb.value) {
+            missing.push('--kb (and current directory is not a GeneXus KB)');
+            if (kbCandidates && kbCandidates.length > 1) {
+                help.push(`Found ${kbCandidates.length} candidate KB folder${kbCandidates.length === 1 ? '' : 's'}. Pick one and pass it as --kb:`);
+                for (const c of kbCandidates.slice(0, 10)) {
+                    help.push(`  --kb "${c.path}"   (${c.source})`);
+                }
+                if (kbCandidates.length > 10) {
+                    help.push(`  ... and ${kbCandidates.length - 10} more.`);
+                }
+            }
+        }
         if (!resolution.gx.value) missing.push('--gx (and no GeneXus installation was auto-discovered)');
         return {
             exitCode: ctx.EXIT_CODES.USAGE,
-            envelope: usageEnvelope(
-                `Cannot resolve required paths: ${missing.join('; ')}. Pass flags explicitly or run from inside a KB folder.`,
-                ctx.EXIT_CODES.USAGE
+            envelope: {
+                error: { code: 'usage_error', message: `Cannot resolve required paths: ${missing.join('; ')}. Pass flags explicitly or run from inside a KB folder.` },
+                help: help.length ? help : [
+                    'Run `genexus-mcp help` for command reference.',
+                    'Run `genexus-mcp init --kb "<kbPath>" --gx "<geneXusPath>"` for non-interactive setup.'
+                ],
+                meta: { exitCode: ctx.EXIT_CODES.USAGE }
+            }
+        };
+    }
+
+    // Validate the supplied GeneXus path before we commit it to disk. A non-default
+    // install (e.g. C:\...\GeneXus18u7 vs the GeneXus18 default) used to slip through
+    // — init wrote the config, then the worker crashed on first MCP call with no
+    // useful signal back to the operator.
+    if (!fs.existsSync(path.join(resolution.gx.value, 'genexus.exe'))) {
+        const help = [
+            `Path checked: ${resolution.gx.value}`,
+            `Source: --${resolution.gx.source === 'flag' ? 'gx flag' : resolution.gx.source}`
+        ];
+        const suggested = resolution.gx.source === 'flag' ? discoverGeneXusInstallation() : null;
+        if (suggested && suggested.toLowerCase() !== resolution.gx.value.toLowerCase()) {
+            help.push(`Detected a working GeneXus install at: ${suggested}`);
+            help.push(`Re-run: genexus-mcp init --kb "${resolution.kb.value}" --gx "${suggested}"`);
+        } else {
+            help.push('Omit --gx to let init auto-discover via registry / Program Files (matches GeneXus18, GeneXus18u7, etc.).');
+        }
+        return {
+            exitCode: ctx.EXIT_CODES.ERROR,
+            envelope: operationalErrorEnvelope(
+                `Configured GeneXus path does not contain genexus.exe. Init aborted before writing config to avoid silent worker crashes.`,
+                ctx.EXIT_CODES.ERROR,
+                help
+            )
+        };
+    }
+
+    if (!fs.existsSync(resolution.kb.value)) {
+        return {
+            exitCode: ctx.EXIT_CODES.ERROR,
+            envelope: operationalErrorEnvelope(
+                `Configured KB path does not exist on disk. Init aborted.`,
+                ctx.EXIT_CODES.ERROR,
+                [
+                    `Path checked: ${resolution.kb.value}`,
+                    'Create the KB in GeneXus first, then re-run init pointing at its folder.'
+                ]
             )
         };
     }
@@ -1014,7 +1378,8 @@ async function handleInit(options, ctx) {
         }
 
         const verification = await runPostInitVerification({
-            cwd: ctx.cwd,
+            cwd: resolution.kb.value,
+            configPath: created.targetConfigPath,
             includeSmoke: !options.noSmoke,
             ctx
         });
@@ -1031,15 +1396,27 @@ async function handleInit(options, ctx) {
         if (patchResult.patched.length > 0 && process.platform === 'win32' && !process.env.GENEXUS_MCP_GATEWAY_EXE) {
             help.push('Windows + corporate AppLocker: the npx launcher resolves the gateway from %LOCALAPPDATA%\\npm-cache, which is commonly blocked. If clients fail with "Failed to connect" / Access denied, reinstall to a whitelisted path via scripts/install.ps1.');
         }
-        if (verification.summary.fail > 0 || verification.summary.warn > 0) {
-            help.push('Some verification checks did not pass. Run `genexus-mcp doctor --mcp-smoke` for details.');
+        if (verification.summary.fail > 0) {
+            const failedIds = verification.checks
+                .filter((c) => c.status === 'fail')
+                .map((c) => c.id)
+                .join(', ');
+            help.push(`Verification failed (${verification.summary.fail} check${verification.summary.fail === 1 ? '' : 's'}: ${failedIds}). The config was written but the MCP will not work until these are fixed.`);
+            help.push('Run `genexus-mcp doctor --mcp-smoke` for full details.');
+        } else if (verification.summary.warn > 0) {
+            help.push('Some verification checks emitted warnings. Run `genexus-mcp doctor --mcp-smoke` for details.');
         }
         if (options.noSmoke) {
             help.push('MCP protocol smoke was skipped (--no-smoke). Re-run `genexus-mcp doctor --mcp-smoke` to validate end-to-end.');
         }
 
+        // A non-zero exit when any critical check failed gives the caller (install.ps1,
+        // CI, AI client) something to react to. Previously init always returned OK and
+        // the failure surfaced later as a generic worker crash.
+        const initExitCode = verification.summary.fail > 0 ? ctx.EXIT_CODES.ERROR : ctx.EXIT_CODES.OK;
+
         return {
-            exitCode: ctx.EXIT_CODES.OK,
+            exitCode: initExitCode,
             envelope: {
                 ok: {
                     action: 'init',
@@ -1103,14 +1480,95 @@ async function warmGateway({ configPath }) {
     });
 }
 
-async function runPostInitVerification({ cwd, includeSmoke, ctx }) {
-    const doctorResult = await handleDoctor(
-        { full: false, mcpSmoke: !!includeSmoke, fields: null, limit: 100 },
-        { cwd, EXIT_CODES: ctx.EXIT_CODES }
-    );
+async function runPostInitVerification({ cwd, configPath, includeSmoke, ctx }) {
+    // Doctor inspects buildStatusData(cwd), which only finds config.json if it sits
+    // at cwd or if GX_CONFIG_PATH is exported. Init runs from wherever the operator
+    // typed `npx genexus-mcp init` (often C:\windows\system32) — so we point doctor
+    // at the freshly-written config explicitly.
+    const priorEnv = process.env.GX_CONFIG_PATH;
+    if (configPath) process.env.GX_CONFIG_PATH = configPath;
+    try {
+        const doctorResult = await handleDoctor(
+            { full: false, mcpSmoke: !!includeSmoke, fields: null, limit: 100 },
+            { cwd, EXIT_CODES: ctx.EXIT_CODES }
+        );
+
+        const { checks, summary } = doctorResult.envelope.ok;
+
+        let workerSmoke = null;
+        if (includeSmoke && configPath) {
+            workerSmoke = await probeWorkerStartup({ configPath });
+            checks.push({ id: 'worker_startup_smoke', status: workerSmoke.status, detail: workerSmoke.detail });
+            summary[workerSmoke.status] = (summary[workerSmoke.status] || 0) + 1;
+        }
+
+        return { checks, summary };
+    } finally {
+        if (priorEnv === undefined) delete process.env.GX_CONFIG_PATH;
+        else process.env.GX_CONFIG_PATH = priorEnv;
+    }
+}
+
+// Spawn the gateway with the resolved config and watch for an early crash.
+// If the worker can't load the KB (bad GX path, missing genexus.exe, KB lock,
+// AppLocker block, etc.), the process exits fast with a non-zero code. Without
+// this probe init prints "ok" and the failure only surfaces later on the first
+// MCP call, with a generic "Worker crashed/exited" — exactly what bit the user
+// who had GeneXus18u7 instead of GeneXus18.
+async function probeWorkerStartup({ configPath, observeMs = 2500 }) {
+    const gatewayExePath = getGatewayExePath();
+    if (!fs.existsSync(gatewayExePath)) {
+        return { status: 'warn', detail: 'Worker smoke skipped: gateway exe not found.' };
+    }
+
+    return await new Promise((resolve) => {
+        let stderr = '';
+        let stdout = '';
+        let resolved = false;
+        const finish = (payload) => {
+            if (resolved) return;
+            resolved = true;
+            resolve(payload);
+        };
+
+        let child;
+        try {
+            child = spawn(gatewayExePath, [], {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                windowsHide: true,
+                env: { ...process.env, GX_CONFIG_PATH: configPath }
+            });
+        } catch (err) {
+            return finish({ status: 'fail', detail: `Worker smoke: failed to launch gateway: ${err.message}` });
+        }
+
+        child.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+        child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
 
-    const { checks, summary } = doctorResult.envelope.ok;
-    return { checks, summary };
+        child.once('error', (err) => {
+            finish({ status: 'fail', detail: `Worker smoke: gateway spawn error: ${err.message}` });
+        });
+
+        child.once('exit', (code) => {
+            if (code === 0) {
+                finish({ status: 'pass', detail: 'Worker smoke: gateway exited cleanly during observation window.' });
+            } else {
+                const preview = sanitizeOperationalMessage((stderr || stdout || '').trim(), '');
+                finish({
+                    status: 'fail',
+                    detail: preview
+                        ? `Worker smoke: gateway crashed (exit ${code}): ${preview}`
+                        : `Worker smoke: gateway crashed (exit ${code}) with no stderr. Run \`genexus-mcp doctor --mcp-smoke\` for details.`
+                });
+            }
+        });
+
+        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.` });
+        }, observeMs);
+    });
 }
 
 async function handleWhoami(options, ctx) {
@@ -1403,8 +1861,8 @@ function commandHelpMap() {
             examples: ['genexus-mcp status', 'genexus-mcp status --full --format json']
         },
         doctor: {
-            usage: 'genexus-mcp doctor [--full] [--mcp-smoke] [--fields f1,f2] [--limit N] [--format toon|json|text]',
-            examples: ['genexus-mcp doctor', 'genexus-mcp doctor --full --mcp-smoke --format json']
+            usage: 'genexus-mcp doctor [--full] [--mcp-smoke] [--dump] [--fields f1,f2] [--limit N] [--format toon|json|text]',
+            examples: ['genexus-mcp doctor', 'genexus-mcp doctor --full --mcp-smoke --format json', 'genexus-mcp doctor --dump   # build a support bundle zip']
         },
         tools: {
             usage: 'genexus-mcp tools list [--query text] [--fields f1,f2] [--limit N] [--full] [--format ...]',

package/cli/index.js

@@ -43,6 +43,7 @@ const GLOBAL_DEFAULTS = {
     clients: null,
     allClients: false,
     mcpSmoke: false,
+    dump: false,
     noSmoke: false,
     warm: false,
     yes: false,
@@ -268,6 +269,9 @@ function parseArgs(argv) {
             case 'mcp-smoke':
                 result.options.mcpSmoke = true;
                 break;
+            case 'dump':
+                result.options.dump = true;
+                break;
             case 'no-smoke':
                 result.options.noSmoke = true;
                 break;

package/cli/lib/config.js

@@ -134,6 +134,77 @@ function discoverKnowledgeBase(cwd) {
     return null;
 }
 
+// Broader KB discovery: walk up the cwd ancestry, then scan a small set of common
+// roots where developers stash KBs. Returns deduped candidates with a `source` tag
+// so the caller can explain its pick. Bounded so we never recurse into giant trees.
+function discoverKnowledgeBases(cwd, { maxResults = 25, scanDepth = 2 } = {}) {
+    const results = [];
+    const seen = new Set();
+    const push = (dir, source) => {
+        if (!dir) return;
+        const key = path.resolve(dir).toLowerCase();
+        if (seen.has(key)) return;
+        if (results.length >= maxResults) return;
+        if (directoryLooksLikeKnowledgeBase(dir)) {
+            seen.add(key);
+            results.push({ path: path.resolve(dir), source });
+        }
+    };
+
+    // 1. cwd and ancestors (a developer running `npx init` from a KB subdirectory
+    //    almost certainly meant that KB).
+    if (cwd) {
+        let current = path.resolve(cwd);
+        let lastParent = null;
+        while (current && current !== lastParent && results.length < maxResults) {
+            push(current, 'cwd-ancestor');
+            lastParent = current;
+            current = path.dirname(current);
+            if (current === lastParent) break;
+        }
+    }
+
+    // 2. Common KB roots — drives + user folders. Scan a shallow depth only.
+    const roots = [];
+    for (const drive of ['C', 'D', 'E']) {
+        roots.push(`${drive}:\\KBs`);
+        roots.push(`${drive}:\\KB`);
+        roots.push(`${drive}:\\GeneXus`);
+    }
+    if (process.env.USERPROFILE) {
+        roots.push(path.join(process.env.USERPROFILE, 'Documents', 'GeneXus'));
+        roots.push(path.join(process.env.USERPROFILE, 'KBs'));
+        roots.push(path.join(process.env.USERPROFILE, 'source', 'repos'));
+    }
+
+    const scanRoot = (root, depth) => {
+        if (depth < 0) return;
+        if (results.length >= maxResults) return;
+        let entries;
+        try {
+            entries = fs.readdirSync(root, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (results.length >= maxResults) return;
+            if (!entry.isDirectory()) continue;
+            const full = path.join(root, entry.name);
+            push(full, 'common-root');
+            if (depth > 0) scanRoot(full, depth - 1);
+        }
+    };
+
+    for (const root of roots) {
+        try {
+            if (fs.existsSync(root)) scanRoot(root, scanDepth);
+        } catch {
+        }
+    }
+
+    return results;
+}
+
 function directoryLooksLikeKnowledgeBase(dir) {
     try {
         const files = fs.readdirSync(dir);
@@ -684,6 +755,7 @@ module.exports = {
     discoverGeneXusInstallation,
     discoverGeneXusFromRegistry,
     discoverKnowledgeBase,
+    discoverKnowledgeBases,
     directoryLooksLikeKnowledgeBase,
     readJsonFileSafe,
     resolveConfigPathNoMutate,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genexus-mcp",
-  "version": "2.6.5",
+  "version": "2.6.6",
   "mcpName": "io.github.lennix1337/genexus",
   "description": "GeneXus 18 MCP server — read, edit, and analyze GeneXus knowledge base objects (transactions, web panels, procedures, SDTs) directly from Claude, Cursor, and other AI agents over the Model Context Protocol.",
   "keywords": [

package/publish/GxMcp.Gateway.deps.json

@@ -7,7 +7,7 @@
   "targets": {
     ".NETCoreApp,Version=v8.0": {},
     ".NETCoreApp,Version=v8.0/win-x64": {
-      "GxMcp.Gateway/2.6.5": {
+      "GxMcp.Gateway/2.6.6": {
         "dependencies": {
           "Newtonsoft.Json": "13.0.3",
           "System.Management": "10.0.5",
@@ -66,7 +66,7 @@
     }
   },
   "libraries": {
-    "GxMcp.Gateway/2.6.5": {
+    "GxMcp.Gateway/2.6.6": {
       "type": "project",
       "serviceable": false,
       "sha512": ""

package/publish/tool_definitions.json

@@ -4,17 +4,17 @@
   {"name":"genexus_query","description":"Search objects in the active KB. Supports prefixes (type:, usedby:, parent:, parentPath:, description:). Compact projection by default. See genexus://kb/tool-help/genexus_query for examples.","inputSchema":{"type":"object","properties":{"query":{"type":"string"},"typeFilter":{"type":"string"},"domainFilter":{"type":"string"},"limit":{"type":"integer"},"inline_read_top":{"type":"integer","description":"0-3. Inline reads of top N in response."},"kb":{"type":"string","description":"Target KB. Required when 2+ open."},"axiCompact":{"type":"boolean","description":"Default true. Returns compact projection (name,type,path). Pass false for full payload.","default":true}},"required":["query"]}},
   {"name":"genexus_list_objects","description":"List objects with pagination. Feed nextOffset until hasMore=false. Returns minimal shape by default (name, type, path, parent); verbose=true for full shape.","inputSchema":{"type":"object","properties":{"filter":{"type":"string","description":"Legacy: matches name OR description. Prefer nameFilter/descriptionFilter."},"nameFilter":{"type":"string","description":"Substring match on object name only."},"descriptionFilter":{"type":"string","description":"Substring match on description only."},"pathPrefix":{"type":"string","description":"Folder path prefix, e.g. 'Root Module/ClickSign/'."},"limit":{"type":"integer"},"offset":{"type":"integer"},"parent":{"type":"string"},"parentPath":{"type":"string"},"typeFilter":{"type":"string"},"verbose":{"type":"boolean","description":"When true, returns full item shape (default false)."},"inline_read_top":{"type":"integer","description":"0-3. Inline reads of top N in response."},"kb":{"type":"string","description":"Target KB. Required when 2+ open."},"axiCompact":{"type":"boolean","description":"Default true. Returns compact projection (name,type,path,parentPath). Pass false for full payload.","default":true}}}},
   {"name":"genexus_read","description":"Read source/metadata parts of one or more objects. Pass name or targets, plus parts=[...]. Paginate large source with offset/limit. See genexus://kb/tool-help/genexus_read for examples.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"targets":{"type":"array","items":{"type":"string"}},"part":{"type":"string"},"parts":{"type":"array","items":{"type":"string"},"description":"When set, only the listed parts are returned in a combined response. Mutually exclusive with part/offset/limit."},"offset":{"type":"integer"},"limit":{"type":"integer"},"type":{"type":"string"},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}}}},
-  {"name":"genexus_edit","description":"Edit an object part. Pass name or targets (mutually exclusive). Mode: full | patch. Use dryRun before persisting. For WWP screens edit the host WorkWithPlus<X>.PatternInstance — NOT the WebForm of the parent (gets overwritten on reapply). See recipe 'edit_pattern_instance' and 'add_custom_button' via genexus_recipe.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"part":{"type":"string"},"mode":{"type":"string","enum":["full","patch","ops"]},"content":{"type":"string"},"ops":{"type":"array","description":"RFC 6902 JSON-Patch ops. Supported: add, remove, replace, test.","items":{"type":"object","properties":{"op":{"type":"string","enum":["add","remove","replace","test"]},"path":{"type":"string"},"value":{}},"required":["op","path"]}},"patch":{"description":"Legacy string replacement OR {find, replace} JSON object. Prefer separate operation/context/content params for new code.","anyOf":[{"type":"string"},{"type":"object","properties":{"find":{"type":"string"},"replace":{"type":"string"}},"required":["find","replace"]}]},"context":{"type":"string"},"operation":{"type":"string","enum":["Replace","Insert_After","Append"]},"expectedCount":{"type":"integer"},"dryRun":{"type":"boolean"},"verifyRollback":{"type":"boolean"},"targets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"content":{"type":"string"}},"required":["name","content"]}},"type":{"type":"string"},"return_post_state":{"type":"boolean","description":"Set false to omit post_state.diff from the response (default true)."},"verbose":{"type":"boolean","description":"When true, adds slices (±15 lines around each hunk) to post_state (default false)."},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}}}},
+  {"name":"genexus_edit","description":"Edit an object part. Pass name or targets (mutually exclusive). Mode: full | patch. Use dryRun before persisting. For WWP screens edit the host WorkWithPlus<X>.PatternInstance — NOT the WebForm of the parent (gets overwritten on reapply). See recipe 'edit_pattern_instance' and 'add_custom_button' via genexus_recipe.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"part":{"type":"string"},"mode":{"type":"string","enum":["full","patch","ops"]},"content":{"type":"string"},"ops":{"type":"array","description":"RFC 6902 JSON-Patch ops. Supported: add, remove, replace, test.","items":{"type":"object","properties":{"op":{"type":"string","enum":["add","remove","replace","test"]},"path":{"type":"string"},"value":{}},"required":["op","path"]}},"patch":{"description":"Legacy string replacement OR {find, replace} JSON object. Prefer separate operation/context/content params for new code.","anyOf":[{"type":"string"},{"type":"object","properties":{"find":{"type":"string"},"replace":{"type":"string"}},"required":["find","replace"]}]},"context":{"type":"string"},"operation":{"type":"string","enum":["Replace","Insert_After","Append"]},"expectedCount":{"type":"integer"},"dryRun":{"type":"boolean"},"verifyRollback":{"type":"boolean"},"targets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"content":{"type":"string"}},"required":["name","content"]}},"type":{"type":"string"},"return_post_state":{"type":"boolean","description":"Set false to omit post_state.diff from the response (default true)."},"verbose":{"type":"boolean","description":"When true, adds slices (±15 lines around each hunk) to post_state (default false)."},"validate":{"type":"string","enum":["strict","best-effort","only"],"description":"v2.6.6 FR#13. strict (default) aborts on the first op compile error. best-effort applies every op that compiles and reports per-op outcomes under result.opResults[]. only runs ops in-memory and returns diagnostics without persisting."},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}}}},
   {"name":"genexus_inspect","description":"Snapshot of an object: metadata, variables, structure, signature. Raw object shape without source text. For source/code use genexus_read.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"include":{"type":"array","items":{"type":"string","enum":["metadata","variables","signature","structure","parts","controls","events_repertoire","callers"]}},"type":{"type":"string"},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["name"]}},
   {"name":"genexus_analyze","description":"Cross-object semantic analysis: impact, dependencies, complexity, naming, summary. See genexus://kb/tool-help/genexus_analyze for mode selection.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"mode":{"type":"string","enum":["linter","navigation","hierarchy","impact","data_context","ui_context","pattern_metadata","summary"]},"kb":{"type":"string","description":"Target KB. Required when 2+ open."},"waitForIndex":{"type":"boolean","description":"For mode=impact: when true (default) block up to 30s for the index to be Ready; when false return a status envelope immediately if the index is Cold/Reindexing.","default":true}},"required":["name","mode"]}},
   {"name":"genexus_inject_context","description":"Inject SDT structures and Procedure signatures of called objects.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"recursive":{"type":"boolean"},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["name"]}},
-  {"name":"genexus_lifecycle","description":"Build, validate, index, or poll the KB. Long ops are async with operationId. See genexus://kb/tool-help/genexus_lifecycle for actions and target formats.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["build","cancel","rebuild","reorg","validate","validate-kb","sync","index","status","result","snapshots-list","snapshots-restore"]},"target":{"type":"string","description":"Object name(s), taskId, job_id, or op:<operationId>."},"code":{"type":"string"},"limit":{"type":"integer"},"snapshotPath":{"type":"string"},"estimated_seconds":{"type":"integer","description":"Build: <20 forces sync fast-path (one turn); >=20 (default 60) goes async."},"wait_seconds":{"type":"integer","description":"Status: 0-25. >0 long-polls server-side until terminal or timeout."},"compact":{"type":"boolean","description":"Status: when true (default) returns counts + top-10 errors + warning dedup. Set false for legacy full Output/Errors[]."},"force":{"type":"boolean","description":"Index: when true, clears in-memory + on-disk snapshot and runs a full SDK rescan. Use when impact analyze reports indexEdgesMissing or after adding/renaming objects."},"includeCallees":{"type":"string","enum":["none","direct","transitive"],"description":"Build: auto-expand target via call graph so callees compile before callers (fixes CS0246 from missing DLLs). Default transitive."},"buildPlanCap":{"type":"integer","description":"Build: max expanded nodes before BuildPlanTooLarge (default 200)."},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["action"]}},
+  {"name":"genexus_lifecycle","description":"Build, validate, index, or poll the KB. Long ops are async with operationId. See genexus://kb/tool-help/genexus_lifecycle for actions and target formats.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["build","cancel","rebuild","reorg","validate","validate-kb","sync","index","status","result","snapshots-list","snapshots-restore"]},"target":{"type":"string","description":"Object name(s), taskId, job_id, or op:<operationId>. For build/rebuild, accepts a CSV of objects (comma or semicolon, e.g. 'Foo,Bar,Baz') — compiles only those plus their callees per includeCallees. Use this to act on `suggested_retry.target` from a failed build response."},"code":{"type":"string"},"limit":{"type":"integer"},"snapshotPath":{"type":"string"},"estimated_seconds":{"type":"integer","description":"Build: <20 forces sync fast-path (one turn); >=20 (default 60) goes async."},"wait_seconds":{"type":"integer","description":"Status: 0-25. >0 long-polls server-side until terminal or timeout."},"wait":{"type":"integer","description":"Status taskId: 0-300. Event-driven block until baseline (phase/counts/done) changes."},"since":{"type":"string","description":"Status: prior _meta.snapshot for chained waits."},"compact":{"type":"boolean","description":"Status: when true (default) returns counts + top-10 errors + warning dedup. Set false for legacy full Output/Errors[]."},"force":{"type":"boolean","description":"Index: when true, clears in-memory + on-disk snapshot and runs a full SDK rescan. Use when impact analyze reports indexEdgesMissing or after adding/renaming objects."},"includeCallees":{"type":"string","enum":["none","direct","transitive"],"description":"Build: auto-expand target via call graph so callees compile before callers (fixes CS0246 from missing DLLs). Default transitive."},"buildPlanCap":{"type":"integer","description":"Build: max expanded nodes before BuildPlanTooLarge (default 200)."},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["action"]}},
   {"name":"genexus_forge","description":"Generate new code or structures from templates or translations.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["scaffold","translate","sample"]},"type":{"type":"string"},"name":{"type":"string"},"content":{"type":"string"},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["action"]}},
   {"name":"genexus_test","description":"Execute native GeneXus tests (GXtest).","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["name"]}},
   {"name":"genexus_create_object","description":"Create any IDE-creatable GeneXus object (Transaction, Procedure, WebPanel, SDPanel, SDT, DataProvider, Domain, Dashboard, WorkflowDiagram, etc.). Domain takes dataType+length or enumValues. NOT for WorkWithPlus/WWP — that is a pattern applied via genexus_apply_pattern (see recipe 'wwp_on_transaction' or 'wwp_on_webpanel'). NOT for popups with editable inputs — use genexus_create_popup. See genexus://kb/tool-help/genexus_create_object.","inputSchema":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"dataType":{"type":"string"},"length":{"type":"integer"},"decimals":{"type":"integer"},"signed":{"type":"boolean"},"description":{"type":"string"},"basedOn":{"type":"string"},"enumValues":{"type":"array","items":{"type":"object"}},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["type","name"]}},
   {"name":"genexus_logs","description":"Read worker_debug.log tail for error diagnosis or correlation.","inputSchema":{"type":"object","properties":{"lines":{"type":"integer"},"filterCorrelation":{"type":"string"},"grep":{"type":"string"}}}},
   {"name":"genexus_sdk_probe","description":"Scan loaded GeneXus SDK assemblies and dump a structured map of every public type, method, property to docs/sdk-probe/. Use when investigating new SDK surface or hunting for an entry point. Outputs raw.json + INDEX.md + generators.md.","inputSchema":{"type":"object","properties":{"outputDir":{"type":"string","description":"Optional absolute path. Defaults to <repo>/docs/sdk-probe/ or %TEMP%/gxmcp_sdk_probe/."}}}},
-  {"name":"genexus_worker_reload","description":"Hot-reload worker: copy new binaries and respawn.","inputSchema":{"type":"object","properties":{"sourceDir":{"type":"string","description":"Absolute path to freshly built bin/Release."}},"required":["sourceDir"]}},
+  {"name":"genexus_worker_reload","description":"Reload worker. mode=soft (default): drain + clean exit, gateway respawns same binary, JobRegistry preserved. mode=hard: copy sourceDir over publish/worker and respawn (iterating on worker code).","inputSchema":{"type":"object","properties":{"mode":{"type":"string","enum":["soft","hard"]},"sourceDir":{"type":"string","description":"Required for mode=hard."},"drainTimeoutMs":{"type":"integer","description":"Soft only; default 30000."}}}},
   {"name":"genexus_delete_object","description":"Delete an object from the KB. Irreversible — confirm=true required.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"confirm":{"type":"boolean"},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["name","confirm"]}},
   {"name":"genexus_export_object","description":"Export a GeneXus object part to a text file on disk.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"outputPath":{"type":"string"},"part":{"type":"string"},"type":{"type":"string"},"overwrite":{"type":"boolean"},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["name","outputPath"]}},
   {"name":"genexus_import_object","description":"Import a text file from disk into a GeneXus object part.","inputSchema":{"type":"object","properties":{"name":{"type":"string"},"inputPath":{"type":"string"},"part":{"type":"string"},"type":{"type":"string"},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["name","inputPath"]}},
@@ -30,14 +30,14 @@
   {"name":"genexus_format","description":"Format a GeneXus code snippet using worker rules.","inputSchema":{"type":"object","properties":{"code":{"type":"string"},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["code"]}},
   {"name":"genexus_properties","description":"Read or update GeneXus object properties. Note: Description is the title-bar text shown when a WebPanel/Popup is opened via .Popup().","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["get","set"]},"name":{"type":"string"},"control":{"type":"string","description":"Optional. Layout control name (e.g. BtnConfirmar), variable name with & prefix (e.g. &Alu2RegProf), or attribute name."},"propertyName":{"type":"string"},"value":{"type":"string"},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["action","name"]}},
   {"name":"genexus_asset","description":"Find, read, or write binary assets inside the active KB.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["find","read","write"]},"path":{"type":"string"},"includeContent":{"type":"boolean"},"maxBytes":{"type":"integer"},"pattern":{"type":"string"},"relativeRoot":{"type":"string"},"limit":{"type":"integer"},"contentBase64":{"type":"string"},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["action"]}},
-  {"name":"genexus_history","description":"List, read, save, or restore GeneXus object history snapshots.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["list","get_source","save","restore"]},"name":{"type":"string"},"versionId":{"type":"integer"},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["action","name"]}},
+  {"name":"genexus_history","description":"List, read, save, or restore GeneXus object history snapshots. v2.6.6 (FR#28): restore now supports IDE 'Discard changes' parity — pass discard=true with part=<part> to restore the most recent EditSnapshotStore baseline. Returns {status:NoSnapshot,hint:...} when no baseline exists.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["list","get_source","save","restore"]},"name":{"type":"string"},"versionId":{"type":"integer"},"part":{"type":"string","description":"Part name for snapshot-based restore (default 'Source')."},"snapshot":{"type":"string","description":"Snapshot token (timestamp or 'latest') for explicit edit-snapshot restore."},"discard":{"type":"boolean","default":false,"description":"action=restore only. When true and no snapshot is supplied, restore the most recent EditSnapshotStore baseline for (name,part) — IDE History|Restore (Discard changes) parity."},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["action","name"]}},
   {"name":"genexus_structure","description":"Read or update visual and logical structure of GeneXus objects.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["get_visual","update_visual","get_indexes","get_logic"]},"name":{"type":"string"},"payload":{"type":"object","description":"Update payload for update_visual."},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["action","name"]}},
   {"name":"genexus_layout","description":"Native SDK layout/WebForm operations: get_tree, set_property, find_controls, inspect_surface, scan_mutators.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["get_tree","set_property","find_controls","set_properties","inspect_surface","get_preview","scan_mutators","rename_printblock","add_printblock"]},"name":{"type":"string"},"target":{"type":"string","description":"Object name alias for backward compatibility."},"control":{"type":"string"},"propertyName":{"type":"string"},"value":{"type":"string"},"query":{"type":"string"},"changes":{"type":"array","items":{"type":"object","properties":{"control":{"type":"string"},"propertyName":{"type":"string"},"value":{"type":"string"}},"required":["control","propertyName","value"]}},"limit":{"type":"integer"},"currentName":{"type":"string"},"newName":{"type":"string"},"printBlockName":{"type":"string"},"height":{"type":"integer"},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["action"]}},
   {"name":"genexus_doc","description":"Generate structured docs (wiki, sequence diagrams, health reports) for an object/domain. Not for programmatic analysis (see genexus_analyze) or source (see genexus_read).","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["wiki","visualize","health"]},"target":{"type":"string","description":"Object or domain name."}},"required":["action"]}},
   {"name":"genexus_search_source","description":"Regex/semantic search across Procedure/DataProvider/WebPanel/Transaction source.","inputSchema":{"type":"object","properties":{"callee":{"type":"string","description":"Method/function name (qualified or unqualified)."},"argMatches":{"type":"object","description":"Positional arg index to expected literal text."},"pattern":{"type":"string"},"typeFilter":{"type":"string"},"scope":{"type":"array","items":{"type":"string"}},"maxResults":{"type":"integer"},"caseSensitive":{"type":"boolean"},"includeComments":{"type":"boolean"},"inline_read_top":{"type":"integer","description":"0-3. Inline reads of top N distinct objects in response."},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}}}},
   {"name":"genexus_kb","description":"Manage open KBs: list (with PID/RSS/idle), open (acquire Worker), close (release), set_default (persist alias to config.json).","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["list","open","close","set_default"]},"alias":{"type":"string","description":"KB alias (for open/close). For open, auto-generated from path basename if omitted."},"path":{"type":"string","description":"Absolute path to the KB (required for action=open if alias is not declared in config)."}},"required":["action"]}},
   {"name":"genexus_sql","description":"SQL for a Transaction/Table (DDL) or a procedure For Each navigation.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["ddl","navigation"]},"name":{"type":"string"},"includeSubordinated":{"type":"boolean","description":"action=ddl only."},"levelNumber":{"type":"integer","description":"action=navigation only."},"type":{"type":"string"},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["action","name"]}},
-  {"name":"genexus_preview","description":"Render preview of a WebPanel via headless Chrome (chrome-devtools-axi). Opens the launcher page, fills required parms, navigates to the target, captures HTML/a11y/screenshot, optionally diffs vs baseline. Returns status + captures.","inputSchema":{"type":"object","properties":{"name":{"type":"string","description":"Target WebPanel name."},"parms":{"type":"object","description":"Per-call launcher parms (merged over config defaults and objectParms)."},"launcher":{"type":"string","description":"Launcher page (default 'auto' = config.launcher)."},"buildFirst":{"type":"boolean","default":false,"description":"If true, dispatch a build before opening the browser."},"waitMs":{"type":"integer","default":3000,"description":"Milliseconds to wait after navigation before capture."},"capture":{"type":"array","items":{"type":"string","enum":["html","a11y","screenshot","console"]},"description":"Capture set (default ['html','a11y'])."},"diffBaseline":{"type":"boolean","default":false,"description":"Compute structural diff vs stored a11y baseline."},"updateBaseline":{"type":"boolean","default":false,"description":"Persist current a11y snapshot as the new baseline."},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}},"required":["name"]}},
+  {"name":"genexus_preview","description":"Render preview of a WebPanel via headless Chrome (chrome-devtools-axi). Opens the launcher page, fills required parms, navigates to the target, captures HTML/a11y/screenshot, optionally diffs vs baseline. Returns status + captures.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["render","run"],"default":"render","description":"v2.6.6 Stream H (FR#25): 'run' resolves the KB launcher object automatically when name is omitted (IDE F5 parity). 'render' (default) requires explicit name."},"name":{"type":"string","description":"Target WebPanel name. Optional when action=run."},"parms":{"type":"object","description":"Per-call launcher parms (merged over config defaults and objectParms)."},"launcher":{"type":"string","description":"Launcher page (default 'auto' = config.launcher)."},"buildFirst":{"type":"boolean","default":false,"description":"If true, dispatch a build before opening the browser."},"waitMs":{"type":"integer","default":3000,"description":"Milliseconds to wait after navigation before capture."},"capture":{"type":"array","items":{"type":"string","enum":["html","a11y","screenshot","console"]},"description":"Capture set (default ['html','a11y'])."},"diffBaseline":{"type":"boolean","default":false,"description":"Compute structural diff vs stored a11y baseline."},"updateBaseline":{"type":"boolean","default":false,"description":"Persist current a11y snapshot as the new baseline."},"fill":{"type":"object","description":"GX-aware form fills (logical attr names → values)."},"click":{"type":"string","description":"GX-aware click target (button/link logical name)."},"auth":{"type":"object","description":"GAM auth override (mode/user/pass)."},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}}}},
   {"name":"genexus_apply_pattern","description":"Apply a GeneXus pattern (e.g. WorkWithPlus) to a parent object. Equivalent to IDE 'Right-click → Apply Pattern'. ALWAYS run genexus_inspect first to confirm parentType — Transaction (family-gen, no template) vs WebPanel/SDPanel (direct-attach, pass settings.template). Other types are rejected. See recipe 'wwp_on_transaction' or 'wwp_on_webpanel' via genexus_recipe.","inputSchema":{"type":"object","required":["name","pattern"],"properties":{"name":{"type":"string","description":"Target KBObject name (Transaction, WebPanel, etc.)"},"pattern":{"type":"string","description":"Pattern key ('WorkWithPlus') or GUID"},"settings":{"type":"object","description":"Optional pattern-instance settings (deeply nested config tree from the pattern's settings dialog)"},"reapply":{"type":"boolean","default":false,"description":"Re-run on existing instance instead of first-time apply"},"validate":{"type":"boolean","default":false,"description":"After apply, build the generated host to verify it compiles cleanly. Response gains a `validation` block: {status: ok|failed|timeout, errorCount, warningCount, errors[], warnings[], durationMs}. Adds 60-180s wall time but catches binding/wiring errors the LLM would only see by opening the IDE."},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}}}},
   {"name":"genexus_edit_and_build","description":"Edit an object then rebuild its callers in one call. Returns edit diff + impact + build operationId. See genexus://kb/tool-help/genexus_edit_and_build for examples.","inputSchema":{"type":"object","properties":{"name":{"type":"string","description":"Target object name."},"part":{"type":"string","description":"Part to edit (Source, Rules, ...)."},"content":{"type":"string","description":"New content or unified diff."},"mode":{"type":"string","enum":["full","patch"],"default":"patch"},"type":{"type":"string","description":"Disambiguates when name matches multiple objects."},"dryRun":{"type":"boolean","default":false},"buildIncludeCallees":{"type":"string","enum":["none","direct","transitive"],"default":"direct"},"buildPlanCap":{"type":"integer","default":200},"waitForIndex":{"type":"boolean","default":true},"waitTimeoutMs":{"type":"integer","default":30000}},"required":["name","part","content"]}},
   {"name":"genexus_create_popup","description":"W3: create a popup WebPanel with a Form type=\"layout\" body so radio/combo bindings render editable. Spec carries title, description, inputs (radio|combo|text with options), buttons, inParms, outParms.","inputSchema":{"type":"object","required":["name","spec"],"properties":{"name":{"type":"string","description":"WebPanel name. Created if missing; updated if exists."},"spec":{"type":"object","description":"Popup spec.","properties":{"title":{"type":"string"},"description":{"type":"string"},"inputs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["radio","combo","text"]},"varName":{"type":"string"},"label":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"}}}},"showWhen":{"type":"string","description":"e.g. \"RespRegProf == 'S'\"; emits Refresh event toggling group visibility."}},"required":["type","varName"]}},"buttons":{"type":"array","items":{"type":"object","properties":{"caption":{"type":"string"},"event":{"type":"string"}}}},"inParms":{"type":"array","items":{"type":"string"},"description":"e.g. [\"AluAnoCad:Numeric(2)\"]"},"outParms":{"type":"array","items":{"type":"string"}}}},"kb":{"type":"string","description":"Target KB. Required when 2+ open."}}}}