The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat(control-pane): wire agent-proximity into the snapshot (opt-in, live)
Affaan Mustafa7df803935ac8
diff --git a/scripts/lib/control-pane/proximity.js b/scripts/lib/control-pane/proximity.jsnew file mode 100644index 000000000..bc7378d38--- /dev/null+++ b/scripts/lib/control-pane/proximity.js@@ -0,0 +1,111 @@+'use strict';++/**+ * Control-pane integration for the agent-space proximity metric.+ *+ * Turns live sessions into agent working sets (the files each session's worktree+ * has changed), builds the dependency graph over those files, and runs the+ * TCAS-style airspace scan — so the board can surface "two agents are converging"+ * advisories and a 3D position per agent. See docs/design/agent-proximity.md.+ */++const path = require('path');+const { execFileSync } = require('child_process');++const { scanAirspace } = require('../agent-proximity');+const { buildDependencyGraph } = require('../agent-proximity/graph');++/**+ * Default working-set source: `git diff --name-only <base>` inside a session's+ * worktree, returning repo-relative changed files. Returns [] on any failure so+ * proximity degrades gracefully (never throws into the snapshot path).+ */+function defaultChangedFilesFor(session) {+ const wt = session && session.worktree;+ if (!wt || !wt.path) return [];+ const base = wt.base || 'HEAD';+ try {+ const out = execFileSync('git', ['-C', wt.path, 'diff', '--name-only', `${base}...HEAD`], {+ encoding: 'utf8',+ timeout: 4000,+ stdio: ['ignore', 'pipe', 'ignore']+ });+ return out+ .split('\n')+ .map(s => s.trim())+ .filter(Boolean);+ } catch {+ return [];+ }+}++/**+ * Map sessions to agent working sets. Only sessions with a worktree and at least+ * one changed file participate (an agent with no edits cannot collide).+ */+function sessionsToAgents(sessions, deps = {}) {+ const changedFilesFor = deps.changedFilesFor || defaultChangedFilesFor;+ const agents = [];+ for (const session of sessions || []) {+ const files = changedFilesFor(session).map(p => ({ path: p, weight: 1 }));+ if (files.length === 0) continue;+ agents.push({+ agentId: session.id,+ label: session.task || session.id,+ startedAt: session.createdAt || null,+ files+ });+ }+ return agents;+}++/**+ * Compute the proximity snapshot from the control-pane sessions.+ *+ * @param {Array} sessions normalized control-pane sessions+ * @param {object} [options] { repoRoot, changedFilesFor, ...scanOptions }+ * @returns {{ enabled, advisories, positions, links, counts }}+ */+function buildProximitySnapshot(sessions, options = {}) {+ const repoRoot = path.resolve(options.repoRoot || path.join(__dirname, '..', '..', '..'));+ const agents = sessionsToAgents(sessions, options);++ // Need at least two participating agents for a collision to be possible.+ if (agents.length < 2) {+ return {+ enabled: true,+ advisories: [],+ positions: agents.map(a => ({ agentId: a.agentId, position: [0, 0, 0], fileCount: a.files.length })),+ links: [],+ counts: { agents: agents.length, advisories: 0, resolutions: 0 }+ };+ }++ const touched = [...new Set(agents.flatMap(a => a.files.map(f => f.path)))];+ let graph = { adjacency: {}, files: [] };+ try {+ graph = options.graph || buildDependencyGraph(repoRoot, touched, options.graphDeps || {});+ } catch {+ graph = { adjacency: {}, files: [] };+ }++ const scan = scanAirspace(agents, graph, options);+ const labels = new Map(agents.map(a => [a.agentId, a.label]));+ return {+ enabled: true,+ advisories: scan.advisories.map(adv => ({+ ...adv,+ aLabel: labels.get(adv.a) || adv.a,+ bLabel: labels.get(adv.b) || adv.b+ })),+ positions: scan.positions,+ links: scan.links,+ counts: scan.counts+ };+}++module.exports = {+ buildProximitySnapshot,+ sessionsToAgents,+ defaultChangedFilesFor+};diff --git a/scripts/lib/control-pane/state.js b/scripts/lib/control-pane/state.jsindex af10fc6a0..b6c41d056 100644--- a/scripts/lib/control-pane/state.js+++ b/scripts/lib/control-pane/state.js@@ -633,6 +633,14 @@ async function buildControlPaneSnapshot(options = {}) {const entities = readEntities(db);const observations = readObservations(db);const relationCounts = readRelationCounts(db);+ // Proximity (agent-space collision avoidance) is opt-in: it shells `git diff`+ // per worktree, so we only compute it when explicitly requested to keep the+ // default snapshot fast.+ let proximity = null;+ if (options.includeProximity) {+ const { buildProximitySnapshot } = require('./proximity');+ proximity = buildProximitySnapshot(sessions, { repoRoot, ...(options.proximityOptions || {}) });+ }return {...base,summary: summarizeSessions(sessions),@@ -649,7 +657,8 @@ async function buildControlPaneSnapshot(options = {}) {limit})},- connectors: connectorStatus(config, db)+ connectors: connectorStatus(config, db),+ proximity};} finally {db.close();diff --git a/tests/lib/control-pane-proximity.test.js b/tests/lib/control-pane-proximity.test.jsnew file mode 100644index 000000000..e15bc51d1--- /dev/null+++ b/tests/lib/control-pane-proximity.test.js@@ -0,0 +1,91 @@+'use strict';+/**+ * Tests for the control-pane proximity integration (sessions -> airspace scan).+ */++const assert = require('assert');++const { buildProximitySnapshot, sessionsToAgents } = require('../../scripts/lib/control-pane/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;+ }+}++const sessions = [+ {+ id: 'lead-hermes',+ task: 'Build the API',+ createdAt: '2026-06-19T10:00:00Z',+ worktree: { path: '/wt/lead', base: 'main' }+ },+ {+ id: 'worker-kb',+ task: 'Also touch the API',+ createdAt: '2026-06-19T10:05:00Z',+ worktree: { path: '/wt/worker', base: 'main' }+ },+ {+ id: 'docs-bot',+ task: 'Write docs',+ createdAt: '2026-06-19T10:06:00Z',+ worktree: { path: '/wt/docs', base: 'main' }+ },+ { id: 'no-worktree', task: 'idle', createdAt: '2026-06-19T10:07:00Z', worktree: null }+];++// Injected working sets: lead + worker both edit the same API file (collision);+// docs-bot edits an unrelated file (clear).+const changedFilesFor = session =>+ ({+ 'lead-hermes': ['src/api/users.js'],+ 'worker-kb': ['src/api/users.js'],+ 'docs-bot': ['docs/guide.md'],+ 'no-worktree': []+ })[session.id] || [];++test('sessionsToAgents: only worktree sessions with edits participate', () => {+ const agents = sessionsToAgents(sessions, { changedFilesFor });+ assert.deepStrictEqual(agents.map(a => a.agentId).sort(), ['docs-bot', 'lead-hermes', 'worker-kb']);+ assert.strictEqual(agents.find(a => a.agentId === 'lead-hermes').files[0].path, 'src/api/users.js');+});++test('buildProximitySnapshot: same-file editors get a resolution; the later one steers', () => {+ const prox = buildProximitySnapshot(sessions, { changedFilesFor, graph: { adjacency: {} } });+ assert.strictEqual(prox.enabled, true);+ assert.strictEqual(prox.counts.agents, 3);+ const collision = prox.advisories.find(a => [a.a, a.b].includes('lead-hermes') && [a.a, a.b].includes('worker-kb'));+ assert.ok(collision, 'lead/worker should produce an advisory');+ assert.strictEqual(collision.level, 'resolution', `level ${collision.level} risk ${collision.risk}`);+ // lead started earlier ⇒ holds; worker steers.+ assert.strictEqual(collision.steer, 'worker-kb');+ assert.strictEqual(collision.hold, 'lead-hermes');+ // docs-bot is clear of both.+ assert.ok(!prox.advisories.some(a => a.a === 'docs-bot' || a.b === 'docs-bot'));+ // every participating agent gets a 3D position.+ assert.strictEqual(prox.positions.length, 3);+});++test('buildProximitySnapshot: fewer than two participants ⇒ no advisories', () => {+ const single = buildProximitySnapshot([sessions[0]], { changedFilesFor });+ assert.strictEqual(single.counts.agents, 1);+ assert.strictEqual(single.advisories.length, 0);+});++test('buildProximitySnapshot: advisories carry human-readable labels', () => {+ const prox = buildProximitySnapshot(sessions, { changedFilesFor, graph: { adjacency: {} } });+ const collision = prox.advisories[0];+ assert.ok(collision.aLabel && collision.bLabel, 'labels present');+});++console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);+if (failed > 0) process.exit(1);