fix: Propagate a failing task's exit code instead of collapsing it to 1

`moon run`, `moon ci`, and `moon check` always exited with code 1 on task
failure, regardless of the underlying process's real exit code. This prevented
CI pipelines from distinguishing between failure codes.

The exit code now propagates across both pipeline paths:

- Bail path (the default): the pipeline bubbles up an `Err`, which starbase
  otherwise collapses to 1. We now extract the process exit code from the error
  chain at the CLI boundary (mirroring the existing broken-pipe handling),
  render the error as before, and exit with the task's real code.
- Continue path (`exec --on-failure continue`): `ExecWorkflow::execute` reads
  the failed action's exit code directly.

Signals, aborts, non-task failures, and codes outside the 0-255 range fall back
to a generic 1.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: milesj

CHANGELOG.md

@@ -35,6 +35,11 @@
 - Fixed tasks that emit read-only outputs (e.g. `0444` files) failing on every cache hit with a
   "Permission denied" error when the `casOutputsCache` experiment is enabled. Caches that already
   contain read-only objects are healed automatically.
+- Fixed an issue where a failing task would always exit moon with code `1`, instead of propagating
+  the task's actual exit code. Commands like `moon run`, `moon ci`, and `moon check` now exit with
+  the underlying process's exit code (matching `make`, `npm`, `just`, etc.), so CI pipelines can
+  distinguish between failure codes. Signals, aborts, and codes outside the `0-255` range still fall
+  back to `1`.
 
 ## 2.4.2
 

crates/action/src/action.rs

@@ -153,6 +153,16 @@ impl Action {
         miette::miette!("Unknown error!")
     }
 
+    /// Return the exit code of the last executed task operation, if this
+    /// action ran a task/process. Returns `None` when no execution occurred
+    /// (setup/sync actions), or when a code wasn't captured (aborts, signals).
+    pub fn get_exit_code(&self) -> Option<i32> {
+        self.operations
+            .get_last_execution()
+            .and_then(|operation| operation.get_exec_output())
+            .and_then(|output| output.exit_code)
+    }
+
     pub fn get_prefix(&self) -> &str {
         match &*self.node {
             ActionNode::None => "unknown",

crates/action/tests/action_test.rs

@@ -0,0 +1,74 @@
+use moon_action::{Action, ActionStatus, Operation};
+
+fn task_op(exit_code: Option<i32>, status: ActionStatus) -> Operation {
+    let mut op = Operation::task_execution("cmd");
+
+    if let Some(output) = op.get_exec_output_mut() {
+        output.exit_code = exit_code;
+    }
+
+    op.finish(status);
+    op
+}
+
+mod get_exit_code {
+    use super::*;
+
+    #[test]
+    fn none_when_no_operations() {
+        let action = Action::default();
+
+        assert_eq!(action.get_exit_code(), None);
+    }
+
+    #[test]
+    fn none_when_no_execution_operation() {
+        let mut action = Action::default();
+        action.operations.push(Operation::hash_generation());
+
+        assert_eq!(action.get_exit_code(), None);
+    }
+
+    #[test]
+    fn returns_the_execution_exit_code() {
+        let mut action = Action::default();
+        action
+            .operations
+            .push(task_op(Some(80), ActionStatus::Failed));
+
+        assert_eq!(action.get_exit_code(), Some(80));
+    }
+
+    #[test]
+    fn returns_zero_for_passing_execution() {
+        let mut action = Action::default();
+        action
+            .operations
+            .push(task_op(Some(0), ActionStatus::Passed));
+
+        assert_eq!(action.get_exit_code(), Some(0));
+    }
+
+    #[test]
+    fn returns_the_last_execution_code_when_retried() {
+        let mut action = Action::default();
+        action
+            .operations
+            .push(task_op(Some(1), ActionStatus::Failed));
+        action
+            .operations
+            .push(task_op(Some(70), ActionStatus::Failed));
+
+        assert_eq!(action.get_exit_code(), Some(70));
+    }
+
+    #[test]
+    fn returns_negative_one_for_injected_aborts() {
+        let mut action = Action::default();
+        action
+            .operations
+            .push(task_op(Some(-1), ActionStatus::Aborted));
+
+        assert_eq!(action.get_exit_code(), Some(-1));
+    }
+}

crates/app/src/commands/exec.rs

@@ -285,15 +285,35 @@ impl ExecWorkflow {
             .execute_action_pipeline(action_context, action_graph)
             .await?;
 
-        let failed = results.into_iter().any(|result| {
-            if result.has_failed() {
-                !result.allow_failure
-            } else {
-                false
+        // Determine the exit code to bubble up. When a task fails, propagate its
+        // actual exit code (like make, npm, and just) so that CI and callers can
+        // distinguish between failure codes. For aborts, signals, non-task
+        // failures, or codes that can't be represented, fall back to a generic 1.
+        let mut any_failed = false;
+        let mut exit_code = None;
+
+        for result in &results {
+            if !result.has_failed() || result.allow_failure {
+                continue;
+            }
+
+            any_failed = true;
+
+            if let Some(code) = result
+                .get_exit_code()
+                .and_then(|code| u8::try_from(code).ok())
+                .filter(|code| *code != 0)
+            {
+                exit_code = Some(code);
+                break;
             }
-        });
+        }
+
+        if let Some(code) = exit_code {
+            return Ok(Some(code));
+        }
 
-        if failed {
+        if any_failed {
             return Ok(Some(1));
         }
 

crates/app/src/helpers.rs

@@ -10,12 +10,39 @@ use moon_action_pipeline::ActionPipeline;
 use moon_common::Id;
 use moon_console::ui::{OwnedOrShared, Progress, ProgressDisplay, ProgressReporter};
 use moon_console::{Console, ConsoleError, Level};
+use moon_process::ProcessError;
 use serde::Serialize;
 use starbase_utils::{fs, json, toml, yaml};
 use std::ops::Deref;
 use std::path::{Path, PathBuf};
 use std::sync::Arc;
 
+/// Walk an error chain and return the underlying process exit code, if the
+/// failure originated from a task/process that exited with a non-zero status.
+/// Signals, aborts, and codes that can't be represented as a `u8` yield `None`,
+/// so the caller can fall back to a generic exit code. This lets the pipeline's
+/// bubbled-up error propagate the task's real exit code, which `starbase` would
+/// otherwise collapse to 1.
+pub fn extract_task_exit_code(report: &miette::Report) -> Option<u8> {
+    report
+        .chain()
+        .find_map(|error| {
+            // The process error is usually boxed within its parent (e.g.
+            // `TaskRunnerError` wraps `Box<ProcessError>`), which surfaces as a
+            // `Box<ProcessError>` in the chain, so check both shapes.
+            error
+                .downcast_ref::<ProcessError>()
+                .or_else(|| {
+                    error
+                        .downcast_ref::<Box<ProcessError>>()
+                        .map(|boxed| boxed.as_ref())
+                })
+                .and_then(ProcessError::get_exit_code)
+        })
+        .and_then(|code| u8::try_from(code).ok())
+        .filter(|code| *code != 0)
+}
+
 pub fn serialize_config_based_on_extension(
     plugin_id: &Id,
     path: &Path,

crates/app/src/lib.rs

@@ -13,4 +13,5 @@ pub mod watchers;
 
 pub use app::*;
 pub use app_error::*;
+pub use helpers::extract_task_exit_code;
 pub use session::*;

crates/app/tests/helpers_test.rs

@@ -0,0 +1,78 @@
+use miette::Diagnostic;
+use moon_app::extract_task_exit_code;
+use moon_process::ProcessError;
+use thiserror::Error;
+
+// Mirrors how `TaskRunnerError::RunFailed` wraps `Box<ProcessError>`, which
+// surfaces the process error as a `Box<ProcessError>` in the error chain.
+#[derive(Debug, Diagnostic, Error)]
+#[error("task failed to run")]
+struct WrappedError {
+    #[source]
+    error: Box<ProcessError>,
+}
+
+fn exit_nonzero(code: Option<i32>) -> ProcessError {
+    ProcessError::ExitNonZero {
+        bin: "bash".into(),
+        status: "exit code".into(),
+        code,
+    }
+}
+
+fn wrapped(code: Option<i32>) -> miette::Report {
+    WrappedError {
+        error: Box::new(exit_nonzero(code)),
+    }
+    .into()
+}
+
+mod extract_task_exit_code {
+    use super::*;
+
+    #[test]
+    fn extracts_from_boxed_process_error() {
+        assert_eq!(extract_task_exit_code(&wrapped(Some(80))), Some(80));
+    }
+
+    #[test]
+    fn extracts_from_bare_process_error() {
+        let report: miette::Report = exit_nonzero(Some(2)).into();
+
+        assert_eq!(extract_task_exit_code(&report), Some(2));
+    }
+
+    #[test]
+    fn propagates_codes_above_127() {
+        assert_eq!(extract_task_exit_code(&wrapped(Some(200))), Some(200));
+    }
+
+    #[test]
+    fn none_for_signal_without_code() {
+        assert_eq!(extract_task_exit_code(&wrapped(None)), None);
+    }
+
+    #[test]
+    fn none_for_injected_abort_code() {
+        // Aborts before a process spawns are recorded with an exit code of -1
+        assert_eq!(extract_task_exit_code(&wrapped(Some(-1))), None);
+    }
+
+    #[test]
+    fn none_for_zero_code() {
+        assert_eq!(extract_task_exit_code(&wrapped(Some(0))), None);
+    }
+
+    #[test]
+    fn none_for_out_of_u8_range() {
+        // e.g. large Windows exit codes that can't map to a u8
+        assert_eq!(extract_task_exit_code(&wrapped(Some(300))), None);
+    }
+
+    #[test]
+    fn none_for_non_process_error() {
+        let report = miette::miette!("something else went wrong");
+
+        assert_eq!(extract_task_exit_code(&report), None);
+    }
+}

crates/cli/src/shared.rs

@@ -295,5 +295,17 @@ pub async fn run_cli(args: Vec<OsString>) -> MainResult {
         return Ok(ExitCode::from(BROKEN_PIPE_EXIT_CODE));
     }
 
+    // A task failed with a specific exit code. Render the error as the
+    // top-level handler would, then exit with the task's actual code so
+    // callers can distinguish between failure codes (like make, npm, and
+    // just). `starbase` otherwise collapses every error to exit code 1.
+    if let Some(error) = &outcome.error
+        && let Some(code) = moon_app::extract_task_exit_code(error)
+    {
+        eprintln!("Error: {error:?}");
+
+        return Ok(ExitCode::from(code));
+    }
+
     outcome.into_exit_result()
 }

crates/cli/tests/exec_test.rs

@@ -169,6 +169,20 @@ mod exec {
                 .stderr(predicate::str::contains("stderr"));
         }
 
+        // The script exits with a distinct code (2) so we can verify moon
+        // propagates the task's actual exit code, instead of collapsing it to 1.
+        #[test]
+        #[cfg(unix)]
+        fn propagates_process_exit_code() {
+            let sandbox = create_pipeline_sandbox();
+
+            let assert = sandbox.run_bin(|cmd| {
+                cmd.arg("exec").arg(target("exitNonZeroInline"));
+            });
+
+            assert.failure().code(2);
+        }
+
         #[test]
         fn passes_args_through() {
             let sandbox = create_pipeline_sandbox();

crates/process/src/output.rs

@@ -67,6 +67,7 @@ impl Output {
 
     pub fn to_error(&self, bin: impl AsRef<str>, with_message: bool) -> ProcessError {
         let bin = bin.as_ref().to_owned();
+        let code = self.code();
 
         let status = match &self.exit {
             ChildExit::Completed(status) => match status.code() {
@@ -79,7 +80,7 @@ impl Output {
         };
 
         if !with_message {
-            return ProcessError::ExitNonZero { bin, status };
+            return ProcessError::ExitNonZero { bin, status, code };
         }
 
         let mut message = output_to_trimmed_string(&self.stderr);
@@ -96,6 +97,7 @@ impl Output {
         ProcessError::ExitNonZeroWithOutput {
             bin,
             status,
+            code,
             output: message,
         }
     }