cloudposse
diff --git a/‎cmd/cmd_utils.go‎
Lines changed: 28 additions & 1 deletion b/‎cmd/cmd_utils.go‎
Lines changed: 28 additions & 1 deletion
diff --git a/‎errors/error_funcs.go‎
Lines changed: 9 additions & 0 deletions b/‎errors/error_funcs.go‎
Lines changed: 9 additions & 0 deletions
diff --git a/‎errors/error_funcs_test.go‎
Lines changed: 26 additions & 0 deletions b/‎errors/error_funcs_test.go‎
Lines changed: 26 additions & 0 deletions
diff --git a/‎errors/errors.go‎
Lines changed: 6 additions & 0 deletions b/‎errors/errors.go‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎internal/exec/workflow_utils.go‎
Lines changed: 46 additions & 2 deletions b/‎internal/exec/workflow_utils.go‎
Lines changed: 46 additions & 2 deletions
diff --git a/‎internal/exec/workflow_utils_test.go‎
Lines changed: 58 additions & 0 deletions b/‎internal/exec/workflow_utils_test.go‎
Lines changed: 58 additions & 0 deletions
diff --git a/‎main.go‎
Lines changed: 46 additions & 9 deletions b/‎main.go‎
Lines changed: 46 additions & 9 deletions
@@ -31,6 +31,7 @@ import (
 	l "github.com/cloudposse/atmos/pkg/list"
 	log "github.com/cloudposse/atmos/pkg/logger"
 	"github.com/cloudposse/atmos/pkg/perf"
+	"github.com/cloudposse/atmos/pkg/process"
 	"github.com/cloudposse/atmos/pkg/reexec"
 	stepPkg "github.com/cloudposse/atmos/pkg/runner/step"
 	"github.com/cloudposse/atmos/pkg/schema"
@@ -729,6 +730,13 @@ func executeCustomCommand(
 		log.Debug("Using working directory for custom command", "command", commandConfig.Name, "working_directory", workDir)
 	}
 
+	// Validate exec steps before executing anything: an exec step replaces
+	// the Atmos process, so it must be the final step and must not set
+	// supervisor-only fields (tty, interactive, retry, timeout, output).
+	if err := schema.ValidateExecTasks(commandConfig.Steps); err != nil {
+		errUtils.CheckErrorPrintAndExit(err, "", "https://atmos.tools/cli/configuration/commands#interactive-and-tty-steps")
+	}
+
 	// Initialize step executor once before loop - reused across steps to preserve outputs.
 	executor := stepPkg.NewStepExecutor()
 
@@ -892,8 +900,27 @@ func executeCustomCommand(
 		switch stepType {
 		case "shell":
 			// Execute shell command (backward compatible).
+			// Steps with tty/interactive attach the user's terminal so commands
+			// like `aws ssm start-session` get a real TTY and own Ctrl-C.
 			commandName := fmt.Sprintf("%s-step-%d", commandConfig.Name, i)
-			err = e.ExecuteShell(commandToRun, commandName, workDir, env, false)
+			err = process.RunShellStep(context.Background(), &process.ShellSessionSpec{
+				Command:     commandToRun,
+				Name:        commandName,
+				Dir:         workDir,
+				Env:         env,
+				TTY:         step.Tty,
+				Interactive: step.Interactive,
+			}, func() error {
+				return e.ExecuteShell(commandToRun, commandName, workDir, env, false)
+			})
+		case schema.TaskTypeExec:
+			// Replace the Atmos process with the command (shell exec semantics).
+			err = process.ReplaceShellSession(&process.ExecSpec{
+				Command: commandToRun,
+				Name:    fmt.Sprintf("%s-step-%d", commandConfig.Name, i),
+				Dir:     workDir,
+				Env:     env,
+			})
 		case "atmos":
 			// Execute atmos command.
 			args := strings.Fields(commandToRun)
 
@@ -336,6 +336,15 @@ func CheckErrorPrintAndExit(err error, title string, suggestion string) {
 			Exit(0)
 			return
 		}
+		// Silent exits propagate the code without printing (terminal-handoff
+		// steps; rendering would query the terminal and can hang).
+		if exitCodeErr.Silent {
+			if atmosConfig != nil && atmosConfig.Errors.Sentry.Enabled {
+				CloseSentry()
+			}
+			Exit(exitCodeErr.Code)
+			return
+		}
 		// Non-zero exit codes: print error and exit with that code
 		CheckErrorAndPrint(err, title, suggestion)
 
 
@@ -123,6 +123,32 @@ func TestCheckErrorPrintAndExit_ExitCodeError(t *testing.T) {
 	}
 }
 
+func TestCheckErrorPrintAndExit_SilentExitCodeError(t *testing.T) {
+	if os.Getenv("TEST_SILENT_EXIT") == "1" {
+		err := ExitCodeError{Code: 7, Silent: true}
+		CheckErrorPrintAndExit(err, "Should Not Print", "")
+		return
+	}
+
+	execPath, err := exec.LookPath(os.Args[0])
+	assert.Nil(t, err)
+	cmd := exec.Command(execPath, "-test.run=TestCheckErrorPrintAndExit_SilentExitCodeError")
+	cmd.Env = append(os.Environ(), "TEST_SILENT_EXIT=1")
+	var stderr bytes.Buffer
+	cmd.Stderr = &stderr
+	runErr := cmd.Run()
+
+	var exitError *exec.ExitError
+	if errors.As(runErr, &exitError) {
+		assert.Equal(t, 7, exitError.ExitCode(), "silent error must still propagate the exit code")
+	} else {
+		assert.Fail(t, "Expected an exit error with code 7")
+	}
+	// Silent errors must not render a themed error box (which would query the terminal).
+	assert.NotContains(t, stderr.String(), "subcommand exited")
+	assert.NotContains(t, stderr.String(), "# Error")
+}
+
 func TestCheckErrorPrintAndExit_ExecExitError(t *testing.T) {
 	if os.Getenv("TEST_EXEC_EXIT") == "1" {
 		// Create an exec.ExitError using platform-appropriate command.
 
@@ -1223,6 +1223,12 @@ var (
 // This avoids deep exits (os.Exit) which are untestable.
 type ExitCodeError struct {
 	Code int
+	// Silent suppresses themed error rendering: the process exits with Code
+	// without printing an error box. Used for terminal-handoff steps (tty,
+	// interactive, exec) where, like a shell, a non-zero exit from the child
+	// program should propagate the code without Atmos rendering its own error
+	// (which would query the terminal and can hang when stdin is contended).
+	Silent bool
 }
 
 func (e ExitCodeError) Error() string {
 
@@ -27,6 +27,7 @@ import (
 	envpkg "github.com/cloudposse/atmos/pkg/env"
 	log "github.com/cloudposse/atmos/pkg/logger"
 	"github.com/cloudposse/atmos/pkg/perf"
+	"github.com/cloudposse/atmos/pkg/process"
 	"github.com/cloudposse/atmos/pkg/retry"
 	stepPkg "github.com/cloudposse/atmos/pkg/runner/step"
 	"github.com/cloudposse/atmos/pkg/schema"
@@ -279,6 +280,18 @@ func ExecuteWorkflow(
 	// Check if the workflow steps have the `name` attribute
 	checkAndGenerateWorkflowStepNames(workflowDefinition)
 
+	// Validate exec steps before executing anything: an exec step replaces
+	// the Atmos process, so it must be the final step and must not set
+	// supervisor-only fields (tty, interactive, retry, timeout, output).
+	if err := schema.ValidateExecWorkflowSteps(workflowDefinition.Steps); err != nil {
+		return errUtils.Build(err).
+			WithTitle(WorkflowErrTitle).
+			WithHint("Steps of type `exec` replace the Atmos process; move the exec step to the end of the workflow and remove unsupported fields").
+			WithContext("workflow", workflow).
+			WithExitCode(1).
+			Err()
+	}
+
 	log.Debug("Executing workflow", "workflow", workflow, "path", workflowPath)
 
 	if atmosConfig.Logs.Level == u.LogLevelTrace || atmosConfig.Logs.Level == u.LogLevelDebug {
@@ -402,10 +415,34 @@ func ExecuteWorkflow(
 		switch commandType {
 		case "shell":
 			// Render command before execution if show.command is enabled.
+			// Steps with tty/interactive attach the user's terminal; plain
+			// steps keep the existing masked shell-interpreter behavior.
 			stepPkg.RenderCommand(&step, workflowDefinition, command)
 			commandName := fmt.Sprintf("%s-step-%d", workflow, stepIdx)
 			err = retry.Do(context.Background(), step.Retry, func() error {
-				return ExecuteShell(command, commandName, ".", stepEnv, dryRun)
+				return process.RunShellStep(context.Background(), &process.ShellSessionSpec{
+					Command:     command,
+					Name:        commandName,
+					Dir:         ".",
+					Env:         stepEnv,
+					TTY:         step.Tty,
+					Interactive: step.Interactive,
+					DryRun:      dryRun,
+				}, func() error {
+					return ExecuteShell(command, commandName, ".", stepEnv, dryRun)
+				})
+			})
+		case schema.TaskTypeExec:
+			// Replace the Atmos process with the command (shell exec semantics).
+			// Validated earlier to be the final step; no retry wrapper (the
+			// process is replaced, so a retry could never run).
+			stepPkg.RenderCommand(&step, workflowDefinition, command)
+			err = process.ReplaceShellSession(&process.ExecSpec{
+				Command: command,
+				Name:    fmt.Sprintf("%s-step-%d", workflow, stepIdx),
+				Dir:     ".",
+				Env:     stepEnv,
+				DryRun:  dryRun,
 			})
 		case "atmos":
 			// Parse command using shell.Fields for proper quote handling.
@@ -464,7 +501,7 @@ func ExecuteWorkflow(
 				return errUtils.Build(errUtils.ErrInvalidWorkflowStepType).
 					WithTitle(WorkflowErrTitle).
 					WithHintf("Step type '%s' is not supported", commandType).
-					WithHint("Each step must specify a valid type: 'atmos', 'shell', or an interactive type like 'input', 'confirm', 'choose'").
+					WithHint("Each step must specify a valid type: 'atmos', 'shell', 'exec', or an interactive type like 'input', 'confirm', 'choose'").
 					WithExitCode(1).
 					Err()
 			}
@@ -476,6 +513,13 @@ func ExecuteWorkflow(
 			if progressRenderer.IsEnabled() {
 				progressRenderer.Done()
 			}
+			// Terminal-handoff steps (tty/interactive/exec) that exit non-zero
+			// propagate the code silently, like a shell - don't wrap them in a
+			// themed workflow error (which would query the terminal post-session).
+			var silentExit errUtils.ExitCodeError
+			if errors.As(err, &silentExit) && silentExit.Silent {
+				return err
+			}
 			return buildWorkflowStepError(err, &workflowStepErrorContext{
 				WorkflowPath:     workflowPath,
 				WorkflowBasePath: atmosConfig.Workflows.BasePath,
 
@@ -1694,3 +1694,61 @@ func TestDoubleHyphenIssue1967(t *testing.T) {
 	assert.Equal(t, "--", args[5], "sixth arg should be --")
 	assert.Equal(t, "-consolidate-warnings=false", args[6], "seventh arg should be -consolidate-warnings=false")
 }
+
+func TestExecuteWorkflowExecStep_ValidationViaSchema(t *testing.T) {
+	// The workflow runner validates exec steps before executing anything.
+	err := schema.ValidateExecWorkflowSteps([]schema.WorkflowStep{
+		{Type: schema.TaskTypeExec, Command: "psql"},
+		{Type: schema.TaskTypeShell, Command: "echo never runs"},
+	})
+	require.ErrorIs(t, err, schema.ErrExecStepNotLast)
+
+	err = schema.ValidateExecWorkflowSteps([]schema.WorkflowStep{
+		{Type: schema.TaskTypeShell, Command: "echo first"},
+		{Type: schema.TaskTypeExec, Command: "psql"},
+	})
+	assert.NoError(t, err)
+}
+
+func TestExecuteWorkflow_ExecStepDryRun(t *testing.T) {
+	testDir := "../../tests/fixtures/scenarios/workflows"
+	t.Setenv("ATMOS_CLI_CONFIG_PATH", testDir)
+	t.Setenv("ATMOS_BASE_PATH", testDir)
+
+	atmosConfig, err := cfg.InitCliConfig(schema.ConfigAndStacksInfo{}, false)
+	require.NoError(t, err)
+
+	workflowDefinition := &schema.WorkflowDefinition{
+		Description: "Exec step as the final step",
+		Steps: []schema.WorkflowStep{
+			{Name: "prep", Type: "shell", Command: "echo preparing"},
+			{Name: "session", Type: schema.TaskTypeExec, Command: "echo session"},
+		},
+	}
+
+	// Dry-run exercises validation and the exec routing without replacing the process.
+	err = ExecuteWorkflow(atmosConfig, "exec-dry-run", "test.yaml", workflowDefinition, true, "", "", "")
+	require.NoError(t, err)
+}
+
+func TestExecuteWorkflow_ExecStepNotLastFails(t *testing.T) {
+	testDir := "../../tests/fixtures/scenarios/workflows"
+	t.Setenv("ATMOS_CLI_CONFIG_PATH", testDir)
+	t.Setenv("ATMOS_BASE_PATH", testDir)
+
+	atmosConfig, err := cfg.InitCliConfig(schema.ConfigAndStacksInfo{}, false)
+	require.NoError(t, err)
+
+	workflowDefinition := &schema.WorkflowDefinition{
+		Description: "Exec step in the wrong position",
+		Steps: []schema.WorkflowStep{
+			{Name: "session", Type: schema.TaskTypeExec, Command: "echo session"},
+			{Name: "after", Type: "shell", Command: "echo never runs"},
+		},
+	}
+
+	// Validation must fail before any step executes, even in dry-run.
+	err = ExecuteWorkflow(atmosConfig, "exec-not-last", "test.yaml", workflowDefinition, true, "", "", "")
+	require.Error(t, err)
+	assert.ErrorIs(t, err, schema.ErrExecStepNotLast)
+}
@@ -1,6 +1,7 @@
 package main
 
 import (
+	"errors"
 	"os"
 	"os/signal"
 	"strings"
@@ -11,23 +12,33 @@ import (
 	ioLayer "github.com/cloudposse/atmos/pkg/io"
 	log "github.com/cloudposse/atmos/pkg/logger"
 	"github.com/cloudposse/atmos/pkg/panics"
+	"github.com/cloudposse/atmos/pkg/signals"
 )
 
 func main() {
 	// Set up signal handling for graceful shutdown.
 	sigChan := make(chan os.Signal, 1)
 	signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)
 	go func() {
-		sig := <-sigChan
-		// Clean up resources before exit.
-		cmd.Cleanup()
-		// Exit with correct POSIX exit code (128 + signal number).
-		// Use errUtils.OsExit to allow test interception (Go 1.25+ panics on os.Exit in tests).
-		if s, ok := sig.(syscall.Signal); ok {
-			errUtils.OsExit(128 + int(s))
+		for sig := range sigChan {
+			// While an interactive/TTY step owns the terminal, SIGINT belongs to
+			// the foreground child process - keep waiting instead of exiting.
+			if !shouldExitOnSignal(sig) {
+				continue
+			}
+			// Run registered exit cleanups (e.g. restore the terminal from raw
+			// mode) - os.Exit below skips deferred functions.
+			signals.RunExitCleanups()
+			// Clean up resources before exit.
+			cmd.Cleanup()
+			// Exit with correct POSIX exit code (128 + signal number).
+			// Use errUtils.OsExit to allow test interception (Go 1.25+ panics on os.Exit in tests).
+			if s, ok := sig.(syscall.Signal); ok {
+				errUtils.OsExit(128 + int(s))
+			}
+			// Fallback to SIGINT exit code if signal type assertion fails.
+			errUtils.OsExit(130)
 		}
-		// Fallback to SIGINT exit code if signal type assertion fails.
-		errUtils.OsExit(130)
 	}()
 
 	// Disable timestamp in logs so snapshots work. We will address this in a future PR updating styles, etc.
@@ -81,6 +92,13 @@ func run() (exitCode int) {
 
 	err := cmd.Execute()
 	if err != nil {
+		// Silent exit-code carriers (terminal-handoff steps) propagate the
+		// child's code without themed rendering, which would query the
+		// terminal and can hang when stdin is still contended by the session.
+		if code, ok := silentExitCode(err); ok {
+			return code
+		}
+
 		// Capture error to Sentry if configured (safe to call even if Sentry not initialized).
 		errUtils.CaptureError(err)
 
@@ -97,6 +115,25 @@ func run() (exitCode int) {
 	return 0
 }
 
+// silentExitCode reports the exit code to use when err is a silent exit-code
+// carrier (a terminal-handoff step that exited non-zero). Such errors must
+// propagate the code without themed rendering, which would query the terminal
+// and can hang when the session still contends for stdin.
+func silentExitCode(err error) (int, bool) {
+	var exitCodeErr errUtils.ExitCodeError
+	if errors.As(err, &exitCodeErr) && exitCodeErr.Silent {
+		return exitCodeErr.Code, true
+	}
+	return 0, false
+}
+
+// shouldExitOnSignal reports whether the process should exit in response to sig.
+// SIGINT is ignored while a foreground interactive/TTY step owns the terminal
+// (the child process handles Ctrl-C). SIGTERM always exits as an escape hatch.
+func shouldExitOnSignal(sig os.Signal) bool {
+	return sig != os.Interrupt || !signals.InterruptExitSuspended()
+}
+
 // hasVersionFlag checks if --version flag is present in args.
 // Only checks for --version as the first argument after the program name
 // to catch the simple "atmos --version" case for early exit; other flag