/docs/design/agent-proximity.md

# Agent-space distance metric & collision avoidance (Layer 4)

> Status: v0 implemented in `scripts/lib/agent-proximity/`. This is the moat
> layer of ECC 2.0 — *spatial deconfliction for multiple agents (and humans)
> working the same codebase*, modeled on aircraft collision avoidance (TCAS).

## The analogy

Two aircraft sharing airspace don't wait until they touch — TCAS continuously
measures their separation and closure rate, issues a **Traffic Advisory** ("there
is traffic near you") and then a coordinated **Resolution Advisory** ("you climb,
the other descends"). We want the same for agents: a continuous notion of *how
close two agents are in code-space*, so that as they approach we fire a trigger
that makes them **transmit what they're doing** to each other and, if needed,
makes one **steer away** — before they collide at the git/merge layer.

## 1. Agent state

At time *t*, agent *a* has a **working set**

```
W_a = { (f, R_f, w_f) }                                              (1)
```

where *f* is a touched file, *R_f* the set of edited line ranges in *f*, and
*w_f ∈ (0,1]* a recency weight (older edits decay toward a floor). An agent may
also declare an **intent set** *I_a* of files it is about to touch (look-ahead).

## 2. Collision is multi-channel (noisy-OR)

Two agents can collide through several independent channels. Each channel *i*
yields a collision probability *r_i ∈ [0,1]*; we combine them as the probability
of colliding through **at least one** channel:

```
R(a,b) = 1 − Π_i ( 1 − ω_i · r_i )                                   (2)
```

with channel weights *ω_i ∈ [0,1]*. The reported **distance** is the dual
*D(a,b) = 1 − R(a,b)*.

### Channel 1 — edit overlap *r_overlap*

For shared files *S = files(W_a) ∩ files(W_b)*:

```
lineOverlap(f) = |R_f^a ∩ R_f^b| / min(|R_f^a|, |R_f^b|)   (overlap coefficient)
r_overlap = max_{f∈S} w_f^a·w_f^b · lineOverlap(f)                        (3)
```

The overlap coefficient (not Jaccard) is the right measure: it stays high when one
agent's small edit sits inside the other's large region (Jaccard would dilute it by
union size). A whole-file edit (no line info) ⇒ `lineOverlap = 1`. Same file,
overlapping lines ⇒ imminent collision; same file, *disjoint* line ranges (different
functions) ⇒ low `r_overlap`. Different files ⇒ no shared `f` ⇒ `r_overlap = 0`.

### Channel 2 — dependency coupling *r_dep*

Build a dependency graph *G=(V,E)*, edge *f→g* iff *f* imports *g*. Even when two
files sit in distant subtrees, if one agent edits a file the other imports, the
edit breaks the importer. Coupling decays with (direction-agnostic) graph
distance *d_G*:

```
coupling(f,g) = γ^{ d_G(f,g) − 1 }     γ ∈ (0,1), 0 if unreachable   (4)
r_dep = max_{f∈W_a, g∈W_b}  w_f · w_g · coupling(f,g)                (5)
```

A direct import (*d_G = 1*) ⇒ *coupling = 1*. This is the **"collision even when
far away"** term the metric must capture — a cross-file parameter/return
dependency that fails at a distance.

### Channel 3 — tree proximity *r_tree* (soft prior)

For two paths with lowest-common-ancestor depth *L*:

```
treeDistance(f,g) = ((depth_f − L) + (depth_g − L)) / (depth_f + depth_g)  (6)
r_tree = 1 − min_{f∈W_a, g∈W_b} treeDistance(f,g)
```

(0 = same file, 1 = disjoint roots.) Tree proximity alone rarely causes a
collision, so *ω_tree* is small — it nudges the metric, never dominates it.

### Future channels (same shape)

Call-graph distance (two functions near in the call stack), symbol-level
read/write hazard (a writes a symbol b reads), and test-coverage overlap all slot
in as additional *r_i* with their own weights — the noisy-OR (2) absorbs them
without changing the framework.

## 3. The TCAS protocol

Two thresholds carve a protected zone around *R*:

| Risk band | Advisory | Action |
|---|---|---|
| `R < τ_TA` | **Clear** | nothing |
| `τ_TA ≤ R < τ_RA` | **Traffic Advisory** | both agents **transmit intent** to each other (the scout handshake — "here is what I'm doing / did") |
| `R ≥ τ_RA` | **Resolution Advisory** | the **lower-priority** agent steers away; the other holds course |

The resolution is **coordinated and deterministic** (like one plane climbing while
the other descends) so the two agents never pick the same maneuver. Right-of-way
priority:

```
priority(a) = ( committed-work(a),  age(a) )      lexicographic
```

More committed work wins; ties break on earlier start; the final tiebreak is a
stable agent id. The lower-priority agent receives the steer.

**Closure rate.** TCAS escalates on *closing speed*, not just separation. From two
risk samples Δt apart, `closureRate = (R_t − R_{t−Δt}) / Δt`; a positive closure
rate near *τ_TA* can pre-emptively escalate before the protected zone is entered.

## 4. Vector-space view (the visualization)

Each file gets a coordinate via a **space-filling embedding of its path** (files
sharing a long directory prefix share most of their coordinate), then pulled
toward its dependency neighbours by one averaging step. An agent sits at the
recency-weighted centroid of its files' coordinates. The result: `‖v_a − v_b‖`
tracks the collision risk *R*, so a **3D "where are the agents" view** renders
agents as moving points in a file-cloud — you literally watch them crawl toward
each other, see the advisory line light up, and watch one steer away.

`scanAirspace(agents, graph)` returns, in one pass: the non-clear `advisories`
(what the trigger layer acts on), the 3D `positions` and `fileCoordinates` (what
the renderer draws), and pairwise `links` with risk (the edges to color).

## 5. How it wires into ECC

- **Inputs** come from the session/work state: each running session's worktree
  diff gives its working set *W_a*; the dependency graph is built from the repo
  (`buildDependencyGraph`).
- **Triggers**: the control-pane tick calls `scanAirspace`; a Traffic Advisory
  injects a "transmit intent" message between the two agents' sessions; a
  Resolution Advisory tells the lower-priority agent to steer (re-target to a
  different file/subtree) — the first concrete realization of *just-in-time
  multi-agent (and multi-human) deconfliction*.
- **Board**: advisories surface on the kanban as proximity warnings, extending
  the agent/human JIT assignment layer already in the control pane.

## Roadmap

- v0 (done): tree + overlap + dependency channels, noisy-OR risk, TCAS advisories,
  priority/steer, 3D embedding, full test coverage.
- v1: call-graph & symbol read/write channels; intent look-ahead; closure-rate
  escalation wired to live session diffs.
- v2: cross-machine airspace over Tailscale (teammate agents enter the same
  space); the recorded "N agents, M humans, zero merge conflicts" demo.