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 / workflow-execution-and-worktrees

Workflow execution and worktrees

Workflow execution turns a worker plan into parallel, isolated engineering sessions. It gives each worker a branch, worktree, task record, handoff record, and status record, then runs the worker in a tmux pane so an operator can inspect progress and collect results.

Orchestration model

Worker sessions

The orchestration model treats each worker as a bounded unit of work inside one named session. A plan describes the session and its workers. The launcher turns that plan into Git worktrees, coordination files, and tmux panes.

Workers communicate through artifacts rather than through the parent process. The task file supplies the objective and any local overlays. The launcher owns the status and handoff files. This keeps worker activity inside its assigned worktree while leaving a durable record for inspection.

References: scripts/…/tmux-worktree-orchestrator.js• L175-250 scripts/…/tmux-worktree-orchestrator.js• L314-322 scripts/…/orchestration-session.js• L131-153

Workflow entrypoints

The repository exposes three orchestration entrypoints through package scripts. They cover launch, worker execution, and state inspection.

Entry pointRole
orchestrate:tmuxBuild or run a multi-worker tmux and worktree session from a JSON plan.
orchestrate:workerRun one worker from its task file and write launcher-managed results.
orchestrate:statusRead a session or plan target and print a normalized session snapshot.

The launch entrypoint supports a dry run by default. It can instead write coordination artifacts or execute the plan. This separates plan review from resource creation.

References: package.json• L466-468 scripts/orchestrate-worktrees.js• L13-24 scripts/orchestrate-worktrees.js• L69-97

Worker launch flow

Plan materialization

Plan materialization creates the shared coordination directory before any worker starts. Each worker receives a task file with its objective, a pending handoff file, and an initial status file.

The plan also resolves worker names into stable slugs. Those slugs link the branch, worktree path, tmux pane title, and coordination directory. A launcher command can use plan variables such as the worker worktree and artifact paths, so the same plan can start different worker runtimes.

The diagram shows how a plan becomes worker resources and an executable session.

flowchart TD
    Plan[JSON worker plan] --> Build[Build worker plans]
    Build --> Artifacts[Task, handoff, and status files]
    Build --> Trees[Branch-backed worktrees]
    Build --> Session[Named tmux session]
    Trees --> Panes[Worker tmux panes]
    Artifacts --> Panes
    Panes --> Launch[Launcher command]

References: scripts/…/tmux-worktree-orchestrator.js• L175-251 scripts/…/tmux-worktree-orchestrator.js• L314-322 scripts/…/tmux-worktree-orchestrator.js• L523-567

Worker execution

The Codex worker launcher is the standard single-worker path. It requires a task file, starts with a running status, and passes the task to Codex in the current worktree. The worker must not modify sibling worktrees or create nested agents.

On success, the launcher captures the worker response in the handoff file and records the current Git status. On failure, it records a failed status and a failure handoff. Missing or unreadable task input fails before Codex runs and still produces those failure artifacts.

References: scripts/orchestrate-codex-worker.sh• L4-11 scripts/orchestrate-codex-worker.sh• L33-49 scripts/orchestrate-codex-worker.sh• L58-78 scripts/orchestrate-codex-worker.sh• L80-106

Review workflow

The native orch-review workflow is a gated review segment rather than a worktree creator. It accepts a unified diff and optional language and changed-file context. It runs a quality review in parallel with a language review when one is known and a security review when the diff matches security-sensitive signals.

The workflow then verifies every high-severity finding with an independent reviewer. It returns blocking and advisory findings. A failed review dimension or an uncertain blocker keeps the result at CHANGES_REQUESTED, so incomplete review cannot pass the gate.

References: workflows/orch-review.workflow.js• L1-31 workflows/orch-review.workflow.js• L177-215 workflows/orch-review.workflow.js• L240-295

Worktree isolation

Worktree setup

Each worker starts from the plan's base reference on its own branch. The worktree sits beside the repository by default, while coordination files remain under the configured coordination root. This lets workers edit in parallel without sharing an index or working directory.

Plans can copy selected seed paths from the repository into each worker worktree. Seed paths must remain inside the repository root. The copy gives a worker local context without changing the branch history of the worktree.

References: scripts/…/tmux-worktree-orchestrator.js• L53-105 scripts/…/tmux-worktree-orchestrator.js• L207-232 scripts/…/tmux-worktree-orchestrator.js• L513-521

Resource cleanup

Execution checks that the repository and tmux are available before it creates resources. It rejects an existing session unless replacement is requested. If setup fails after partial creation, it removes only the resources created by that run and reports cleanup errors with the original failure.

Replacement cleanup removes the old tmux session and matching worktrees and branches. Because this can discard existing work, replacement is an explicit plan choice rather than the default behavior.

References: scripts/…/tmux-worktree-orchestrator.js• L390-423 scripts/…/tmux-worktree-orchestrator.js• L426-480 scripts/…/tmux-worktree-orchestrator.js• L482-508 scripts/…/tmux-worktree-orchestrator.js• L569-579

Worktree lifecycle

The lifecycle report compares every Git worktree with a selected base branch. It distinguishes active work from cleanup candidates by combining branch position, uncommitted changes, predicted merge conflicts, and last-commit age.

The scripts/worktree-lifecycle.js command turns this report into an operator view. It can show all worktrees, limit the view to conflict or stale queues, emit the versioned JSON report, or show a cleanup plan. The default comparison uses main and marks clean work as stale after seven days unless the operator selects different values.

Git access uses the target repository and worktree paths without inherited Git environment settings. This keeps lifecycle checks focused on the selected repository, including when the command runs from a hook or another Git-controlled process. Safe worktree-path parsing requires Git 2.36 or newer.

StateMeaning for orchestration
main or detachedPrimary or branchless workspace that is not normal worker output.
dirtyUncommitted work that must not be removed automatically.
merge-readyClean work with commits ahead of the base and no predicted conflict.
conflictClean work that needs conflict resolution before merge.
mergedNo unique commits remain ahead of the base.
staleUnmerged work with no recent activity and a need for salvage before removal.
idleClean work with no current merge contribution.

The cleanup plan removes only fully merged worktrees. It places stale unmerged work in a salvage queue and keeps dirty, conflicting, and other unmerged worktrees.

References: scripts/worktree-lifecycle.js• L6-17 scripts/worktree-lifecycle.js• L49-68 scripts/…/git.js• L5-17 scripts/…/git.js• L63-95 scripts/…/lifecycle.js• L7-25 scripts/…/lifecycle.js• L27-61 scripts/…/lifecycle.js• L109-145 scripts/…/lifecycle.js• L149-182

Orchestration state

Session inspection

The status entrypoint accepts either a session name or a plan file. A plan target supplies the repository and coordination locations from the plan. A session-name target uses the standard .claude/orchestration/<session> location.

Inspection reads worker task, status, and handoff records and joins them with tmux pane data. The result shows session activity, worker state, pane health, worktree, objective, and reported outputs. Operators can print the result or save the JSON snapshot for another tool.

References: scripts/orchestration-status.js• L9-18 scripts/orchestration-status.js• L30-50 scripts/…/orchestration-session.js• L218-285 scripts/…/dmux-tmux.js• L43-79

Canonical session snapshots

Session adapters convert different runtime records into the shared ecc.session.v1 shape. This gives orchestration state one view even when the runtime is tmux-backed, Codex-backed, or supplied by another host adapter.

The shared view keeps session state separate from worker health. It also keeps worker intent, runtime details, outputs, and artifact paths together. Snapshots can be sent to the configured state store or retained as JSON recordings when no state store writer is available.

References: scripts/…/canonical-session.js• L162-263 scripts/…/canonical-session.js• L388-423 scripts/…/registry.js• L99-141

Codex coordination

Codex session discovery

The Codex worktree adapter treats Codex rollout logs as session records. It accepts a codex: or codex-worktree: target, the special latest target, a session identifier, or a direct rollout file path. It locates append-only JSONL rollout files and uses their recent activity to decide whether the session is active.

The adapter extracts the worktree path, branch, objective, model, origin, and start data. It ignores the injected harness preamble when it derives the worker objective, and it tolerates an incomplete trailing record while a rollout is still being written. This makes a Codex session visible through the same inspection surface as other workers.

References: scripts/…/codex-worktree.js• L10-25 scripts/…/codex-worktree.js• L56-134 scripts/…/codex-worktree.js• L187-203 scripts/…/codex-worktree.js• L278-301

Codex session normalization

A Codex rollout becomes a one-worker canonical session. Its runtime is identified as Codex. Its worktree and branch come from the rollout context. Its activity state becomes active while recent records exist and recorded after activity stops.

The adapter can persist the normalized snapshot through the shared state store or the JSON recording fallback. The registry maps both codex and codex-worktree target types to this adapter, so callers can use a stable target contract without knowing the storage layout.

References: scripts/…/canonical-session.js• L529-577 scripts/…/codex-worktree.js• L304-345 scripts/…/registry.js• L8-17

Change checklist

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

  • Keep the launcher template variables aligned with the task, handoff, and status paths that plan materialization creates.
  • Keep the coordination directory rules aligned between plan targets and session-name targets. They use different default roots.
  • Preserve the worker artifact headings and fields that session inspection parses into objectives, states, validation, and risks.
  • Preserve the ecc.session.v1 shape when changing any adapter. Downstream state storage and operator views depend on its required fields.
  • Keep cleanup rules conservative when changing lifecycle states. Dirty or unmerged work must not become an automatic removal candidate.
  • Keep the lifecycle command's Git version requirement and repository-target rules aligned with the Git runner.
  • Keep Codex target prefixes and rollout parsing aligned with the session adapter registry.

Important failure modes

TriggerConsequenceGuard
A plan has no workers or a worker has no task or launcherPlan creation stops before resources are created.Validate the plan before execution.
Two worker names produce the same slugBranches and coordination paths would collide.Require unique worker slugs.
A tmux session with the same name already existsA new run is rejected.Inspect the existing session or explicitly choose replacement.
A worker setup step fails after resources existThe run fails and cleanup runs for resources created before the failure.Use execution rollback and inspect cleanup errors.
A task file is missing or unreadableCodex does not run. Status and handoff record failure.Materialize and check task artifacts before launch.
A worktree is dirty, conflicting, or unmergedAutomatic cleanup can lose work or create an unsafe merge.Keep it out of removal; use the conflict or salvage queue.
Lifecycle checks run with an old Git version or inherited Git repository variablesWorktree paths may not be read safely, or checks may inspect the wrong repository.Require Git 2.36+ and clear inherited Git environment settings before inspection.
A Codex target has no matching rollout or uses an unsupported pathSession inspection fails instead of returning a false session.Use a supported target prefix, identifier, latest target, or rollout file.
A review dimension fails or a high-severity finding cannot be refuted with confidenceThe review returns CHANGES_REQUESTED.Treat incomplete and uncertain review as blocking.

Key files

FileWhy to read it
scripts/orchestrate-worktrees.jsPrimary command for dry runs, artifact-only setup, and live multi-worker launch.
scripts/…/tmux-worktree-orchestrator.jsDefines the plan-to-worktree-to-tmux flow and resource rollback boundary.
scripts/orchestrate-codex-worker.shDefines the single-worker Codex contract and handoff behavior.
scripts/orchestration-status.jsProvides the operator-facing session inspection command.
scripts/…/orchestration-session.jsShows how coordination files and tmux panes become a session snapshot.
scripts/worktree-lifecycle.jsProvides lifecycle reports, conflict and stale queues, and cleanup plans.
scripts/…/git.jsDefines the repository-scoped Git checks that support safe lifecycle classification.
scripts/…/lifecycle.jsDefines the worktree state model and cleanup safety rules.
scripts/…/codex-worktree.jsConnects Codex rollout sessions to worktrees and session inspection.
scripts/…/canonical-session.jsDefines the shared session snapshot and persistence contract.
workflows/orch-review.workflow.jsDefines the parallel review and adversarial verification segment used by the orchestration workflow.