ECC/docs/design/agent-proximity.md

Agent-space proximity and advisory prototypes (Layer 4)

Status: v0 proximity scoring exists in scripts/lib/agent-proximity/. A separate v1 shadow trail records bounded advisories and declared responses. Current scores and drawings have no calibrated conflict probability or live conflict-reduction result.

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)

Several channels contribute bounded heuristic scores r_i ∈ [0,1]. The shipped noisy-OR-shaped combination is:

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

with channel weights ω_i ∈ [0,1]. The reported distance score is the dual D(a,b) = 1 − R(a,b). Correlated channels and unvalidated weights mean R is not a calibrated probability, and D need not satisfy metric axioms.

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 resulting 3D display illustrates path and dependency proximity. Its Euclidean separation has not been shown to preserve the risk score or predict collisions.

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: control-pane prototype code can derive messages from scanAirspace. Delivery, acknowledgement, scope authorization and actual conflict resolution are separate evidence. The shadow trail below calls no sink, hook or steer path.
• Board: advisories surface on the kanban as proximity warnings, extending the agent/human JIT assignment layer already in the control pane.

Passive shadow receipt trail (v1)

scripts/lib/agent-proximity/shadow-trail.js accepts two supplied, versioned observations with task/repository/base/scope identity, read/write path sets, completeness and expiry. It computes a local advisory using the shipped three-channel scorer. An exact write/write or write/read path overlap takes precedence over a low score. Incomplete, expired, future or incomparable critical observations produce unknown; an absent advisory means only that no advisory was found within the complete, comparable supplied scope and supplied dependency graph. The optional graph defaults to empty and may be supplied anew for re-observation; a quiet advisory says nothing about unsupplied dependencies.

Call createShadowTrail, then appendAcknowledgement for both observed agents, appendScopeRevision for one externally declared revision and its new footprint, and appendReobservation with a fresh matching pair. summarizeShadowTrail reports the latest scoped advisory, its own advisory-bound ACKs, separate historical acknowledgers and outcome: unadjudicated. Both original observations must still be current when the scope-change declaration is recorded. verifyShadowTrail checks the bounded local receipt chain after JSON persistence. Each receipt hash binds the trail ID, event ID, time, predecessor hash and canonical payload. The verifier rejects noncanonical persisted payload field and path order before comparing hashes. Append results copy earlier receipts, so changing an earlier returned object cannot change a later returned trail. Returned data can still be mutated; verification detects inconsistent local content. A party able to rewrite and rehash the entire trail can forge a consistent chain. These hashes do not establish trusted identity, permission, delivery, whole-log immutability or an independently verified result.

The module issues no grants and sends no messages. The scope-change receipt's authorizationRef is a caller declaration and is labelled declared-only; the actual authority owner must validate it before any real work changes. It records path metadata locally, so a caller must apply its own publication policy. It accepts no memory summary or required-state payload. Approximate summaries belong to the separately owned memory envelope; exact task constraints and authority remain outside this heuristic score. The trail is limited to one two-agent change, so it cannot grant coherent ownership across a three-agent conflict component.

Roadmap

• v0 (source present): tree + overlap + dependency channels, noisy-OR-shaped risk score, advisory/priority prototype and display embedding.
• v1 shadow (source present): passive two-agent observation/advisory/ACK/scope revision/re-observation receipts; no active steering or measured benefit.
• 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.

The control pane compares each worktree against the merge base of its declared base and HEAD. Committed, staged, and unstaged tracked edits carry changed line ranges. Untracked files that Git does not ignore participate as whole-file working sets. Changes made only on the base branch after the worktree diverged do not participate.