agent-enderun 1.0.7 → 1.0.9

package/framework-mcp/dist/src/tools/index.js

@@ -0,0 +1,25 @@
+import { TOOLS } from "./definitions.js";
+import { handleReadFile } from "./file_system/read_file.js";
+import { handleWriteFile } from "./file_system/write_file.js";
+import { handleReplaceText } from "./file_system/replace_text.js";
+import { handlePatchFile } from "./file_system/patch_file.js";
+import { handleGetFrameworkStatus } from "./framework/get_status.js";
+import { handleUpdateProjectMemory } from "./framework/update_memory.js";
+import { handleOrchestrateLoop } from "./framework/orchestrate.js";
+import { handleUpdateContractHash } from "./framework/update_contract_hash.js";
+import { handleSendAgentMessage } from "./messaging/send_message.js";
+import { handleLogAgentAction } from "./messaging/log_action.js";
+// Map of tool names to their handler functions
+export const toolHandlers = {
+    read_file: handleReadFile,
+    write_file: handleWriteFile,
+    replace_text: handleReplaceText,
+    patch_file: handlePatchFile,
+    get_framework_status: handleGetFrameworkStatus,
+    update_project_memory: handleUpdateProjectMemory,
+    orchestrate_loop: handleOrchestrateLoop,
+    send_agent_message: handleSendAgentMessage,
+    log_agent_action: handleLogAgentAction,
+    update_contract_hash: handleUpdateContractHash,
+};
+export { TOOLS };

package/framework-mcp/dist/src/tools/messaging/log_action.js

@@ -0,0 +1,22 @@
+import fs from "fs";
+import path from "path";
+import { resolveFrameworkDir } from "../../utils/security.js";
+export function handleLogAgentAction(projectRoot, args) {
+    const { agent, action, traceId, status, summary } = args;
+    const findings = args.findings ? args.findings.split(",").map(f => f.trim()) : [];
+    const frameworkDir = resolveFrameworkDir(projectRoot);
+    const agentName = agent.replace("@", "");
+    const logPath = path.join(projectRoot, frameworkDir, "logs", `${agentName}.json`);
+    const logEntry = {
+        timestamp: new Date().toISOString(),
+        agent,
+        action,
+        requestId: traceId,
+        status,
+        summary,
+        findings
+    };
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    fs.appendFileSync(logPath, JSON.stringify(logEntry) + "\n");
+    return { content: [{ type: "text", text: `✅ Action logged for ${agent} to ${path.join(frameworkDir, "logs", `${agentName}.json`)}` }] };
+}

package/framework-mcp/dist/src/tools/messaging/send_message.js

@@ -0,0 +1,23 @@
+import fs from "fs";
+import path from "path";
+import { resolveFrameworkDir } from "../../utils/security.js";
+export function handleSendAgentMessage(projectRoot, args) {
+    const { to, category, content, traceId } = args;
+    // `from` is optional — falls back to "@mcp" for backward compatibility
+    const from = args.from || "@mcp";
+    const frameworkDir = resolveFrameworkDir(projectRoot);
+    const agentName = to.replace("@", "");
+    const messagePath = path.join(projectRoot, frameworkDir, "messages", `${agentName}.json`);
+    const message = {
+        timestamp: new Date().toISOString(),
+        from,
+        to,
+        category,
+        traceId,
+        content,
+        status: "PENDING"
+    };
+    fs.mkdirSync(path.dirname(messagePath), { recursive: true });
+    fs.appendFileSync(messagePath, JSON.stringify(message) + "\n");
+    return { content: [{ type: "text", text: `✅ Message sent to ${to} (from: ${from})` }] };
+}

package/framework-mcp/dist/src/tools/types.js

@@ -0,0 +1 @@
+export {};

package/framework-mcp/dist/src/utils/cli.js

@@ -0,0 +1,20 @@
+import { execFileSync } from "child_process";
+/**
+ * Executes a CLI command safely using execFileSync (no shell injection risk).
+ * Captures stderr gracefully to prevent stream crashes.
+ */
+export function safeExec(command, args, cwd, timeout) {
+    try {
+        return execFileSync(command, args, {
+            cwd,
+            encoding: "utf8",
+            timeout: timeout || 30000,
+            maxBuffer: 1024 * 1024,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+    }
+    catch (error) {
+        const err = error;
+        throw new Error(err.stderr || err.message || "Command execution failed", { cause: error });
+    }
+}

package/framework-mcp/dist/src/utils/security.js

@@ -0,0 +1,53 @@
+import path from "path";
+import fs from "fs";
+/**
+ * Validates and resolves a user-provided path to prevent path traversal attacks.
+ * Ensures the resolved path stays within the project root boundary.
+ */
+export function safePath(projectRoot, userPath) {
+    const resolved = path.resolve(projectRoot, userPath);
+    const normalizedRoot = path.resolve(projectRoot);
+    if (!resolved.startsWith(normalizedRoot + path.sep) && resolved !== normalizedRoot) {
+        throw new Error(`Access denied: path "${userPath}" escapes project root.`);
+    }
+    return resolved;
+}
+/**
+ * Resolves the active framework directory.
+ * Priority: package.json `enderun.frameworkDir` → `.enderun` → adapter dirs.
+ * This ensures the canonical framework directory is always used,
+ * even when adapter-specific dirs (e.g. `.gemini`) exist alongside it.
+ */
+export function resolveFrameworkDir(projectRoot) {
+    // 1. Authoritative source: read from package.json if present
+    try {
+        const pkgPath = path.join(projectRoot, "package.json");
+        if (fs.existsSync(pkgPath)) {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+            const enderunConfig = pkg["enderun"];
+            if (enderunConfig && typeof enderunConfig["frameworkDir"] === "string") {
+                return enderunConfig["frameworkDir"];
+            }
+        }
+    }
+    catch {
+        // ignore — fall through to filesystem scan
+    }
+    // 2. Filesystem scan — .enderun takes precedence over adapter-specific dirs
+    const candidates = [
+        ".enderun",
+        ".claude",
+        ".grok",
+        ".agent",
+        ".gemini/antigravity",
+        ".gemini/antigravity-cli",
+        ".gemini",
+    ];
+    for (const candidate of candidates) {
+        const candidatePath = path.join(projectRoot, candidate);
+        if (fs.existsSync(candidatePath)) {
+            return candidate;
+        }
+    }
+    return ".enderun";
+}

package/framework-mcp/dist/tests/tools/file_system/replace_text.test.js

@@ -0,0 +1,68 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs";
+import path from "path";
+import { handleReplaceText } from "../../../src/tools/file_system/replace_text.js";
+const TEST_DIR = path.join(__dirname, "../_temp_test_files");
+const TEST_FILE = path.join(TEST_DIR, "test_file.txt");
+beforeEach(() => {
+    fs.mkdirSync(TEST_DIR, { recursive: true });
+});
+afterEach(() => {
+    fs.rmSync(TEST_DIR, { recursive: true, force: true });
+});
+describe("handleReplaceText", () => {
+    it("should replace a single occurrence of text", () => {
+        fs.writeFileSync(TEST_FILE, "hello world", "utf8");
+        const args = {
+            path: TEST_FILE,
+            oldText: "world",
+            newText: "there",
+        };
+        const result = handleReplaceText(TEST_DIR, args);
+        expect(result.content[0].text).toContain("✅ Surgical edit successful");
+        expect(fs.readFileSync(TEST_FILE, "utf8")).toBe("hello there");
+    });
+    it("should throw an error if text is not found", () => {
+        fs.writeFileSync(TEST_FILE, "hello world", "utf8");
+        const args = {
+            path: TEST_FILE,
+            oldText: "missing",
+            newText: "found",
+        };
+        expect(() => handleReplaceText(TEST_DIR, args)).toThrowError("Text not found in file");
+    });
+    it("should throw an error for ambiguous replacement if allowMultiple is false", () => {
+        fs.writeFileSync(TEST_FILE, "hello world world", "utf8");
+        const args = {
+            path: TEST_FILE,
+            oldText: "world",
+            newText: "there",
+            allowMultiple: false,
+        };
+        expect(() => handleReplaceText(TEST_DIR, args)).toThrowError("Ambiguous replacement");
+    });
+    it("should replace all occurrences of text if allowMultiple is true", () => {
+        fs.writeFileSync(TEST_FILE, "hello world world", "utf8");
+        const args = {
+            path: TEST_FILE,
+            oldText: "world",
+            newText: "there",
+            allowMultiple: true,
+        };
+        const result = handleReplaceText(TEST_DIR, args);
+        expect(result.content[0].text).toContain("✅ Surgical edit successful");
+        expect(fs.readFileSync(TEST_FILE, "utf8")).toBe("hello there there");
+    });
+    it("should handle special characters in oldText when allowMultiple is true", () => {
+        fs.writeFileSync(TEST_FILE, "test.txt", "utf8");
+        const args = {
+            path: TEST_FILE,
+            oldText: ".txt",
+            newText: ".md",
+            allowMultiple: true,
+        };
+        const result = handleReplaceText(TEST_DIR, args);
+        expect(result.content[0].text).toContain("✅ Surgical edit successful");
+        expect(fs.readFileSync(TEST_FILE, "utf8")).toBe("test.md");
+    });
+});

package/framework-mcp/dist/tools/definitions.js

@@ -77,6 +77,7 @@ export const TOOLS = [
         inputSchema: {
             type: "object",
             properties: {
+                from: { type: "string", description: "Sender agent (e.g., @manager, @backend). Defaults to @mcp if omitted." },
                 to: { type: "string", description: "Target agent (e.g., @backend, @qa)" },
                 category: { type: "string", enum: ["ACTION", "DELEGATION", "INFO", "ALERT"] },
                 content: { type: "string", description: "Message content" },

package/framework-mcp/dist/tools/file_system/replace_text.js

@@ -5,10 +5,27 @@ export function handleReplaceText(projectRoot, args) {
     let content = fs.readFileSync(filePath, "utf8");
     const oldText = args.oldText;
     const newText = args.newText;
+    const allowMultiple = args.allowMultiple || false; // Default to false
     if (!content.includes(oldText)) {
         throw new Error(`Text not found in file: ${oldText.slice(0, 100)}...`);
     }
-    content = content.replace(oldText, newText);
+    // Surgical precision guard: reject ambiguous replacements unless allowMultiple is true.
+    if (!allowMultiple) {
+        const firstIndex = content.indexOf(oldText);
+        const lastIndex = content.lastIndexOf(oldText);
+        if (firstIndex !== lastIndex) {
+            const count = (content.match(new RegExp(oldText.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g")) || []).length;
+            throw new Error(`Ambiguous replacement: "${oldText.slice(0, 80)}..." found ${count} times in ${args.path}. ` +
+                "Provide a longer, unique context string or set 'allow_multiple' to true.");
+        }
+    }
+    // Perform replacement(s)
+    if (allowMultiple) {
+        content = content.replace(new RegExp(oldText.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g"), newText);
+    }
+    else {
+        content = content.replace(oldText, newText);
+    }
     fs.writeFileSync(filePath, content);
     return { content: [{ type: "text", text: `✅ Surgical edit successful in ${args.path}` }] };
 }

package/framework-mcp/dist/tools/framework/get_status.js

@@ -1,5 +1,5 @@
 import { safeExec } from "../../utils/cli.js";
-export function handleGetFrameworkStatus(projectRoot) {
-    const output = safeExec("npx", ["agent-enderun", "status"], projectRoot);
+export function handleGetFrameworkStatus(projectRoot, args) {
+    const output = safeExec("npx", ["agent-enderun", "status"], projectRoot, args.timeout);
     return { content: [{ type: "text", text: output }] };
 }

package/framework-mcp/dist/tools/framework/orchestrate.js

@@ -1,5 +1,5 @@
 import { safeExec } from "../../utils/cli.js";
-export function handleOrchestrateLoop(projectRoot) {
-    const output = safeExec("npx", ["agent-enderun", "orchestrate"], projectRoot);
+export function handleOrchestrateLoop(projectRoot, args) {
+    const output = safeExec("npx", ["agent-enderun", "orchestrate"], projectRoot, args.timeout);
     return { content: [{ type: "text", text: output }] };
 }

package/framework-mcp/dist/tools/framework/update_contract_hash.js

@@ -1,5 +1,5 @@
 import { safeExec } from "../../utils/cli.js";
-export function handleUpdateContractHash(projectRoot) {
-    const output = safeExec("npx", ["agent-enderun", "update-contract"], projectRoot);
+export function handleUpdateContractHash(projectRoot, args) {
+    const output = safeExec("npx", ["agent-enderun", "update-contract"], projectRoot, args.timeout);
     return { content: [{ type: "text", text: output }] };
 }

package/framework-mcp/dist/tools/framework/update_memory.js

@@ -3,6 +3,6 @@ export function handleUpdateProjectMemory(projectRoot, args) {
     const section = args.section;
     const content = args.content;
     // Using execFileSync with array args prevents command injection
-    safeExec("npx", ["agent-enderun", "update_project_memory", section, content], projectRoot);
+    safeExec("npx", ["agent-enderun", "update_project_memory", section, content], projectRoot, args.timeout);
     return { content: [{ type: "text", text: `✅ Section ${section} updated.` }] };
 }

package/framework-mcp/dist/tools/messaging/send_message.js

@@ -3,12 +3,14 @@ import path from "path";
 import { resolveFrameworkDir } from "../../utils/security.js";
 export function handleSendAgentMessage(projectRoot, args) {
     const { to, category, content, traceId } = args;
+    // `from` is optional — falls back to "@mcp" for backward compatibility
+    const from = args.from || "@mcp";
     const frameworkDir = resolveFrameworkDir(projectRoot);
     const agentName = to.replace("@", "");
     const messagePath = path.join(projectRoot, frameworkDir, "messages", `${agentName}.json`);
     const message = {
         timestamp: new Date().toISOString(),
-        from: "@mcp",
+        from,
         to,
         category,
         traceId,
@@ -17,5 +19,5 @@ export function handleSendAgentMessage(projectRoot, args) {
     };
     fs.mkdirSync(path.dirname(messagePath), { recursive: true });
     fs.appendFileSync(messagePath, JSON.stringify(message) + "\n");
-    return { content: [{ type: "text", text: `✅ Message sent to ${to}` }] };
+    return { content: [{ type: "text", text: `✅ Message sent to ${to} (from: ${from})` }] };
 }

package/framework-mcp/dist/utils/cli.js

@@ -3,12 +3,12 @@ import { execFileSync } from "child_process";
  * Executes a CLI command safely using execFileSync (no shell injection risk).
  * Captures stderr gracefully to prevent stream crashes.
  */
-export function safeExec(command, args, cwd) {
+export function safeExec(command, args, cwd, timeout) {
     try {
         return execFileSync(command, args, {
             cwd,
             encoding: "utf8",
-            timeout: 30000,
+            timeout: timeout || 30000,
             maxBuffer: 1024 * 1024,
             stdio: ["pipe", "pipe", "pipe"],
         });

package/framework-mcp/dist/utils/security.js

@@ -13,17 +13,35 @@ export function safePath(projectRoot, userPath) {
     return resolved;
 }
 /**
- * Resolves the active framework directory by scanning known candidates.
+ * Resolves the active framework directory.
+ * Priority: package.json `enderun.frameworkDir` → `.enderun` → adapter dirs.
+ * This ensures the canonical framework directory is always used,
+ * even when adapter-specific dirs (e.g. `.gemini`) exist alongside it.
  */
 export function resolveFrameworkDir(projectRoot) {
+    // 1. Authoritative source: read from package.json if present
+    try {
+        const pkgPath = path.join(projectRoot, "package.json");
+        if (fs.existsSync(pkgPath)) {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+            const enderunConfig = pkg["enderun"];
+            if (enderunConfig && typeof enderunConfig["frameworkDir"] === "string") {
+                return enderunConfig["frameworkDir"];
+            }
+        }
+    }
+    catch {
+        // ignore — fall through to filesystem scan
+    }
+    // 2. Filesystem scan — .enderun takes precedence over adapter-specific dirs
     const candidates = [
-        ".gemini/antigravity",
-        ".gemini/antigravity-cli",
-        ".gemini",
+        ".enderun",
         ".claude",
         ".grok",
         ".agent",
-        ".enderun",
+        ".gemini/antigravity",
+        ".gemini/antigravity-cli",
+        ".gemini",
     ];
     for (const candidate of candidates) {
         const candidatePath = path.join(projectRoot, candidate);

package/framework-mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-enderun/mcp",
-  "version": "1.0.6",
+  "version": "1.0.9",
   "description": "Agent Enderun Model Context Protocol (MCP) Server",
   "type": "module",
   "scripts": {
@@ -13,7 +13,7 @@
     "zod": "^3.24.2"
   },
   "devDependencies": {
-    "@types/node": "^22.19.19",
-    "typescript": "^5.9.3"
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3"
   }
 }

package/framework-mcp/src/index.ts

@@ -13,8 +13,8 @@ import { TOOLS, toolHandlers } from "./tools/index.js";
 
 const server = new Server(
     {
-        name: "agent-enderun",
-        version: "1.0.0",
+        name: "@agent-enderun/mcp",
+        version: "1.0.9",
     },
     {
         capabilities: {

package/framework-mcp/src/tools/definitions.ts

@@ -79,6 +79,7 @@ export const TOOLS: ToolDefinition[] = [
         inputSchema: {
             type: "object",
             properties: {
+                from: { type: "string", description: "Sender agent (e.g., @manager, @backend). Defaults to @mcp if omitted." },
                 to: { type: "string", description: "Target agent (e.g., @backend, @qa)" },
                 category: { type: "string", enum: ["ACTION", "DELEGATION", "INFO", "ALERT"] },
                 content: { type: "string", description: "Message content" },

package/framework-mcp/src/tools/file_system/replace_text.ts

@@ -7,12 +7,32 @@ export function handleReplaceText(projectRoot: string, args: ToolArgs): ToolResu
     let content = fs.readFileSync(filePath, "utf8");
     const oldText = args.oldText as string;
     const newText = args.newText as string;
+    const allowMultiple = args.allowMultiple || false; // Default to false
 
     if (!content.includes(oldText)) {
         throw new Error(`Text not found in file: ${oldText.slice(0, 100)}...`);
     }
 
-    content = content.replace(oldText, newText);
+    // Surgical precision guard: reject ambiguous replacements unless allowMultiple is true.
+    if (!allowMultiple) {
+        const firstIndex = content.indexOf(oldText);
+        const lastIndex = content.lastIndexOf(oldText);
+        if (firstIndex !== lastIndex) {
+            const count = (content.match(new RegExp(oldText.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g")) || []).length;
+            throw new Error(
+                `Ambiguous replacement: "${oldText.slice(0, 80)}..." found ${count} times in ${args.path}. ` +
+                "Provide a longer, unique context string or set 'allow_multiple' to true."
+            );
+        }
+    }
+
+    // Perform replacement(s)
+    if (allowMultiple) {
+        content = content.replace(new RegExp(oldText.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g"), newText);
+    } else {
+        content = content.replace(oldText, newText);
+    }
+    
     fs.writeFileSync(filePath, content);
     return { content: [{ type: "text", text: `✅ Surgical edit successful in ${args.path}` }] };
 }

package/framework-mcp/src/tools/framework/get_status.ts

@@ -1,7 +1,7 @@
 import { safeExec } from "../../utils/cli.js";
-import { ToolResult } from "../types.js";
+import { ToolArgs, ToolResult } from "../types.js";
 
-export function handleGetFrameworkStatus(projectRoot: string): ToolResult {
-    const output = safeExec("npx", ["agent-enderun", "status"], projectRoot);
+export function handleGetFrameworkStatus(projectRoot: string, args: ToolArgs): ToolResult {
+    const output = safeExec("npx", ["agent-enderun", "status"], projectRoot, args.timeout);
     return { content: [{ type: "text", text: output }] };
 }

package/framework-mcp/src/tools/framework/orchestrate.ts

@@ -1,7 +1,7 @@
 import { safeExec } from "../../utils/cli.js";
-import { ToolResult } from "../types.js";
+import { ToolArgs, ToolResult } from "../types.js";
 
-export function handleOrchestrateLoop(projectRoot: string): ToolResult {
-    const output = safeExec("npx", ["agent-enderun", "orchestrate"], projectRoot);
+export function handleOrchestrateLoop(projectRoot: string, args: ToolArgs): ToolResult {
+    const output = safeExec("npx", ["agent-enderun", "orchestrate"], projectRoot, args.timeout);
     return { content: [{ type: "text", text: output }] };
 }

package/framework-mcp/src/tools/framework/update_contract_hash.ts

@@ -1,7 +1,7 @@
 import { safeExec } from "../../utils/cli.js";
-import { ToolResult } from "../types.js";
+import { ToolArgs, ToolResult } from "../types.js";
 
-export function handleUpdateContractHash(projectRoot: string): ToolResult {
-    const output = safeExec("npx", ["agent-enderun", "update-contract"], projectRoot);
+export function handleUpdateContractHash(projectRoot: string, args: ToolArgs): ToolResult {
+    const output = safeExec("npx", ["agent-enderun", "update-contract"], projectRoot, args.timeout);
     return { content: [{ type: "text", text: output }] };
 }

package/framework-mcp/src/tools/framework/update_memory.ts

@@ -5,6 +5,6 @@ export function handleUpdateProjectMemory(projectRoot: string, args: ToolArgs):
     const section = args.section as string;
     const content = args.content as string;
     // Using execFileSync with array args prevents command injection
-    safeExec("npx", ["agent-enderun", "update_project_memory", section, content], projectRoot);
+    safeExec("npx", ["agent-enderun", "update_project_memory", section, content], projectRoot, args.timeout);
     return { content: [{ type: "text", text: `✅ Section ${section} updated.` }] };
 }

package/framework-mcp/src/tools/messaging/send_message.ts

@@ -5,13 +5,16 @@ import { ToolArgs, ToolResult } from "../types.js";
 
 export function handleSendAgentMessage(projectRoot: string, args: ToolArgs): ToolResult {
     const { to, category, content, traceId } = args as Required<Pick<ToolArgs, "to" | "category" | "content" | "traceId">>;
+    // `from` is optional — falls back to "@mcp" for backward compatibility
+    const from = (args.from as string) || "@mcp";
+
     const frameworkDir = resolveFrameworkDir(projectRoot);
     const agentName = to.replace("@", "");
     const messagePath = path.join(projectRoot, frameworkDir, "messages", `${agentName}.json`);
 
     const message = {
         timestamp: new Date().toISOString(),
-        from: "@mcp",
+        from,
         to,
         category,
         traceId,
@@ -22,5 +25,5 @@ export function handleSendAgentMessage(projectRoot: string, args: ToolArgs): Too
     fs.mkdirSync(path.dirname(messagePath), { recursive: true });
     fs.appendFileSync(messagePath, JSON.stringify(message) + "\n");
 
-    return { content: [{ type: "text", text: `✅ Message sent to ${to}` }] };
+    return { content: [{ type: "text", text: `✅ Message sent to ${to} (from: ${from})` }] };
 }

package/framework-mcp/src/tools/types.ts

@@ -32,6 +32,9 @@ export interface ToolArgs {
     status?: "SUCCESS" | "FAILURE";
     summary?: string;
     findings?: string;
+    allowMultiple?: boolean;
+    timeout?: number;
+    from?: string;
 }
 
 export interface ToolResult {

package/framework-mcp/src/utils/cli.ts

@@ -4,12 +4,12 @@ import { execFileSync } from "child_process";
  * Executes a CLI command safely using execFileSync (no shell injection risk).
  * Captures stderr gracefully to prevent stream crashes.
  */
-export function safeExec(command: string, args: string[], cwd: string): string {
+export function safeExec(command: string, args: string[], cwd: string, timeout?: number): string {
     try {
         return execFileSync(command, args, {
             cwd,
             encoding: "utf8",
-            timeout: 30000,
+            timeout: timeout || 30000,
             maxBuffer: 1024 * 1024,
             stdio: ["pipe", "pipe", "pipe"],
         });

package/framework-mcp/src/utils/security.ts

@@ -17,17 +17,35 @@ export function safePath(projectRoot: string, userPath: string): string {
 }
 
 /**
- * Resolves the active framework directory by scanning known candidates.
+ * Resolves the active framework directory.
+ * Priority: package.json `enderun.frameworkDir` → `.enderun` → adapter dirs.
+ * This ensures the canonical framework directory is always used,
+ * even when adapter-specific dirs (e.g. `.gemini`) exist alongside it.
  */
 export function resolveFrameworkDir(projectRoot: string): string {
+    // 1. Authoritative source: read from package.json if present
+    try {
+        const pkgPath = path.join(projectRoot, "package.json");
+        if (fs.existsSync(pkgPath)) {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8")) as Record<string, unknown>;
+            const enderunConfig = pkg["enderun"] as Record<string, unknown> | undefined;
+            if (enderunConfig && typeof enderunConfig["frameworkDir"] === "string") {
+                return enderunConfig["frameworkDir"];
+            }
+        }
+    } catch {
+        // ignore — fall through to filesystem scan
+    }
+
+    // 2. Filesystem scan — .enderun takes precedence over adapter-specific dirs
     const candidates = [
-        ".gemini/antigravity",
-        ".gemini/antigravity-cli",
-        ".gemini",
+        ".enderun",
         ".claude",
         ".grok",
         ".agent",
-        ".enderun",
+        ".gemini/antigravity",
+        ".gemini/antigravity-cli",
+        ".gemini",
     ];
 
     for (const candidate of candidates) {