fix(orchestrator): include phase/step context and original error chain in build cancellation messages

Previously, when a build was cancelled or timed out, the user-facing error
message was always the generic "build was cancelled" or "build timed out",
regardless of the underlying cause. This made it very difficult to diagnose
why a build actually failed (e.g. envd crash due to GLIBC incompatibility,
VM process exit, timeout during a specific phase).

Changes:
- PhaseBuildError.Error() now includes phase and step context when available,
  e.g. "context canceled (phase: provision, step: 1)"
- phases.Run() annotates context cancellation/timeout errors with the metadata
  of the phase that was active when the interruption occurred
- WrapContextAsUserError() preserves the original error chain instead of
  replacing it, so diagnostic details like "wait for envd: failed to init
  new envd" are visible to the user
- Added sanitizeErrorMessage() to handle newlines from errors.Join

Before: Build failed: build was cancelled
After:  Build failed: build was cancelled: wait for envd: failed to init new envd: context canceled
   or:  Build failed: context canceled (phase: provision, step: 1)

Author: orion-gmx

packages/orchestrator/pkg/template/build/builderrors/errors.go

@@ -5,6 +5,8 @@ package builderrors
 import (
 	"context"
 	"errors"
+	"fmt"
+	"strings"
 
 	"github.com/e2b-dev/infra/packages/orchestrator/pkg/template/build/phases"
 	template_manager "github.com/e2b-dev/infra/packages/shared/pkg/grpc/template-manager"
@@ -28,29 +30,80 @@ func IsUserError(err error) bool {
 
 // WrapContextAsUserError wraps context.Canceled as a user error if no user error already exists.
 // This ensures that user-initiated cancellations are tracked as user errors in metrics.
+//
+// When the error already contains a PhaseBuildError (e.g. annotated by phases.Run
+// with the active phase/step), the phase metadata is extracted and re-wrapped with
+// the standardized ErrCanceled/ErrTimeout sentinel so that errors.Is still works.
+// The original error chain is preserved via a sanitizedError wrapper that cleans
+// up newlines in Error() while keeping Unwrap() intact.
 func WrapContextAsUserError(err error) error {
 	if err == nil {
 		return nil
 	}
 
-	// If it's already a user error, return as-is
-	if IsUserError(err) {
-		return err
+	// Extract phase metadata if present, so we can re-wrap with the standard sentinel.
+	// When err is exactly the PhaseBuildError (not wrapped by an outer error like
+	// errors.Join), we unwrap to pbe.Err to avoid duplicating phase/step in the
+	// message. When err has outer wrapping context, we keep the full err so that
+	// diagnostic details are not lost.
+	var phase, step string
+	errToWrap := err
+	if pbe := phases.UnwrapPhaseBuildError(err); pbe != nil {
+		phase = pbe.Phase
+		step = pbe.Step
+		// Only unwrap when err is the PhaseBuildError itself; if there is
+		// outer wrapping (e.g. errors.Join), preserve the full context.
+		if err == error(pbe) {
+			errToWrap = pbe.Err
+		}
+		// For non-cancel/timeout user errors, return as-is.
+		if !errors.Is(err, context.Canceled) && !errors.Is(err, context.DeadlineExceeded) {
+			return err
+		}
+	}
+
+	// wrapWithPhase creates a PhaseBuildError preserving any phase/step context
+	// extracted above, with the given sentinel wrapping the original error chain.
+	wrapWithPhase := func(sentinel error) error {
+		return &phases.PhaseBuildError{
+			Phase: phase,
+			Step:  step,
+			Err:   fmt.Errorf("%w: %w", sentinel, sanitizedError{errToWrap}),
+		}
 	}
 
-	// If it's a canceled context, wrap it as a user error
+	// If it's a canceled context, wrap it as a user error while preserving the
+	// original error chain for diagnostics.
 	if errors.Is(err, context.Canceled) {
-		return phases.NewPhaseBuildError(phases.PhaseMeta{}, ErrCanceled)
+		return wrapWithPhase(ErrCanceled)
 	}
 
-	// If it's a timeout context, wrap it as a user error
+	// If it's a timeout context, wrap it as a user error while preserving the
+	// original error chain for diagnostics.
 	if errors.Is(err, context.DeadlineExceeded) {
-		return phases.NewPhaseBuildError(phases.PhaseMeta{}, ErrTimeout)
+		return wrapWithPhase(ErrTimeout)
 	}
 
 	return err
 }
 
+// sanitizedError wraps an error, replacing newlines in Error() output
+// (e.g. from errors.Join) while preserving the original error chain via Unwrap.
+type sanitizedError struct {
+	err error
+}
+
+func (e sanitizedError) Error() string {
+	if e.err == nil {
+		return ""
+	}
+	return strings.ReplaceAll(e.err.Error(), "\n", "; ")
+}
+
+func (e sanitizedError) Unwrap() error {
+	return e.err
+}
+
 func UnwrapUserError(err error) *template_manager.TemplateBuildStatusReason {
 	phaseBuildError := phases.UnwrapPhaseBuildError(err)
 	if phaseBuildError != nil {

packages/orchestrator/pkg/template/build/phases/errors.go

@@ -4,6 +4,7 @@ package phases
 
 import (
 	"errors"
+	"fmt"
 )
 
 type PhaseBuildError struct {
@@ -13,7 +14,27 @@ type PhaseBuildError struct {
 }
 
 func (e *PhaseBuildError) Error() string {
-	return e.Err.Error()
+	if e.Err == nil {
+		if e.Phase == "" && e.Step == "" {
+			return "unknown build error"
+		}
+		if e.Step == "" {
+			return fmt.Sprintf("build error (phase: %s)", e.Phase)
+		}
+		return fmt.Sprintf("build error (phase: %s, step: %s)", e.Phase, e.Step)
+	}
+
+	// If the inner error chain already contains a PhaseBuildError, skip
+	// appending phase/step to avoid duplicate metadata in the message.
+	if (e.Phase == "" && e.Step == "") || UnwrapPhaseBuildError(e.Err) != nil {
+		return e.Err.Error()
+	}
+
+	if e.Step == "" {
+		return fmt.Sprintf("%s (phase: %s)", e.Err.Error(), e.Phase)
+	}
+
+	return fmt.Sprintf("%s (phase: %s, step: %s)", e.Err.Error(), e.Phase, e.Step)
 }
 
 func (e *PhaseBuildError) Unwrap() error {

packages/orchestrator/pkg/template/build/phases/phase.go

@@ -75,6 +75,26 @@ func Run(
 
 	sourceLayer := LayerResult{}
 
+	// wrapContextErr annotates a context cancellation/timeout error with the
+	// phase metadata that was active when the error occurred, so that the
+	// user-facing message includes which build step was interrupted.
+	wrapContextErr := func(err error, meta PhaseMeta) error {
+		if err == nil {
+			return nil
+		}
+
+		// Already a PhaseBuildError — keep it as-is.
+		if UnwrapPhaseBuildError(err) != nil {
+			return err
+		}
+
+		if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
+			return NewPhaseBuildError(meta, err)
+		}
+
+		return err
+	}
+
 	for _, builder := range builders {
 		meta := builder.Metadata()
 
@@ -91,19 +111,19 @@ func Run(
 		phaseStartTime := time.Now()
 		hash, err := builder.Hash(ctx, sourceLayer)
 		if err != nil {
-			return LayerResult{}, fmt.Errorf("getting hash: %w", err)
+			return LayerResult{}, wrapContextErr(fmt.Errorf("getting hash: %w", err), meta)
 		}
 
 		currentLayer, err := builder.Layer(ctx, sourceLayer, hash)
 		if err != nil {
-			return LayerResult{}, fmt.Errorf("getting layer: %w", err)
+			return LayerResult{}, wrapContextErr(fmt.Errorf("getting layer: %w", err), meta)
 		}
 		metrics.RecordCacheResult(ctx, meta.Phase, meta.StepType, currentLayer.Cached)
 
 		prefix := builder.Prefix()
 		source, err := builder.String(ctx)
 		if err != nil {
-			return LayerResult{}, fmt.Errorf("getting source: %w", err)
+			return LayerResult{}, wrapContextErr(fmt.Errorf("getting source: %w", err), meta)
 		}
 		stepUserLogger.Info(ctx, layerInfo(currentLayer.Cached, prefix, source, currentLayer.Hash))
 
@@ -127,7 +147,7 @@ func Run(
 		metrics.RecordPhaseDuration(ctx, phaseDuration, meta.Phase, meta.StepType, false)
 
 		if err != nil {
-			return LayerResult{}, err
+			return LayerResult{}, wrapContextErr(err, meta)
 		}
 
 		sourceLayer = res