agent-enderun 1.10.4 → 1.11.1

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

@@ -0,0 +1,89 @@
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+
+// ─── File System ────────────────────────────────────────────────
+export interface ReadFileArgs { path: string; startLine?: number; endLine?: number; }
+export interface WriteFileArgs { path: string; content: string; }
+export interface ReplaceTextArgs { path: string; oldText: string; newText: string; allowMultiple?: boolean; }
+export interface PatchFileArgs { path: string; startLine: number; endLine: number; newContent: string; }
+export interface BatchSurgicalEditArgs {
+    edits: Array<{ path: string; oldText: string; newText: string; allowMultiple?: boolean; }>;
+}
+
+// ─── Search & Discovery ──────────────────────────────────────────
+export interface ListDirArgs { path?: string; }
+export interface GrepSearchArgs { pattern: string; includePattern?: string; excludePattern?: string; }
+export interface GetProjectMapArgs { maxDepth?: number; includeFiles?: boolean; }
+export interface GetProjectGapsArgs { path?: string; }
+
+// ─── Messaging (Hermes) ─────────────────────────────────────────
+export interface SendAgentMessageArgs {
+    from: string;
+    to: string;
+    category: "ACTION" | "DELEGATION" | "SUBTASK" | "REPLY" | "ALERT";
+    content: string;
+    traceId: string;
+    parentId?: string;
+    priority?: "HIGH" | "NORMAL" | "LOW";
+    requiresApproval?: boolean;
+}
+export interface LogAgentActionArgs {
+    agent: string;
+    action: string;
+    traceId: string;
+    status: "SUCCESS" | "FAILURE";
+    summary: string;
+    findings?: string;
+}
+
+// ─── Control Plane ──────────────────────────────────────────────
+export interface AcquireLockArgs { resource: string; agent: string; ttl?: number; }
+export interface ReleaseLockArgs { resource: string; agent: string; }
+export interface RegisterAgentArgs { agent: string; role: string; capability?: number; }
+
+// ─── Observability & Utils ──────────────────────────────────────
+export interface StartDashboardArgs { port?: number; }
+export interface CheckActivePortsArgs { filter?: string; }
+export interface RunTestsArgs { command?: string; timeout?: number; }
+export interface UpdateProjectMemoryArgs { section: string; content: string; }
+export interface GetStatusArgs { timeout?: number; }
+export interface OrchestrateArgs { timeout?: number; }
+export interface UpdateContractHashArgs { timeout?: number; }
+export interface RunCommandArgs { command: string; }
+
+export type ToolArgs =
+    | ReadFileArgs
+    | WriteFileArgs
+    | ReplaceTextArgs
+    | PatchFileArgs
+    | BatchSurgicalEditArgs
+    | ListDirArgs
+    | GrepSearchArgs
+    | GetProjectMapArgs
+    | GetProjectGapsArgs
+    | SendAgentMessageArgs
+    | LogAgentActionArgs
+    | AcquireLockArgs
+    | ReleaseLockArgs
+    | RegisterAgentArgs
+    | StartDashboardArgs
+    | CheckActivePortsArgs
+    | RunTestsArgs
+    | UpdateProjectMemoryArgs
+    | GetStatusArgs
+    | OrchestrateArgs
+    | UpdateContractHashArgs;
+
+export interface ToolResult {
+    isError?: boolean;
+    content: Array<{ type: "text"; text: string }>;
+}
+
+export type ToolHandler = (projectRoot: string, args: unknown) => ToolResult | Promise<ToolResult>;

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

@@ -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: string, args: string[], cwd: string, timeout?: number): string {
+    try {
+        return execFileSync(command, args, {
+            cwd,
+            encoding: "utf8",
+            timeout: timeout || 30000,
+            maxBuffer: 1024 * 1024,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+    } catch (error: unknown) {
+        const err = error as { stderr?: string; message?: string };
+        throw new Error(err.stderr || err.message || "Command execution failed", { cause: error });
+    }
+}

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

@@ -0,0 +1,37 @@
+/**
+ * Enterprise Compliance Guardrail
+ * Checks content against corporate standards before allowing file mutations.
+ */
+export function verifyCorporateCompliance(content: string, filePath: string): void {
+    // 1. Zero Console Policy
+    if (content.includes("console.log(") || content.includes("console.warn(") || content.includes("console.error(")) {
+        if (!filePath.includes("logger.ts") && !filePath.includes("check.ts") && !filePath.includes("cli.ts")) {
+            throw new Error(
+                "❌ Corporate Compliance Breach: 'console.log/warn/error' usage is forbidden. " +
+                "Use the 'logger' system from '@/shared/logger' instead."
+            );
+        }
+    }
+
+    // 2. No Explicit Any Policy
+    const anyRegex = /[:<]\s*any\b|\bas\s+any\b/g;
+    if (anyRegex.test(content)) {
+        if (!filePath.includes("definitions.ts") && !filePath.includes("types.ts")) {
+            throw new Error(
+                "❌ Corporate Compliance Breach: 'any' type is forbidden. " +
+                "Use 'unknown', 'generics', or proper interfaces for type safety."
+            );
+        }
+    }
+
+    // 3. Hardcoded Secrets Guard (Simple heuristic)
+    const secretKeywords = [/API_KEY\s*=\s*['"][^'"]+['"]/i, /SECRET\s*=\s*['"][^'"]+['"]/i, /PASSWORD\s*=\s*['"][^'"]+['"]/i];
+    for (const regex of secretKeywords) {
+        if (regex.test(content) && !filePath.endsWith(".env.example")) {
+            throw new Error(
+                "❌ Corporate Compliance Breach: Hardcoded secrets detected. " +
+                "All sensitive data must be managed via '.env' files."
+            );
+        }
+    }
+}

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

@@ -0,0 +1,45 @@
+import fs from "fs";
+import path from "path";
+
+/**
+ * Ensures directory existence.
+ */
+export function ensureDir(dirPath: string): void {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+    }
+}
+
+/**
+ * Atomically writes a text file.
+ */
+export function writeTextFileAtomic(filePath: string, content: string): void {
+    const dir = path.dirname(filePath);
+    ensureDir(dir);
+
+    const tempPath = `${filePath}.${Math.random().toString(36).slice(2, 9)}.tmp`;
+    const finalContent = content.endsWith("\n") ? content : `${content}\n`;
+
+    try {
+        fs.writeFileSync(tempPath, finalContent, "utf8");
+        fs.renameSync(tempPath, filePath);
+    } catch (err) {
+        if (fs.existsSync(tempPath)) {
+            try { fs.unlinkSync(tempPath); } catch { /* ignore */ }
+        }
+        throw err;
+    }
+}
+
+/**
+ * Atomically appends to a file (if supported by OS) or simulates it.
+ * Note: Real atomic append on POSIX is a single write() call with O_APPEND.
+ * For simplicity and robustness across platforms, we use a simple append here
+ * as the risk of corruption is lower than a full rewrite, but for logs
+ * it's acceptable.
+ */
+export function appendFileSafe(filePath: string, content: string): void {
+    const dir = path.dirname(filePath);
+    ensureDir(dir);
+    fs.appendFileSync(filePath, content, "utf8");
+}

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

@@ -0,0 +1,73 @@
+import fs from "fs";
+import path from "path";
+import { resolveFrameworkDir } from "./security.js";
+/**
+ * Token and Metric Tracker for Agent Enderun.
+ * Estimates token usage and logs operational costs.
+ */
+
+interface MetricEntry {
+    timestamp: string;
+    agent: string;
+    action: string;
+    estimatedTokens: number;
+    error?: string;
+}
+
+export const Metrics = {
+    /**
+     * Estimates tokens based on character count (rough heuristic: 1 token ~= 4 chars).
+     */
+    estimateTokens: (text: string): number => {
+        return Math.ceil(text.length / 4);
+    },
+
+    /**
+     * Logs the token usage and action to the observability metrics file.
+     */
+    logUsage: (projectRoot: string, agent: string, action: string, tokens: number) => {
+        Metrics.saveMetric(projectRoot, {
+            timestamp: new Date().toISOString(),
+            agent,
+            action,
+            estimatedTokens: tokens
+        });
+    },
+
+    /**
+     * Logs an error occurrence to the observability metrics file.
+     */
+    logError: (projectRoot: string, agent: string, action: string, error: string) => {
+        Metrics.saveMetric(projectRoot, {
+            timestamp: new Date().toISOString(),
+            agent,
+            action: `ERROR: ${action}`,
+            estimatedTokens: 0,
+            error
+        });
+    },
+
+    /**
+     * Internal helper to save metric entries.
+     */
+    saveMetric: (projectRoot: string, entry: MetricEntry) => {
+        const frameworkDir = resolveFrameworkDir(projectRoot);
+        const metricsPath = path.join(projectRoot, frameworkDir, "observability/metrics.json");
+        try {
+            const metricsDir = path.dirname(metricsPath);
+            if (!fs.existsSync(metricsDir)) fs.mkdirSync(metricsDir, { recursive: true });
+
+            let currentMetrics: MetricEntry[] = [];
+            if (fs.existsSync(metricsPath)) {
+                currentMetrics = JSON.parse(fs.readFileSync(metricsPath, "utf8"));
+            }
+
+            currentMetrics.push(entry);
+
+            // Keep only last 100 entries to save space
+            if (currentMetrics.length > 100) currentMetrics.shift();
+
+            fs.writeFileSync(metricsPath, JSON.stringify(currentMetrics, null, 2));
+        } catch { /* ignore: metrics should not block the main process */ }
+    }
+};

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

@@ -0,0 +1,66 @@
+import path from "path";
+import fs from "fs";
+import { FRAMEWORK, MCP, UNIFIED_HUB_DIR } from "../constants.js"; // New import
+import os from "os"; // Need os.homedir()
+
+/**
+ * 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: string, userPath: string): string {
+    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: ENDERUN_TEST_DIR (env) -> package.json `enderun.frameworkDir` -> `.enderun` -> other adapter dirs -> global HOME.
+ */
+export function resolveFrameworkDir(projectRoot: string): string {
+    // For test environments, use the explicitly set test directory.
+    const testDir = process.env[MCP.TEST_DIR_ENV];
+    if (testDir) return testDir;
+
+    // 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") {
+                // Ensure the path is relative if it's within the project, otherwise use as-is.
+                const resolvedDir = path.resolve(projectRoot, enderunConfig["frameworkDir"]);
+                if (resolvedDir.startsWith(path.resolve(projectRoot))) {
+                    return path.relative(projectRoot, resolvedDir);
+                }
+                return enderunConfig["frameworkDir"];
+            }
+        }
+    } catch {
+        // ignore — fall through to filesystem scan
+    }
+
+    // 2. Filesystem scan in projectRoot for common framework directories
+    const localCandidates = [
+        FRAMEWORK.CORE_DIR, // .enderun
+        UNIFIED_HUB_DIR,    // .agents
+        // Add other adapter specific directories if needed, or remove if unified is strictly enforced
+    ];
+
+    for (const candidate of localCandidates) {
+        const candidatePath = path.join(projectRoot, candidate);
+        if (fs.existsSync(candidatePath)) {
+            return candidate;
+        }
+    }
+
+    // 3. Fallback to global home directory.
+    const homeDir = os.homedir();
+    return path.join(homeDir, FRAMEWORK.CORE_DIR);
+}

package/framework-mcp/tests/tools/file_system/file_system_tools.test.ts

@@ -0,0 +1,212 @@
+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";
+import { handlePatchFile } from "../../../src/tools/file_system/patch_file.js";
+import { handleReadFile } from "../../../src/tools/file_system/read_file.js";
+import { handleWriteFile } from "../../../src/tools/file_system/write_file.js";
+import { ToolArgs } from "../../../src/tools/types.js";
+
+import os from "os"; // Need to import os
+
+let TEST_DIR: string; // Declare as let
+let TEST_FILE: string;
+let MEMORY_DIR: string;
+let MEMORY_FILE: string;
+
+beforeEach(() => {
+    TEST_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "fs-tools-test-")); // Unique temp dir
+    fs.mkdirSync(path.join(TEST_DIR, ".enderun"));
+    TEST_FILE = path.join(TEST_DIR, "test_file.txt");
+    MEMORY_DIR = path.join(TEST_DIR, ".enderun/memory");
+    MEMORY_FILE = path.join(MEMORY_DIR, "PROJECT_MEMORY.md");
+});
+
+afterEach(() => {
+    fs.rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+describe("File System Tools", () => {
+    
+    describe("handleReplaceText", () => {
+        it("should replace a single occurrence of text", () => {
+            fs.writeFileSync(TEST_FILE, "hello world", "utf8");
+            const args: ToolArgs = {
+                path: TEST_FILE,
+                oldText: "world",
+                newText: "there",
+            };
+            const result = handleReplaceText(TEST_DIR, args as any);
+            expect(result.content[0].text).toContain("✅ Surgical edit successful in");
+            expect(fs.readFileSync(TEST_FILE, "utf8")).toBe("hello there\n");
+        });
+
+        it("should throw an error if text is not found", () => {
+            fs.writeFileSync(TEST_FILE, "hello world", "utf8");
+            const args: ToolArgs = {
+                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: ToolArgs = {
+                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: ToolArgs = {
+                path: TEST_FILE,
+                oldText: "world",
+                newText: "there",
+                allowMultiple: true,
+            };
+            const result = handleReplaceText(TEST_DIR, args as any);
+            expect(result.content[0].text).toContain("✅ Surgical edit successful in");
+            expect(fs.readFileSync(TEST_FILE, "utf8")).toBe("hello there there\n");
+        });
+
+        it("should log usage to metrics.json upon replace", () => {
+            fs.writeFileSync(TEST_FILE, "hello world", "utf8");
+            const args: ToolArgs = {
+                path: TEST_FILE,
+                oldText: "world",
+                newText: "there",
+            };
+            handleReplaceText(TEST_DIR, args);
+            const metricsPath = path.join(TEST_DIR, ".enderun/observability/metrics.json");
+            expect(fs.existsSync(metricsPath)).toBe(true);
+            const metrics = JSON.parse(fs.readFileSync(metricsPath, "utf8"));
+            expect(metrics[0].action).toContain("replace_text");
+        });
+    });
+
+    describe("handlePatchFile", () => {
+        it("should replace lines in specified range", () => {
+            fs.writeFileSync(TEST_FILE, "line1\nline2\nline3\nline4", "utf8");
+            const args: ToolArgs = {
+                path: TEST_FILE,
+                startLine: 2,
+                endLine: 3,
+                newContent: "patched2\npatched3",
+            };
+            const result = handlePatchFile(TEST_DIR, args);
+            expect(result.content[0].text).toContain("✅ File patched successfully");
+            expect(fs.readFileSync(TEST_FILE, "utf8")).toBe("line1\npatched2\npatched3\nline4");
+        });
+
+        it("should throw an error for invalid start line", () => {
+            fs.writeFileSync(TEST_FILE, "line1\nline2", "utf8");
+            const args: ToolArgs = {
+                path: TEST_FILE,
+                startLine: 5,
+                endLine: 2,
+                newContent: "error",
+            };
+            expect(() => handlePatchFile(TEST_DIR, args)).toThrowError("Invalid start line");
+        });
+
+        it("should throw an error for invalid end line", () => {
+            fs.writeFileSync(TEST_FILE, "line1\nline2", "utf8");
+            const args: ToolArgs = {
+                path: TEST_FILE,
+                startLine: 1,
+                endLine: 5,
+                newContent: "error",
+            };
+            expect(() => handlePatchFile(TEST_DIR, args)).toThrowError("Invalid end line");
+        });
+
+        it("should log usage to metrics.json upon patch", () => {
+            fs.writeFileSync(TEST_FILE, "line1\nline2\nline3\nline4", "utf8");
+            const args: ToolArgs = {
+                path: TEST_FILE,
+                startLine: 2,
+                endLine: 3,
+                newContent: "patched2\npatched3",
+            };
+            handlePatchFile(TEST_DIR, args as any);
+            const metricsPath = path.join(TEST_DIR, ".enderun/observability/metrics.json");
+            expect(fs.existsSync(metricsPath)).toBe(true);
+            const metrics = JSON.parse(fs.readFileSync(metricsPath, "utf8"));
+            expect(metrics[0].action).toContain("patch_file");
+        });
+    });
+
+    describe("handleReadFile", () => {
+        it("should read full file content", () => {
+            fs.writeFileSync(TEST_FILE, "hello world", "utf8");
+            const args: ToolArgs = { path: TEST_FILE };
+            const result = handleReadFile(TEST_DIR, args as any);
+            expect(result.content[0].text).toBe("hello world");
+        });
+
+        it("should read sliced lines", () => {
+            fs.writeFileSync(TEST_FILE, "line1\nline2\nline3\nline4", "utf8");
+            const args: ToolArgs = {
+                path: TEST_FILE,
+                startLine: 2,
+                endLine: 3
+            };
+            const result = handleReadFile(TEST_DIR, args as any);
+            expect(result.content[0].text).toBe("line2\nline3");
+        });
+
+        it("should truncate long files", () => {
+            const longContent = Array.from({ length: 1005 }, (_, i) => `line ${i + 1}`).join("\n");
+            fs.writeFileSync(TEST_FILE, longContent, "utf8");
+            const args: ToolArgs = { path: TEST_FILE };
+            const result = handleReadFile(TEST_DIR, args as any);
+            expect(result.content[0].text).toContain("TRUNCATED");
+            expect(result.content[0].text).toContain("line 1000");
+            expect(result.content[0].text).not.toContain("line 1001");
+        });
+    });
+
+    describe("handleWriteFile", () => {
+        it("should write new file and log usage", () => {
+            const args: ToolArgs = {
+                path: TEST_FILE,
+                content: "hello world"
+            };
+            const result = handleWriteFile(TEST_DIR, args);
+            expect(result.content[0].text).toContain("✅ File written:");
+            expect(fs.readFileSync(TEST_FILE, "utf8")).toBe("hello world\n");
+        });
+
+        it("should write new file and log usage to metrics.json", () => {
+            const args: ToolArgs = {
+                path: TEST_FILE,
+                content: "hello world"
+            };
+            handleWriteFile(TEST_DIR, args);
+            const metricsPath = path.join(TEST_DIR, ".enderun/observability/metrics.json");
+            expect(fs.existsSync(metricsPath)).toBe(true);
+            const metrics = JSON.parse(fs.readFileSync(metricsPath, "utf8"));
+            expect(metrics[0].action).toContain("write_file");
+            expect(metrics[0].estimatedTokens).toBeGreaterThan(0);
+        });
+
+        it("should append update to PROJECT_MEMORY.md if it exists", () => {
+            fs.mkdirSync(MEMORY_DIR, { recursive: true });
+            fs.writeFileSync(MEMORY_FILE, "## CURRENT STATUS\n", "utf8");
+            const args: ToolArgs = {
+                path: TEST_FILE,
+                content: "hello world"
+            };
+            handleWriteFile(TEST_DIR, args);
+            const memoryContent = fs.readFileSync(MEMORY_FILE, "utf8");
+            expect(memoryContent).toContain("Auto-Update");
+            expect(memoryContent).toContain("wrote file");
+        });
+    });
+});

package/framework-mcp/tests/tools/messaging/send_message.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs";
+import path from "path";
+import { handleSendAgentMessage } from "../../../src/tools/messaging/send_message.js";
+import { ToolArgs } from "../../../src/tools/types.js";
+
+const TEST_DIR = path.resolve(__dirname, "../../_temp_messaging_tests");
+const MESSAGES_DIR = path.join(TEST_DIR, ".gemini/messages");
+const BACKEND_LOCK_FILE = path.join(MESSAGES_DIR, "backend.lock");
+
+beforeEach(() => {
+    fs.mkdirSync(TEST_DIR, { recursive: true });
+    // Write a dummy package.json to test directory to lock frameworkDir as .gemini
+    const dummyPkg = {
+        name: "test-pkg",
+        enderun: {
+            frameworkDir: ".gemini"
+        }
+    };
+    fs.writeFileSync(path.join(TEST_DIR, "package.json"), JSON.stringify(dummyPkg, null, 2), "utf8");
+});
+
+afterEach(() => {
+    fs.rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+describe("Hermes Lock Protocol & Message sending", () => {
+    it("should successfully send message when lock is not present", async () => {
+        const args: ToolArgs = {
+            to: "@backend",
+            from: "@manager",
+            category: "ACTION",
+            content: "Build database models",
+            traceId: "T-123",
+            priority: "HIGH"
+        };
+
+        const result = await handleSendAgentMessage(TEST_DIR, args);
+        expect(result.content[0].text).toContain("✅ Message sent to @backend");
+
+        // Verify the message file contains the sent message
+        const messageFilePath = path.join(MESSAGES_DIR, "backend.json");
+        expect(fs.existsSync(messageFilePath)).toBe(true);
+
+        const content = fs.readFileSync(messageFilePath, "utf8");
+        const msg = JSON.parse(content.trim());
+        expect(msg.from).toBe("@manager");
+        expect(msg.to).toBe("@backend");
+        expect(msg.category).toBe("ACTION");
+        expect(msg.content).toBe("Build database models");
+        expect(msg.traceId).toBe("T-123");
+        expect(msg.priority).toBe("HIGH");
+        expect(msg.status).toBe("PENDING");
+    });
+
+    it("should retry and fail to send message if lock is kept busy", async () => {
+        // Prepare a busy lock file
+        fs.mkdirSync(MESSAGES_DIR, { recursive: true });
+        fs.writeFileSync(BACKEND_LOCK_FILE, "Locked by @test at " + new Date().toISOString(), "utf8");
+
+        const args: ToolArgs = {
+            to: "@backend",
+            from: "@manager",
+            category: "ACTION",
+            content: "Build database models",
+            traceId: "T-123"
+        };
+
+        const startTime = Date.now();
+        const result = await handleSendAgentMessage(TEST_DIR, args);
+        const duration = Date.now() - startTime;
+
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain("❌ Could not send message to @backend: Hermes lock is busy.");
+        // Retries takes 3 attempts with 500ms delay -> duration should be at least ~1000ms
+        expect(duration).toBeGreaterThanOrEqual(1000);
+    });
+
+    it("should bypass and acquire lock if existing lock is stale (older than 5s)", async () => {
+        fs.mkdirSync(MESSAGES_DIR, { recursive: true });
+        // Set lock file mtime to 10 seconds ago
+        fs.writeFileSync(BACKEND_LOCK_FILE, "Locked by @test at " + new Date().toISOString(), "utf8");
+        const tenSecondsAgo = new Date(Date.now() - 10000);
+        fs.utimesSync(BACKEND_LOCK_FILE, tenSecondsAgo, tenSecondsAgo);
+
+        const args: ToolArgs = {
+            to: "@backend",
+            from: "@manager",
+            category: "ACTION",
+            content: "Build database models",
+            traceId: "T-123"
+        };
+
+        const result = await handleSendAgentMessage(TEST_DIR, args);
+        expect(result.content[0].text).toContain("✅ Message sent to @backend");
+        expect(fs.existsSync(BACKEND_LOCK_FILE)).toBe(false); // Lock should have been unlinked in finally
+    });
+
+    it("should safely resolve concurrent messages and execute them in sequence", async () => {
+        const send1Promise = handleSendAgentMessage(TEST_DIR, {
+            to: "@backend",
+            from: "@manager",
+            category: "ACTION",
+            content: "Job 1",
+            traceId: "T-123"
+        });
+
+        // Delay starting the second call slightly to make sure lock is acquired by Job 1 first
+        await new Promise((resolve) => setTimeout(resolve, 50));
+
+        const send2Promise = handleSendAgentMessage(TEST_DIR, {
+            to: "@backend",
+            from: "@frontend",
+            category: "ACTION",
+            content: "Job 2",
+            traceId: "T-123"
+        });
+
+        const [res1, res2] = await Promise.all([send1Promise, send2Promise]);
+
+        expect(res1.isError).toBeFalsy();
+        expect(res2.isError).toBeFalsy();
+        expect(res1.content[0].text).toContain("✅ Message sent to @backend");
+        expect(res2.content[0].text).toContain("✅ Message sent to @backend");
+
+        // Verify both messages exist in order in the message log file
+        const messageFilePath = path.join(MESSAGES_DIR, "backend.json");
+        const lines = fs.readFileSync(messageFilePath, "utf8").trim().split("\n");
+        expect(lines.length).toBe(2);
+
+        const msg1 = JSON.parse(lines[0]);
+        const msg2 = JSON.parse(lines[1]);
+        expect(msg1.content).toBe("Job 1");
+        expect(msg2.content).toBe("Job 2");
+    });
+});