feat: Deep Squad Integration — Phase 1 & 2 (#436)

[PureWeen]

Deep Squad Integration (Issue #436)

This PR implements Phase 1 (Squad as Config) and Phase 2 (Squad as Runtime) of the Squad integration roadmap.

---

How Users Use This Feature

Mode 1: Squad as Config (Phase 1)

Use when you want PP's multi-agent orchestrator with Squad's team definitions and skills.

# 1. Initialize Squad in your repo
cd your-repo
squad init --no-workflows

# 2. Open PolyPilot → pick your repo worktree
# 3. Your Squad team appears under "📂 From Repo" in the preset picker
#    with metadata badges: 🛠️ skills count, 🔗 upstream connections, ⚠️ config.ts warning
# 4. Click the preset → PP creates a multi-agent group with Squad's agent charters
# 5. Squad's 29 skills are auto-injected into each session's context

Squad owns: team definitions, skills, MCP config, upstream registry.
PP owns: orchestration, session lifecycle, UI rendering.

Or click "Set up Squad" in the preset picker to run squad init --no-workflows directly from PolyPilot.

Mode 2: Squad as Runtime (Phase 2)

Use when you want Squad's full runtime — coordinator persona, casting, event bus, history.

# 1. Start Squad's RemoteBridge
cd your-repo
squad rc --port 4242

# 2. Configure the provider (env vars or config file)
export SQUAD_BRIDGE_PORT=4242
export SQUAD_BRIDGE_TOKEN=<session-token-from-squad>

# 3. Load the SquadSessionProvider plugin in PolyPilot
# → "🫡 Squad" group appears in sidebar with live agent roster
# → Send prompts — Squad's coordinator routes to workers
# → Tool calls stream in real-time
# → Permission requests pop for approve/deny
# → Custom actions: /status, /nap, /cast, /economy

Squad owns: everything (orchestration, agents, tools, history).
PP owns: native UI, mobile access, permission approval.

Mobile: squad rc --tunnel + PP mobile QR scanner → approve permissions from phone.

---

What's Included

Phase 1 — Squad as Config (7 features)

1. Project-level MCP config — LoadMcpServers() merges project-local .copilot/mcp-config.json
2. Squad metadata surfacing — reads manifest.json, upstream.json, identity/now.md from .squad/
3. Squad initialized badge — detects .squad/team.md + .copilot/skills/ and shows ✅ badge
4. Set up Squad button — runs squad init --no-workflows from preset picker (with 60s timeout)
5. Skills source labels — tags Squad-provided vs project-specific skills
6. SquadWriter safety — rejects writes when squad.config.ts exists
7. Upstream visualization — manifest description + upstream entries in preset picker

Phase 2 — Squad as Runtime (4 components)

1. SquadSessionProvider — Full IPermissionAwareProvider implementation mapping Squad's RC protocol:

   • RCDeltaEvent → OnContentReceived / OnMemberContentReceived
   • RCAgentsEvent → GetMembers() with live status (idle/working/streaming)
   • RCToolCallEvent → OnToolStarted / OnToolCompleted (with correlated callIds)
   • RCPermissionEvent → OnPermissionRequested → approve/deny flow
   • RCCompleteEvent → history + OnTurnEnd
   • Protocol version check on connect (warns on major mismatch)

2. SquadBridgeClient — WebSocket client with:

   • Ticket-based authentication (one-time tickets via HTTP POST)
   • SemaphoreSlim for thread-safe concurrent sends
   • 4MB max message size (DoS protection)
   • 30s keepalive pings
   • Graceful disconnect with loop await

3. SquadProviderFactory — DI factory with env var + JSON file config

4. IPermissionAwareProvider — Extension interface in Provider.Abstractions for permission approval flows

Review Fixes (21 findings addressed)

• Thread safety: SemaphoreSlim for WS sends, lock+snapshot for lists, Interlocked for init
• Security: 4MB message cap, no token in URL, port validation
• Reliability: loop await on disconnect, client cleanup on failure, idempotent connect
• UX: 60s timeout for squad init, result feedback rendering

---

Files Changed

Area	Files
Squad Provider Plugin	PolyPilot.Provider.Squad/ — SquadProtocol.cs, SquadBridgeClient.cs, SquadSessionProvider.cs, SquadProviderFactory.cs
Provider Abstractions	IPermissionAwareProvider.cs, ProviderPermissionRequest.cs
Phase 1 Features	SquadDiscovery.cs (metadata), SessionSidebar.razor (UI), CopilotService.cs (MCP merge), SquadWriter.cs (safety)
Permission Wiring	CopilotService.Providers.cs (permission event wiring)
Tests	48 new tests in SquadProviderTests.cs + existing tests across Phase 1 features

Test Results

• 3403 tests pass, 0 failures
• 48 new Squad-specific tests covering protocol models, event handling, provider compliance, factory config, thread safety

Known Limitations

• Token discovery is manual — Squad's rc command uses random ports and doesn't expose the session token. A .squad/rc-session.json auto-discovery mechanism would improve UX (Squad-side feature request).
• The plugin is built as a separate DLL but not auto-loaded — a Settings UI for host/port/token entry is the next step.
• Squad is pre-1.0 (v0.9.1) — protocol may change.

Closes #436 (Phase 1 & 2)

[PureWeen]

🔍 Multi-Model Re-Review — PR #575 (Final)

Tests: ✅ 3403 passed, 0 failed
CI: ⚠️ No CI checks on this branch
Reviewers: 2/3 completed successfully

---

Previous Findings — All Critical/Moderate Fixed

#	Finding	Status
1	Concurrent WS sends	✅ FIXED — SemaphoreSlim
2	Thread-unsafe lists	✅ FIXED — lock + snapshots
3	IsProcessing off UI thread	⚠️ Host wiring handles marshaling
4	Unbounded WS buffer	✅ FIXED — 4MB cap
5	Disconnect doesn't await	✅ FIXED — 5s timeout
6	Tool call key collision	⚠️ Dictionary added; concurrent same-tool edge case remains
7	Token in URL	✅ FIXED
8	Dead _pendingPermissions	➖ Deferred (cross-cutting)
9	CTS leaked	✅ FIXED
10	Client leaked on init	✅ FIXED
11	Non-idempotent connect	✅ FIXED
12	Non-atomic init	✅ FIXED — Interlocked
13	RunSquadInit timeout	✅ FIXED — 60s CTS
14	Port validation	✅ FIXED
15	Double-disconnect	✅ FIXED (commit c8f226c)
16-17	Resource disposal	✅ FIXED
18	Win32Exception	⚠️ Minor — generic check
19	Structural tests	➖ Deferred
20	Permission timeout	➖ Deferred
21	TryGetProperty	✅ FIXED

Re-Review New Issues — Fixed

#	New Finding	Status
NEW-1	DisposeAsync skips cleanup	✅ FIXED (commit c8f226c)
NEW-2	Sequential stdout/stderr deadlock	✅ FIXED (commit c8f226c)
NEW-3	Fallback auth is no-auth	🟢 Acceptable — server rejects unauthenticated

Recommendation

✅ Approve — All critical and moderate issues are resolved. 3 items deferred as cross-cutting concerns for follow-up. Tests green (3403 passed).