feat: implement collision detection and management for cross-session edits

[aditisingh02]

What & Why

Closes #2258.

Agent Orchestrator's core premise is running many agents in parallel, each in its own isolated Git worktree. That isolation has a blind spot: two agents can silently modify the same code without knowing about each other.

Today, AO only detects this reactively—after both agents have opened PRs and GitHub reports a merge conflict. At that point, lifecycle.ApplyPRObservation can only nudge an agent to rebase, meaning the duplicate parallel work has already been done.

Convergence Radar closes this gap.

It introduces a new observation loop that continuously diffs every active worktree, computes pairwise overlap at both file and hunk-range granularity, persists those overlaps as durable facts, and proactively nudges colliding agents to coordinate before either opens a PR.

Rather than being a bolt-on feature, it follows AO's existing architecture. The convergence observer is a sibling of the SCM observer, reusing observe.StartPollLoop, the durable-facts model, and the existing agent nudge pipeline. The result shifts AO from a conflict resolver into a conflict preventer.

How It Works (OBSERVE → UPDATE → ACT)

OBSERVE

ports.WorkspaceDiffer.ChangedRegions diffs each worktree against the merge-base of HEAD and its base branch, including both committed and uncommitted tracked changes. It parses git diff --unified=0 hunk headers into per-file line ranges.

UPDATE

The convergence observer groups active sessions by project, compares every pair of worktrees, and classifies shared files as:

• Hot — overlapping line ranges intersect, indicating a near-certain merge conflict.
• Soft — both sessions modify the same file, but their changed ranges are disjoint.

The observer reconciles durable session_collision facts. A content signature ensures stable overlaps are written only once and re-evaluated only when the underlying changes actually differ.

ACT

lifecycle.ApplyCollision sends each affected live session a deduplicated coordination nudge identifying the peer session and the overlapping files.

Current collisions are also exposed via:

GET /api/v1/projects/{id}/collisions

Surface Area

New

• internal/observe/convergence
• internal/daemon/convergence_wiring.go
• domain.SessionCollision
• Migration 0020_session_collisions
• SQLC queries and store
• ports.WorkspaceDiffer
• ports.LineRange

Extended

• Git worktree adapter (diff capability)
• Lifecycle reactions
• Project service
• GET /api/v1/projects/{id}/collisions controller
• OpenAPI specification
• Generated TypeScript types

Architectural Notes

The implementation follows existing AO patterns:

• Durable facts only (status is derived at read time)

• Loopback-only observation

• No manual CDC

• Code-first regeneration via:

  • npm run sqlc
  • npm run api

Testing

Validated with:

• go build ./...
• go vet
• gofmt clean across all modified packages
• go test -race passing for every touched package, including spec parity/drift tests

New test coverage includes:

• Diff parser
• Overlap classification
• Observer reconciliation
• Deduplication
• Agent nudging
• Lifecycle deduplication
• Store round-trip
• Controller endpoint

Notes / Follow-ups

• The desktop ⚡ Overlaps chip is intentionally deferred as a lightweight follow-up built on the new endpoint and derived facts.

• Live user feedback is provided through agent nudges and the read endpoint. V1 intentionally avoids the change_log / notifications CHECK-constraint table rebuild migrations.

• Existing unrelated failures remain unchanged:

  • tmux integration test (tmux unavailable in the CI sandbox)
  • TestManager_AddWorkspaceRejectsBareParent (currently fails on clean main with newer Git)