ECC2 sessions, communications, and worktrees
ECC2 manages concurrent engineering work as tracked agent sessions. Each session has a task, an execution policy, a state, and a working directory. ECC2 keeps this state durable, routes structured handoffs, monitors worker liveness, and can give each task an isolated Git worktree so concurrent work does not share changes by accident. See the ECC2 terminal control plane for the wider system view and ECC2 observability, notifications, and TUI for the operator view.
Session lifecycle
Session creation and execution
A session begins as a durable task record. ECC2 selects the agent and profile, chooses the working directory, and either starts the runner or waits for an isolated worktree slot. This lets the command that creates work return quickly while the daemon starts queued work when capacity is available.
flowchart LR
Request[Task request] --> Record[Pending session record]
Record --> Decision{Isolated worktree?}
Decision -->|No| Runner[Start agent runner]
Decision -->|Yes and slot free| Isolated[Create isolated worktree]
Decision -->|Yes and no slot| Queue[Pending worktree queue]
Queue --> Activate[Daemon activates queued session]
Isolated --> Runner
Activate --> Runner
Runner --> Live[Running session]
Live --> End[Completed, failed, or stopped]
The Start, Delegate, Assign, Template, Schedule, and Remote command groups create or route work. A delegated session stays linked to its lead through a task handoff. An assignment can reuse an idle delegate, use an active delegate when its inbox is clear, or create a new delegate when capacity permits.
References: ecc2/…/manager.rs• L26-155 ecc2/…/manager.rs• L1615-1760 ecc2/…/manager.rs• L2601-2715 ecc2/…/main.rs• L1509-1645 ecc2/…/main.rs• L2650-2889
Session state and liveness
Session state shows where work is in its life. ECC2 accepts only valid state changes, and a heartbeat records recent runner activity even when the agent produces no output.
| State group | States | Meaning |
|---|---|---|
| Not yet live | pending | The task exists but its runner or worktree is not ready. |
| Live | running, idle | The session can take part in active work or receive a handoff. |
| Suspect | stale | The heartbeat is too old, but automatic termination is not enabled. |
| Ended | completed, failed, stopped | The session is no longer an active worker. |
The daemon checks heartbeats and process presence. At startup it marks a running session with a dead process as failed. Later checks mark an old session stale or stop it when stale-session termination is enabled. A stopped or failed session can be resumed. A completed session cannot.
Automatic handoff dispatch is stricter than operator-led recovery. It sends work only to live native sessions. An operator can drain an inbox for a terminal session when explicit recovery is needed.
References: ecc2/…/mod.rs• L304-394 ecc2/…/store.rs• L1355-1423 ecc2/…/store.rs• L2664-2673 ecc2/…/manager.rs• L801-845 ecc2/…/manager.rs• L924-1044 ecc2/…/daemon.rs• L18-98
Session output
Session output is a bounded record of the runner's standard output and error streams. ECC2 keeps recent lines in durable state for later inspection and publishes each new line to live subscribers so a dashboard can update without a full reload.
The output path has two views with different roles:
- The live output store keeps a recent ring buffer and broadcasts new lines.
- The session store keeps the same recent window for later snapshots and cursor-based reads.
This supports both a newly opened dashboard and a dashboard that stays open while several sessions write at once. The retained window is limited to the most recent 1,000 lines per session. A persistence failure interrupts normal capture instead of showing output that cannot be recovered from session state.
References: ecc2/…/output.rs• L7-115 ecc2/…/runtime.rs• L137-245 ecc2/…/store.rs• L287-293 ecc2/…/store.rs• L4111-4159 ecc2/…/dashboard.rs• L4503-4541
Agent selection and execution profiles
Agent selection separates the task from the program that runs it. ECC2 supports built-in runners for Claude, Codex, OpenCode, and Gemini. A configured harness runner can add another agent by describing how to start it and how to pass its task and working directory.
An agent profile is a named execution policy. Profiles can inherit from another profile and add model choices, tool rules, extra directories, budget limits, or prompt guidance. A child session inherits its source profile unless the request names another one. Automatic selection uses project markers and configured runners to choose a launchable agent.
References: ecc2/…/mod.rs• L16-110 ecc2/…/mod.rs• L217-293 ecc2/…/mod.rs• L63-111 ecc2/…/mod.rs• L382-490 ecc2/…/manager.rs• L2639-2682 ecc2/…/manager.rs• L3260-3347
Coordination messages
Delegation and backlog routing
ECC2 models a lead session and its delegate sessions as a small work team. A task handoff is a durable message that carries task context and priority. The lead can route work directly, drain unread handoffs later, or let the daemon dispatch and rebalance the backlog.
When ECC2 assigns work, it follows this order:
- Reuse an idle delegate with no unread handoff backlog.
- Start a new delegate when the team has room.
- Reuse a suitable active delegate when it has no queued work.
- Keep the handoff unread when the team is saturated.
The coordination status reports absorbable and saturated teams. Rebalancing moves lead-created handoffs away from backed-up delegates when another delegate is clear or the team has room. The daemon records deferred work and uses recent dispatch activity to avoid repeating a saturated pass too quickly.
References: ecc2/…/manager.rs• L999-1122 ecc2/…/manager.rs• L1115-1222 ecc2/…/manager.rs• L1615-1760 ecc2/…/daemon.rs• L145-245 ecc2/…/store.rs• L124-206 ecc2/…/store.rs• L3923-4039
Message types and inboxes
The communication layer gives sessions a small structured message contract. Messages record sender, recipient, type, read status, time, and provenance. The session store provides inbox views and marks messages read when an operator reads an inbox or when a handoff is successfully routed.
| Message type | Main use |
|---|---|
TaskHandoff | Send work to a delegate with priority and task context. |
Query | Ask another session for information or approval. |
Response | Answer a query. |
Completed | Report finished work and changed files. |
Conflict | Tell another session that shared work needs attention. |
Native assignment notices remain visible for inbox and capacity reporting, but automatic dispatch and rebalancing exclude them. This prevents a task already assigned by ECC2 from being treated as new intake work. Each message also creates a context-graph relation so later routing and recall can use session history.
References: ecc2/…/mod.rs• L7-170 ecc2/…/store.rs• L2702-2727 ecc2/…/store.rs• L2891-3024 ecc2/…/store.rs• L3027-3060 ecc2/…/main.rs• L2602-2648
Scheduled and remote task intake
Scheduled tasks and remote requests enter the same session system as local tasks. A schedule stores recurring task rules and a worktree policy. A remote request targets an existing session when one is named or creates a new top-level session when no target exists.
This shared path keeps agent selection, profile checks, project grouping, worktree limits, and backlog rules consistent across local and external sources. Remote requests can be standard tasks or computer-use tasks. Both end as a session assignment, a deferred request, or a recorded failure.
References: ecc2/…/manager.rs• L116-155 ecc2/…/manager.rs• L206-254 ecc2/…/manager.rs• L257-425 ecc2/…/manager.rs• L477-601 ecc2/…/main.rs• L2650-2890
Workspace isolation
Worktree allocation
A session worktree is an isolated Git checkout for one task. ECC2 creates it from the current repository state, gives it a branch derived from the session ID, records its path and base branch, and runs the agent there.
The worktree limit is separate from the session limit. When all worktree slots are in use, ECC2 keeps the session pending in a first-requested queue. The daemon activates queued sessions as slots become free. Sessions that do not request a worktree run in the repository directory instead, so concurrent work without isolation remains an explicit choice.
References: ecc2/…/mod.rs• L112-191 ecc2/…/manager.rs• L2493-2599 ecc2/…/manager.rs• L2670-2715 ecc2/…/store.rs• L1447-1564
Dependency cache sharing
Worktrees stay separate for source changes, but ECC2 can share known dependency directories when their dependency inputs match the base checkout. This reduces repeated setup cost without sharing a cache after its package definition has changed.
The supported cache layouts cover common Node, Cargo, and Python projects. ECC2 compares the relevant package-definition and lock files before it links a cache. If the fingerprint differs, the worktree keeps an independent directory. A cache setup warning does not discard the session.
References: ecc2/…/mod.rs• L1264-1404 ecc2/…/mod.rs• L1406-1426
Merge readiness and cleanup
Worktree completion is separate from session completion. A finished session may still have commits, uncommitted changes, or a branch that cannot merge cleanly. ECC2 checks these conditions before it merges the branch into its base branch.
The merge queue orders inactive worktrees and shows why blocked entries cannot proceed. It can rebase a clean branch when the only blocker is an earlier merge, then retry the queue. Active sessions, dirty worktrees, conflicted branches, and a dirty base checkout remain blocked. Cleanup removes the worktree and branch after merge or stop. Retention can keep inactive worktrees for later review.
References: ecc2/…/mod.rs• L746-935 ecc2/…/manager.rs• L1839-2012 ecc2/…/manager.rs• L2177-2329 ecc2/…/manager.rs• L2101-2141 ecc2/…/daemon.rs• L368-472
Concurrent file conflicts
Separate worktrees reduce direct interference, but two sessions can still produce changes that cannot merge. ECC2 tracks file activity and can create a conflict incident when active sessions change the same path. The configured conflict strategy decides which session stays active and which session pauses.
The available strategies are escalation, last-write-wins, and manual merge. ECC2 can send a conflict message to the paused session and its lead. This makes a merge problem part of session coordination instead of leaving it as an unexplained Git failure.
References: ecc2/…/manager.rs• L1322-1478 ecc2/…/mod.rs• L37-51 ecc2/…/store.rs• L89-122 ecc2/…/store.rs• L416-431
Operating configuration
Configuration layers and capacity
ECC2 loads defaults first, then applies global and nearest-project TOML settings. The primary global file is the XDG-style ecc2/config.toml; the older ~/…/ecc2.toml path remains a global fallback. A project can use ecc2.toml or .claude/ecc2.toml near the current directory.
The settings that shape concurrent work are:
| Setting area | System effect |
|---|---|
| Session and worktree limits | Bound live sessions and isolated checkouts. |
| Worktree root, branch prefix, and retention | Define where isolation lives and how long inactive workspaces remain. |
| Heartbeat interval, timeout, and stale termination | Define when ECC2 treats a worker as unhealthy. |
| Default agent, profile, runners, and templates | Define how new work is launched and split. |
| Automatic handoff dispatch and merge | Decide which coordination and cleanup steps the daemon performs. |
| Conflict policy | Decide how overlapping file activity pauses or escalates work. |
The built-in defaults allow eight sessions and six worktrees, create worktrees by default, keep automatic merge off, and use a 30-second heartbeat with a one-hour timeout. Change these values with care because they alter queue pressure and cleanup behavior for every launch source.
References: ecc2/…/mod.rs• L218-254 ecc2/…/mod.rs• L284-322 ecc2/…/mod.rs• L493-607 ecc2/…/main.rs• L1425-1435
Harness runners and profiles
Harness runner settings connect an agent name to a launch program and describe how ECC2 passes the task, working directory, model, permissions, and environment. This is the extension point for agents that are not one of the built-in direct runners.
Profiles provide a reusable policy for those launches. A profile can set a model, tool allow and deny rules, permission mode, extra directories, budget limits, and system guidance. ECC2 resolves inheritance before it starts a session and rejects an inheritance cycle or an unknown profile.
References: ecc2/…/mod.rs• L63-111 ecc2/…/mod.rs• L466-490 ecc2/…/manager.rs• L3071-3230
Templates and grouping
An orchestration template describes a named set of session steps. Each step can choose its task, agent, profile, worktree policy, project, and task group. ECC2 resolves template variables, checks that enough session slots exist, creates the steps, and links later steps to the anchor session with task handoffs.
Project and task-group labels give concurrent work a shared view. A delegated task inherits these labels from its lead unless the request overrides them. They help the dashboard, backlog reports, and merge queue relate sessions that belong to the same engineering effort.
References: ecc2/…/mod.rs• L113-135 ecc2/…/mod.rs• L392-464 ecc2/…/manager.rs• L619-750 ecc2/…/mod.rs• L696-721
Change checklist
When these files or sections are changed, remember to consider these:
- When a
SessionStateorAssignmentActionchanges, review active-session filters, heartbeat handling, backlog health, merge eligibility, and the CLI status output together. - When a message type or field changes, update serialization, message previews, task-handoff parsing, provenance checks, inbox routing, and context-graph relation mapping as one contract.
- When native assignment notices change, keep their visibility for capacity reporting separate from their exclusion from automatic dispatch and rebalancing.
- When session output fields, retention, or cursors change, keep runner capture, durable output reads, live output subscribers, and dashboard snapshot or delta refreshes aligned.
- When
WorktreeInfoor worktree limits change, keep session creation, the pending worktree queue, attachment and clearing, merge processing, and pruning aligned. - When runner or profile fields change, verify the config resolver and the command builder still pass the same policy to built-in and configured harnesses.
- When config paths or precedence change, check that scheduled tasks, remote dispatch, templates, and the daemon all use the same resolved settings.
- When conflict handling changes, keep incident records, pause actions, conflict messages, and lead notification behavior consistent.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| All worktree slots are used | A requested isolated session stays pending until activation finds a slot. | Set a suitable max_parallel_worktrees value and monitor the pending queue. |
| A lead session has a relative working directory | Native assignment is rejected instead of being routed against an unrelated operator directory. | Register sessions with an absolute project working directory. |
| An assignment notice is treated as new intake work | The same task can be dispatched a second time or moved away from its assigned worker. | Preserve native assignment provenance and use the dispatch-specific inbox filter. |
| A merge is requested for an active session | ECC2 rejects the merge to avoid changing a workspace that can still write. | Stop or complete the session before merging. |
| A worktree is dirty, conflicted, or based on a dirty base checkout | The merge queue blocks the branch and leaves it for review. | Inspect status and conflicts, then commit, discard, rebase, or resolve the branch. |
| A runner stops heartbeating or its process is gone | The daemon marks the session stale or failed. It may terminate the process when configured to do so. | Use heartbeat and timeout settings that match the runner, then resume only a recoverable session. |
| A delegate team has no free capacity | The handoff remains unread and the assignment is reported as deferred. | Drain or rebalance the backlog, or raise session capacity. |
| Output is produced faster than the retained session window | Older lines are removed, so a later session view cannot recover them from the state store. | Read or export important output while it is live and size retention for the workload. |
| A profile, template variable, or configured runner is invalid | Session creation or dispatch fails before useful work starts. | Resolve named profiles and templates before launch and keep runner programs and required variables valid. |
| A completed session is resumed or an active session is deleted | ECC2 rejects the operation because the lifecycle rule is invalid. | Use resume for failed or stopped sessions and delete only ended sessions. |
Key files
| File | Why to read it |
|---|---|
| ecc2/…/main.rs | Shows the public command surface for starting, delegating, routing, inspecting, stopping, and resuming sessions. |
| ecc2/…/mod.rs | Defines the session record, lifecycle states, harness identity, worktree link, and message data model. |
| ecc2/…/manager.rs | Connects task requests to session creation, assignment, heartbeats, conflict response, merge flow, and cleanup. |
| ecc2/…/store.rs | Defines the durable state boundary for sessions, output, messages, worktree queues, schedules, remote requests, and conflict incidents. |
| ecc2/…/output.rs | Shows the bounded live output buffer and event stream used while session output is being produced. |
| ecc2/…/runtime.rs | Shows how a runner becomes live, updates heartbeats, captures output, and reaches a final state. |
| ecc2/…/daemon.rs | Shows the recurring checks that recover dead sessions, dispatch and rebalance backlog, activate worktrees, merge ready branches, and prune old workspaces. |
| ecc2/…/mod.rs | Defines the structured message contract, provenance boundary, and task-handoff priority model. |
| ecc2/…/mod.rs | Defines isolated checkout creation, fingerprinted cache sharing, health checks, merge readiness, rebase, merge, and removal. |
| ecc2/…/mod.rs | Defines layered operating settings, agent profiles, harness runners, templates, capacity, and conflict policy. |