cortivex-mesh-coordination

Cortivex Mesh Coordination (Enhanced)

This skill extends the base cortivex-mesh protocol with MeshResolver node capabilities, automated conflict detection, and resolution strategies adapted from SWARM's coordination patterns. While cortivex-mesh defines the file ownership protocol that every agent must follow, this skill adds the orchestration layer that detects, prevents, and resolves conflicts across the agent pool.

Overview

In multi-agent pipelines, file conflicts are inevitable. Two agents may need the same file, an agent may hold a claim too long, or a complex refactor may touch files that another agent is reviewing. The MeshResolver node sits alongside the SwarmCoordinator and actively manages these situations:

• Detects potential conflicts before they occur by analyzing task scopes
• Prevents conflicts by pre-allocating file ownership based on task assignments
• Resolves conflicts using configurable strategies when they do occur
• Detects deadlocks when two agents are each waiting for files held by the other

When to Use

• Pipelines with 3+ agents that may modify overlapping files
• Refactoring or migration pipelines that touch many files across the codebase
• When agents have long-running tasks and file claims may expire before completion
• Pipelines where conflict-related failures have occurred in previous runs
• Any orchestrated pipeline where you want proactive conflict management rather than reactive error handling

You do NOT need a MeshResolver for:

• Pipelines where agents work on strictly separate file sets
• Read-only analysis pipelines (no file modifications)
• Single-agent pipelines

How It Works

Conflict Detection

The MeshResolver continuously monitors the mesh state and detects conflicts in three categories:

1. Direct Conflicts -- Two agents attempt to claim the same file simultaneously.

Agent A claims src/auth/login.ts for "auto-fixing"
Agent B claims src/auth/login.ts for "refactoring"
--> MeshResolver detects: direct conflict on src/auth/login.ts

2. Scope Overlaps -- Two agents' task scopes cover the same directory or module, creating a high probability of future conflicts.

Agent A assigned to "refactor src/auth/ module"
Agent B assigned to "add input validation to src/auth/ endpoints"
--> MeshResolver detects: scope overlap on src/auth/

3. Deadlocks -- Two or more agents are each waiting for files held by the other, creating a circular wait.

Agent A holds src/auth/login.ts, waiting for src/auth/session.ts
Agent B holds src/auth/session.ts, waiting for src/auth/login.ts
--> MeshResolver detects: deadlock between Agent A and Agent B

Resolution Strategies

The MeshResolver supports five resolution strategies, configured per-pipeline or per-conflict:

| Strategy | Behavior | Best For | |----------|----------|----------| | priority | Higher-priority task wins; lower-priority agent releases its claim | Tasks with clear priority differences | | first-claim | The agent that claimed first keeps the file; the other waits | Fair ordering; equal-priority tasks | | preempt | The coordinator forcibly releases one agent's claim | Time-critical situations | | partition | The MeshResolver splits the file scope so each agent works on a subset | Large refactors touching many files | | serialize | One agent completes fully before the other begins on the contested files | When parallel work on the same files is unsafe |

Deadlock Resolution

When a deadlock is detected, the MeshResolver:

1. Identifies the cycle of waiting agents
2. Selects the agent with the lowest-priority task as the "victim"
3. Forcibly releases the victim's claim
4. Requeues the victim's task with status ready
5. Broadcasts a deadlock_resolved event to all agents
6. Logs the deadlock for post-run analysis

Pre-Allocation

Before agents begin work, the MeshResolver can analyze all task assignments and pre-allocate file ownership to prevent conflicts entirely:

cortivex_mesh_resolver({
  action: "pre_allocate",
  tasks: [
    { task_id: "task-1", agent_id: "agent-1", files: ["src/auth/login.ts", "src/auth/session.ts"] },
    { task_id: "task-2", agent_id: "agent-2", files: ["src/api/routes.ts", "src/api/middleware.ts"] },
    { task_id: "task-3", agent_id: "agent-3", files: ["src/auth/session.ts", "src/models/user.ts"] }
  ]
})

Response:

{
  "status": "conflicts_detected",
  "conflicts": [
    {
      "file": "src/auth/session.ts",
      "agents": ["agent-1", "agent-3"],
      "tasks": ["task-1", "task-3"]
    }
  ],
  "resolution": {
    "strategy": "serialize",
    "order": ["task-1", "task-3"],
    "reason": "task-1 has higher priority (8) than task-3 (6)"
  },
  "allocation": {
    "agent-1": ["src/auth/login.ts", "src/auth/session.ts"],
    "agent-2": ["src/api/routes.ts", "src/api/middleware.ts"],
    "agent-3": ["src/models/user.ts"]
  },
  "deferred": {
    "agent-3": {
      "files": ["src/auth/session.ts"],
      "available_after": "task-1 completes"
    }
  }
}

Pipeline Configuration

Adding a MeshResolver to an Orchestrated Pipeline

name: conflict-aware-refactor
version: "1.0"
description: Multi-agent refactor with proactive conflict resolution
nodes:
  - id: coordinator
    type: SwarmCoordinator
    config:
      pool_size: 4
      runtime: auto
      task_strategy: priority-queue

  - id: resolver
    type: MeshResolver
    depends_on: [coordinator]
    config:
      strategy: priority
      deadlock_detection: true
      deadlock_check_interval_seconds: 10
      pre_allocate: true
      stale_claim_timeout_seconds: 300
      max_wait_seconds: 60
      on_conflict: resolve
      on_deadlock: release_lowest
      log_conflicts: true

  - id: monitor
    type: AgentMonitor
    depends_on: [coordinator]
    config:
      auto_recovery: true

  - id: analyze
    type: ArchitectAnalyzer
    depends_on: [resolver]
    config:
      target_path: src/
      managed_by: coordinator

  - id: refactor_auth
    type: RefactorAgent
    depends_on: [analyze]
    config:
      target_path: src/auth/
      managed_by: coordinator
      mesh_aware: true

  - id: refactor_api
    type: RefactorAgent
    depends_on: [analyze]
    config:
      target_path: src/api/
      managed_by: coordinator
      mesh_aware: true

  - id: refactor_models
    type: RefactorAgent
    depends_on: [analyze]
    config:
      target_path: src/models/
      managed_by: coordinator
      mesh_aware: true

  - id: test_run
    type: TestRunner
    depends_on: [refactor_auth, refactor_api, refactor_models]
    config:
      test_command: npm test
      coverage_threshold: 80

MeshResolver with Partition Strategy

For large-scale migrations where many agents need to touch many files:

name: large-migration
version: "1.0"
description: TypeScript migration with file partitioning
nodes:
  - id: coordinator
    type: SwarmCoordinator
    config:
      pool_size: 5
      runtime: auto

  - id: resolver
    type: MeshResolver
    depends_on: [coordinator]
    config:
      strategy: partition
      partition_method: directory
      pre_allocate: true
      deadlock_detection: true

  - id: analyze
    type: ArchitectAnalyzer
    depends_on: [resolver]
    config:
      target_path: src/
      managed_by: coordinator

  - id: migrate
    type: TypeMigrator
    depends_on: [analyze]
    config:
      source_dir: src/
      managed_by: coordinator
      mesh_aware: true
      batch_size: 10

  - id: test
    type: TestRunner
    depends_on: [migrate]
    config:
      test_command: npx tsc --noEmit && npm test

With partition strategy, the MeshResolver divides src/ into non-overlapping directory partitions and assigns each to a different agent instance, preventing any possibility of file conflicts.

Conflict Event Flow

When a conflict occurs during execution, the following sequence plays out:

1. Agent B calls cortivex_mesh({ action: