Orchestrator

Reference Architecture

The Orchestrator is the bounded execution loop of the Decision plane. It runs the Planner / Executor / Critic triad, manages subagent lanes, and persists checkpoints for durable background sessions.

This is a component design. The repository provides deterministic lifecycle, operation, checkpoint and budget validators; the implementing controller/store must atomically enforce expected revisions, ownership generations, reservations and fencing. The roles can share a process; three separately deployed agents are not required. Exact profile/feature admission happens before work and cannot be demoted by a plan or retry.

Definition

A coordinator component that owns one Run Context’s worth of execution. Reads the CompiledContext; runs the triad until the Critic emits a terminal verdict; produces a DecisionRecord. See Orchestration for the spec narrative.

Why it exists

Keeping planning, execution and judgment explicit gives the runtime auditable artifacts (plan, transcript, verdict) and supports replay. Role/child allocations remain bounded reservations from the same original root budget; separation cannot mint independent capacity.

Inputs

• CompiledContext from the Compiler
• Run Context with RunBudget (atomic accumulators)
• DecisionSpec registry from the Decision Catalog
• Tool registry with native ActionRisk declarations and v1 approval projections

Outputs

• Typed Plan and step transcripts
• DecisionRecord with evidence_refs, approvals, controls_active
• Memory write proposals
• OTEL trace bundle stitched across subagent lanes
• Owned ExecutionCheckpoint snapshots (in long_running mode)

How it works

1. Plan — Planner reads CompiledContext; emits typed Plan with steps, tool intents, decision checkpoints.
2. Verify — Critic checks the plan against tool allow-lists, evidence requirements, native action risk, v1 compatibility projections, and policy obligations.
3. Execute — Executor runs verified steps via the Tool Manager. Required approval binds the complete action and current stored proposal; immediately before dispatch, recheck authority/revocation, exact approval/redemption, actual boundary/data route and aggregate reservation.
4. Verify effect and score — retain stable operation identity and provider-specific outcome evidence, verify required postconditions, then score. retry is a proposal subject to bounded recovery safety, not permission to repeat an uncertain effect.
5. Consolidate — extracts effects + evidence into memory write proposals.
6. Loop or terminate — re-plan attempts capped by RunBudget.max_replan_attempts.

Subagent lanes

• Lanes have child Run Context/identity, a reserved slice of original aggregate capacity/deadline, narrowed authority/tool surface and trace correlation. Intersect verified ancestor grants and current revocation; a serialized delegation envelope cannot authenticate itself.
• Lane outputs return as typed envelopes; lane traces stitched into the parent.
• Lanes cannot mutate parent effects[]; they propose results the parent’s Critic accepts or rejects.
• Check actual child recipients, namespace and output labels; a parent’s data access does not authorize arbitrary child/model disclosure. Propagate cancellation and fence stale workers, preserving uncertain child effects/reservations until verified settlement.

Background sessions

• Persist canonical checkpoints at safe owned recovery points, binding exact contract/pack/policy/tool/profile/release pins and current run/operation/budget stores.
• A session_id locates work; current revision/generation ownership and required target fencing authorize recovery. Revalidate all six resume checks: support, authority, approval, boundary, external preconditions and budget.
• An interruption records stop/suspend intent rather than automatically authorizing resume. Changed artifact interpretation requires explicit migration/reauthorization; original operation identities, uncertainty, reservations and absolute deadline survive restart.

Use the exact RunStatus lifecycle: created, running, waiting_approval, waiting_external, suspended, cancel_requested, completed, failed, cancelled, expired. A successful completion requires all declared required effects confirmed and children settled. A stop acknowledgement can establish cancelled execution while an external effect remains unknown; cancellation is not rollback. Execution Contract distinguishes run, decision and effect states.

Failure modes

• Plan contains disallowed tools or missing approvals — caught by Critic at verify.
• Tool response lost after a possible effect — record unknown; retry only under the configured strategy with verified provider-specific idempotency or definitive absence evidence. A key alone cannot establish safety.
• Subagent lane modifies parent effects — invariant violation; lane terminated.
• Background session resumes against a different pack version — refuse with pack_version_mismatch.
• Loop guard trips silently without a structured reason — bug; loop guard must always set loop_detected reason.

Operational concerns

• Explicit replan limits per admitted workflow (the worked reference uses 2); no universal default or runtime self-expansion. Planner, model, evaluator, retry and child work share original limits and verified accounting.
• Verification cost and strictness scale with native risk dimensions; the v1 risk_class remains a coarse compatibility and sampling signal.
• Workflow timeouts and SLA enforcement at the Run Context boundary.
• Subagent lane fan-out limits to bound cost and latency.
• Background session checkpoint storage and TTL by tenant.

Evaluation metrics

• Plan-verification pass rate.
• Step completion rate.
• Retry and recovery rate.
• Escalation rate by native risk dimension and v1 compatibility tier.
• Subagent lane success rate vs. parent re-plan rate.
• Mean time to safe completion.