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 / ecc2-observability-notifications-and-tui

ECC2 observability, notifications, and TUI

ECC2 gives an operator one view of live agent work and the records needed to understand it later. The terminal UI combines session state, output, activity, cost, risk, worktree health, coordination pressure, and harness data. A refresh cycle keeps that view current and sends selected state changes to desktop or webhook targets. This page describes the observation side of the ECC2 terminal control plane; session messaging and worktree ownership are covered in sessions, communications, and worktrees.

Operator dashboard

The dashboard is the main operator surface for ECC2. It turns stored session state and live output into a navigable terminal view while keeping action feedback close to the state that caused it. The CLI opens this view through ecc2/…/app.rs and ecc2/…/main.rs.

The layout presents these related views:

ViewOperator question
SessionsWhich sessions exist and which ones need attention from approvals, backlog, or worktree state?
OutputWhat is the selected agent saying or doing now?
MetricsWhat is the selected session using and what is the team using overall?
BoardHow is work grouped and moving through coordination lanes?
LogWhich tools ran, for how long, and with what risk?

The operator can change pane focus, layout, theme, scroll position, search scope, and output mode without leaving the dashboard. The same surface exposes session control and worktree actions. It also shows operator notes and an aggregate cost summary beside the normal status bar, so a signal can lead directly to a response without changing tools. References: ecc2/…/app.rs• L15-149, ecc2/…/dashboard.rs• L658-692, ecc2/…/dashboard.rs• L1442-1529

Runtime state views

The dashboard presents runtime state as several views over the same session history. This lets an operator choose between immediate output, a time-ordered record, a relationship view, or source-change evidence.

Session output

Session output is a bounded live buffer for each session. New lines are kept in memory and broadcast to subscribers. The dashboard reloads the stored lines during refresh and shows the selected session with filters for all output, errors, tool calls, or file changes. Time filters and search can narrow the view to one session or all sessions where the view supports it.

References: ecc2/…/output.rs• L7-17 ecc2/…/output.rs• L62-130 ecc2/…/dashboard.rs• L5244-5262

Timeline and context graph

The timeline makes session history easy to scan. It joins lifecycle changes, messages, tool calls, file changes, and decisions into a time-ordered view. The context graph shows named entities and their relations, which gives the operator a view of how sessions, files, functions, and decisions connect. Both views can target the selected session or the full session set and can apply event, entity, and time filters.

References: ecc2/…/dashboard.rs• L5264-5281 ecc2/…/dashboard.rs• L5518-5567

Worktree evidence

The output area can switch from agent output to a worktree diff, selected-file patch, Git status, or conflict protocol. These views connect runtime progress to the state that can be merged or needs repair. Timeline and context-graph modes add event and relationship views without changing the session itself. All of these are presentation views over worktree and session data rather than separate execution paths. During a refresh, the selected worktree status and its selected-file patch are derived from one status read so these views stay aligned without duplicate status work.

References: ecc2/…/dashboard.rs• L850-1003 ecc2/…/dashboard.rs• L1005-1074 ecc2/…/dashboard.rs• L1391-1440 ecc2/…/dashboard.rs• L4700-4805

Runtime metrics and risk

ECC2 turns usage and tool activity into operator signals. Session metrics track token use, tool calls, changed files, duration, and cost. The dashboard adds these values across sessions and compares them with configured token and cost budgets.

The metrics pane shows two budget meters and details for the selected session. Budget state moves from normal through advisory, warning, and critical levels to over budget. A missing or non-positive budget is shown as unconfigured rather than as a false percentage. References: ecc2/…/dashboard.rs• L1300-1367, ecc2/…/dashboard.rs• L6066-6091, ecc2/…/widgets.rs• L9-27, ecc2/…/widgets.rs• L114-156

Tool activity provides a second type of signal. Each tool record carries its name, input and output summaries, trigger context, duration, and risk score. Risk is a bounded assessment based on the tool and the operation's sensitivity, reach, and reversibility. Its result helps the operator decide whether an action was ordinary, needs review, needs confirmation, or should be blocked. References: ecc2/…/mod.rs• L7-33, ecc2/…/mod.rs• L35-117, ecc2/…/dashboard.rs• L1369-1417

Coordination and worktree status

The metrics and board views also explain pressure around a selected session. They show team counts, unread approvals, handoff backlog, daemon dispatch and recovery state, delegate progress, worktree health, merge readiness, and harness identity. This connects a local session signal to the wider coordination state that can delay or block it.

References: ecc2/…/dashboard.rs• L726-848 ecc2/…/dashboard.rs• L1322-1389 ecc2/…/dashboard.rs• L6133-6455

ECC2 can also export session and tool activity as OTLP-compatible JSON. The export uses one session span as the parent for that session's tool spans and links delegated work to its parent session. This gives external telemetry systems a stable view of session duration, state, usage, cost, tool timing, and risk. References: ecc2/…/main.rs• L408-414, ecc2/…/main.rs• L2579-2592, ecc2/…/main.rs• L8272-8392

Refresh and signal flow

The dashboard refresh cycle joins persisted state, live output, external metric files, and policy checks before it redraws the operator view. It preserves the selected session while it reloads related queues, worktree state, daemon activity, lineage, and logs. This diagram shows how runtime inputs become dashboard state and outward signals.

flowchart LR
    A[Session store] --> R[Dashboard refresh]
    B[Live output] --> R
    C[Cost and tool metric files] --> R
    R --> V[Session, output, metrics, board, timeline, log views]
    R --> P[Heartbeat, budget, and conflict checks]
    P --> N[Operator notes and notifications]
    R --> E[Completion summaries and observations]

The dashboard checks for new output events, updates pending worktree sessions, refreshes durations and metric files, and runs heartbeat, budget, and conflict checks. It then reloads sessions and derived counts before it updates output, worktree, messages, lineage, daemon activity, logs, and budget signals. Selected worktree Git status is read once during this synchronization pass and then supports both status and patch presentation. A failed refresh of one source is logged and the affected view falls back to an empty or prior-safe result instead of stopping the whole dashboard. References: ecc2/…/dashboard.rs• L4018-4087, ecc2/…/dashboard.rs• L4090-4151, ecc2/…/dashboard.rs• L4700-4805

Harness evaluation visibility

Harness evaluation gives operators a controlled way to compare a candidate agent setup with the active baseline before promotion. A harness candidate is an immutable, content-addressed configuration with trace and evidence references. Evaluation uses explicit unique seeds and paired candidate and baseline scores.

The promotion result reports whether the candidate passed the minimum sample, mean improvement, and win-rate policy. A passing comparison still requires a health check. If that check fails or does not match the recorded health evidence, ECC2 rolls the active configuration back to the baseline. Each evaluation and promotion decision remains in an append-only audit trail. References: ecc2/…/harness_eval.rs• L184-249, ecc2/…/harness_eval.rs• L460-577, ecc2/…/store.rs• L431-486, ecc2/…/store.rs• L5451-5548

Harness identity is also visible in the dashboard at session level. ECC2 shows the primary harness and any other harnesses detected in the session's working directory. The operator can therefore relate a session's behavior to the assistant surface that ran it. References: ecc2/…/mod.rs• L119-177, ecc2/…/store.rs• L2361-2385, ecc2/…/dashboard.rs• L6438-6444

The CLI exposes the evaluation lifecycle through harness-eval: record a candidate, activate the first baseline, run a bounded comparison, and inspect the audit entries. The command prints a candidate identifier or a structured promotion outcome. References: ecc2/…/main.rs• L110-118, ecc2/…/main.rs• L446-484, ecc2/…/main.rs• L1437-1504

Notification delivery

Notifications carry important state changes beyond the active terminal. ECC2 recognizes session start, completion, failure, budget alert, and approval request events. Desktop delivery is controlled by event flags and local quiet hours. Webhook delivery is controlled by event flags and a list of HTTP targets for Slack or Discord.

ChannelMain useDelivery guard
TUI popupRead a completion summary while the dashboard is openCompletion summary delivery selects popup or combined delivery
DesktopAlert an operator who is not watching the dashboardGlobal enablement, event flag, and quiet hours
WebhookSend state to an external team channelGlobal enablement, event flag, and at least one valid HTTP target

Desktop notifications use the host notification command where ECC2 has a supported mapping. Webhooks send provider-specific payloads and isolate target failures so one bad target does not prevent attempts to other targets. Invalid webhook URLs are removed during configuration sanitization. References: ecc2/…/notifications.rs• L9-16, ecc2/…/notifications.rs• L18-79, ecc2/…/notifications.rs• L101-165, ecc2/…/notifications.rs• L204-253, ecc2/…/notifications.rs• L257-342

Completion summaries

Completion summaries turn a terminal state into a compact operator report. They combine task identity with files changed, token use, cost, duration, detected tests, recent files, key decisions, and warnings. ECC2 stores the summary as a session observation and can deliver it as a desktop notice, a TUI popup, or both. Multiple summaries are queued so a burst of completed sessions does not hide earlier results.

References: ecc2/…/dashboard.rs• L60-74 ecc2/…/dashboard.rs• L404-503 ecc2/…/dashboard.rs• L4314-4469

State change notifications

The dashboard compares the current session state with the last state it saw. It sends start, completion, and failure signals only when a meaningful transition is detected. Approval notices use the newest unread approval message and a remembered message ID to avoid repeated alerts. Budget notices use rising budget states, so the same threshold does not alert on every refresh. A completion popup remains active until the operator dismisses it, and later summaries wait in a queue rather than replacing it.

References: ecc2/…/dashboard.rs• L4153-4208 ecc2/…/dashboard.rs• L4210-4312 ecc2/…/dashboard.rs• L4349-4405

Notification settings and budget thresholds are part of the ECC2 configuration. The default profile enables desktop completion, failure, budget, and approval alerts while leaving webhooks disabled until targets are configured. Completion summaries default to desktop delivery. References: ecc2/…/mod.rs• L218-253, ecc2/…/mod.rs• L284-320, ecc2/…/notifications.rs• L130-175

Change checklist

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

  • Keep the event names and event flags aligned across notifications.rs and the dashboard transition logic. A new event that lacks one side can silently lose a delivery path.
  • Keep budget threshold meaning aligned across Config, BudgetState, TokenMeter, and sync_budget_alerts. A change in ordering can alter both colors and alert suppression.
  • Keep completion summary fields aligned across the popup, desktop body, webhook body, and stored observation. A field added to only one surface creates different operator reports.
  • Keep session and tool span parent and link rules aligned with handoff relationships when changing OTLP export fields.
  • Keep harness candidate identity, evidence references, health assertions, and audit records in the same content-addressed contract when changing evaluation data.
  • Keep metric-file readers aligned with the writers that produce cost and tool-activity JSONL. Invalid or renamed fields can leave the dashboard with stale usage while the session still runs.
  • Keep selected Git status and selected-file patch views on the same refresh snapshot. Separate reads can show mismatched worktree evidence or add avoidable refresh cost.

Important failure modes

TriggerConsequenceGuard
Cost or tool metric data is missing or malformedSession usage and budget views can remain at older values or omit new activityRefresh is signature-based and skips malformed JSONL rows; inspect the source metric files when values look stale
Budget crosses a threshold while the dashboard is not refreshingNo new dashboard-side alert is emitted until a refresh observes the new stateKeep the dashboard or another operational monitor active when budget alerts are required
Desktop notifications are disabled, filtered by event, or inside quiet hoursThe operator receives no local alert for that eventCheck global and event flags plus the quiet-hour range
Webhook targets are invalid or all deliveries failExternal channels do not receive the state changeUse HTTP(S) targets and review warning logs for failed deliveries
A completion popup is left open during several completionsLater summaries wait in the popup queueDismiss the current popup to advance through queued summaries
Candidate comparison fails its sample, delta, or win-rate policyThe candidate is recorded as rejected and the active baseline stays unchangedReview the structured outcome and provide enough unique paired samples
Post-promotion health is false or inconsistent with evidenceECC2 rolls the candidate back and records the health result in the audit trailTreat promotion and health as one gate; inspect harness-eval audit

Key files

FileWhy to read it
ecc2/…/app.rsShows the dashboard runtime loop and the operator input boundary.
ecc2/…/dashboard.rsShows the operator model, views, refresh cycle, metrics, summaries, and notification triggers.
ecc2/…/widgets.rsShows how token and cost budget state becomes visible meter and alert state.
ecc2/…/output.rsShows the bounded live-output and broadcast model used by the TUI.
ecc2/…/mod.rsDefines tool activity records and risk assessments.
ecc2/…/main.rsConnects CLI commands to the dashboard, harness evaluation, and OTLP export.
ecc2/…/harness_eval.rsDefines candidate comparison, promotion policy, and health evidence.
ecc2/…/notifications.rsDefines notification events, delivery channels, filtering, and provider payloads.
ecc2/…/store.rsPersists metrics, tool logs, harness evaluations, and audit data used by the presentation layer.
ecc2/…/mod.rsDefines the operator controls for budgets, notification delivery, harness runners, and TUI presentation.