Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

feat(layer4): agent-space distance metric + TCAS-style collision avoidance (v0)

Affaan Mustafa726972d73557
diff --git a/docs/design/agent-proximity.md b/docs/design/agent-proximity.md
new file mode 100644
index 000000000..649d13a93
--- /dev/null
+++ b/docs/design/agent-proximity.md
@@ -0,0 +1,147 @@
+# 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| / |R_f^a ∪ R_f^b|
+r_overlap = max( Jaccard(files_a, files_b), max_{f∈S} lineOverlap(f) ) (3)
+```
+
+Same file, overlapping lines ⇒ imminent collision (*r_overlap → 1*).
+
+### 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.
diff --git a/scripts/lib/agent-proximity/distance.js b/scripts/lib/agent-proximity/distance.js
new file mode 100644
index 000000000..7118825f1
--- /dev/null
+++ b/scripts/lib/agent-proximity/distance.js
@@ -0,0 +1,326 @@
+'use strict';
+
+/**
+ * Agent-space distance metric + collision avoidance (ECC 2.0, Layer 4 v0).
+ *
+ * Two agents editing the same codebase are like two aircraft sharing airspace:
+ * we want a continuous notion of "how close are they" so that, as they approach,
+ * we fire a TCAS-style protocol — first a Traffic Advisory (exchange intent),
+ * then a Resolution Advisory (one steers away) — *before* they collide at the
+ * git/merge layer.
+ *
+ * ── The state of an agent ──────────────────────────────────────────────────
+ * At time t, agent a has a working set
+ * W_a = { (f, R_f, w_f) } (1)
+ * where f is a file it has touched, R_f the set of line ranges it edited in f,
+ * and w_f ∈ (0,1] a recency weight (older edits decay). Optionally an agent
+ * declares an intent set I_a of files it is about to touch.
+ *
+ * ── Collision is multi-channel ─────────────────────────────────────────────
+ * Two agents can collide through several independent channels, so we model a
+ * per-channel collision probability r_i ∈ [0,1] and combine with a noisy-OR
+ * (probability of colliding through *at least one* channel):
+ * R(a,b) = 1 − Π_i (1 − ω_i · r_i) (2)
+ * with channel weights ω_i ∈ [0,1]. R is the agent-distance's dual: we report
+ * both the risk R ∈ [0,1] and a distance D = 1 − R.
+ *
+ * Channels (each defined below):
+ * r_overlap — same file / overlapping line ranges (imminent)
+ * r_dep — one agent's files depend on the other's (collision even when
+ * far apart in the tree: edit there breaks here)
+ * r_tree — proximity in the directory tree (a soft prior)
+ *
+ * ── Channel 1: edit overlap ────────────────────────────────────────────────
+ * For the shared files S = files(W_a) ∩ files(W_b):
+ * - same file, no line info → Jaccard of the file sets is the floor.
+ * - same file with line ranges → fraction of overlapping lines:
+ * lineOverlap(f) = |R_f^a ∩ R_f^b| / |R_f^a ∪ R_f^b|.
+ * r_overlap = max( jaccard(files_a, files_b), max_{f∈S} lineOverlap(f) ). (3)
+ *
+ * ── Channel 2: dependency coupling ─────────────────────────────────────────
+ * Build a directed dependency graph G=(V,E), V=files, edge f→g iff f imports g.
+ * Even if f and g are in distant subtrees, if f (agent a) depends on g (agent b)
+ * then b's edit to g can break a. Coupling decays with graph distance:
+ * coupling(f,g) = γ^{ d_G(f,g) − 1 } (γ∈(0,1)), 0 if unreachable. (4)
+ * A direct edge (d_G=1) ⇒ coupling=1. We take the recency-weighted max over
+ * cross pairs:
+ * r_dep = max_{f∈W_a, g∈W_b} w_f·w_g·max(coupling(f,g), coupling(g,f)). (5)
+ *
+ * ── Channel 3: tree proximity ──────────────────────────────────────────────
+ * For two paths split into segments with lowest-common-ancestor depth L:
+ * treeDistance(f,g) = ((depth_f − L) + (depth_g − L)) / (depth_f + depth_g) (6)
+ * (0 = same file, 1 = disjoint roots). r_tree = 1 − min cross-pair treeDist.
+ * Tree proximity alone rarely causes a collision, so ω_tree is small — it nudges
+ * the metric, it does not dominate it.
+ *
+ * ── TCAS protocol ──────────────────────────────────────────────────────────
+ * Two thresholds carve a protected zone:
+ * R < τ_TA → CLEAR
+ * τ_TA ≤ R < τ_RA → TRAFFIC ADVISORY: each agent transmits what it is
+ * doing/has done to the other (the scout handshake)
+ * R ≥ τ_RA → RESOLUTION ADVISORY: the lower-priority agent steers
+ * away; the higher-priority one holds course.
+ * Like TCAS coordinating climb/descend, the resolution is *coordinated* and
+ * deterministic so both agents never pick the same maneuver: priority(a) breaks
+ * the tie (right-of-way to the agent with more committed work / earlier start;
+ * stable agentId as the final tiebreak). See advise().
+ *
+ * ── Vector-space view ──────────────────────────────────────────────────────
+ * embedAgent() places each agent at the recency-weighted centroid of its files'
+ * coordinates, where a file's coordinate is a low-dim hash of its path segments
+ * smoothed toward its dependency neighbours. Then ‖v_a − v_b‖ tracks R, which is
+ * what a 3D "where are the agents" visualization renders. See embed.js.
+ */
+
+const DEFAULTS = {
+ channelWeights: { overlap: 1.0, dependency: 0.9, tree: 0.25 },
+ depDecay: 0.5, // γ in (4)
+ recencyFloor: 0.15, // weight never decays below this so stale-but-relevant files still count
+ thresholds: { ta: 0.35, ra: 0.7 } // τ_TA, τ_RA
+};
+
+function clamp01(x) {
+ if (!Number.isFinite(x)) return 0;
+ return x < 0 ? 0 : x > 1 ? 1 : x;
+}
+
+function normalizePath(p) {
+ return String(p || '')
+ .replace(/\\/g, '/')
+ .replace(/^\.\//, '')
+ .replace(/\/+$/, '');
+}
+
+function segments(p) {
+ return normalizePath(p).split('/').filter(Boolean);
+}
+
+/**
+ * Tree distance ∈ [0,1] between two file paths — eq. (6). 0 = same file.
+ */
+function treeDistance(a, b) {
+ const sa = segments(a);
+ const sb = segments(b);
+ if (sa.length === 0 || sb.length === 0) return 1;
+ let lca = 0;
+ while (lca < sa.length && lca < sb.length && sa[lca] === sb[lca]) lca += 1;
+ const da = sa.length;
+ const db = sb.length;
+ if (da === db && lca === da) return 0; // identical path
+ return clamp01((da - lca + (db - lca)) / (da + db));
+}
+
+/**
+ * Line-range overlap fraction (Jaccard over covered lines) for two range lists.
+ * Each range is [start, end] inclusive. Empty/absent ranges ⇒ treat the whole
+ * file as touched, so two file-level edits to the same file count as full overlap.
+ */
+function lineRangeOverlap(rangesA, rangesB) {
+ const a = Array.isArray(rangesA) ? rangesA : [];
+ const b = Array.isArray(rangesB) ? rangesB : [];
+ if (a.length === 0 || b.length === 0) return 1; // file-level edit ⇒ whole-file overlap
+ const covered = ranges => {
+ const set = new Set();
+ for (const [s, e] of ranges) {
+ const lo = Math.min(s, e);
+ const hi = Math.max(s, e);
+ for (let i = lo; i <= hi; i += 1) set.add(i);
+ }
+ return set;
+ };
+ const ca = covered(a);
+ const cb = covered(b);
+ let inter = 0;
+ for (const v of ca) if (cb.has(v)) inter += 1;
+ const union = ca.size + cb.size - inter;
+ return union === 0 ? 0 : inter / union;
+}
+
+function fileSet(workingSet) {
+ return new Set((workingSet.files || []).map(f => normalizePath(f.path)));
+}
+
+function jaccard(setA, setB) {
+ if (setA.size === 0 && setB.size === 0) return 0;
+ let inter = 0;
+ for (const v of setA) if (setB.has(v)) inter += 1;
+ const union = setA.size + setB.size - inter;
+ return union === 0 ? 0 : inter / union;
+}
+
+/**
+ * Channel 1 — edit overlap, eq. (3).
+ */
+function overlapRisk(a, b) {
+ const filesA = a.files || [];
+ const filesB = b.files || [];
+ const setA = fileSet(a);
+ const setB = fileSet(b);
+ let r = jaccard(setA, setB);
+ const byPathB = new Map(filesB.map(f => [normalizePath(f.path), f]));
+ for (const fa of filesA) {
+ const fb = byPathB.get(normalizePath(fa.path));
+ if (fb) {
+ const w = (fa.weight ?? 1) * (fb.weight ?? 1);
+ r = Math.max(r, w * lineRangeOverlap(fa.lines, fb.lines));
+ }
+ }
+ return clamp01(r);
+}
+
+/**
+ * Shortest-path distance in a directed dependency graph, treated as undirected
+ * for reachability (a depends-on edge couples both endpoints). BFS, capped.
+ */
+function graphDistance(graph, from, to, cap = 6) {
+ const start = normalizePath(from);
+ const goal = normalizePath(to);
+ if (start === goal) return 0;
+ const adj = graph && graph.adjacency ? graph.adjacency : graph || {};
+ const seen = new Set([start]);
+ let frontier = [start];
+ for (let depth = 1; depth <= cap; depth += 1) {
+ const next = [];
+ for (const node of frontier) {
+ const neighbours = adj[node] || [];
+ for (const nb of neighbours) {
+ const n = normalizePath(nb);
+ if (n === goal) return depth;
+ if (!seen.has(n)) {
+ seen.add(n);
+ next.push(n);
+ }
+ }
+ }
+ if (next.length === 0) break;
+ frontier = next;
+ }
+ return Infinity;
+}
+
+/**
+ * Channel 2 — dependency coupling, eqs. (4)-(5).
+ */
+function dependencyRisk(a, b, graph, opts = {}) {
+ const decay = opts.depDecay ?? DEFAULTS.depDecay;
+ const filesA = a.files || [];
+ const filesB = b.files || [];
+ let r = 0;
+ for (const fa of filesA) {
+ for (const fb of filesB) {
+ // A depends-on edge couples both endpoints, so use the smaller of the two
+ // directed distances (importer→imported or imported→importer).
+ const d = Math.min(graphDistance(graph, fa.path, fb.path), graphDistance(graph, fb.path, fa.path));
+ if (d === Infinity || d === 0) continue;
+ const coupling = Math.pow(decay, d - 1); // γ^{d-1}
+ const w = (fa.weight ?? 1) * (fb.weight ?? 1);
+ r = Math.max(r, w * coupling);
+ }
+ }
+ return clamp01(r);
+}
+
+/**
+ * Channel 3 — tree proximity (soft prior), eq. (6).
+ */
+function treeRisk(a, b) {
+ const filesA = a.files || [];
+ const filesB = b.files || [];
+ let minDist = 1;
+ for (const fa of filesA) {
+ for (const fb of filesB) {
+ minDist = Math.min(minDist, treeDistance(fa.path, fb.path));
+ }
+ }
+ return clamp01(1 - minDist);
+}
+
+/**
+ * Collision risk R(a,b) ∈ [0,1] via the noisy-OR of channels, eq. (2).
+ * Returns the risk, its dual distance, and the per-channel breakdown.
+ */
+function collisionRisk(a, b, graph = {}, options = {}) {
+ const weights = { ...DEFAULTS.channelWeights, ...(options.channelWeights || {}) };
+ const channels = {
+ overlap: overlapRisk(a, b),
+ dependency: dependencyRisk(a, b, graph, options),
+ tree: treeRisk(a, b)
+ };
+ let product = 1;
+ for (const key of Object.keys(channels)) {
+ const w = clamp01(weights[key] ?? 0);
+ product *= 1 - w * channels[key];
+ }
+ const risk = clamp01(1 - product);
+ return { risk, distance: clamp01(1 - risk), channels };
+}
+
+/**
+ * Right-of-way priority: the agent with more committed work and the earlier
+ * start holds course; the other steers. Higher number = higher priority.
+ */
+function agentPriority(agent) {
+ const progress = (agent.files || []).reduce((s, f) => s + (f.weight ?? 1), 0);
+ const startedAt = agent.startedAt ? Date.parse(agent.startedAt) || 0 : 0;
+ // Earlier start ⇒ larger right-of-way term (negative ms, so earlier = larger).
+ return { progress, ageMs: startedAt ? Date.now() - startedAt : 0 };
+}
+
+/**
+ * TCAS-style advisory between two agents given their collision risk.
+ * Returns { level: 'clear'|'advisory'|'resolution', risk, transmit, steer, hold }.
+ * - advisory: both should transmit intent to each other.
+ * - resolution: `steer` is the agentId that must move; `hold` holds course.
+ */
+function advise(a, b, graph = {}, options = {}) {
+ const thresholds = { ...DEFAULTS.thresholds, ...(options.thresholds || {}) };
+ const { risk, channels, distance } = collisionRisk(a, b, graph, options);
+
+ if (risk < thresholds.ta) {
+ return { level: 'clear', risk, distance, channels, transmit: false, steer: null, hold: null };
+ }
+
+ const pa = agentPriority(a);
+ const pb = agentPriority(b);
+ // Right-of-way: more progress wins; tie → earlier start (greater age) wins;
+ // final deterministic tiebreak on agentId so the maneuver is coordinated.
+ let aHasPriority;
+ if (pa.progress !== pb.progress) aHasPriority = pa.progress > pb.progress;
+ else if (pa.ageMs !== pb.ageMs) aHasPriority = pa.ageMs > pb.ageMs;
+ else aHasPriority = String(a.agentId) < String(b.agentId);
+
+ const hold = aHasPriority ? a.agentId : b.agentId;
+ const steer = aHasPriority ? b.agentId : a.agentId;
+
+ if (risk < thresholds.ra) {
+ // Traffic advisory: exchange intent, no one has to move yet.
+ return { level: 'advisory', risk, distance, channels, transmit: true, steer: null, hold: null };
+ }
+ // Resolution advisory: the lower-priority agent steers away.
+ return { level: 'resolution', risk, distance, channels, transmit: true, steer, hold };
+}
+
+/**
+ * Closure rate: how fast two agents are converging, from two risk samples
+ * Δt apart (TCAS uses closure rate, not just separation, to decide urgency).
+ * Positive ⇒ approaching. Used to escalate before the protected zone is reached.
+ */
+function closureRate(prevRisk, currRisk, dtMs) {
+ const dt = Number(dtMs) > 0 ? Number(dtMs) : 1;
+ return (clamp01(currRisk) - clamp01(prevRisk)) / (dt / 1000);
+}
+
+module.exports = {
+ DEFAULTS,
+ treeDistance,
+ lineRangeOverlap,
+ graphDistance,
+ overlapRisk,
+ dependencyRisk,
+ treeRisk,
+ collisionRisk,
+ agentPriority,
+ advise,
+ closureRate,
+ _internal: { normalizePath, segments, jaccard }
+};
diff --git a/scripts/lib/agent-proximity/graph.js b/scripts/lib/agent-proximity/graph.js
new file mode 100644
index 000000000..98bc05a3d
--- /dev/null
+++ b/scripts/lib/agent-proximity/graph.js
@@ -0,0 +1,140 @@
+'use strict';
+
+/**
+ * Lightweight dependency-graph builder for the agent-proximity metric.
+ *
+ * Edge f → g iff f imports/requires g. This is the structure the dependency
+ * channel (distance.js, eqs. 4-5) walks: two agents far apart in the tree still
+ * collide if one edits a file the other imports.
+ *
+ * v0 scans JS/TS `require()` / `import ... from` / `import(...)` for relative
+ * specifiers and resolves them to repo-relative paths. It is intentionally
+ * static and dependency-free; richer languages and call-graph edges are future
+ * channels that slot into the same adjacency shape.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SOURCE_EXTENSIONS = ['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx'];
+const RESOLVE_EXTENSIONS = ['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.json'];
+
+function toRepoRel(repoRoot, absPath) {
+ return path.relative(repoRoot, absPath).split(path.sep).join('/');
+}
+
+// Match relative specifiers only (./ or ../). Bare specifiers are node_modules
+// and never the target of an in-repo collision.
+const SPEC_PATTERNS = [
+ /require\(\s*['"](\.[^'"]+)['"]\s*\)/g,
+ /import\s+(?:[^'"]*?\s+from\s+)?['"](\.[^'"]+)['"]/g,
+ /import\(\s*['"](\.[^'"]+)['"]\s*\)/g,
+ /export\s+(?:\*|\{[^}]*\})\s+from\s+['"](\.[^'"]+)['"]/g
+];
+
+function extractRelativeSpecifiers(source) {
+ const specs = new Set();
+ for (const re of SPEC_PATTERNS) {
+ re.lastIndex = 0;
+ let m;
+ while ((m = re.exec(source)) !== null) {
+ specs.add(m[1]);
+ }
+ }
+ return [...specs];
+}
+
+/**
+ * Resolve a relative specifier from `fromFile` to a repo-relative path, trying
+ * extension and /index resolution like Node/TS would.
+ */
+function resolveSpecifier(repoRoot, fromFile, spec) {
+ const baseDir = path.dirname(path.join(repoRoot, fromFile));
+ const target = path.resolve(baseDir, spec);
+ const candidates = [target];
+ for (const ext of RESOLVE_EXTENSIONS) candidates.push(target + ext);
+ for (const ext of RESOLVE_EXTENSIONS) candidates.push(path.join(target, 'index' + ext));
+ for (const cand of candidates) {
+ try {
+ if (fs.existsSync(cand) && fs.statSync(cand).isFile()) {
+ return toRepoRel(repoRoot, cand);
+ }
+ } catch {
+ /* ignore unreadable candidate */
+ }
+ }
+ return null;
+}
+
+function isSourceFile(p) {
+ return SOURCE_EXTENSIONS.includes(path.extname(p));
+}
+
+/**
+ * Build a dependency graph from an explicit list of repo-relative files.
+ * Returns { adjacency: { file: [importedFile, ...] }, files: [...] }.
+ *
+ * @param {string} repoRoot
+ * @param {string[]} files repo-relative paths to scan
+ * @param {object} [deps] injectable fs for testing: { readFileSync, existsSync, statSync }
+ */
+function buildDependencyGraph(repoRoot, files, deps = {}) {
+ const read = deps.readFileSync || fs.readFileSync;
+ const adjacency = {};
+ const scanned = [];
+ for (const rel of files || []) {
+ const normalized = String(rel).replace(/\\/g, '/');
+ if (!isSourceFile(normalized)) continue;
+ scanned.push(normalized);
+ let source = '';
+ try {
+ source = String(read(path.join(repoRoot, normalized), 'utf8'));
+ } catch {
+ adjacency[normalized] = adjacency[normalized] || [];
+ continue;
+ }
+ const edges = new Set(adjacency[normalized] || []);
+ for (const spec of extractRelativeSpecifiers(source)) {
+ const resolved = resolveSpecifier(repoRoot, normalized, spec);
+ if (resolved && resolved !== normalized) edges.add(resolved);
+ }
+ adjacency[normalized] = [...edges];
+ }
+ return { adjacency, files: scanned };
+}
+
+/**
+ * Build a graph directly from an in-memory map of { file: sourceText }, for
+ * callers that already have file contents (and for tests). Specifiers are
+ * resolved against the provided file set rather than the filesystem.
+ */
+function buildDependencyGraphFromSources(sources = {}) {
+ const adjacency = {};
+ const fileList = Object.keys(sources).map(f => f.replace(/\\/g, '/'));
+ const fileSet = new Set(fileList);
+ const tryResolve = (fromFile, spec) => {
+ const base = path.posix.dirname(fromFile);
+ const target = path.posix.normalize(path.posix.join(base, spec));
+ const candidates = [target];
+ for (const ext of RESOLVE_EXTENSIONS) candidates.push(target + ext);
+ for (const ext of RESOLVE_EXTENSIONS) candidates.push(path.posix.join(target, 'index' + ext));
+ return candidates.find(c => fileSet.has(c)) || null;
+ };
+ for (const file of fileList) {
+ const edges = new Set();
+ for (const spec of extractRelativeSpecifiers(String(sources[file] || ''))) {
+ const resolved = tryResolve(file, spec);
+ if (resolved && resolved !== file) edges.add(resolved);
+ }
+ adjacency[file] = [...edges];
+ }
+ return { adjacency, files: fileList };
+}
+
+module.exports = {
+ buildDependencyGraph,
+ buildDependencyGraphFromSources,
+ extractRelativeSpecifiers,
+ resolveSpecifier,
+ isSourceFile
+};
diff --git a/scripts/lib/agent-proximity/index.js b/scripts/lib/agent-proximity/index.js
new file mode 100644
index 000000000..cd934c27a
--- /dev/null
+++ b/scripts/lib/agent-proximity/index.js
@@ -0,0 +1,170 @@
+'use strict';
+
+/**
+ * Agent-proximity orchestration: scan all agents in a codebase, compute the
+ * pairwise TCAS advisories that drive the steer/transmit triggers, and embed
+ * each agent in 3D space for the "where are the agents" visualization.
+ *
+ * This is the call the control pane / hook layer makes each tick:
+ * const scan = scanAirspace(agents, graph)
+ * for (const a of scan.advisories) fireTrigger(a) // transmit / steer
+ * renderViz(scan.positions, scan.advisories) // 3D crawl view
+ */
+
+const crypto = require('crypto');
+const { advise, collisionRisk, DEFAULTS } = require('./distance');
+const { buildDependencyGraph, buildDependencyGraphFromSources } = require('./graph');
+
+const { normalizePath, segments } = require('./distance')._internal;
+
+/**
+ * Deterministic hash of a string to a unit-ish vector in R^dims (components in
+ * roughly [-1, 1]). Used to place tree prefixes in space.
+ */
+function hashVec(str, dims) {
+ const digest = crypto.createHash('sha256').update(String(str)).digest();
+ const v = new Array(dims).fill(0);
+ for (let d = 0; d < dims; d += 1) {
+ // Two bytes per dim → [-1, 1).
+ const hi = digest[(d * 2) % digest.length];
+ const lo = digest[(d * 2 + 1) % digest.length];
+ v[d] = ((hi << 8) | lo) / 32768 - 1;
+ }
+ return v;
+}
+
+/**
+ * Coordinate of a file: a space-filling embedding of its path. Files that share
+ * a long directory prefix share most of their coordinate (deeper segments
+ * perturb less), so tree-close files are space-close — exactly what eq. (6)
+ * wants the visualization to show.
+ */
+function fileCoordinate(filePath, dims = 3) {
+ const segs = segments(filePath);
+ const v = new Array(dims).fill(0);
+ let prefix = '';
+ for (let i = 0; i < segs.length; i += 1) {
+ prefix += '/' + segs[i];
+ const h = hashVec(prefix, dims);
+ const scale = 1 / Math.pow(2, i);
+ for (let d = 0; d < dims; d += 1) v[d] += h[d] * scale;
+ }
+ return v;
+}
+
+/**
+ * Pull a file's coordinate toward the coordinates of its dependency neighbours
+ * (one averaging step), so coupled files that are far in the tree are drawn
+ * closer in space — the dependency channel made visible.
+ */
+function smoothByDependency(coords, graph, alpha = 0.35) {
+ const adj = (graph && graph.adjacency) || {};
+ const out = {};
+ for (const file of Object.keys(coords)) {
+ const base = coords[file];
+ const neighbours = (adj[file] || []).map(normalizePath).filter(n => coords[n]);
+ if (neighbours.length === 0) {
+ out[file] = base.slice();
+ continue;
+ }
+ const dims = base.length;
+ const avg = new Array(dims).fill(0);
+ for (const n of neighbours) for (let d = 0; d < dims; d += 1) avg[d] += coords[n][d];
+ for (let d = 0; d < dims; d += 1) avg[d] /= neighbours.length;
+ out[file] = base.map((x, d) => (1 - alpha) * x + alpha * avg[d]);
+ }
+ return out;
+}
+
+function weightedCentroid(files, fileCoords, dims) {
+ const v = new Array(dims).fill(0);
+ let wsum = 0;
+ for (const f of files) {
+ const c = fileCoords[normalizePath(f.path)];
+ if (!c) continue;
+ const w = f.weight ?? 1;
+ for (let d = 0; d < dims; d += 1) v[d] += c[d] * w;
+ wsum += w;
+ }
+ if (wsum > 0) for (let d = 0; d < dims; d += 1) v[d] /= wsum;
+ return v;
+}
+
+/**
+ * Embed agents in R^dims for visualization. Returns one position per agent plus
+ * the file coordinates used, so a renderer can draw both the agents and the
+ * file-cloud they sit in.
+ */
+function embedAgents(agents, graph = {}, options = {}) {
+ const dims = options.dims || 3;
+ const fileCoords = {};
+ for (const agent of agents) {
+ for (const f of agent.files || []) {
+ const p = normalizePath(f.path);
+ if (!fileCoords[p]) fileCoords[p] = fileCoordinate(p, dims);
+ }
+ }
+ const smoothed = smoothByDependency(fileCoords, graph, options.dependencyPull ?? 0.35);
+ const positions = agents.map(agent => ({
+ agentId: agent.agentId,
+ position: weightedCentroid(agent.files || [], smoothed, dims),
+ fileCount: (agent.files || []).length
+ }));
+ return { dims, positions, fileCoordinates: smoothed };
+}
+
+/**
+ * Scan the whole airspace: pairwise advisories + 3D positions in one pass.
+ *
+ * @param {Array<{agentId,files,startedAt?,intent?}>} agents
+ * @param {object} graph dependency graph (adjacency)
+ * @param {object} [options]
+ * @returns {{ advisories, positions, links, generatedAt }}
+ */
+function scanAirspace(agents, graph = {}, options = {}) {
+ const list = Array.isArray(agents) ? agents.filter(a => a && a.agentId !== null && a.agentId !== undefined) : [];
+ const advisories = [];
+ const links = [];
+ for (let i = 0; i < list.length; i += 1) {
+ for (let j = i + 1; j < list.length; j += 1) {
+ const a = list[i];
+ const b = list[j];
+ const verdict = advise(a, b, graph, options);
+ links.push({
+ a: a.agentId,
+ b: b.agentId,
+ risk: verdict.risk,
+ distance: verdict.distance,
+ level: verdict.level
+ });
+ if (verdict.level !== 'clear') {
+ advisories.push({ a: a.agentId, b: b.agentId, ...verdict });
+ }
+ }
+ }
+ advisories.sort((x, y) => y.risk - x.risk);
+ links.sort((x, y) => y.risk - x.risk);
+ const embedding = embedAgents(list, graph, options);
+ return {
+ advisories,
+ positions: embedding.positions,
+ fileCoordinates: embedding.fileCoordinates,
+ links,
+ counts: {
+ agents: list.length,
+ advisories: advisories.length,
+ resolutions: advisories.filter(a => a.level === 'resolution').length
+ }
+ };
+}
+
+module.exports = {
+ DEFAULTS,
+ scanAirspace,
+ embedAgents,
+ fileCoordinate,
+ collisionRisk,
+ advise,
+ buildDependencyGraph,
+ buildDependencyGraphFromSources
+};
diff --git a/tests/lib/agent-proximity.test.js b/tests/lib/agent-proximity.test.js
new file mode 100644
index 000000000..f4b2787fa
--- /dev/null
+++ b/tests/lib/agent-proximity.test.js
@@ -0,0 +1,170 @@
+'use strict';
+/**
+ * Tests for the agent-space distance metric + collision avoidance (Layer 4 v0).
+ */
+
+const assert = require('assert');
+
+const { treeDistance, lineRangeOverlap, graphDistance, collisionRisk, advise, closureRate } = require('../../scripts/lib/agent-proximity/distance');
+const { buildDependencyGraphFromSources, extractRelativeSpecifiers } = require('../../scripts/lib/agent-proximity/graph');
+const { scanAirspace, embedAgents } = require('../../scripts/lib/agent-proximity');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+ try {
+ fn();
+ console.log(` PASS ${name}`);
+ passed += 1;
+ } catch (e) {
+ console.log(` FAIL ${name}`);
+ console.log(` ${e.message}`);
+ failed += 1;
+ }
+}
+
+function euclid(a, b) {
+ return Math.sqrt(a.reduce((s, x, i) => s + (x - b[i]) ** 2, 0));
+}
+
+console.log('\n=== Testing agent-proximity ===\n');
+
+// ── tree distance ──
+test('treeDistance: identical path is 0', () => {
+ assert.strictEqual(treeDistance('a/b/c.js', 'a/b/c.js'), 0);
+});
+test('treeDistance: siblings are closer than cousins', () => {
+ const sib = treeDistance('src/api/users.js', 'src/api/posts.js');
+ const cousin = treeDistance('src/api/users.js', 'src/db/schema.js');
+ const disjoint = treeDistance('src/api/users.js', 'docs/guide.md');
+ assert.ok(sib < cousin, `siblings ${sib} should be < cousins ${cousin}`);
+ assert.ok(cousin < disjoint, `cousins ${cousin} should be < disjoint ${disjoint}`);
+ assert.ok(sib >= 0 && disjoint <= 1);
+});
+
+// ── line overlap ──
+test('lineRangeOverlap: full overlap when whole-file (no ranges)', () => {
+ assert.strictEqual(lineRangeOverlap([], []), 1);
+});
+test('lineRangeOverlap: partial overlapping ranges', () => {
+ const r = lineRangeOverlap([[1, 10]], [[5, 14]]);
+ // overlap lines 5..10 = 6, union 1..14 = 14 → 6/14
+ assert.ok(Math.abs(r - 6 / 14) < 1e-9, `got ${r}`);
+});
+test('lineRangeOverlap: disjoint ranges are 0', () => {
+ assert.strictEqual(lineRangeOverlap([[1, 5]], [[20, 25]]), 0);
+});
+
+// ── dependency graph + distance ──
+test('builds a dependency graph from require/import sources', () => {
+ const g = buildDependencyGraphFromSources({
+ 'src/a.js': "const b = require('./b');\nimport c from './sub/c.js';",
+ 'src/b.js': 'module.exports = {};',
+ 'src/sub/c.js': 'export default 1;'
+ });
+ assert.deepStrictEqual(new Set(g.adjacency['src/a.js']), new Set(['src/b.js', 'src/sub/c.js']));
+ assert.deepStrictEqual(g.adjacency['src/b.js'], []);
+});
+test('extractRelativeSpecifiers ignores bare (node_modules) specifiers', () => {
+ const specs = extractRelativeSpecifiers("require('fs'); require('./local'); import x from 'lodash';");
+ assert.deepStrictEqual(specs, ['./local']);
+});
+test('graphDistance: direct edge is 1, two hops is 2, unreachable is Infinity', () => {
+ const g = { adjacency: { 'a.js': ['b.js'], 'b.js': ['c.js'], 'c.js': [], 'z.js': [] } };
+ assert.strictEqual(graphDistance(g, 'a.js', 'b.js'), 1);
+ assert.strictEqual(graphDistance(g, 'a.js', 'c.js'), 2);
+ assert.strictEqual(graphDistance(g, 'a.js', 'z.js'), Infinity);
+});
+
+// ── collision risk channels ──
+test('collisionRisk: two agents editing the SAME file ⇒ high risk', () => {
+ const a = { agentId: 'a', files: [{ path: 'src/api/users.js', lines: [[1, 50]] }] };
+ const b = { agentId: 'b', files: [{ path: 'src/api/users.js', lines: [[40, 90]] }] };
+ const { risk, channels } = collisionRisk(a, b, {});
+ assert.ok(risk > 0.5, `same-file risk ${risk} should be high`);
+ assert.ok(channels.overlap > 0);
+});
+test('collisionRisk: unrelated far-apart files ⇒ low risk', () => {
+ const a = { agentId: 'a', files: [{ path: 'src/api/users.js' }] };
+ const b = { agentId: 'b', files: [{ path: 'docs/guide.md' }] };
+ const { risk } = collisionRisk(a, b, {});
+ assert.ok(risk < 0.35, `unrelated risk ${risk} should be low`);
+});
+test('collisionRisk: dependency edge raises risk even when tree-distant', () => {
+ // a edits a deep util that b's distant file imports.
+ const graph = { adjacency: { 'apps/web/page.js': ['packages/core/util.js'], 'packages/core/util.js': [] } };
+ const a = { agentId: 'a', files: [{ path: 'packages/core/util.js' }] };
+ const b = { agentId: 'b', files: [{ path: 'apps/web/page.js' }] };
+ const coupled = collisionRisk(a, b, graph).risk;
+ const uncoupled = collisionRisk(a, b, {}).risk; // same files, no graph
+ assert.ok(coupled > uncoupled, `coupled ${coupled} should exceed uncoupled ${uncoupled}`);
+ assert.ok(coupled > 0.3, `dependency-coupled risk ${coupled} should be elevated`);
+});
+
+// ── TCAS advisories ──
+test('advise: clear when far apart', () => {
+ const a = { agentId: 'a', files: [{ path: 'src/api/users.js' }] };
+ const b = { agentId: 'b', files: [{ path: 'docs/guide.md' }] };
+ assert.strictEqual(advise(a, b, {}).level, 'clear');
+});
+test('advise: resolution on same-file, lower-priority agent steers', () => {
+ // a has more committed work (3 weighted files) ⇒ holds; b steers.
+ const a = {
+ agentId: 'lead',
+ files: [
+ { path: 'src/api/users.js', lines: [[1, 80]], weight: 1 },
+ { path: 'src/api/posts.js', weight: 1 },
+ { path: 'src/api/auth.js', weight: 1 }
+ ]
+ };
+ const b = { agentId: 'worker', files: [{ path: 'src/api/users.js', lines: [[1, 80]], weight: 1 }] };
+ const v = advise(a, b, {});
+ assert.strictEqual(v.level, 'resolution', `level was ${v.level} (risk ${v.risk})`);
+ assert.strictEqual(v.transmit, true);
+ assert.strictEqual(v.steer, 'worker', 'lower-priority worker steers');
+ assert.strictEqual(v.hold, 'lead', 'higher-priority lead holds');
+});
+test('advise: deterministic — same inputs give same maneuver', () => {
+ const a = { agentId: 'a', files: [{ path: 'x/y.js', lines: [[1, 20]] }] };
+ const b = { agentId: 'b', files: [{ path: 'x/y.js', lines: [[1, 20]] }] };
+ const v1 = advise(a, b, {});
+ const v2 = advise(a, b, {});
+ assert.deepStrictEqual({ s: v1.steer, h: v1.hold, l: v1.level }, { s: v2.steer, h: v2.hold, l: v2.level });
+});
+
+// ── closure rate ──
+test('closureRate: positive when approaching', () => {
+ assert.ok(closureRate(0.2, 0.5, 1000) > 0);
+ assert.ok(closureRate(0.6, 0.3, 1000) < 0);
+});
+
+// ── embedding ──
+test('embedAgents: tree-close agents embed closer than far ones', () => {
+ const near1 = { agentId: 'n1', files: [{ path: 'src/api/users.js' }] };
+ const near2 = { agentId: 'n2', files: [{ path: 'src/api/posts.js' }] };
+ const far = { agentId: 'f', files: [{ path: 'docs/guide.md' }] };
+ const { positions } = embedAgents([near1, near2, far], {});
+ const pos = Object.fromEntries(positions.map(p => [p.agentId, p.position]));
+ const dNear = euclid(pos.n1, pos.n2);
+ const dFar = euclid(pos.n1, pos.f);
+ assert.ok(dNear < dFar, `near pair ${dNear} should embed closer than far ${dFar}`);
+});
+
+// ── full scan ──
+test('scanAirspace: surfaces only non-clear advisories, sorted by risk', () => {
+ const agents = [
+ { agentId: 'a', files: [{ path: 'src/api/users.js', lines: [[1, 50]] }] },
+ { agentId: 'b', files: [{ path: 'src/api/users.js', lines: [[1, 50]] }] }, // collides with a
+ { agentId: 'c', files: [{ path: 'docs/guide.md' }] } // clear of everyone
+ ];
+ const scan = scanAirspace(agents, {});
+ assert.strictEqual(scan.counts.agents, 3);
+ assert.ok(scan.advisories.length >= 1, 'a/b should produce an advisory');
+ assert.strictEqual(scan.advisories[0].risk, Math.max(...scan.advisories.map(x => x.risk)));
+ // c is clear of both ⇒ not in advisories
+ assert.ok(!scan.advisories.some(adv => adv.a === 'c' || adv.b === 'c'));
+ assert.strictEqual(scan.positions.length, 3);
+});
+
+console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
+if (failed > 0) process.exit(1);