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-terminal-control-plane

ECC2 terminal control plane

ECC2 is a Rust-based alpha control plane for running and supervising AI coding sessions. It gives an engineer one place to start work, route work between sessions, isolate changes, inspect progress, and act on risks through a terminal dashboard or command line. It is usable for local operator work, but it is not the finished ECC 2.0 product.

Control-plane scope

ECC2 coordinates work around a durable session record. A session ties a task to an agent, a project and task group, a working directory, process state, output, metrics, messages, and an optional Git worktree. The control plane turns those records into actions for agents and clear status for the operator.

Control-plane responsibilities

The control plane keeps several concerns in step:

  • Session operation: Start, stop, resume, inspect, and remove agent sessions.
  • Work routing: Delegate tasks, reuse available delegates, queue work at capacity, and rebalance backed-up teams.
  • Workspace safety: Give sessions separate worktrees when policy allows. Check merge readiness before changes return to the base branch.
  • Policy: Apply agent profiles, budgets, concurrency limits, heartbeat rules, conflict rules, and notification preferences.
  • Evidence: Keep output, tool activity, file activity, decisions, messages, and context graph records available for review.
  • Operator access: Present live state in the TUI and provide scriptable CLI commands with human or JSON output.

References: ecc2/…/main.rs• L110-432 ecc2/…/main.rs• L1562-1729 ecc2/…/mod.rs• L304-412 ecc2/…/store.rs• L208-429

Control-plane lifecycle

ECC2 starts from shared configuration and a local state store. A command then creates or finds work, while the runner, daemon, dashboard, and CLI use the same stored view of session state.

Application startup

The application loads logging, configuration, and the SQLite state store before it handles a command. With no command, or with dashboard, it opens the terminal dashboard. Other commands use the same configuration and store for direct control, inspection, background work, remote intake, or export.

The database is the cross-process source of truth because session runners run as separate processes. The dashboard loads a bounded recent-output snapshot at startup or after recovery, then applies only rows newer than its monotonic output cursor during normal refreshes. This keeps the interactive view current without re-reading all stored output on every tick.

References: ecc2/README.md• L7-21 ecc2/…/main.rs• L1478-1561 ecc2/…/store.rs• L208-215 ecc2/…/store.rs• L4028-4072 ecc2/…/dashboard.rs• L529-655 ecc2/…/dashboard.rs• L4503-4541

Session lifecycle

When an engineer starts work, ECC2 resolves the requested agent and policy, records a pending session, and either gives it a worktree or waits for a worktree slot. The agent process then moves through live states until it completes, fails, stops, or becomes stale.

The session state is the main contract between the runner, daemon, CLI, and dashboard. A running process sends heartbeats even when it produces no output. This lets the control plane separate quiet work from lost work.

The following flow shows the main path from an operator request to a visible result.

flowchart LR
    Request[CLI or TUI request] --> Policy[Resolve config and agent policy]
    Policy --> Record[Create pending session record]
    Record --> Workspace{Worktree available?}
    Workspace -->|yes| Run[Run agent in session workspace]
    Workspace -->|no| Queue[Wait in worktree queue]
    Queue --> Daemon[Daemon activates queued session]
    Daemon --> Run
    Run --> Capture[Capture output, heartbeat, and metrics]
    Capture --> Result[Completed, failed, stopped, or stale]
    Result --> Views[Dashboard, CLI status, notifications, and logs]

References: ecc2/…/main.rs• L1562-1611 ecc2/…/main.rs• L2594-2601 ecc2/…/manager.rs• L2452-2557 ecc2/…/manager.rs• L2614-2673 ecc2/…/mod.rs• L321-394

Daemon coordination

The daemon is the background control loop for work that should continue without an open dashboard. At startup it marks running sessions with dead process IDs as failed. Each cycle checks heartbeats, dispatches due schedules and remote requests, coordinates handoff backlog, merges eligible worktrees, prunes inactive worktrees, and activates sessions waiting for capacity.

Automatic handoff dispatch only uses exact session records that are still running or idle. It does not consume inboxes for terminal sessions. An explicit CLI or TUI recovery action can still route an operator-authorized handoff to a pending, stopped, or completed lead.

Backlog coordination records routed and deferred work. Repeated saturation can make the daemon rebalance before another dispatch attempt, pause retry during a cool-off period, and mark the need for operator attention when pressure does not clear. The daemon does not replace the operator view. It records activity so the TUI and coordination status commands can show whether work was routed, deferred, rebalanced, merged, or held for attention.

References: ecc2/…/daemon.rs• L18-56 ecc2/…/daemon.rs• L58-93 ecc2/…/daemon.rs• L100-124 ecc2/…/daemon.rs• L145-245 ecc2/…/daemon.rs• L260-428 ecc2/…/manager.rs• L924-1044 ecc2/…/store.rs• L124-205

Session coordination

Sessions can form lead-and-delegate teams. A lead sends task handoffs to child sessions. ECC2 can reuse an idle delegate, start another delegate within capacity, route work to a suitable active delegate, or leave the handoff queued when the team is saturated.

The detailed session, message, and worktree model is described in ECC2 sessions, communication, and worktrees. This page treats that model as one control-plane capability: it lets the operator shape parallel work without losing task ownership or workspace boundaries.

Work dispatch

Dispatch can start a single session, delegate from an existing session, launch a named multi-step template, or accept scheduled and remote requests. Project and task-group labels keep related sessions visible as one unit. Task handoffs can carry low, normal, high, or critical priority so operators and intake clients preserve urgency as work moves through the control plane.

Dispatch reports whether work was spawned, reused, rerouted, or deferred. That distinction matters because a deferred task remains an operational backlog rather than a completed assignment. Coordination commands can run one pass, maintain work only when health needs attention, or repeat passes until the backlog is healthy or capacity is reached.

References: ecc2/…/main.rs• L166-280 ecc2/…/main.rs• L1784-1963 ecc2/…/manager.rs• L459-601 ecc2/…/manager.rs• L924-1044 ecc2/…/mod.rs• L7-15

Communication channels

Inter-session communication uses structured messages. A message can carry a task handoff, a question, a response, a completion summary, or a conflict notice. Task handoffs include priority and context. Unread handoffs form a dispatch backlog. Questions and conflicts form an approval queue that needs operator or lead attention.

ECC2-generated assignment notices have native provenance and are kept with their intended delegate. Ordinary user handoffs remain eligible for inbox routing and rebalance. The CLI and dashboard can inspect messages, and sending a message records its relation to the shared context graph so communication can remain part of later session recall.

References: ecc2/…/main.rs• L486-552 ecc2/…/main.rs• L2655-2682 ecc2/…/mod.rs• L29-86 ecc2/…/manager.rs• L1108-1120 ecc2/…/store.rs• L2579-2729 ecc2/…/dashboard.rs• L704-826

Workspace boundaries

Worktrees give sessions isolated Git working directories and branches. This keeps parallel agents from writing into the same checkout by default and gives the control plane a clear unit for diff review, conflict checks, merge, and cleanup.

When the base checkout already has matching dependency inputs, ECC2 can make supported dependency caches available in a session worktree. It compares the dependency inputs before sharing a cache. A cache with different inputs stays independent, so workspace isolation remains the safe default.

Worktree lifecycle

ECC2 can create a worktree when a session starts. If the configured worktree limit is full, it records the session as pending and lets the daemon or dashboard activate it later. After an inactive session finishes, the operator or daemon can inspect its changes, rebase when needed, merge ready work, and remove the worktree.

Merge is guarded by session state, clean working changes, base-branch availability, and branch conflict checks. A dirty or conflicted worktree stays visible as blocked work instead of being merged silently. The operator can also review file status and selected hunks, stage or discard changes, create commits, and prepare a draft pull request from the worktree.

References: ecc2/…/main.rs• L297-356 ecc2/…/main.rs• L1987-2120 ecc2/…/mod.rs• L95-175 ecc2/…/mod.rs• L253-489 ecc2/…/mod.rs• L722-910 ecc2/…/mod.rs• L1209-1365 ecc2/…/manager.rs• L2452-2557 ecc2/…/manager.rs• L2690-2724

Conflict boundaries

ECC2 watches file activity across active sessions. When two sessions overlap on a changed path, the configured conflict strategy decides whether to escalate, keep the last writer active, or pause work for a merge review. The control plane records an incident and can notify the lead.

This protection is separate from final Git merge readiness. File activity can signal a live coordination problem before the branches reach the merge queue.

References: ecc2/…/manager.rs• L1255-1411 ecc2/…/mod.rs• L37-51 ecc2/…/store.rs• L64-97

Configuration model

Configuration defines the operating policy for the control plane. ECC2 starts from defaults, applies global files, and then applies the nearest project override. The TUI can persist selected operator changes such as pane layout, theme, worktree creation, daemon dispatch policy, and automatic merge policy.

Agent and orchestration policy

An agent profile groups execution choices such as the model, tool allow-list, permission mode, extra directories, and per-session budgets. Profiles can inherit from other profiles. Orchestration templates use these profiles and variables to describe a repeatable set of session tasks.

The same policy is used by direct starts, delegated work, scheduled tasks, remote intake, and template launches. A policy change therefore affects both how a session starts and how its later status should be read.

References: ecc2/…/mod.rs• L63-135 ecc2/…/mod.rs• L218-254 ecc2/…/mod.rs• L382-464 ecc2/…/main.rs• L1562-1709 ecc2/…/main.rs• L2684-2858 ecc2/…/manager.rs• L2572-2615

Resource policy

Resource policy limits parallel sessions and worktrees. It also sets session timeouts, heartbeat intervals, token and cost budgets, budget alert levels, worktree retention, and automatic actions. The control plane uses these limits to pause new work, mark stale sessions, or defer cleanup instead of allowing pressure to remain hidden.

References: ecc2/…/mod.rs• L220-253 ecc2/…/manager.rs• L787-831 ecc2/…/manager.rs• L1161-1244 ecc2/…/manager.rs• L2034-2073

Observability surfaces

ECC2 makes session activity inspectable at several levels. The operator can see live process output, a cross-event timeline, tool records with risk scores, file changes, decisions, context graph data, budgets, and OTLP-compatible export data.

The detailed observability and notification interfaces are described in ECC2 observability, notifications, and TUI. This page treats them as the evidence layer that supports control decisions and post-run review.

Activity evidence

Tool calls carry input and output summaries, duration, and a risk score. The score combines the tool type with signs of sensitive files, broad scope, shared state, and hard-to-reverse actions. The resulting action is an allow, review, confirmation, or block suggestion.

Session output is available as bounded stored history and live events. The dashboard keeps the most recent output for each session and applies new persisted rows in insertion order. File activity and decision records add the reason and impact behind changes. The context graph links entities, relations, and observations so later work can recall useful prior context.

References: ecc2/…/main.rs• L2121-2159 ecc2/…/main.rs• L2288-2577 ecc2/…/main.rs• L2579-2593 ecc2/…/mod.rs• L7-117 ecc2/…/output.rs• L7-123 ecc2/…/store.rs• L3960-4072 ecc2/…/mod.rs• L541-683

Context graph intake

The context graph can receive structured memory from configured JSONL, Markdown, and dotenv files or directories. ECC2 maps records into entities and observations, remembers source checkpoints, skips unchanged sources, and reports what it read or added. Dotenv intake redacts secret-like values while allowing configured safe values. This gives external memory and imported workspace knowledge the same recall surface as session evidence.

References: ecc2/…/main.rs• L1038-1075 ecc2/…/main.rs• L2933-3071 ecc2/…/main.rs• L3073-3519 ecc2/…/mod.rs• L500-607

Notification delivery

Notifications turn important control-plane events into operator attention outside the active view. Desktop delivery supports event flags and quiet hours. Webhook delivery supports configured Slack or Discord targets. Completion summaries can use desktop delivery, a TUI popup, or both.

Notification settings are a delivery policy, not a second source of session state. The session record and activity evidence remain authoritative when a platform lacks a notification command or a network target is unavailable.

References: ecc2/…/notifications.rs• L9-79 ecc2/…/notifications.rs• L101-193 ecc2/…/notifications.rs• L229-341 ecc2/…/dashboard.rs• L379-477

Terminal operation

The TUI is the primary interactive control surface. It keeps the sessions pane as the anchor and changes the detail panes to match the selected session. The operator can move between sessions, follow or search output, inspect metrics and logs, review worktree changes, and act without leaving the terminal.

Dashboard views

The dashboard combines the following views:

  • Sessions: State, agent, project, task group, branch, approval counts, handoff backlog, and usage.
  • Output: Live or stored session output with content and time filters. The view keeps a bounded recent window.
  • Timeline: Lifecycle, message, tool, file-change, and decision events.
  • Context graph: Related entities and observations for one session or all sessions.
  • Metrics: Token and cost budgets plus selected-session detail.
  • Board: Delegate status, backlog, activity, and conflict signals.
  • Log: Recent tool calls and risk scores.
  • Git views: Worktree diffs, file status, patches, hunks, and conflict protocol.

References: ecc2/…/output.rs• L7-123 ecc2/…/dashboard.rs• L82-176 ecc2/…/dashboard.rs• L726-848 ecc2/…/dashboard.rs• L850-952 ecc2/…/dashboard.rs• L4090-4135 ecc2/…/dashboard.rs• L4503-4541

Operator actions

The dashboard turns selection into control. An operator can create or assign work, drain or rebalance handoffs, jump to approval targets, stop or resume sessions, merge or clean worktrees, stage or reset selected Git changes, and change policy. It also supports staged Git actions and draft pull request creation from a selected worktree.

The event loop gives input modes priority over normal shortcuts. This prevents a search, commit, pull request, spawn prompt, or completion popup from being mistaken for a control action. Policy changes such as automatic dispatch, automatic merge, worktree creation, and per-lead dispatch limits are saved for later daemon cycles.

References: ecc2/…/app.rs• L15-150 ecc2/…/dashboard.rs• L2159-2259 ecc2/…/dashboard.rs• L2367-2409 ecc2/…/dashboard.rs• L2651-2769 ecc2/…/dashboard.rs• L3927-4016

Command and intake interfaces

The CLI provides the scriptable face of the same control plane. It supports human summaries for direct operation and JSON output for automation. A command can inspect state or request an action without requiring the TUI to run.

Scheduled and remote intake

Scheduled tasks store a cron rule and session policy. When a task becomes due, ECC2 creates the session and advances the next run time. Remote requests use a durable queue with priority and status. They can target a lead session or create a top-level session. They support standard tasks and computer-use goals.

The remote server is a small token-authenticated intake boundary with health, standard dispatch, and computer-use endpoints. Intake only queues work. The normal dispatch path still applies agent, worktree, grouping, capacity, and failure rules.

References: ecc2/…/main.rs• L398-415 ecc2/…/main.rs• L555-689 ecc2/…/main.rs• L2684-2934 ecc2/…/main.rs• L4021-4199 ecc2/…/manager.rs• L271-438 ecc2/…/manager.rs• L467-601

Scriptable status

Status commands expose sessions, teams, coordination health, worktree readiness, merge queues, decisions, messages, and exported activity. JSON output lets external tools check backlog pressure or worktree attention without parsing the TUI. Coordination commands can also return a non-zero exit code when health, saturation, or required attention crosses the configured check boundary.

References: ecc2/…/main.rs• L229-415 ecc2/…/main.rs• L1784-1930 ecc2/…/main.rs• L1959-2159 ecc2/…/main.rs• L2579-2649

Migration and evaluation interfaces

The CLI also provides controlled entry points for moving older workspace data into ECC2 and for evaluating harness configuration changes. Migration commands audit a source workspace, create a plan, scaffold ECC2 artifacts, and import supported schedules, memory, environment context, skills, tools, plugins, and remote tasks. Harness evaluation records candidates and evidence, compares a candidate with a baseline, and keeps an audit of promotion decisions.

Harness evaluation is bounded and operator-driven. It compares recorded measurements with explicit seeds and promotion rules. It does not rewrite prompts or configuration, call network or process evaluators, alter running sessions, or deploy the active registry pointer into a harness runtime.

These interfaces extend the control plane without changing the session model. Imported or evaluated material still enters through durable ECC2 records and policy checks rather than bypassing normal operation.

References: ecc2/README.md• L79-92 ecc2/…/main.rs• L110-118 ecc2/…/main.rs• L446-484 ecc2/…/main.rs• L661-783 ecc2/…/main.rs• L1478-1505 ecc2/…/main.rs• L2160-2287

Change checklist

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

  • Changes to session fields or state names must stay aligned across session records, state transitions, dashboard summaries, CLI status, and daemon recovery.
  • Changes to message kinds or handoff provenance must update serialization, priority handling, message previews, unread approval rules, native-assignment protection, backlog routing, and timeline display.
  • Changes to automatic or manual handoff eligibility must preserve the split between exact live native recipients and explicit operator recovery.
  • Changes to worktree policy must cover immediate creation, pending-slot activation, merge-queue checks, auto-merge, pruning, Git status actions, and dependency-cache fingerprint checks.
  • Changes to configuration keys must preserve layered loading and TUI persistence. Check the CLI, remote intake, and daemon consumers of the same policy.
  • Changes to daemon coordination state must keep dispatch, recovery dispatch, rebalance, saturation cool-off, auto-merge, auto-prune, status output, and dashboard summaries aligned.
  • Changes to activity events must keep stored records, live TUI views, context graph sync, risk display, and OTLP export consistent.
  • Changes to persisted output must keep the per-session retention limit, startup snapshot, monotonic cursor, bounded delta batches, and live output view aligned.
  • Changes to notification events must update event flags and each enabled delivery path without making delivery failure change session truth.
  • Changes to CLI output, JSON payloads, or --check exit rules must keep human summaries, machine output, and automation health checks aligned.
  • Changes to remote intake must keep CLI requests, authenticated HTTP payloads, request status, priority, computer-use defaults, and normal dispatch policy aligned.
  • Changes to memory intake must preserve source provenance, connector checkpoint behavior, secret redaction, and the distinction between imported data and live session state.
  • Changes to harness evaluation must keep candidate identity, measurement gates, health evidence, atomic pointer updates, rollback evidence, and immutable audit records aligned.

Important failure modes

TriggerConsequenceGuard
State store cannot open or its writer channel closesSession state, output, and heartbeat updates failOpen the configured store before starting the control surface. Treat writer acknowledgements as required.
Agent process exits with a non-success status, or a running record has a dead process ID at daemon startupSession becomes failed and its process ID is clearedInspect stored output and tool activity before retrying or resuming.
Heartbeat exceeds the configured timeoutSession becomes stale, or becomes failed when stale-session termination is enabledUse the daemon heartbeat check and inspect the last heartbeat before taking recovery action.
Worktree is active, dirty, or conflictedMerge is blocked and the worktree remains for reviewCheck worktree status, merge readiness, and the merge queue before merging.
Worktree dependency inputs do not match the base checkoutThe dependency cache stays private to the worktreeTreat independent dependency inputs as a workspace boundary. Do not force a shared cache.
Delegate capacity is full with no usable idle delegateHandoff stays deferred in the lead backlog, and repeated pressure can enter cool-offRebalance the team or increase capacity before retrying dispatch. Check coordination status when saturation persists.
Automatic backlog coordination finds a missing, terminal, or non-live leadThe handoff remains unread instead of being replayed to an unauthorized targetUse explicit CLI or TUI recovery when the operator has approved routing work from that lead.
A native assignment notice is treated as ordinary intake workWork can be duplicated or moved away from its intended delegatePreserve native assignment provenance and exclude native notices from rebalance.
Desktop command or webhook target is unavailableNotification is not delivered, while session state remains unchangedUse the dashboard, stored activity, or CLI status as the source of truth.
Dashboard output backlog exceeds one refresh batchThe output pane remains behind for a refresh cycle, but later rows remain available in SQLiteLet the dashboard advance its cursor over later refreshes instead of treating a partial batch as data loss.
A memory source is missing, invalid, unchanged, or only partly readImported graph context is incomplete or the source is skipped or retried laterReview connector status and sync counts. Treat skipped records and source checkpoints as part of the import result.
A dotenv connector selects secret-like keysSecret values are not added to graph detailsUse connector include and exclude rules. Treat redaction as part of the imported record contract.
Remote request lacks valid bearer authentication or required task dataThe intake endpoint rejects the request and does not queue workUse the configured bearer token and validate the request before relying on its returned status.
A migration item needs local authentication or manual translationThe source item is reported but is not imported as a working ECC2 featureUse the audit and plan reports to complete the item through its stated target surface.
Harness evaluation lacks required paired measurements or fails its health assertionPromotion is rejected, or the active pointer rolls back with audit evidenceProvide the requested seeds and evidence, then inspect the evaluation and audit records before retrying.

Key files

FileWhy to read it
ecc2/…/main.rsDefines the single CLI and TUI entry point, startup path, coordination commands, intake boundaries, connector handling, and evaluation surfaces.
ecc2/…/mod.rsDefines the shared session concepts, states, metrics, messages, and context records.
ecc2/…/manager.rsShows how session creation, dispatch, exact automatic-recipient checks, explicit recovery, capacity, budgets, conflicts, and worktree actions are coordinated.
ecc2/…/runtime.rsShows the boundary between an agent process and the session state and output stream.
ecc2/…/daemon.rsShows the background cycle for recovery, dispatch, saturation handling, merge, pruning, and queued worktree activation.
ecc2/…/output.rsDefines the bounded in-process output history and live output events used by session views.
ecc2/…/store.rsShows the durable state model shared by the CLI, daemon, runner, and TUI, including exact session-state reads and daemon activity.
ecc2/…/mod.rsDefines the operating policy and its global and project-level loading model.
ecc2/…/mod.rsDefines structured communication, handoff priority, and native assignment notices between sessions.
ecc2/…/mod.rsDefines workspace isolation, dependency cache sharing, Git health, status and patch review, merge, rebase, and cleanup boundaries.
ecc2/…/mod.rsDefines tool evidence, risk assessment, and paged tool-log access.
ecc2/…/notifications.rsDefines desktop, webhook, quiet-hour, and completion-summary delivery policy.
ecc2/…/app.rsDefines the terminal event loop and input-mode precedence.
ecc2/…/dashboard.rsDefines the operator dashboard views, refresh model, controls, coordination indicators, Git actions, output cursor, and evidence display.
ecc2/README.mdStates the alpha scope, cross-process SQLite model, operator commands, and limits of harness evaluation.