vibe-gate-mcp 0.1.5 → 0.1.7

package/.env.example

@@ -3,9 +3,13 @@
 # NEVER commit real keys. Pick one API provider with a key OR a signed-in local CLI.
 # =============================================================================
 
-# --- Required: Critic provider ---
+# --- Critic provider (optional) ---
+# When unset, Vibe-Gate selects the first installed CLI in this order:
+# codex-cli -> claude-code -> cursor-agent -> opencode-cli; provider/model CRITIC_MODEL prefers opencode-cli.
+# If no local CLI is found, OpenAI remains the default and requires OPENAI_API_KEY.
+# To choose an API provider or override auto-detection, set CRITIC_PROVIDER explicitly.
 # One of: openai | anthropic | google | minimax | opencode | codex-cli | claude-code | cursor-agent | opencode-cli
-CRITIC_PROVIDER=openai
+# CRITIC_PROVIDER=openai
 
 # --- API key for direct API providers (uncomment ONE block when needed) ---
 
@@ -35,7 +39,7 @@ OPENAI_API_KEY=
 # Optional executable paths when the MCP host PATH cannot find the CLI
 # CODEX_CLI_PATH=/absolute/path/to/codex
 # CLAUDE_CODE_CLI_PATH=/absolute/path/to/claude
-# CURSOR_AGENT_CLI_PATH=/absolute/path/to/cursor-agent
+# CURSOR_AGENT_CLI_PATH=/absolute/path/to/agent
 # OPENCODE_CLI_PATH=/absolute/path/to/opencode
 # CRITIC_CLI_TIMEOUT_MS=120000
 

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.7] - 2026-09-24
+
+### Fixed
+
+- Detect and launch Windows `.cmd` and `.bat` CLI shims through `cmd.exe` while keeping native executables on the direct spawn path.
+
+### Tests
+
+- Cover Windows `PATHEXT` shim resolution and safely quoted batch-shim invocation.
+
+## [0.1.6] - 2026-09-24
+
+### Added
+
+- Auto-detect an installed local CLI when `CRITIC_PROVIDER` is unset and report the selected CLI in the first review response.
+
+### Fixed
+
+- Use Cursor's current `agent` command by default and fall back to the legacy `cursor-agent` command when it is unavailable.
+
+### Tests
+
+- Cover local CLI auto-detection and Cursor Agent's legacy executable fallback.
+
 ## [0.1.5] - 2026-09-23
 
 ### Fixed

package/README.md

@@ -6,7 +6,7 @@ An **Adversarial Quality Gate** for AI-assisted IDEs: the IDE agent and a Critic
 
 ### 1. Choose a Critic provider
 
-Use a direct API provider with its key, or use a local CLI that is already installed and signed in. Local CLI providers do not need a separate provider API key.
+Use a direct API provider with its key, or use a local CLI that is already installed and signed in. Local CLI providers do not need a separate provider API key. If `CRITIC_PROVIDER` is omitted, Vibe-Gate selects the first installed local CLI in this order: Codex, Claude Code, Cursor Agent, then OpenCode CLI. OpenCode CLI moves to the front when `CRITIC_MODEL` is in `provider/model` form. The first review response includes a notice naming the selected CLI. If none is found, OpenAI remains the default and requires `OPENAI_API_KEY`. Set `CRITIC_PROVIDER` to choose explicitly.
 
 Copy from the package’s [`.env.example`](.env.example):
 
@@ -40,9 +40,11 @@ OPENAI_API_KEY=YOUR_OPENAI_API_KEY
 | OpenCode      | `opencode`        | `OPENCODE_API_KEY` (+ optional `OPENCODE_PLAN`) |
 | Codex CLI     | `codex-cli`       | Existing `codex login` session                  |
 | Claude Code   | `claude-code`     | Existing Claude Code account session            |
-| Cursor Agent  | `cursor-agent`    | Existing `cursor-agent login` session           |
+| Cursor Agent  | `cursor-agent`    | Existing `agent login` session                  |
 | OpenCode CLI  | `opencode-cli`    | Saved `opencode auth login` credentials + model |
 
+For Cursor Agent, Vibe-Gate runs `agent` first and falls back to the legacy `cursor-agent` executable if the primary command is unavailable.
+
 `opencode` is still the separate Zen/Go HTTP provider and needs `OPENCODE_API_KEY`. `opencode-cli` runs the local CLI and requires a `provider/model` value in `CRITIC_MODEL`; see the CLI guide for details.
 
 `CRITIC_MODEL` is passed to the selected provider or CLI without a Vibe-Gate model allowlist; the provider must support that model ID. The OpenAI API provider uses the Responses API. See [provider configuration](docs/USAGE.md#configuration--providers).

package/dist/index.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { dirname, isAbsolute, join, normalize, relative, resolve } from "node:path";
+import { basename, delimiter, dirname, extname, isAbsolute, join, normalize, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { config } from "dotenv";
-import { existsSync, readFileSync } from "node:fs";
+import { accessSync, constants, existsSync, readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -111,9 +111,11 @@ const PROVIDERS = {
 const CLI_DEFAULT_COMMANDS = {
 	[PROVIDERS.CODEX_CLI]: "codex",
 	[PROVIDERS.CLAUDE_CODE]: "claude",
-	[PROVIDERS.CURSOR_AGENT]: "cursor-agent",
+	[PROVIDERS.CURSOR_AGENT]: "agent",
 	[PROVIDERS.OPENCODE_CLI]: "opencode"
 };
+/** Previous Cursor CLI executable name retained for older installations. */
+const CURSOR_AGENT_LEGACY_COMMAND = "cursor-agent";
 /** Environment keys removed from local CLI processes unless a provider explicitly needs one. */
 const CLI_STRIPPED_ENV_KEYS = [
 	ENV_KEYS.OPENAI_API_KEY,
@@ -329,7 +331,7 @@ const CONFLICT_LOOP = {
 };
 /** Error messages (SSoT) */
 const ERROR_MESSAGES = {
-	NO_LLM_PROVIDER: "No LLM provider available. Set CRITIC_PROVIDER and either the required API key or an installed, authenticated local CLI.",
+	NO_LLM_PROVIDER: "No LLM provider available. Check CRITIC_PROVIDER and its required API key, or install and sign in to a supported local CLI.",
 	STARTUP_FAILED: "Vibe-Gate failed to start:"
 };
 /** Debug log prefix (stderr) */
@@ -603,7 +605,7 @@ const personaSchema = z.enum([
 	PERSONAS.CLEAN_CODE_MONK
 ]);
 const configSchema = z.object({
-	criticProvider: providerSchema.default(PROVIDERS.OPENAI),
+	criticProvider: providerSchema.optional(),
 	criticModel: z.string().min(1).optional(),
 	criticPersona: personaSchema.default(PERSONAS.CLEAN_CODE_MONK),
 	openaiApiKey: z.string().optional(),
@@ -631,7 +633,7 @@ function getEnv(key) {
 }
 function loadConfig() {
 	const raw = {
-		criticProvider: getEnv(ENV_KEYS.CRITIC_PROVIDER) ?? PROVIDERS.OPENAI,
+		criticProvider: getEnv(ENV_KEYS.CRITIC_PROVIDER)?.trim() || void 0,
 		criticModel: getEnv(ENV_KEYS.CRITIC_MODEL),
 		criticPersona: getEnv(ENV_KEYS.CRITIC_PERSONA) ?? PERSONAS.CLEAN_CODE_MONK,
 		openaiApiKey: getEnv(ENV_KEYS.OPENAI_API_KEY),
@@ -648,9 +650,9 @@ function loadConfig() {
 	};
 	return configSchema.parse(raw);
 }
-function getEffectiveModel(config) {
+function getEffectiveModel(config, providerId) {
 	if (config.criticModel) return config.criticModel;
-	return DEFAULT_MODELS[config.criticProvider];
+	return DEFAULT_MODELS[providerId ?? config.criticProvider ?? PROVIDERS.OPENAI];
 }
 //#endregion
 //#region src/utils/debug.ts
@@ -2475,6 +2477,42 @@ function createOpenCodeProvider(apiKey, model, plan = OPENCODE_PLANS.ZEN) {
 	} };
 }
 //#endregion
+//#region src/llm/cli-command.ts
+/** Platform-specific executable lookup and process invocation for local CLIs. */
+const WINDOWS_EXECUTABLE_EXTENSIONS = /* @__PURE__ */ new Set([
+	".COM",
+	".EXE",
+	".BAT",
+	".CMD"
+]);
+const WINDOWS_BATCH_EXTENSIONS = /* @__PURE__ */ new Set([".BAT", ".CMD"]);
+function executableExtensions(command, isWindows, pathExt = process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD") {
+	if (!isWindows || extname(command)) return [""];
+	return pathExt.split(";").filter((extension) => WINDOWS_EXECUTABLE_EXTENSIONS.has(extension.toUpperCase()));
+}
+function quoteCmdToken(value) {
+	if (/[%"\0\r\n]/.test(value)) throw new Error("Windows CLI arguments cannot contain percent signs, quotes, or line breaks.");
+	return `"${value}"`;
+}
+function buildCliSpawnTarget(command, args, platform = process.platform, comspec = process.env.ComSpec ?? process.env.COMSPEC ?? "cmd.exe") {
+	const extension = extname(command).toUpperCase();
+	if (platform !== "win32" || !WINDOWS_BATCH_EXTENSIONS.has(extension)) return {
+		command,
+		args
+	};
+	return {
+		command: comspec,
+		args: [
+			"/d",
+			"/s",
+			"/v:off",
+			"/c",
+			`"${[command, ...args].map(quoteCmdToken).join(" ")}"`
+		],
+		windowsVerbatimArguments: true
+	};
+}
+//#endregion
 //#region src/llm/cli.ts
 /**
 * Local authenticated CLI providers. These CLIs receive the complete review
@@ -2483,9 +2521,11 @@ function createOpenCodeProvider(apiKey, model, plan = OPENCODE_PLANS.ZEN) {
 */
 var CliExecutionError = class extends Error {
 	stdout;
-	constructor(message, stdout) {
+	code;
+	constructor(message, stdout, code) {
 		super(message);
 		this.stdout = stdout;
+		this.code = code;
 		this.name = "CliExecutionError";
 	}
 };
@@ -2516,11 +2556,13 @@ function sanitizeStderr(stderr) {
 }
 function runCli({ command, args, cwd, input, timeoutMs, label, env, keepCredentialEnvKeys }) {
 	return new Promise((resolve, reject) => {
-		const child = spawn(command, args, {
+		const target = buildCliSpawnTarget(command, args);
+		const child = spawn(target.command, target.args, {
 			cwd,
 			env: createChildEnv(env, keepCredentialEnvKeys),
 			shell: false,
 			windowsHide: true,
+			...target.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {},
 			stdio: [
 				"pipe",
 				"pipe",
@@ -2558,8 +2600,9 @@ function runCli({ command, args, cwd, input, timeoutMs, label, env, keepCredenti
 			stderr = keepTail(stderr, chunk, CLI_PROVIDER_MAX_STDERR_BYTES);
 		});
 		child.on("error", (error) => {
-			const detail = error.code === "ENOENT" ? `Install ${label} or set its executable path in the MCP environment.` : error.message;
-			finish(new CliExecutionError(`${label} CLI could not be started. ${detail}`, stdout.toString("utf8")));
+			const errorCode = error.code;
+			const detail = errorCode === "ENOENT" ? `Install ${label} or set its executable path in the MCP environment.` : error.message;
+			finish(new CliExecutionError(`${label} CLI could not be started. ${detail}`, stdout.toString("utf8"), errorCode));
 		});
 		child.on("close", (code, signal) => {
 			if (failure) {
@@ -2584,6 +2627,18 @@ function runCli({ command, args, cwd, input, timeoutMs, label, env, keepCredenti
 		child.stdin.end(input);
 	});
 }
+async function runCliWithFallback(options, fallbackCommands = []) {
+	const commands = [options.command, ...fallbackCommands];
+	for (const [index, command] of commands.entries()) try {
+		return await runCli({
+			...options,
+			command
+		});
+	} catch (error) {
+		if (!(error instanceof CliExecutionError && error.code === "ENOENT" && index < commands.length - 1)) throw error;
+	}
+	throw new Error(`${options.label} CLI could not be started.`);
+}
 function parseCodexOutput(stdout) {
 	const messages = [];
 	for (const line of stdout.split(/\r?\n/)) {
@@ -2844,14 +2899,14 @@ async function completeCursorAgent(options, cwd, input) {
 		"json",
 		...modelArgs(options.model, "--model")
 	];
-	return { content: parseJsonResult(await runCli({
+	return { content: parseJsonResult(await runCliWithFallback({
 		command: options.command,
 		args,
 		cwd,
 		input,
 		timeoutMs: options.timeoutMs,
 		label: options.label
-	}), options.label) };
+	}, options.fallbackCommands), options.label) };
 }
 async function deleteOpenCodeSession(options, cwd, env, sessionId) {
 	await runCli({
@@ -2965,13 +3020,14 @@ function createClaudeCodeProvider(command, model, timeoutMs) {
 		timeoutMs
 	});
 }
-function createCursorAgentProvider(command, model, timeoutMs) {
+function createCursorAgentProvider(command, model, timeoutMs, allowLegacyFallback = command === CLI_DEFAULT_COMMANDS[PROVIDERS.CURSOR_AGENT]) {
 	return createCliProvider({
 		id: PROVIDERS.CURSOR_AGENT,
 		label: "Cursor Agent",
 		command,
 		model,
-		timeoutMs
+		timeoutMs,
+		fallbackCommands: allowLegacyFallback ? [CURSOR_AGENT_LEGACY_COMMAND] : []
 	});
 }
 function createOpenCodeCliProvider(command, model, timeoutMs) {
@@ -2985,40 +3041,119 @@ function createOpenCodeCliProvider(command, model, timeoutMs) {
 }
 //#endregion
 //#region src/llm/index.ts
+/**
+* LLM provider factory and local CLI auto-detection.
+*/
+const AUTO_DETECT_CLI_ORDER = [
+	PROVIDERS.CODEX_CLI,
+	PROVIDERS.CLAUDE_CODE,
+	PROVIDERS.CURSOR_AGENT,
+	PROVIDERS.OPENCODE_CLI
+];
+function configuredCliPath(id, config) {
+	switch (id) {
+		case PROVIDERS.CODEX_CLI: return config.codexCliPath;
+		case PROVIDERS.CLAUDE_CODE: return config.claudeCodeCliPath;
+		case PROVIDERS.CURSOR_AGENT: return config.cursorAgentCliPath;
+		case PROVIDERS.OPENCODE_CLI: return config.opencodeCliPath;
+	}
+}
+function commandCandidates(id, config) {
+	const configuredPath = configuredCliPath(id, config);
+	if (configuredPath) return [configuredPath];
+	if (id === PROVIDERS.CURSOR_AGENT) return [CLI_DEFAULT_COMMANDS[id], CURSOR_AGENT_LEGACY_COMMAND];
+	return [CLI_DEFAULT_COMMANDS[id]];
+}
+function commandSearchBases(command) {
+	if (isAbsolute(command) || command.includes("/") || command.includes("\\")) return [resolve(command)];
+	return (process.env.PATH ?? process.env.Path ?? "").split(delimiter).filter(Boolean).map((dir) => join(dir, command));
+}
+function canExecute(path, isWindows) {
+	try {
+		accessSync(path, isWindows ? constants.F_OK : constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function findExecutable(command) {
+	const isWindows = process.platform === "win32";
+	const bases = commandSearchBases(command);
+	const extensions = executableExtensions(command, isWindows);
+	for (const base of bases) for (const extension of extensions) {
+		const candidate = extension ? `${base}${extension}` : base;
+		if (canExecute(candidate, isWindows)) return candidate;
+	}
+}
+function hasOpenCodeModel(config) {
+	const model = config.criticModel;
+	const separator = model?.indexOf("/") ?? -1;
+	return Boolean(model && separator > 0 && separator < model.length - 1);
+}
+function detectLocalCli(config) {
+	const configuredOrder = AUTO_DETECT_CLI_ORDER.filter((id) => configuredCliPath(id, config));
+	const defaultOrder = AUTO_DETECT_CLI_ORDER.filter((id) => !configuredCliPath(id, config));
+	const openCodeHasExplicitModel = hasOpenCodeModel(config) && defaultOrder.includes(PROVIDERS.OPENCODE_CLI);
+	const preferredOrder = [
+		...configuredOrder,
+		...openCodeHasExplicitModel ? [PROVIDERS.OPENCODE_CLI] : [],
+		...defaultOrder.filter((id) => !openCodeHasExplicitModel || id !== PROVIDERS.OPENCODE_CLI)
+	];
+	for (const id of preferredOrder) {
+		if (id === PROVIDERS.OPENCODE_CLI && !hasOpenCodeModel(config)) continue;
+		for (const candidate of commandCandidates(id, config)) {
+			const command = findExecutable(candidate);
+			if (command) return {
+				id,
+				command
+			};
+		}
+	}
+}
+const providerLabels = {
+	[PROVIDERS.OPENAI]: "OpenAI",
+	[PROVIDERS.ANTHROPIC]: "Anthropic",
+	[PROVIDERS.GOOGLE]: "Google Gemini",
+	[PROVIDERS.MINIMAX]: "MiniMax",
+	[PROVIDERS.OPENCODE]: "OpenCode",
+	[PROVIDERS.CODEX_CLI]: "Codex CLI",
+	[PROVIDERS.CLAUDE_CODE]: "Claude Code",
+	[PROVIDERS.CURSOR_AGENT]: "Cursor Agent",
+	[PROVIDERS.OPENCODE_CLI]: "OpenCode CLI"
+};
+function isCliProvider(id) {
+	return AUTO_DETECT_CLI_ORDER.includes(id);
+}
+function getProviderLabel(id) {
+	return providerLabels[id];
+}
 function createLLMProvider(config) {
-	const model = getEffectiveModel(config);
-	const factory = {
-		[PROVIDERS.OPENAI]: () => {
-			const key = config.openaiApiKey;
-			if (!key) return null;
-			return createOpenAIProvider(key, model);
-		},
-		[PROVIDERS.ANTHROPIC]: () => {
-			const key = config.anthropicApiKey;
-			if (!key) return null;
-			return createAnthropicProvider(key, model);
-		},
-		[PROVIDERS.GOOGLE]: () => {
-			const key = config.googleApiKey;
-			if (!key) return null;
-			return createGoogleProvider(key, model);
-		},
-		[PROVIDERS.MINIMAX]: () => {
-			const key = config.minimaxApiKey;
-			if (!key) return null;
-			return createMiniMaxProvider(key, model);
-		},
-		[PROVIDERS.OPENCODE]: () => {
-			const key = config.opencodeApiKey;
-			if (!key) return null;
-			return createOpenCodeProvider(key, model, config.opencodePlan);
-		},
-		[PROVIDERS.CODEX_CLI]: () => createCodexCliProvider(config.codexCliPath ?? CLI_DEFAULT_COMMANDS[PROVIDERS.CODEX_CLI], model, config.criticCliTimeoutMs),
-		[PROVIDERS.CLAUDE_CODE]: () => createClaudeCodeProvider(config.claudeCodeCliPath ?? CLI_DEFAULT_COMMANDS[PROVIDERS.CLAUDE_CODE], model, config.criticCliTimeoutMs),
-		[PROVIDERS.CURSOR_AGENT]: () => createCursorAgentProvider(config.cursorAgentCliPath ?? CLI_DEFAULT_COMMANDS[PROVIDERS.CURSOR_AGENT], model, config.criticCliTimeoutMs),
-		[PROVIDERS.OPENCODE_CLI]: () => createOpenCodeCliProvider(config.opencodeCliPath ?? CLI_DEFAULT_COMMANDS[PROVIDERS.OPENCODE_CLI], model, config.criticCliTimeoutMs)
-	}[config.criticProvider];
-	return factory ? factory() : null;
+	const detected = config.criticProvider ? void 0 : detectLocalCli(config);
+	const providerId = config.criticProvider ?? detected?.id ?? PROVIDERS.OPENAI;
+	const autoDetected = !config.criticProvider && detected !== void 0;
+	const model = getEffectiveModel(config, providerId);
+	const command = (id, configuredPath) => {
+		if (detected && id === detected.id) return detected.command;
+		return configuredPath ?? CLI_DEFAULT_COMMANDS[id];
+	};
+	const provider = {
+		[PROVIDERS.OPENAI]: () => config.openaiApiKey ? createOpenAIProvider(config.openaiApiKey, model) : null,
+		[PROVIDERS.ANTHROPIC]: () => config.anthropicApiKey ? createAnthropicProvider(config.anthropicApiKey, model) : null,
+		[PROVIDERS.GOOGLE]: () => config.googleApiKey ? createGoogleProvider(config.googleApiKey, model) : null,
+		[PROVIDERS.MINIMAX]: () => config.minimaxApiKey ? createMiniMaxProvider(config.minimaxApiKey, model) : null,
+		[PROVIDERS.OPENCODE]: () => config.opencodeApiKey ? createOpenCodeProvider(config.opencodeApiKey, model, config.opencodePlan) : null,
+		[PROVIDERS.CODEX_CLI]: () => createCodexCliProvider(command(PROVIDERS.CODEX_CLI, config.codexCliPath), model, config.criticCliTimeoutMs),
+		[PROVIDERS.CLAUDE_CODE]: () => createClaudeCodeProvider(command(PROVIDERS.CLAUDE_CODE, config.claudeCodeCliPath), model, config.criticCliTimeoutMs),
+		[PROVIDERS.CURSOR_AGENT]: () => createCursorAgentProvider(command(PROVIDERS.CURSOR_AGENT, config.cursorAgentCliPath), model, config.criticCliTimeoutMs, !config.cursorAgentCliPath),
+		[PROVIDERS.OPENCODE_CLI]: () => createOpenCodeCliProvider(command(PROVIDERS.OPENCODE_CLI, config.opencodeCliPath), model, config.criticCliTimeoutMs)
+	}[providerId]();
+	if (!provider) return null;
+	return {
+		...provider,
+		providerId,
+		autoDetected: autoDetected && isCliProvider(providerId),
+		...autoDetected && detected ? { providerCommand: detected.command } : {}
+	};
 }
 //#endregion
 //#region src/summarizer/parse-semantic-diff.ts
@@ -3743,6 +3878,35 @@ async function readRequestedFiles(workspaceRoot, response) {
 * MCP tool: submit_phase_review
 * Implementer reports phase completion; triggers Critic review.
 */
+let autoProviderNoticeSent = false;
+function addAutoProviderNotice(result, provider, providerWasInvoked) {
+	if (autoProviderNoticeSent || !providerWasInvoked || !provider.autoDetected || !provider.providerId || !provider.providerCommand) return result;
+	const command = basename(provider.providerCommand);
+	const notice = `FYI: CRITIC_PROVIDER was not set; Vibe-Gate found ${getProviderLabel(provider.providerId)} (${command}) and is using it for this review.`;
+	const [first, ...rest] = result.content;
+	if (!first) return result;
+	let payload;
+	try {
+		payload = JSON.parse(first.text);
+	} catch {
+		payload = { result: first.text };
+	}
+	const notifiedPayload = typeof payload === "object" && payload !== null && !Array.isArray(payload) ? {
+		...payload,
+		providerNotice: notice
+	} : {
+		result: payload,
+		providerNotice: notice
+	};
+	autoProviderNoticeSent = true;
+	return {
+		...result,
+		content: [{
+			...first,
+			text: JSON.stringify(notifiedPayload)
+		}, ...rest]
+	};
+}
 /**
 * Build a structured history summary from prior rounds.
 *
@@ -3916,7 +4080,7 @@ async function runCriticReview(workspaceRoot, args, session, config, provider) {
 	}
 	const round = args.round ?? 1;
 	const personaPrompt = getPersonaPrompt(config.criticPersona);
-	const model = getEffectiveModel(config);
+	const model = getEffectiveModel(config, provider.providerId);
 	const [status, contextBlockResult, rules, preferencesLog] = await Promise.all([
 		getStatus(workspaceRoot),
 		buildContextBlock(workspaceRoot, args.dependencies ?? [], args.semanticDiff),
@@ -4068,7 +4232,7 @@ const submitPhaseReviewInputSchema = submitPhaseReviewFieldsSchema.superRefine((
 });
 const SUBMIT_PHASE_REVIEW_SCHEMA = {
 	title: "Submit Phase Review",
-	description: "IDE AI (Implementer) submits a phase completion report for Critic review. Prefer files[] (workspace-relative paths; MCP reads disk and builds FILE:...CONTENT:). Alternatives: semanticDiffPath or inline semanticDiff — exactly one. Set updateStatus:false for connectivity probes.",
+	description: "IDE AI (Implementer) submits a phase completion report for Critic review. Prefer files[] (workspace-relative paths; MCP reads disk and builds FILE:...CONTENT:). Alternatives: semanticDiffPath or inline semanticDiff — exactly one. If CRITIC_PROVIDER is unset, Vibe-Gate selects the first installed local CLI and includes providerNotice in the first result. Set updateStatus:false for connectivity probes.",
 	inputSchema: submitPhaseReviewFieldsSchema
 };
 const INSUFFICIENT_REVIEW_GUIDANCE = `
@@ -4245,16 +4409,24 @@ async function handleSubmitPhaseReview(rawArgs) {
 	const session = await readSession(workspaceRoot);
 	const deadlockResult = await checkDeadlockEarly(workspaceRoot, args, session, semanticDiffHints);
 	if (deadlockResult) return deadlockResult;
+	let providerWasInvoked = false;
+	const trackedProvider = {
+		...provider,
+		async complete(messages) {
+			providerWasInvoked = true;
+			return provider.complete(messages);
+		}
+	};
 	try {
-		return processVerdict(await runCriticReview(workspaceRoot, args, session, config, provider), session, workspaceRoot, args, round, semanticDiffHints);
+		return addAutoProviderNotice(await processVerdict(await runCriticReview(workspaceRoot, args, session, config, trackedProvider), session, workspaceRoot, args, round, semanticDiffHints), provider, providerWasInvoked);
 	} catch (err) {
 		const errorMessage = getErrorMessage(err);
 		const errorObj = err;
-		if (errorMessage.includes("401") || errorObj?.status === 401 || errorObj?.statusCode === 401) return { content: [toTextContent({
+		if (!(provider.providerId !== void 0 && isCliProvider(provider.providerId)) && (errorMessage.includes("401") || errorObj?.status === 401 || errorObj?.statusCode === 401)) return addAutoProviderNotice({ content: [toTextContent({
 			error: "Authentication failed (401 Unauthorized). Invalid or missing API keys.",
 			details: "Vibe-Gate reads keys in this order:\n1. Process Environment (MCP config, shell env)\n2. Workspace .env (if VIBE_WORKSPACE_ROOT is set)\n3. Package .env (where vibe-gate-mcp is installed)\n\nPlease ensure your key is correct."
-		})] };
-		return { content: [toTextContent({ error: errorMessage })] };
+		})] }, provider, providerWasInvoked);
+		return addAutoProviderNotice({ content: [toTextContent({ error: errorMessage })] }, provider, providerWasInvoked);
 	}
 }
 //#endregion

package/docs/CLI_PROVIDERS.md

@@ -6,12 +6,16 @@ The CLI is installed locally, but its model request still goes to the provider.
 
 ## Supported CLIs
 
-| `CRITIC_PROVIDER` | Command        | Sign in                                        | Model selection                                    |
-| ----------------- | -------------- | ---------------------------------------------- | -------------------------------------------------- |
-| `codex-cli`       | `codex`        | `codex login`                                  | Optional `CRITIC_MODEL`                            |
-| `claude-code`     | `claude`       | `claude auth login`                            | Optional `CRITIC_MODEL`                            |
-| `cursor-agent`    | `cursor-agent` | `cursor-agent login`                           | Optional `CRITIC_MODEL`                            |
-| `opencode-cli`    | `opencode`     | `opencode auth login` or `/connect` in its TUI | Required `CRITIC_MODEL` in `provider/model` format |
+When `CRITIC_PROVIDER` is empty or unset, Vibe-Gate checks local CLI executables in this order: Codex (`codex`), Claude Code (`claude`), Cursor Agent (`agent`, then legacy `cursor-agent`), and OpenCode CLI (`opencode`). OpenCode CLI is considered only with a `provider/model` `CRITIC_MODEL`, and that model format moves it to the front of the default order. Configured `*_CLI_PATH` values are checked before default PATH names, using the same provider order. The first tool response reports the selected CLI in `providerNotice`. Detection checks whether the executable is available; it does not verify that the CLI is signed in. If the selected CLI needs login, Vibe-Gate returns its error and does not switch to another account or service. If no local CLI is found, Vibe-Gate retains its OpenAI default and requires `OPENAI_API_KEY`. Set `CRITIC_PROVIDER` to select a provider explicitly.
+
+On Windows, discovery follows `PATHEXT` for `.COM`, `.EXE`, `.BAT`, and `.CMD` files. Batch shims (`.bat` and `.cmd`) run through `cmd.exe`; native executables run directly.
+
+| `CRITIC_PROVIDER` | Command                                   | Sign in                                        | Model selection                                    |
+| ----------------- | ----------------------------------------- | ---------------------------------------------- | -------------------------------------------------- |
+| `codex-cli`       | `codex`                                   | `codex login`                                  | Optional `CRITIC_MODEL`                            |
+| `claude-code`     | `claude`                                  | `claude auth login`                            | Optional `CRITIC_MODEL`                            |
+| `cursor-agent`    | `agent` (legacy fallback: `cursor-agent`) | `agent login` (legacy: `cursor-agent login`)   | Optional `CRITIC_MODEL`                            |
+| `opencode-cli`    | `opencode`                                | `opencode auth login` or `/connect` in its TUI | Required `CRITIC_MODEL` in `provider/model` format |
 
 If `CRITIC_MODEL` is omitted, Vibe-Gate leaves model selection to Codex, Claude Code, or Cursor Agent. Use model IDs accepted by the selected CLI when setting an override. Codex is deliberately started with user configuration ignored, so it uses its built-in default model rather than a custom model from `config.toml`; the saved login remains available. OpenCode CLI requires `CRITIC_MODEL` because Vibe-Gate isolates its user configuration.
 
@@ -48,8 +52,8 @@ Vibe-Gate uses print mode and safe mode, disables built-in tools and MCP tools,
 Install Cursor CLI and sign in to your Cursor account:
 
 ```sh
-cursor-agent login
-cursor-agent status
+agent login
+agent status
 ```
 
 Then configure Vibe-Gate:
@@ -57,7 +61,7 @@ Then configure Vibe-Gate:
 ```env
 CRITIC_PROVIDER=cursor-agent
 # Optional when PATH in the IDE differs from your terminal:
-# CURSOR_AGENT_CLI_PATH=/absolute/path/to/cursor-agent
+# CURSOR_AGENT_CLI_PATH=/absolute/path/to/agent
 # Optional model override:
 # CRITIC_MODEL=gpt-5
 ```

package/docs/TROUBLESHOOTING.md

@@ -10,15 +10,15 @@
 
 1. For direct API providers, set its key: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`, `MINIMAX_API_KEY`, or `OPENCODE_API_KEY`.
 2. For a local CLI provider, install the selected CLI, sign in with its account, and check the executable path.
-3. Ensure `CRITIC_PROVIDER` matches one of: `openai`, `anthropic`, `google`, `minimax`, `opencode`, `codex-cli`, `claude-code`, `cursor-agent`, or `opencode-cli`.
+3. If `CRITIC_PROVIDER` is set, ensure it matches one of: `openai`, `anthropic`, `google`, `minimax`, `opencode`, `codex-cli`, `claude-code`, `cursor-agent`, or `opencode-cli`. If it is unset, Vibe-Gate checks for local CLI executables in the documented order.
 4. For `opencode-cli`, set `CRITIC_MODEL` to an available `provider/model` value from `opencode models`.
 5. Verify `.env` is loaded (MCP config must pass `env` or the process must inherit it).
 
 ### Local CLI not found or not authenticated
 
-**Cause:** IDE-launched MCP servers may have a shorter `PATH` than an interactive terminal, or the CLI may not have an account session for this OS user.
+**Cause:** IDE-launched MCP servers may have a shorter `PATH` than an interactive terminal, or the CLI may not have an account session for this OS user. On Windows, the CLI shim may be a `.cmd` or `.bat` file listed in `PATHEXT`.
 
-**Fix:** Run the CLI's login flow in a terminal as the same user running the IDE, then set its matching `*_CLI_PATH` to the absolute executable path if needed. For Claude Code, `claude auth login` defaults to Claude subscription sign-in; `--console` selects API billing. See [CLI_PROVIDERS.md](CLI_PROVIDERS.md) for provider-specific setup.
+**Fix:** Run the CLI's login flow in a terminal as the same user running the IDE, then set its matching `*_CLI_PATH` to the absolute executable path if needed. For Cursor, `cursor-agent` remains the `CRITIC_PROVIDER` value, while the current executable is `agent`; `cursor-agent` is only a legacy fallback. For Claude Code, `claude auth login` defaults to Claude subscription sign-in; `--console` selects API billing. See [CLI_PROVIDERS.md](CLI_PROVIDERS.md) for provider-specific setup.
 
 ### OpenCode CLI reports insufficient balance
 

package/docs/USAGE.md

@@ -48,10 +48,11 @@ Vibe-Gate can call a direct API provider with an API key, or a local CLI using i
 
 ### Local CLI providers (no separate API key)
 
-Install and sign in to one supported CLI, then select it:
+Install and sign in to one supported CLI. If `CRITIC_PROVIDER` is unset, Vibe-Gate automatically uses the first available local CLI in this order: Codex, Claude Code, Cursor Agent, then OpenCode CLI. A `provider/model` `CRITIC_MODEL` moves OpenCode CLI to the front. The first review response identifies the selected CLI. Set `CRITIC_PROVIDER` to choose explicitly.
 
 ```env
-CRITIC_PROVIDER=codex-cli
+# Optional override; omit this to auto-detect a local CLI
+# CRITIC_PROVIDER=codex-cli
 # Or: claude-code | cursor-agent | opencode-cli
 # OpenCode CLI reuses its saved login and requires a model:
 # CRITIC_PROVIDER=opencode-cli
@@ -62,7 +63,7 @@ When `CRITIC_MODEL` is omitted, Codex, Claude Code, and Cursor Agent choose thei
 
 Full setup, security behavior, and alternatives we evaluated are in [CLI_PROVIDERS.md](CLI_PROVIDERS.md).
 
-### OpenAI (default)
+### OpenAI
 
 ```env
 CRITIC_PROVIDER=openai

package/docs/project/VARIABLES.md

@@ -2,20 +2,20 @@
 
 Copy [`.env.example`](../../.env.example) → `.env` in the package directory **or** set the same keys in MCP `env`. Choose a direct API provider with its key, or a signed-in local CLI provider without a separate API key.
 
-## Required (pick one provider)
-
-| Variable                       | When required                  | Description                                                                                                                        |
-| ------------------------------ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `CRITIC_PROVIDER`              | Recommended (default `openai`) | `openai` \| `anthropic` \| `google` \| `minimax` \| `opencode` \| `codex-cli` \| `claude-code` \| `cursor-agent` \| `opencode-cli` |
-| `OPENAI_API_KEY`               | `CRITIC_PROVIDER=openai`       | OpenAI API key                                                                                                                     |
-| `ANTHROPIC_API_KEY`            | `CRITIC_PROVIDER=anthropic`    | Anthropic API key                                                                                                                  |
-| `GOOGLE_GENERATIVE_AI_API_KEY` | `CRITIC_PROVIDER=google`       | Google Gemini API key                                                                                                              |
-| `MINIMAX_API_KEY`              | `CRITIC_PROVIDER=minimax`      | MiniMax API key                                                                                                                    |
-| `OPENCODE_API_KEY`             | `CRITIC_PROVIDER=opencode`     | From https://opencode.ai/auth                                                                                                      |
-| `CODEX_CLI_PATH`               | `CRITIC_PROVIDER=codex-cli`    | Optional path to the `codex` executable                                                                                            |
-| `CLAUDE_CODE_CLI_PATH`         | `CRITIC_PROVIDER=claude-code`  | Optional path to the `claude` executable                                                                                           |
-| `CURSOR_AGENT_CLI_PATH`        | `CRITIC_PROVIDER=cursor-agent` | Optional path to the `cursor-agent` executable                                                                                     |
-| `OPENCODE_CLI_PATH`            | `CRITIC_PROVIDER=opencode-cli` | Optional path to the `opencode` executable                                                                                         |
+## Provider selection (optional)
+
+| Variable                       | When required                    | Description                                                                                                                        |
+| ------------------------------ | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `CRITIC_PROVIDER`              | Optional (auto-detect local CLI) | `openai` \| `anthropic` \| `google` \| `minimax` \| `opencode` \| `codex-cli` \| `claude-code` \| `cursor-agent` \| `opencode-cli` |
+| `OPENAI_API_KEY`               | `CRITIC_PROVIDER=openai`         | OpenAI API key                                                                                                                     |
+| `ANTHROPIC_API_KEY`            | `CRITIC_PROVIDER=anthropic`      | Anthropic API key                                                                                                                  |
+| `GOOGLE_GENERATIVE_AI_API_KEY` | `CRITIC_PROVIDER=google`         | Google Gemini API key                                                                                                              |
+| `MINIMAX_API_KEY`              | `CRITIC_PROVIDER=minimax`        | MiniMax API key                                                                                                                    |
+| `OPENCODE_API_KEY`             | `CRITIC_PROVIDER=opencode`       | From https://opencode.ai/auth                                                                                                      |
+| `CODEX_CLI_PATH`               | `CRITIC_PROVIDER=codex-cli`      | Optional path to the `codex` executable                                                                                            |
+| `CLAUDE_CODE_CLI_PATH`         | `CRITIC_PROVIDER=claude-code`    | Optional path to the `claude` executable                                                                                           |
+| `CURSOR_AGENT_CLI_PATH`        | `CRITIC_PROVIDER=cursor-agent`   | Optional path to the `agent` executable (`cursor-agent` is accepted for legacy installs)                                           |
+| `OPENCODE_CLI_PATH`            | `CRITIC_PROVIDER=opencode-cli`   | Optional path to the `opencode` executable                                                                                         |
 
 ## Optional
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-gate-mcp",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "description": "Adversarial Quality Gate MCP for vibe-coding: IDE AI vs Critic AI, human decides on deadlock",
   "license": "MIT",