Introducing a new way to review your PRs.

Read the announcement

affaan-m / ecc

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

View on GitHub

30 documents · Updated Nov 20, 2026

docs / control-plane-views-and-agent-proximity

Control-plane views and agent proximity

The control-plane view turns live session state, agent proximity, and coordination observations into one read-only operator view. It gives a consumer stable tasks, lanes, pairs, projection points, and events while the proximity tools measure how agent work may converge and place that state in 2D or 3D displays. A shadow coordination trail records observation-only advisory history for the same coordination state. For the wider operator model, see Operator control plane and readiness.

Control-plane view

The control-plane view is the shared contract between the control-pane state source and operator clients. It hides ECC-specific sources behind a document shaped around tasks, lanes, and events.

View contract

The view uses the ecc.control-plane.view.v1 schema. A task represents one session, including its state, worktree, heartbeat, changed files, proximity summary, and declared-only inventory observations. A lane groups tasks by task group first, then project, then harness. An event gives an operator or a polling hook a stable subject, severity, action, and message.

The contract also carries pair links and projection metadata. Pair links retain raw risk and the three shipped channels: tree proximity, edit overlap, and dependency coupling. The projection is a display coordinate and must not be used as a replacement for risk or right-of-way.

The inventory portion adds heartbeat and lease observations to the same view. It is read-only and declared-only. A reported lease conflict is a signal for review, not proof that a lock exists.

References: scripts/…/control-plane-view.js• L3-27 scripts/…/control-plane-view.js• L271-312 docs/…/VIEW-CONTRACT.md• L26-41 docs/…/VIEW-CONTRACT.md• L45-75

View assembly

The view starts with a control-pane snapshot that contains normalized sessions and a proximity snapshot. It maps sessions into tasks and lanes, joins each task to its proximity projection and inventory row, then creates events from proximity links and declared lease conflicts.

The assembly keeps the data sources separate in meaning. Session state says what is running. Proximity says which working sets may collide. Inventory says what was declared and how fresh it appears. This lets an operator compare live activity with coordination evidence without treating any one source as a control command.

The long-lived view source keeps one projection window and refreshes the snapshot at a fixed interval. Concurrent refreshes share one pending result. A client can request the full view or a smaller event feed for polling and hooks.

The main data flow is:

flowchart LR
  S[Session snapshot] --> P[Working sets and proximity scan]
  S --> I[Declared inventory]
  P --> X[Pair links and projection]
  P --> E[Proximity events]
  I --> E2[Lease conflict events]
  S --> T[Tasks and lanes]
  T --> V[Control-plane view]
  X --> V
  E --> V
  E2 --> V
  V --> J[JSON clients and operator pages]

References: scripts/…/control-plane-view.js• L217-285 scripts/…/control-plane-view.js• L321-347 scripts/…/server.js• L247-299 docs/…/VIEW-CONTRACT.md• L14-24

Event meaning

Proximity events use static traffic and resolution thresholds. A traffic event asks both agents to share intent. A resolution event names the agent that steers and the agent that holds course. The right-of-way choice is deterministic so every consumer sees the same maneuver.

Lease-conflict events use a review action. They do not acquire, release, or enforce a lease. Event identifiers remain stable across polls so a consumer can avoid showing the same condition as a new event every time.

References: scripts/…/control-plane-view.js• L155-207 scripts/…/control-plane-view.js• L268-285 docs/…/VIEW-CONTRACT.md• L77-103

Agent-proximity state

Agent proximity turns each session's changed files into a working set and compares participating agents in code space. Only sessions with a worktree and at least one changed file take part in collision checks; sessions without edits remain visible as tasks but have no pair position.

Distance channels

The distance model reports collision risk and its dual distance. It combines three signals with a noisy-OR rule:

  • Edit overlap detects the same file and gives line ranges more precision than file-name matching.
  • Dependency coupling detects files that are linked in the static in-repository import graph, even when their paths are far apart. The graph follows relative JavaScript and TypeScript imports, requires, dynamic imports, and re-exports. It also resolves common source and index-file forms so emitted JavaScript names can still point to TypeScript source.
  • Tree proximity provides a weaker directory-based signal.

Risk bands produce clear state, traffic advisories, or resolution advisories. More committed work gets right-of-way. An earlier start breaks a progress tie, and a stable agent id makes the final choice repeatable.

References: scripts/…/distance.js• L19-31 scripts/…/distance.js• L101-114 scripts/…/distance.js• L243-310 scripts/…/graph.js• L3-13 scripts/…/graph.js• L28-39 docs/…/agent-proximity.md• L29-40 docs/…/agent-proximity.md• L92-111

Proximity snapshot

The control-pane proximity layer supplies the distance model with session working sets and a dependency graph. The graph is built from the files in scope and records only resolvable in-repository relative links. It returns agent summaries, pair links, 3D positions, advisories, and trigger messages as one snapshot. A graph or working-set failure reduces the available proximity data instead of breaking the control-pane snapshot.

The scan is advisory for the view. A separate proximity tick can deliver the resulting transmit, hold, or steer messages to internal ECC sessions. That delivery path is best effort and uses a cooldown so a persistent collision does not repeatedly message agents.

References: scripts/…/proximity.js• L57-72 scripts/…/proximity.js• L92-169 scripts/…/proximity.js• L172-237 scripts/…/graph.js• L92-123 scripts/…/graph.js• L125-148 scripts/…/index.js• L117-159 scripts/proximity-tick.js• L75-100

Shadow coordination trail

A shadow coordination trail is a passive local record of observations and the advisory state derived from them. It gives the operator a bounded history of observations, advisories, acknowledgements, declared scope changes, and re-observations without claiming authority to resolve a conflict or prove delivery.

The trail follows a controlled sequence. It first compares two observations in a shared context, then records an advisory. An advisory can be acknowledged by both agents before one agent declares a scope change. A fresh observation then produces the next advisory. Context mismatch, stale data, or an incomplete footprint produces an unknown state instead of an actionable advisory.

This diagram shows the lifecycle of a shadow coordination trail.

flowchart LR
  O[Pair observations] --> A[Derived advisory]
  A --> K[Agent acknowledgements]
  K --> C[Declared scope change]
  C --> R[Re-observation]
  R --> A2[Next advisory]

Receipt links detect accidental changes and preserve order. They do not authenticate a producer, authorize a scope, enforce a lock, or prove that a message reached an agent.

References: scripts/…/shadow-trail.js• L3-11 scripts/…/shadow-trail.js• L111-130 scripts/…/shadow-trail.js• L211-260 scripts/…/shadow-trail.js• L263-296 scripts/…/shadow-trail.js• L349-357

Spatial positions

The 3D position model gives each file a repeatable coordinate from its path. It pulls coordinates toward dependency neighbors, then places an agent at the weighted center of its files. This makes directory closeness and dependency coupling visible in one code-space display.

The position is for observation. The risk calculation remains the source for advisory level and right-of-way. Operators can therefore use the spatial view to understand why agents appear near each other without treating screen distance as a new decision rule.

References: scripts/…/index.js• L21-53 scripts/…/index.js• L55-113 scripts/…/index.js• L124-159 docs/…/agent-proximity.md• L117-129

Projection and UI assembly

The control pane offers two views of the same coordination state. The control-plane page shows a 2D projection with task and event context. The airspace page shows 3D proximity positions with pair links and advisories.

Pair projection

The 2D projection uses the pair channel vector x_tree, x_overlap, and x_dep. A rolling window supplies context for z-score normalization and tail clipping once it has enough samples. Static channel weights are then applied before PCA produces two display components.

Each agent receives a risk-weighted center of the pair points in which it appears. With too few samples or no variance, the utility returns raw values or zero scores rather than unstable coordinates. The projection reports its normalization mode and window state so a client can explain what the screen shows.

References: scripts/…/projection.js• L4-23 scripts/…/projection.js• L67-125 scripts/…/projection.js• L216-292 docs/…/VIEW-CONTRACT.md• L105-121

Control-plane page

The /control-plane page polls /api/control-plane and validates the schema before replacing its local state. It draws projected agents and pair links on a canvas. The side panel groups tasks by lane and lists advisory or conflict events. Colors make clear, traffic, and resolution states distinct, while task size reflects working-set size.

The page is self-contained. It uses no external scripts or framework, which allows it to run on the loopback control pane under a strict content policy and without network access beyond its API request.

References: scripts/…/control-plane-view-ui.js• L3-10 scripts/…/control-plane-view-ui.js• L111-159 scripts/…/control-plane-view-ui.js• L161-236 scripts/…/server.js• L280-299

Airspace page

The /proximity page polls /api/proximity and renders the scan's 3D positions. It rotates the scene over time, draws risk-bearing pair links beneath the agent points, and lists the current advisories beside the canvas. Agent size reflects the number of changed files, while color reflects the highest pair risk for that agent.

This page is a direct view of the proximity snapshot. It is useful when an operator needs spatial context, while the control-plane page is better for joining proximity with task lanes, inventory, and a unified event feed.

References: scripts/…/proximity-viz.js• L3-14 scripts/…/proximity-viz.js• L90-132 scripts/…/proximity-viz.js• L135-185 scripts/…/server.js• L261-277

Operator boundaries

The view and its visualizations observe and explain coordination state. They do not steer, pause, lock, or claim that a conflict has been reduced. The proximity tick can send internal coordination messages, but that action is separate from rendering and can run in dry-run mode.

Consumers should treat failed or unavailable data as a visible state. An empty view can mean that no sessions or pairs are present. An offline page means its request or view validation failed. An unavailable inventory section means the inventory could not be built; it does not invalidate the session or proximity data.

References: scripts/…/control-plane-view.js• L307-312 scripts/…/control-plane-view.js• L133-140 scripts/…/control-plane-view-ui.js• L209-231 scripts/proximity-tick.js• L47-54 docs/…/VIEW-CONTRACT.md• L137-141

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the ecc.control-plane.view.v1 field meanings aligned across the builder, the full JSON endpoint, the event-only endpoint, and both page validators.
  • If a proximity channel, threshold, or action changes, update the risk labels, event levels, right-of-way fields, and message text together.
  • If projection channels or normalization change, keep the rolling-window metadata, PCA output, 2D renderer, and 3D renderer's risk source distinct.
  • If session or working-set identity rules change, preserve the join between task ids, proximity agent ids, and sanitized inventory ids.
  • If refresh or polling behavior changes, check that the shared projection window does not receive duplicate samples from concurrent or idle reads.
  • If advisory delivery changes, keep the view read-only and preserve tick cooldown and dry-run behavior.
  • If shadow-trail receipt kinds or advisory states change, keep the receipt sequence, summary fields, and observation-only boundary aligned.
  • If dependency-graph resolution changes, keep relative import discovery, TypeScript source fallback, and the graph's repo-relative file identity aligned with the distance channel.

Important failure modes

TriggerConsequenceGuard
A session has no changed filesIt appears as a task but has no pair, projection point, or proximity eventKeep the task in the view and show a null projection point rather than inventing a position
The projection window is cold or has no varianceCoordinates are raw or zero and may not show useful separationRead projection.normalization and window metadata before comparing points
The inventory builder failsInventory is marked unavailable, but session and proximity data can still renderCheck inventory.status and show the reason without replacing the full view with empty data
A lease conflict is reportedOperators may mistake a declared conflict for an enforced lockTreat the event as review-only because its authority is declared-only
The API returns an invalid view or a failed HTTP responseThe control-plane page shows offline state and keeps the bad response out of the rendererValidate schema version, required arrays, thresholds, and projection agents before applying data
A collision persists across proximity ticksAgents could receive repeated coordination messagesUse the per-trigger cooldown or run the tick in dry-run mode
A dependency edge cannot resolve or a scanned source file cannot be readDependency coupling misses a relation and can understate proximity riskKeep graph input paths repo-relative and treat graph output as partial proximity data
Shadow observations use different repositories or base revisionsThe trail reports an unknown state instead of a comparable advisoryKeep observations in the same coordination context before interpreting the result
A shadow observation is stale or incompleteThe trail withholds an actionable advisoryRefresh the observations and complete the working-set footprint
A receipt is changed, reordered, or appended after the trail limitTrail verification fails and its summary is unavailableVerify the trail before using its state and preserve its bounded receipt history

Key files

FileWhy to read it
scripts/…/control-plane-view.jsDefines the stable task, lane, pair, event, projection, and inventory view contract.
scripts/…/control-plane-view-ui.jsShows how the 2D operator page validates and assembles the contract into a canvas and side panels.
scripts/…/proximity.jsConnects control-pane sessions to working sets, dependency scans, advisories, and optional message dispatch.
scripts/…/distance.jsDefines risk channels, thresholds, distance, and deterministic right-of-way.
scripts/…/graph.jsBuilds the static dependency links that support the dependency-coupling distance channel.
scripts/…/index.jsCombines pair scanning, 3D embedding, and proximity triggers.
scripts/…/projection.jsDefines rolling normalization, PCA, pair points, and agent display positions.
scripts/…/shadow-trail.jsRecords observation-only advisory history and its declared coordination changes.
scripts/…/proximity-viz.jsShows the direct 3D airspace presentation of positions, links, and advisories.
scripts/…/server.jsMaps the HTML and JSON routes to the view and proximity sources.
docs/…/VIEW-CONTRACT.mdRecords the consumer-facing schema, endpoint behavior, and limits.
docs/…/agent-proximity.mdExplains the distance model and the operator meaning of its advisories.