feat: Multi-agent orchestration with Squad integration

.github/copilot-instructions.md

@@ -56,6 +56,17 @@ For Android, always run `adb reverse tcp:9223 tcp:9223` after deploy.
 
 ## Architecture
 
+**See `docs/multi-agent-orchestration.md` for the multi-agent architecture spec** (orchestration modes, reflection loop, sentinel protocol, invariants, Squad integration). Test scenarios in `PolyPilot.Tests/Scenarios/multi-agent-scenarios.json`. Read these before modifying orchestration, reconciliation, or TCS completion logic.
+
+### Squad Integration
+PolyPilot discovers [bradygaster/squad](https://github.com/bradygaster/squad) team definitions from `.squad/` (or legacy `.ai-team/`) directories in the worktree root. Each agent's `charter.md` becomes a worker system prompt, `team.md` defines the roster, `decisions.md` provides shared context injected into all worker prompts, and `routing.md` is injected into the orchestrator's planning prompt. Repo-level teams appear in a **"📂 From Repo"** section in the preset picker, above built-in presets.
+
+**Squad write-back:** When saving a multi-agent group as a preset, PolyPilot writes the team definition back to `.squad/` format in the worktree root via `SquadWriter`. This creates `team.md`, `agents/{name}/charter.md`, and optional `decisions.md`/`routing.md`. The preset is also saved to `presets.json` as a personal backup. This enables round-tripping: discover → modify → save back → share via repo.
+
+**Preset priority (three-tier merge):** Built-in presets < User presets (`~/.polypilot/presets.json`) < Repo teams (`.squad/`). Repo teams shadow presets with the same name. The preset picker shows three sections: "📂 From Repo", "⚙️ Built-in", and "👤 My Presets".
+
+**Group deletion:** Deleting a multi-agent team closes and removes all its sessions (they're meaningless without the team). Deleting a regular group moves sessions to the default group.
+
 This is a .NET MAUI Blazor Hybrid app targeting Mac Catalyst, Android, and iOS. It manages multiple GitHub Copilot CLI sessions through a native GUI.
 
 ### Three-Layer Stack

PolyPilot.Tests/BridgeMessageTests.cs

@@ -457,4 +457,74 @@ public void AttentionNeededPayload_AllReasons_RoundTrip(AttentionReason reason)
 
         Assert.Equal(reason, restored!.Reason);
     }
+
+    [Fact]
+    public void MultiAgentBroadcastPayload_RoundTrips()
+    {
+        var payload = new MultiAgentBroadcastPayload
+        {
+            GroupId = "group-123",
+            Message = "Build the feature"
+        };
+        var msg = BridgeMessage.Create(BridgeMessageTypes.MultiAgentBroadcast, payload);
+        var json = msg.Serialize();
+        var restored = BridgeMessage.Deserialize(json)!.GetPayload<MultiAgentBroadcastPayload>();
+
+        Assert.NotNull(restored);
+        Assert.Equal("group-123", restored!.GroupId);
+        Assert.Equal("Build the feature", restored.Message);
+    }
+
+    [Fact]
+    public void MultiAgentCreateGroupPayload_RoundTrips()
+    {
+        var payload = new MultiAgentCreateGroupPayload
+        {
+            Name = "Dev Team",
+            Mode = "Orchestrator",
+            OrchestratorPrompt = "Coordinate the workers",
+            SessionNames = new List<string> { "session-1", "session-2" }
+        };
+        var msg = BridgeMessage.Create(BridgeMessageTypes.MultiAgentCreateGroup, payload);
+        var json = msg.Serialize();
+        var restored = BridgeMessage.Deserialize(json)!.GetPayload<MultiAgentCreateGroupPayload>();
+
+        Assert.NotNull(restored);
+        Assert.Equal("Dev Team", restored!.Name);
+        Assert.Equal("Orchestrator", restored.Mode);
+        Assert.Equal("Coordinate the workers", restored.OrchestratorPrompt);
+        Assert.Equal(2, restored.SessionNames!.Count);
+        Assert.Contains("session-1", restored.SessionNames);
+    }
+
+    [Fact]
+    public void MultiAgentProgressPayload_RoundTrips()
+    {
+        var payload = new MultiAgentProgressPayload
+        {
+            GroupId = "group-1",
+            TotalSessions = 3,
+            CompletedSessions = 1,
+            ProcessingSessions = 2,
+            CompletedSessionNames = new List<string> { "worker-1" }
+        };
+        var msg = BridgeMessage.Create(BridgeMessageTypes.MultiAgentProgress, payload);
+        var json = msg.Serialize();
+        var restored = BridgeMessage.Deserialize(json)!.GetPayload<MultiAgentProgressPayload>();
+
+        Assert.NotNull(restored);
+        Assert.Equal("group-1", restored!.GroupId);
+        Assert.Equal(3, restored.TotalSessions);
+        Assert.Equal(1, restored.CompletedSessions);
+        Assert.Equal(2, restored.ProcessingSessions);
+        Assert.Single(restored.CompletedSessionNames);
+    }
+
+    [Fact]
+    public void MultiAgentMessageTypes_AreCorrectStrings()
+    {
+        Assert.Equal("multi_agent_broadcast", BridgeMessageTypes.MultiAgentBroadcast);
+        Assert.Equal("multi_agent_create_group", BridgeMessageTypes.MultiAgentCreateGroup);
+        Assert.Equal("multi_agent_progress", BridgeMessageTypes.MultiAgentProgress);
+    }
 }

PolyPilot.Tests/MultiAgentGapTests.cs

@@ -0,0 +1,183 @@
+using PolyPilot.Models;
+using PolyPilot.Services;
+
+namespace PolyPilot.Tests;
+
+/// <summary>
+/// Gap-coverage tests for multi-agent parsing, model capabilities, and reflection summaries.
+/// </summary>
+public class MultiAgentGapTests
+{
+    // --- ParseTaskAssignments ---
+
+    [Fact]
+    public void ParseTaskAssignments_EmptyInput_ReturnsEmpty()
+    {
+        var result = CopilotService.ParseTaskAssignments("", new List<string> { "a", "b" });
+        Assert.Empty(result);
+    }
+
+    [Fact]
+    public void ParseTaskAssignments_SingleWorker_ExtractsTask()
+    {
+        var response = "@worker:alpha\nDo the thing.\n@end";
+        var result = CopilotService.ParseTaskAssignments(response, new List<string> { "alpha" });
+
+        Assert.Single(result);
+        Assert.Equal("alpha", result[0].WorkerName);
+        Assert.Contains("Do the thing", result[0].Task);
+    }
+
+    [Fact]
+    public void ParseTaskAssignments_MultipleWorkers_ExtractsAll()
+    {
+        var response = @"@worker:w1
+Task one.
+@end
+@worker:w2
+Task two.
+@end
+@worker:w3
+Task three.
+@end";
+        var workers = new List<string> { "w1", "w2", "w3" };
+        var result = CopilotService.ParseTaskAssignments(response, workers);
+
+        Assert.Equal(3, result.Count);
+        Assert.Equal("w1", result[0].WorkerName);
+        Assert.Equal("w2", result[1].WorkerName);
+        Assert.Equal("w3", result[2].WorkerName);
+    }
+
+    [Fact]
+    public void ParseTaskAssignments_FuzzyMatch_FindsClosestWorker()
+    {
+        // "coder" is a substring of "coder-session" → fuzzy match
+        var response = "@worker:coder\nWrite the code.\n@end";
+        var result = CopilotService.ParseTaskAssignments(response, new List<string> { "coder-session", "reviewer-session" });
+
+        Assert.Single(result);
+        Assert.Equal("coder-session", result[0].WorkerName);
+    }
+
+    [Fact]
+    public void ParseTaskAssignments_UnknownWorker_IsIgnored()
+    {
+        var response = "@worker:ghost\nDo something.\n@end";
+        var result = CopilotService.ParseTaskAssignments(response, new List<string> { "alpha", "beta" });
+
+        Assert.Empty(result);
+    }
+
+    [Fact]
+    public void ParseTaskAssignments_DuplicateWorker_TakesLast()
+    {
+        var response = @"@worker:alpha
+First task.
+@end
+@worker:alpha
+Second task.
+@end";
+        var result = CopilotService.ParseTaskAssignments(response, new List<string> { "alpha" });
+
+        // The regex matches both blocks; both are added (last one wins in practice)
+        Assert.Equal(2, result.Count);
+        Assert.Contains("Second task", result[^1].Task);
+    }
+
+    // --- ModelCapabilities ---
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    public void GetCapabilities_NullOrEmpty_ReturnsNone(string? slug)
+    {
+        var caps = ModelCapabilities.GetCapabilities(slug!);
+        Assert.Equal(ModelCapability.None, caps);
+    }
+
+    [Fact]
+    public void GetCapabilities_KnownModel_ReturnsFlags()
+    {
+        var caps = ModelCapabilities.GetCapabilities("gpt-5");
+        Assert.True(caps.HasFlag(ModelCapability.ReasoningExpert));
+        Assert.True(caps.HasFlag(ModelCapability.CodeExpert));
+        Assert.True(caps.HasFlag(ModelCapability.ToolUse));
+    }
+
+    [Fact]
+    public void GetRoleWarnings_UnknownModel_ReturnsWarning()
+    {
+        var warnings = ModelCapabilities.GetRoleWarnings("totally-unknown-model", MultiAgentRole.Worker);
+        Assert.NotEmpty(warnings);
+        Assert.Contains(warnings, w => w.Contains("Unknown model", StringComparison.OrdinalIgnoreCase));
+    }
+
+    [Fact]
+    public void GetRoleWarnings_WeakOrchestrator_ReturnsWarning()
+    {
+        // claude-haiku-4.5 is CostEfficient + Fast but not ReasoningExpert
+        var warnings = ModelCapabilities.GetRoleWarnings("claude-haiku-4.5", MultiAgentRole.Orchestrator);
+        Assert.NotEmpty(warnings);
+        Assert.Contains(warnings, w => w.Contains("reasoning", StringComparison.OrdinalIgnoreCase));
+    }
+
+    // --- BuildCompletionSummary ---
+
+    [Fact]
+    public void BuildCompletionSummary_GoalMet_ShowsCheckmark()
+    {
+        var cycle = ReflectionCycle.Create("Ship the feature", maxIterations: 5);
+        cycle.Advance("Done!\n[[REFLECTION_COMPLETE]]");
+
+        var summary = cycle.BuildCompletionSummary();
+
+        Assert.Contains("✅", summary);
+        Assert.Contains("Goal met", summary);
+    }
+
+    [Fact]
+    public void BuildCompletionSummary_Stalled_ShowsWarning()
+    {
+        var cycle = ReflectionCycle.Create("Improve quality", maxIterations: 10);
+        // Feed identical responses to trigger stall detection
+        cycle.Advance("Working on the task with specific details about implementation");
+        cycle.Advance("Working on the task with specific details about implementation");
+        cycle.Advance("Working on the task with specific details about implementation");
+
+        var summary = cycle.BuildCompletionSummary();
+
+        // IsStalled takes priority over IsCancelled in the ternary chain
+        Assert.Contains("⚠️", summary);
+        Assert.Contains("Stalled", summary);
+        Assert.DoesNotContain("⏹️", summary);
+    }
+
+    [Fact]
+    public void BuildCompletionSummary_Cancelled_ShowsStop()
+    {
+        var cycle = ReflectionCycle.Create("Long task", maxIterations: 10);
+        cycle.Advance("First attempt with unique content here...");
+        cycle.IsCancelled = true;
+        cycle.IsActive = false;
+
+        var summary = cycle.BuildCompletionSummary();
+
+        Assert.Contains("⏹️", summary);
+        Assert.Contains("Cancelled", summary);
+    }
+
+    [Fact]
+    public void BuildCompletionSummary_MaxIterations_ShowsClock()
+    {
+        var cycle = ReflectionCycle.Create("Goal", maxIterations: 2);
+        cycle.Advance("Trying with approach alpha...");
+        cycle.Advance("Still trying with approach beta and new ideas...");
+
+        var summary = cycle.BuildCompletionSummary();
+
+        Assert.Contains("⏱️", summary);
+        Assert.Contains("Max iterations", summary);
+        Assert.Contains("2/2", summary);
+    }
+}