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 / operator-control-plane-and-readiness

Operator control plane and readiness

The JavaScript operator layer gives ECC operators one local view of agent work, system readiness, and session evidence. It combines live control-pane state with proximity signals, repeatable readiness reports, a capabilities dashboard, and adapter-based session inspection so operators can see current work and decide what needs attention without relying on hosted telemetry.

Operator control plane

The control plane is a local, loopback-only service that turns ECC state into operator views. It reads session and work-item state, adds optional knowledge and proximity data, and exposes both a broad control pane and a focused live control-plane view.

Control-pane state

The control-pane snapshot is the shared state model for the operator service. It gives the UI a current view of sessions, work items, knowledge results, connector status, database presence, and available actions. The snapshot can run without an existing database, which lets the operator distinguish an empty or new setup from a healthy populated one.

References: scripts/…/state.js• L9-35 scripts/…/state.js• L584-669

Local operator interface

The control-pane server serves the main board and JSON endpoints from a local host. Operators can inspect health, request a snapshot, view agent proximity, open the 2D control plane, and use allowlisted work-item actions. Host and origin checks keep this surface local, while --read-only removes action execution when an operator needs observation without mutation.

The main board is the broad operator surface. It presents counts and current work, while the control-plane view is the focused surface for live agent coordination. The related page Control-plane views and agent proximity explains those focused views and their visual model.

References: scripts/control-pane.js• L25-61 scripts/…/server.js• L175-216 scripts/…/server.js• L221-318 scripts/…/ui.js• L1-180

Control-plane view

The live control-plane view joins three operator signals into one read-only document: session state, agent proximity, and coordination inventory. It presents sessions as tasks grouped into lanes, pair links as risk relationships, and advisories or declared lease conflicts as events. This shape lets another board consume the view without knowing the internal ECC data sources.

The view keeps a short rolling sample window for its display projection and refreshes the source on a fixed interval. Repeated or concurrent reads share one refresh, so the dashboard does not create extra scans for every browser request.

References: scripts/…/control-plane-view.js• L4-27 scripts/…/control-plane-view.js• L217-313 scripts/…/control-plane-view.js• L316-347 scripts/…/server.js• L190-205 scripts/…/server.js• L280-300

Readiness and observability

Readiness tools answer a different question from the live control plane: whether the signals and release evidence needed for safe operation are present. They inspect local files and, when requested, live GitHub queues, then report evidence and next actions instead of sending telemetry.

Observability readiness

The observability gate checks whether ECC has the basic signals needed before larger autonomous runs. Its scope covers live loop status, a portable HUD and session-control contract, session traces, harness scorecards, local tool activity, a risk ledger, tracker sync, and release-safety evidence.

The report is deterministic. It returns a score, categories, individual checks, and up to three prioritized fixes. A missing signal fails only the related check, so an operator can see the gap without losing the rest of the report.

References: scripts/observability-readiness.js• L7-19 scripts/observability-readiness.js• L113-139 scripts/observability-readiness.js• L141-350 scripts/observability-readiness.js• L354-400 docs/…/observability-readiness.md• L1-16

Operator readiness dashboard

The operator readiness dashboard combines the platform audit with a wider ECC work and release review. It reports repository state, GitHub queue pressure, discussions, release artifacts, observability, supply-chain protection, progress sync, growth work, and approval-gated next actions.

The dashboard has separate states for objective readiness, dashboard readiness, and publication readiness. This separation prevents a clean local platform audit from being treated as permission to publish or send external communications. Operators can render the report as text, JSON, or Markdown and can save the latter two as evidence.

References: scripts/operator-readiness-dashboard.js• L9-39 scripts/operator-readiness-dashboard.js• L627-650 scripts/operator-readiness-dashboard.js• L974-1034 scripts/operator-readiness-dashboard.js• L1043-1067 tests/…/operator-readiness-dashboard.test.js• L342-463 tests/…/operator-readiness-dashboard.test.js• L699-815

Readiness workflow

Readiness is used as a staged operator check rather than as a single health flag. The flow starts with the local observability gate, adds the broader harness and loop signals, confirms available session adapters, and then checks tracker and release evidence before any public action.

The following sequence shows how local signals become an operator decision.

flowchart TD
    A[Local ECC state] --> B[Observability readiness]
    B --> C[Harness and loop status]
    C --> D[Session adapter and trace review]
    D --> E[Operator readiness dashboard]
    E --> F{Release or publication action?}
    F -->|No| G[Continue local operation]
    F -->|Yes| H[Review approval and safety evidence]
    H --> I[Publish only when separate gates pass]

References: docs/…/observability-readiness.md• L63-85 scripts/observability-readiness.js• L404-445 scripts/operator-readiness-dashboard.js• L1003-1033

Dashboard surfaces

ECC has two JavaScript dashboard families with different jobs. The control pane is a live local operations surface. The capabilities dashboard is a catalog and search surface for the tools that make up ECC.

Capabilities dashboard

The capabilities dashboard gives an operator a searchable view of agents, skills, commands, rules, MCP configurations, and hooks. It reads local project metadata, groups related commands, supports recent-item navigation, and offers language and theme controls. It is useful for finding how ECC can act; it is not the live source of session or readiness state.

The server binds to loopback by default and rejects a non-loopback ECC_DASHBOARD_HOST. This keeps the catalog local while still allowing an operator to choose a valid local port.

References: scripts/dashboard-web.js• L1-45 scripts/dashboard-web.js• L70-143 scripts/dashboard-web.js• L164-181 tests/…/dashboard-web.test.js• L190-220

Session inspection

Session inspection turns different session sources into a common JSON snapshot for operator review. The command can inspect orchestration plans, named sessions, Claude history, direct session files, and the skill improvement loop. It can print the snapshot, write it to disk, or list the adapters that are available in the current installation.

Adapter routing

The adapter registry maps a target type to the session source that understands it. The default set covers Claude history, dmux or tmux sessions, Codex worktrees, and OpenCode. Explicit target types override guessing, which gives operators a stable way to inspect a source when a name could match more than one adapter.

References: scripts/session-inspect.js• L13-37 scripts/…/registry.js• L8-17 scripts/…/registry.js• L35-41 scripts/…/registry.js• L99-141

Canonical session snapshots

Each adapter produces a canonical session snapshot with a schema version, source target, session state, workers, runtime details, intent, and derived health. This common shape lets operators compare sessions from different harnesses and lets later tools persist or process the result without knowing the original source format.

Session inspection also supports the skill improvement loop. Operators can review recorded skill outcomes, propose an amendment from failure evidence, and build a baseline-versus-amended evaluation scaffold through the same command.

References: scripts/…/canonical-session.js• L7-9 scripts/…/canonical-session.js• L69-115 scripts/…/canonical-session.js• L162-220 scripts/session-inspect.js• L66-97 tests/…/session-inspect.test.js• L73-167 tests/…/session-inspect.test.js• L169-294

Operator boundaries

The control-plane data supports review and coordination, but it does not make every observed state authoritative. Operators must read the source and freshness limits of each signal before taking action.

SignalOperator meaningBoundary
Session state and heartbeatCurrent or last-known activity from the local session storeMissing or stale timestamps can make health unknown
Proximity advisoryA risk signal from changed files and dependency relationshipsIt is advisory and does not itself steer, pause, or lock an agent
Inventory lease conflictMultiple declared owners appear to claim one resourceA declared lease is not a real lock
Readiness resultLocal evidence says which checks pass and which need workIt does not grant publication or external-send approval
Session snapshotA normalized view of one inspected sourceIt reflects the adapter's source and capture time

References: scripts/…/control-plane-view.js• L25-27 scripts/…/control-plane-view.js• L268-312 scripts/…/proximity.js• L57-72 scripts/…/canonical-session.js• L77-95 scripts/operator-readiness-dashboard.js• L1003-1033

Change checklist

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

  • Keep the control-plane view schema and the browser validator aligned. A changed task, lane, event, projection, or threshold shape can make the UI show offline even when the server is healthy.
  • Keep the control-pane snapshot fields aligned with the view builder. The view needs sessions and proximity data, while the broader board also depends on work items, knowledge, connectors, and action state.
  • Keep session target types aligned across the CLI help, registry mapping, adapter declarations, and canonical snapshot source metadata.
  • Keep readiness check IDs and report states aligned with the operator dashboard's requirement and top-action logic. A renamed check can silently remove a needed release signal.
  • Keep loopback host and origin rules consistent across the control pane and capabilities dashboard when changing local server exposure.
  • Preserve the declared-only label for inventory observations unless the source gains real lock authority. Operators may act on a warning, but must not read it as a lock.

Important failure modes

TriggerConsequenceGuard
The control-plane API returns an invalid schema or a failed requestThe browser marks the live view offline instead of presenting possibly false healthy dataThe UI validates the schema and treats request or validation errors as offline; tests/…/control-plane-view-ui.test.js• L33-50 covers this behavior
The session database is absent or unreadableThe control pane can return an empty base snapshot, and the view can show no tasks even though the server is runningCheck /api/health, database presence, and snapshot counts before treating an empty view as proof that no sessions exist
A worktree diff or dependency scan failsProximity data becomes incomplete or empty for the affected sessionsTreat missing projection points and zero pairs as unknown coverage, not as proof of no work; scripts/…/proximity.js• L57-72
Inventory construction failsInventory becomes unavailable, but session tasks and proximity advisories can still remain visibleCheck the inventory status and reason separately from the task and event counts; scripts/…/control-plane-view.js• L133-142
A declared lease conflict is treated as an enforced lockAn operator may block or reroute work based on ownership that the system does not enforceRead the event as a review warning because leases are declared-only; scripts/…/control-plane-view.js• L196-207
GitHub checks are skipped or fail in the readiness dashboardQueue and discussion evidence is not current, while local requirements may still look completeInspect githubSkipped and githubErrors before using the dashboard for a release decision; scripts/operator-readiness-dashboard.js• L1009-1023
A session target has no matching adapter or lacks its required type or valueSession inspection stops without a canonical snapshotList adapters or pass an explicit target type before retrying; scripts/…/registry.js• L52-66, scripts/…/registry.js• L119-141

Key files

FileWhy to read it
scripts/control-pane.jsStarts the local operator service and reports its URLs, data paths, and action mode.
scripts/…/server.jsShows how health, snapshots, proximity, control-plane views, events, and actions share one local HTTP surface.
scripts/…/state.jsDefines the broad snapshot that joins sessions, work items, knowledge, connectors, and action availability.
scripts/…/control-plane-view.jsDefines the read-only ecc.control-plane.view.v1 model used by focused control-plane consumers.
scripts/…/control-plane-view-ui.jsShows how the focused view displays projected agents, lanes, tasks, and advisory events.
scripts/operator-readiness-dashboard.jsDefines the broad readiness report, evidence model, output formats, and next work order.
scripts/observability-readiness.jsDefines the deterministic signal and safety checks for local observability readiness.
scripts/session-inspect.jsProvides the operator command for adapter listing, session inspection, skill-loop review, and snapshot writing.
scripts/…/registry.jsDefines target normalization and adapter selection across supported session sources.
scripts/…/canonical-session.jsDefines the common session snapshot and worker health model.
scripts/dashboard-web.jsServes the local searchable catalog of ECC capabilities and enforces loopback host selection.
docs/…/observability-readiness.mdExplains the operator workflow and the limits of local readiness evidence.