@phnx-labs/agents-cli 1.20.66 → 1.20.68

package/dist/lib/exec.js

@@ -104,6 +104,28 @@ export function resolveMode(agent, requested) {
     }
     throw new Error(`${agent} does not support '${requested}' mode. Supported modes: ${supported.join(', ')}.`);
 }
+/**
+ * Resolve a requested mode for a run, honoring whether the run is HEADLESS.
+ *
+ * Wraps resolveMode with one extra rule: an agent may list `plan` in its modes
+ * (so interactive plan works) yet declare `capabilities.headlessPlan === false`
+ * because plan is broken in a headless `--prompt`/`-p` run — kimi refuses
+ * `--prompt` + `--plan`, and grok's `--permission-mode plan` silently stalls at
+ * its ExitPlanMode gate. For those agents, a headless plan request degrades to
+ * `auto` (kimi -p auto-runs; grok maps auto→edit via resolveMode) with a visible
+ * one-line stderr warning, mirroring the graceful plan→edit degrade cursor and
+ * antigravity get for having no plan flag at all. Interactive runs are never
+ * downgraded. This is the single source of truth shared by buildExecCommand
+ * (agents run / teams) and the routine runner.
+ */
+export function resolveHeadlessMode(agent, requested, interactive) {
+    const mode = resolveMode(agent, requested);
+    if (!interactive && mode === 'plan' && AGENTS[agent].capabilities.headlessPlan === false) {
+        process.stderr.write(`warning: ${agent} has no headless plan mode; running --mode auto instead\n`);
+        return resolveMode(agent, 'auto');
+    }
+    return mode;
+}
 /**
  * The mode an agent should run in when the caller has no preference.
  *
@@ -573,9 +595,11 @@ export function buildExecCommand(options) {
     // Resolve the requested mode against the agent's capability table.
     // - `auto` on an agent without auto support → silently degrades to `edit`
     // - `plan` on an agent without a read-only mode → degrades to modes[0]
+    // - headless `plan` on an agent with headlessPlan:false (kimi, grok) →
+    //   degrades to `auto` with a stderr warning (see resolveHeadlessMode)
     // - `skip` on an unsupported agent → throws a clear error
-    // After resolveMode, the chosen mode is guaranteed to be in template.modeFlags.
-    const resolvedMode = resolveMode(options.agent, normalizeMode(options.mode));
+    // After resolution, the chosen mode is guaranteed to be in template.modeFlags.
+    const resolvedMode = resolveHeadlessMode(options.agent, normalizeMode(options.mode), interactive);
     const modeFlags = template.modeFlags[resolvedMode];
     if (!modeFlags) {
         // Defense in depth: would only fire if AGENTS.capabilities.modes and
@@ -609,11 +633,12 @@ export function buildExecCommand(options) {
         // all abort with "Cannot combine --prompt with --X" (verified against the live
         // kimi CLI). The write-capable modes (edit/auto/skip) all collapse to kimi's
         // default `-p` behavior, which already auto-approves tool calls, so we emit no
-        // mode flag. Plan (read-only) has no headless equivalent, so fail closed rather
-        // than silently letting a plan-mode run mutate the workspace.
+        // mode flag. Plan can't reach here headless — resolveHeadlessMode already
+        // downgraded it to auto (kimi's headlessPlan:false); this asserts that
+        // invariant so a plan-mode run can never silently mutate the workspace.
         if (resolvedMode === 'plan') {
-            throw new Error('kimi has no headless read-only mode: `--prompt` cannot be combined with `--plan`. ' +
-                'Run kimi in plan mode interactively (omit the prompt), or use --mode edit, auto, or skip.');
+            throw new Error(`Internal error: kimi reached headless command build with resolved mode 'plan'; ` +
+                `resolveHeadlessMode should have downgraded it to auto (capabilities.headlessPlan is false).`);
         }
         // edit/auto/skip: emit no mode flag — `kimi -p` auto-runs.
     }

package/dist/lib/git.d.ts

@@ -95,6 +95,16 @@ export declare function getGitHubUsername(): Promise<string | null>;
  * Get the remote URL for origin in a git repo.
  */
 export declare function getRemoteUrl(repoPath: string): Promise<string | null>;
+/**
+ * Canonical `host/owner/repo` form of a git remote, transport-agnostic, so the
+ * same repo cloned over SSH vs HTTPS compares equal. Strips protocol, any
+ * `user@`, a trailing `.git`, and folds the scp-style `host:owner/repo` colon to
+ * a slash. Lower-cased. Used to decide whether an existing checkout is "the same
+ * repo" as a requested source before adopting it.
+ */
+export declare function canonicalGitRemote(url: string): string;
+/** True when two git remote URLs point at the same repo across transport forms. */
+export declare function sameGitRemote(a: string | null | undefined, b: string | null | undefined): boolean;
 /**
  * Set the remote URL for origin in a git repo.
  */

package/dist/lib/git.js

@@ -365,6 +365,29 @@ export async function getRemoteUrl(repoPath) {
         return null;
     }
 }
+/**
+ * Canonical `host/owner/repo` form of a git remote, transport-agnostic, so the
+ * same repo cloned over SSH vs HTTPS compares equal. Strips protocol, any
+ * `user@`, a trailing `.git`, and folds the scp-style `host:owner/repo` colon to
+ * a slash. Lower-cased. Used to decide whether an existing checkout is "the same
+ * repo" as a requested source before adopting it.
+ */
+export function canonicalGitRemote(url) {
+    return url
+        .trim()
+        .replace(/\/+$/, '') // trailing slashes first, so a trailing-slash-after-.git still strips
+        .replace(/\.git$/i, '')
+        .replace(/^[a-z][a-z0-9+.-]*:\/\//i, '') // strip scheme (https://, ssh://, git://)
+        .replace(/^[^@/]+@/, '') // strip user@ (git@, ssh user)
+        .replace(':', '/') // scp-style host:owner/repo → host/owner/repo (first colon only)
+        .toLowerCase();
+}
+/** True when two git remote URLs point at the same repo across transport forms. */
+export function sameGitRemote(a, b) {
+    if (!a || !b)
+        return false;
+    return canonicalGitRemote(a) === canonicalGitRemote(b);
+}
 /**
  * Set the remote URL for origin in a git repo.
  */

package/dist/lib/hosts/option.js

@@ -14,7 +14,7 @@ export function addHostOption(cmd) {
     return cmd
         .option('-H, --host <name>', 'Run this command on another machine over SSH instead of locally — a device, a registered host, or user@host. See `agents devices` / `agents hosts`.')
         .option('--device <name>', 'Alias of --host: run this command on a registered device (from `agents devices`).')
-        .option('--remote-cwd <dir>', 'Working directory on the host for --host runs.')
+        .option('--remote-cwd <dir>', "Working directory on the host for --host runs. Resolves on the REMOTE host — pass a '$HOME'-relative path (single-quoted so your local shell doesn't expand it) or a valid remote absolute path; a local ~ expands here and won't exist there (/Users/you vs /home/you). No effect on 'teams add'.")
         .option('--no-tty', 'Force non-interactive output for --host runs even from a terminal.')
         .option('--any', 'With --host <cap> (a capability tag), pick any matching host instead of erroring when several match.');
 }

package/dist/lib/hosts/ready.js

@@ -10,7 +10,7 @@ import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { sshExec, shellQuote } from '../ssh-exec.js';
 import { sshTargetFor } from './types.js';
-import { remoteShellFor, buildWindowsAgentsCommand, encodePowershell, powershellQuote } from './remote-cmd.js';
+import { remoteShellFor, buildWindowsAgentsCommand, encodePowershell, powershellQuote, POWERSHELL_PROGRESS_SILENCE } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
 /** Resolve this CLI's own version by walking up to the nearest package.json. */
 export function localCliVersion() {
@@ -75,7 +75,8 @@ export function remoteAgentsVersion(target, os) {
  * equivalents (`Select-Object -Last`, `Test-Path`). Pure/exported. */
 export function buildBootstrapCommand(spec, os) {
     if (remoteShellFor(os) === 'powershell') {
-        const script = `npm install -g ${powershellQuote(spec)} 2>&1 | Select-Object -Last 3; ` +
+        const script = `${POWERSHELL_PROGRESS_SILENCE}; ` +
+            `npm install -g ${powershellQuote(spec)} 2>&1 | Select-Object -Last 3; ` +
             `if (-not (Test-Path "$HOME/.agents/.system")) { agents setup 2>&1 | Select-Object -Last 3 }; ` +
             `agents --version`;
         return `powershell -NoProfile -EncodedCommand ${encodePowershell(script)}`;
@@ -110,7 +111,8 @@ const READY_MARKER = '@@AGENTS_READY@@';
  */
 export function buildReadyProbeCommand(os) {
     if (remoteShellFor(os) === 'powershell') {
-        const script = `agents --version 2>$null; Write-Output "${READY_MARKER}"; ` +
+        const script = `${POWERSHELL_PROGRESS_SILENCE}; ` +
+            `agents --version 2>$null; Write-Output "${READY_MARKER}"; ` +
             `agents view 2>$null; if ($LASTEXITCODE -ne 0) { agents list 2>$null }`;
         return `powershell -NoProfile -EncodedCommand ${encodePowershell(script)}`;
     }

package/dist/lib/hosts/remote-cmd.d.ts

@@ -117,6 +117,18 @@ export interface WindowsAgentsCommand {
  * `& agents …` invokes the CLI from the machine PATH (Windows has no login
  * shell, so there is no `bash -lc` equivalent — the shim is simply on PATH).
  */
+/**
+ * PowerShell prelude that silences the progress stream. PowerShell 5.1 serializes
+ * progress records ("Preparing modules for first use.") to CLIXML when stderr is a
+ * redirected pipe (an ssh capture, not a console), so a remote `agents …` result
+ * otherwise comes back wrapped in a raw `#< CLIXML <Objs …>` blob — unreadable to
+ * humans and to the JSON parsers that consume doctor / fleet-status output. Prepend
+ * this to EVERY Windows script that invokes `agents` (there is more than one builder
+ * in this file). Verified against a live win-mini (PowerShell 5.1): this clears it.
+ * (`-OutputFormat Text` does NOT — it governs success-stream object serialization,
+ * not the progress stream.)
+ */
+export declare const POWERSHELL_PROGRESS_SILENCE = "$ProgressPreference = 'SilentlyContinue'";
 export declare function windowsAgentsScript(cmd: WindowsAgentsCommand): string;
 /**
  * Build the `ssh <target> <cmd>` string for one `agents …` invocation on a

package/dist/lib/hosts/remote-cmd.js

@@ -110,6 +110,7 @@ export const RUN_OPTION_FORWARDING = {
     lease: 'local-only',
     keepBox: 'local-only',
     copyCreds: 'local-only', // copies creds TO the host before dispatch — local concern only
+    authCheck: 'local-only', // --no-auth-check gates the local interactive login preflight; --host runs skip that preflight entirely
 };
 /** Actionable messages for value-aware rejections, keyed by attribute name. */
 export const RUN_OPTION_REJECT_MESSAGES = {
@@ -190,9 +191,21 @@ export function decodePowershell(encoded) {
  * `& agents …` invokes the CLI from the machine PATH (Windows has no login
  * shell, so there is no `bash -lc` equivalent — the shim is simply on PATH).
  */
+/**
+ * PowerShell prelude that silences the progress stream. PowerShell 5.1 serializes
+ * progress records ("Preparing modules for first use.") to CLIXML when stderr is a
+ * redirected pipe (an ssh capture, not a console), so a remote `agents …` result
+ * otherwise comes back wrapped in a raw `#< CLIXML <Objs …>` blob — unreadable to
+ * humans and to the JSON parsers that consume doctor / fleet-status output. Prepend
+ * this to EVERY Windows script that invokes `agents` (there is more than one builder
+ * in this file). Verified against a live win-mini (PowerShell 5.1): this clears it.
+ * (`-OutputFormat Text` does NOT — it governs success-stream object serialization,
+ * not the progress stream.)
+ */
+export const POWERSHELL_PROGRESS_SILENCE = "$ProgressPreference = 'SilentlyContinue'";
 export function windowsAgentsScript(cmd) {
     const { args, env, cwd, propagateExit = true } = cmd;
-    const parts = [];
+    const parts = [POWERSHELL_PROGRESS_SILENCE];
     if (env)
         for (const [k, v] of Object.entries(env))
             parts.push(`$env:${k} = ${powershellQuote(v)}`);
@@ -232,6 +245,9 @@ export function buildWindowsStdinImportCommand(bundle, opts = {}) {
     // the secret-bearing temp file would otherwise be left behind (RUSH-1764). $tmp
     // starts null so a GetTempFileName that itself throws leaves nothing to remove.
     const script = [
+        // Same CLIXML guard as windowsAgentsScript — this builder also runs `& agents …`
+        // and its raw stderr is printed to the user on failure (secrets export --host <win>).
+        POWERSHELL_PROGRESS_SILENCE,
         '$in = [Console]::In.ReadToEnd()',
         '$tmp = $null',
         `try { $tmp = [System.IO.Path]::GetTempFileName(); [System.IO.File]::WriteAllText($tmp, $in); ` +

package/dist/lib/mcp.d.ts

@@ -108,6 +108,27 @@ export declare function registerMcpCommandToTargets(targets: {
     directAgents: AgentId[];
     versionSelections: Map<AgentId, string[]>;
 }, name: string, commandSpec: McpCommandSpec, scope?: 'user' | 'project', transport?: string): Promise<McpTargetOperationResult[]>;
+/**
+ * MCP server shaped for direct config-file serialization.
+ */
+export interface WritableMcpServer {
+    name: string;
+    transport: 'stdio' | 'http' | 'sse';
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
+}
+/**
+ * Serialize MCP servers into an agent-specific config file.
+ *
+ * `mode: 'overwrite'` replaces the whole MCP section (used for tool-managed
+ * version-home configs). `mode: 'merge'` updates/adds the provided server
+ * entries while preserving existing entries (used for project-level configs
+ * that users may hand-edit or populate via agent CLI commands).
+ */
+export declare function writeMcpConfig(agentId: AgentId, configPath: string, servers: WritableMcpServer[], mode?: 'overwrite' | 'merge'): void;
 /**
  * Install MCP servers to an agent.
  * For Claude/Codex: uses CLI commands (claude mcp add, codex mcp add)

package/dist/lib/mcp.js

@@ -10,12 +10,13 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
+import * as TOML from 'smol-toml';
 import { execFileSync } from 'child_process';
 import * as os from 'os';
 import { getMcpDir, getUserMcpDir, getProjectAgentsDir, getVersionsDir, getUserAgentsDir } from './state.js';
 import { getBinaryPath, getVersionHomePath } from './versions.js';
 import { IS_WINDOWS, execFileShellSpec } from './platform/index.js';
-import { AGENTS } from './agents.js';
+import { AGENTS, getMcpConfigPathForHome, getProjectMcpConfigPath } from './agents.js';
 import { isCapable } from './capabilities.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
 /**
@@ -634,6 +635,225 @@ function installMcpToOpenCodeConfig(server, versionHome) {
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
 }
+/**
+ * Agents whose config file format is implemented by `writeMcpConfig`.
+ * Others are intentionally skipped until their schema is added.
+ */
+function writeMcpConfigSupportsAgent(agentId) {
+    switch (agentId) {
+        case 'claude':
+        case 'cursor':
+        case 'gemini':
+        case 'kimi':
+        case 'droid':
+        case 'forge':
+        case 'openclaw':
+        case 'codex':
+        case 'grok':
+        case 'opencode':
+        case 'hermes':
+            return true;
+        default:
+            return false;
+    }
+}
+/**
+ * Serialize MCP servers into an agent-specific config file.
+ *
+ * `mode: 'overwrite'` replaces the whole MCP section (used for tool-managed
+ * version-home configs). `mode: 'merge'` updates/adds the provided server
+ * entries while preserving existing entries (used for project-level configs
+ * that users may hand-edit or populate via agent CLI commands).
+ */
+export function writeMcpConfig(agentId, configPath, servers, mode = 'overwrite') {
+    if (servers.length === 0) {
+        return;
+    }
+    switch (agentId) {
+        case 'claude':
+        case 'cursor':
+        case 'gemini':
+        case 'kimi':
+        case 'droid':
+        case 'forge': {
+            let config = {};
+            if (fs.existsSync(configPath)) {
+                try {
+                    config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+                }
+                catch {
+                    config = {};
+                }
+            }
+            const mcpServers = mode === 'merge' && config.mcpServers && typeof config.mcpServers === 'object'
+                ? { ...config.mcpServers }
+                : {};
+            for (const server of servers) {
+                if (server.transport === 'stdio') {
+                    mcpServers[server.name] = {
+                        command: server.command,
+                        args: server.args || [],
+                        env: server.env || {},
+                    };
+                }
+                else {
+                    mcpServers[server.name] = {
+                        url: server.url,
+                        ...(server.headers && { headers: server.headers }),
+                    };
+                }
+            }
+            config.mcpServers = mcpServers;
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+            break;
+        }
+        case 'openclaw': {
+            let config = {};
+            if (fs.existsSync(configPath)) {
+                try {
+                    config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+                }
+                catch {
+                    config = {};
+                }
+            }
+            if (!config.mcp || typeof config.mcp !== 'object') {
+                config.mcp = {};
+            }
+            const mcp = config.mcp;
+            const mcpServers = mode === 'merge' && mcp.servers && typeof mcp.servers === 'object'
+                ? { ...mcp.servers }
+                : {};
+            for (const server of servers) {
+                if (server.transport === 'stdio') {
+                    mcpServers[server.name] = {
+                        command: server.command,
+                        args: server.args || [],
+                        env: server.env || {},
+                    };
+                }
+                else {
+                    mcpServers[server.name] = {
+                        url: server.url,
+                        transport: server.transport,
+                        ...(server.headers && { headers: server.headers }),
+                    };
+                }
+            }
+            mcp.servers = mcpServers;
+            config.mcp = mcp;
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+            break;
+        }
+        case 'codex':
+        case 'grok': {
+            let config = {};
+            if (fs.existsSync(configPath)) {
+                try {
+                    config = TOML.parse(fs.readFileSync(configPath, 'utf-8'));
+                }
+                catch {
+                    config = {};
+                }
+            }
+            const mcpServers = mode === 'merge' && config.mcp_servers && typeof config.mcp_servers === 'object'
+                ? { ...config.mcp_servers }
+                : {};
+            for (const server of servers) {
+                if (server.transport === 'stdio') {
+                    mcpServers[server.name] = {
+                        command: server.command,
+                        args: server.args || [],
+                        ...(server.env && { env: server.env }),
+                    };
+                }
+                else {
+                    mcpServers[server.name] = {
+                        url: server.url,
+                        ...(server.headers && { headers: server.headers }),
+                    };
+                }
+            }
+            config.mcp_servers = mcpServers;
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
+            fs.writeFileSync(configPath, TOML.stringify(config), 'utf-8');
+            break;
+        }
+        case 'opencode': {
+            let config = {};
+            if (fs.existsSync(configPath)) {
+                try {
+                    const content = fs.readFileSync(configPath, 'utf-8');
+                    const jsonContent = content.replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '');
+                    config = JSON.parse(jsonContent);
+                }
+                catch {
+                    config = {};
+                }
+            }
+            const mcp = mode === 'merge' && config.mcp && typeof config.mcp === 'object'
+                ? { ...config.mcp }
+                : {};
+            for (const server of servers) {
+                if (server.transport === 'stdio') {
+                    const commandArray = [server.command, ...(server.args || [])];
+                    mcp[server.name] = {
+                        type: 'local',
+                        command: commandArray,
+                        ...(server.env && { env: server.env }),
+                    };
+                }
+                else {
+                    mcp[server.name] = {
+                        type: 'remote',
+                        url: server.url,
+                    };
+                }
+            }
+            config.mcp = mcp;
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+            break;
+        }
+        case 'hermes': {
+            let config = {};
+            if (fs.existsSync(configPath)) {
+                try {
+                    const parsed = yaml.parse(fs.readFileSync(configPath, 'utf-8'));
+                    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                        config = parsed;
+                    }
+                }
+                catch {
+                    config = {};
+                }
+            }
+            const mcpServers = mode === 'merge' && config.mcp_servers && typeof config.mcp_servers === 'object' && !Array.isArray(config.mcp_servers)
+                ? { ...config.mcp_servers }
+                : {};
+            for (const server of servers) {
+                if (server.transport === 'stdio') {
+                    mcpServers[server.name] = {
+                        command: server.command,
+                        args: server.args || [],
+                        ...(server.env && { env: server.env }),
+                    };
+                }
+                else {
+                    mcpServers[server.name] = {
+                        url: server.url,
+                    };
+                }
+            }
+            config.mcp_servers = mcpServers;
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
+            fs.writeFileSync(configPath, yaml.stringify(config), 'utf-8');
+            break;
+        }
+    }
+}
 /**
  * Install MCP servers to an agent.
  * For Claude/Codex: uses CLI commands (claude mcp add, codex mcp add)
@@ -658,47 +878,92 @@ export function installMcpServers(agentId, version, versionHome, mcpNames, optio
         binaryPath += '.cmd';
     }
     for (const server of servers) {
+        let handled = false;
         try {
             if (agentId === 'claude') {
                 installMcpViaClaude(binaryPath, server, versionHome);
-                applied.push(server.name);
+                handled = true;
             }
             else if (agentId === 'codex') {
                 installMcpViaCodex(binaryPath, server, versionHome);
-                applied.push(server.name);
+                handled = true;
             }
             else if (agentId === 'gemini') {
                 installMcpToGeminiConfig(server, versionHome);
-                applied.push(server.name);
+                handled = true;
             }
             else if (agentId === 'cursor') {
                 installMcpToCursorConfig(server, versionHome);
-                applied.push(server.name);
+                handled = true;
             }
             else if (agentId === 'opencode') {
                 installMcpToOpenCodeConfig(server, versionHome);
-                applied.push(server.name);
+                handled = true;
+            }
+            else if (agentId === 'openclaw') {
+                // OpenClaw has no install CLI; write the JSON config directly.
+                // Use merge because this loop runs once per server.
+                const userConfigPath = getMcpConfigPathForHome(agentId, versionHome);
+                const writableServer = {
+                    name: server.config.name,
+                    transport: server.config.transport,
+                    command: server.config.command,
+                    args: server.config.args,
+                    env: server.config.env,
+                    url: server.config.url,
+                };
+                writeMcpConfig(agentId, userConfigPath, [writableServer], 'merge');
+                handled = true;
             }
             else if (agentId === 'grok') {
-                // Grok primarily uses [mcp_servers] in ~/.grok/config.toml (or project .grok/config.toml).
-                // We have the path helper; full writer can be added (reuse codex toml pattern).
-                // For now the general sync + toml editing via agents mcp works via the path helpers.
-                applied.push(server.name);
+                // Grok has no working `grok mcp add` CLI, so write the TOML config
+                // directly into the version-home directory for all scopes.
+                // Use merge because this loop runs once per server.
+                const userConfigPath = getMcpConfigPathForHome(agentId, versionHome);
+                const writableServer = {
+                    name: server.config.name,
+                    transport: server.config.transport,
+                    command: server.config.command,
+                    args: server.config.args,
+                    env: server.config.env,
+                    url: server.config.url,
+                };
+                writeMcpConfig(agentId, userConfigPath, [writableServer], 'merge');
+                handled = true;
             }
             else if (agentId === 'kimi') {
                 installMcpToKimiConfig(server, versionHome);
-                applied.push(server.name);
+                handled = true;
             }
             else if (agentId === 'droid') {
                 installMcpToFactoryConfig(server, versionHome);
-                applied.push(server.name);
+                handled = true;
             }
             else if (agentId === 'hermes') {
                 installMcpToHermesConfig(server, versionHome);
-                applied.push(server.name);
+                handled = true;
             }
             else if (agentId === 'forge') {
                 installMcpToForgeConfig(server, versionHome);
+                handled = true;
+            }
+            // Project-layer servers also get merged into the agent's project-level
+            // config (e.g., .mcp.json, .codex/config.toml) so the CLI discovers them
+            // when run inside the repo.
+            if (server.scope === 'project' && options.cwd && writeMcpConfigSupportsAgent(agentId)) {
+                const projectConfigPath = getProjectMcpConfigPath(agentId, options.cwd);
+                const writableServer = {
+                    name: server.config.name,
+                    transport: server.config.transport,
+                    command: server.config.command,
+                    args: server.config.args,
+                    env: server.config.env,
+                    url: server.config.url,
+                };
+                writeMcpConfig(agentId, projectConfigPath, [writableServer], 'merge');
+                handled = true;
+            }
+            if (handled) {
                 applied.push(server.name);
             }
         }