Pre-PR Checklist

• This PR is a bug fix, not a new feature or enhancement.

Summary

MetaAgent.remove() leaves stale meta_agents and meta_agent references on constituent agents after the meta-agent is removed from the model.

Bug / Issue

• MetaAgent.__init__ sets agent.meta_agents.add(self) and agent.meta_agent = self on every constituent
• Agent.remove() only calls model.deregister_agent(self) — no cleanup of constituent references
• MetaAgent had no remove() override, so constituent agents keep dangling pointers to a dead meta-agent
• Relates to lifecycle concerns in discussion Meta-Agents Refactor (GSOC related) #3403

Implementation

• Override remove() in MetaAgent to call remove_constituting_agents() on all constituents before super().remove()
• Reuses existing cleanup logic that already handles meta_agents set removal and meta_agent pointer updates
• Also fixes incorrect return type hint on get_constituting_agent_instance: was -> set[type], actually returns -> Agent

Testing

Added two tests:

• test_meta_agent_remove_cleans_up_references — all constituents have clean references after removal
• test_meta_agent_remove_with_multiple_memberships — removing one meta-agent preserves the other's references correctly

All 22 meta-agent tests pass.

Additional Notes

None.

GSoC contributor checklist

Context & motivation

While working on meta-agent bugs from #3184, I traced what happens when a MetaAgent is removed from the model. I realized that Agent.remove() just deregisters from the model but never cleans up the references that MetaAgent.__init__ wrote onto constituent agents. This means after removal, constituents still think they belong to a dead group. This is a real problem for any model with dynamic group formation and dissolution, which is the core use case for meta-agents.

What I learned

The fix turned out to be simple — just override remove() and call the existing remove_constituting_agents() before super().remove(). The harder part was verifying the edge case where an agent belongs to two meta-agents and one is removed — the surviving references need to stay intact. I also noticed the return type hint on get_constituting_agent_instance was wrong (set[type] instead of Agent), so I fixed that too.

Learning repo

My learning repo: https://github.com/codebyNJ/GSoC-learning-space

Readiness checks

• This PR addresses an agreed-upon problem (lifecycle cleanup, discussion Meta-Agents Refactor (GSOC related) #3403)
• I have read the contributing guide and deprecation policy
• I have performed a self-review
• Tests pass locally (pytest --cov=mesa tests/)
• Code is formatted (ruff check . --fix)