feat(compose): support depends_on condition service_completed_successfully

Docker Compose's service_completed_successfully waits for a dependency to run
to completion (exit 0) before starting the dependent; a3s-box rejected it at
config time. Now accepted, with boot-time gating: ComposeProject::completed_wait_deps
lists such dependencies and compose up waits for them before booting the
dependent. A dependency is 'completed' once it is no longer active — using a
new zombie-aware process::is_process_exited (the detached shim becomes a zombie
under compose-up when its VM halts, and kill(pid,0) would wrongly report it
alive); a recorded non-zero exit code fails the wait. Verified on Linux: a
dependent only starts after its init service has exited.

Author: Roy Lin

src/cli/src/commands/compose.rs

@@ -304,6 +304,27 @@ async fn execute_up(
             println!(" ✓");
         }
 
+        // Wait for dependencies that must run to completion (exit 0) first.
+        let completed_deps = project.completed_wait_deps(svc_name);
+        if !completed_deps.is_empty() {
+            print!(
+                "  [~] Waiting for {} to complete...",
+                completed_deps.join(", ")
+            );
+            if let Err(error) =
+                wait_for_completed(project_name, &completed_deps, up_args.timeout).await
+            {
+                return rollback_compose_up(
+                    &mut state,
+                    &started_services,
+                    &created_networks,
+                    error,
+                )
+                .await;
+            }
+            println!(" ✓");
+        }
+
         let mut box_config = match project.build_box_config(svc_name, Some(&default_net)) {
             Ok(config) => config,
             Err(error) => {
@@ -663,6 +684,73 @@ async fn wait_for_healthy(
     }
 }
 
+/// Wait for dependency services to run to completion (Docker's
+/// `service_completed_successfully`).
+///
+/// A dependency is "completed" once it is no longer active — preferring the
+/// record's terminal status (set by the monitor) and falling back to shim-PID
+/// liveness for the daemonless case. If an exit code was recorded and is
+/// non-zero, the dependency failed and the wait errors.
+async fn wait_for_completed(
+    project_name: &str,
+    service_names: &[String],
+    timeout_secs: u64,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let deadline = std::time::Instant::now() + std::time::Duration::from_secs(timeout_secs);
+
+    loop {
+        if std::time::Instant::now() > deadline {
+            return Err(format!(
+                "Timed out waiting for services to complete: {}",
+                service_names.join(", ")
+            )
+            .into());
+        }
+
+        let state = StateFile::load_default()?;
+        let mut all_done = true;
+        for svc_name in service_names {
+            let records = state.find_by_label(LABEL_SERVICE, svc_name);
+            let Some(record) = records
+                .iter()
+                .find(|r| r.labels.get(LABEL_PROJECT).map(String::as_str) == Some(project_name))
+            else {
+                all_done = false;
+                continue;
+            };
+
+            // A detached box's shim becomes a zombie under this process when its
+            // VM halts; is_process_exited is zombie-aware (is_process_alive /
+            // kill(pid,0) is not), so a completed dependency is detected.
+            let exited = !status::is_active(record)
+                || record
+                    .pid
+                    .map(crate::process::is_process_exited)
+                    .unwrap_or(true);
+            if !exited {
+                all_done = false;
+                continue;
+            }
+
+            if let Some(code) = record.exit_code {
+                if code != 0 {
+                    return Err(format!(
+                        "dependency service '{}' did not complete successfully (exit code {})",
+                        svc_name, code
+                    )
+                    .into());
+                }
+            }
+        }
+
+        if all_done {
+            return Ok(());
+        }
+
+        tokio::time::sleep(std::time::Duration::from_secs(1)).await;
+    }
+}
+
 // ============================================================================
 // compose down
 // ============================================================================

src/cli/src/process.rs

@@ -28,6 +28,38 @@ pub fn is_process_alive(pid: u32) -> bool {
     unsafe { libc::kill(pid as i32, 0) == 0 }
 }
 
+/// Whether `pid` has exited, treating a zombie (an exited-but-unreaped child)
+/// as exited. Unlike [`is_process_alive`], whose `kill(pid, 0)` succeeds for a
+/// zombie, this inspects `/proc/<pid>/stat` on Linux so a detached box's shim —
+/// which becomes a zombie under its parent the moment the VM halts — is detected
+/// as completed rather than appearing to run forever.
+#[cfg(target_os = "linux")]
+pub fn is_process_exited(pid: u32) -> bool {
+    match std::fs::read_to_string(format!("/proc/{pid}/stat")) {
+        // Format: "<pid> (<comm>) <state> ...". comm may contain spaces/parens,
+        // so scan past the final ')'. Z (zombie) or X (dead) => exited.
+        Ok(stat) => match stat.rfind(')') {
+            Some(idx) => matches!(
+                stat[idx + 1..].trim_start().chars().next(),
+                Some('Z') | Some('X')
+            ),
+            None => false,
+        },
+        // No /proc entry => the process is gone.
+        Err(_) => true,
+    }
+}
+
+#[cfg(all(unix, not(target_os = "linux")))]
+pub fn is_process_exited(pid: u32) -> bool {
+    !is_process_alive(pid)
+}
+
+#[cfg(not(unix))]
+pub fn is_process_exited(pid: u32) -> bool {
+    !is_process_alive(pid)
+}
+
 #[cfg(windows)]
 pub fn is_process_alive(pid: u32) -> bool {
     use windows_sys::Win32::Foundation::STILL_ACTIVE;
@@ -192,6 +224,14 @@ mod tests {
         assert!(!is_process_alive(99999));
     }
 
+    #[test]
+    fn test_is_process_exited_current_and_missing() {
+        // The running test process has not exited.
+        assert!(!is_process_exited(std::process::id()));
+        // A PID with no process is treated as exited.
+        assert!(is_process_exited(0x7fff_fffe));
+    }
+
     #[cfg(unix)]
     #[test]
     fn test_is_process_alive_parent_process() {

src/runtime/src/compose.rs

@@ -281,6 +281,23 @@ impl ComposeProject {
         }
     }
 
+    /// Dependencies this service must wait to run to completion (exit 0) before
+    /// starting — `depends_on: { dep: { condition: service_completed_successfully } }`.
+    pub fn completed_wait_deps(&self, service_name: &str) -> Vec<String> {
+        let Some(svc) = self.config.services.get(service_name) else {
+            return vec![];
+        };
+
+        match &svc.depends_on {
+            a3s_box_core::compose::DependsOn::Map(map) => map
+                .iter()
+                .filter(|(_, cond)| cond.condition == "service_completed_successfully")
+                .map(|(name, _)| name.clone())
+                .collect(),
+            _ => vec![],
+        }
+    }
+
     /// Get the health check config for a service, if defined.
     pub fn healthcheck(&self, service_name: &str) -> Option<HealthCheckSpec> {
         let svc = self.config.services.get(service_name)?;
@@ -419,10 +436,10 @@ fn validate_depends_on_conditions(
 
     for (dep_name, condition) in map {
         match condition.condition.as_str() {
-            "service_started" | "service_healthy" => {}
+            "service_started" | "service_healthy" | "service_completed_successfully" => {}
             other => {
                 return Err(BoxError::ConfigError(format!(
-                    "Service '{}' depends on '{}' with unsupported condition '{}' (supported: service_started, service_healthy)",
+                    "Service '{}' depends on '{}' with unsupported condition '{}' (supported: service_started, service_healthy, service_completed_successfully)",
                     service_name, dep_name, other
                 )));
             }
@@ -1056,6 +1073,25 @@ services:
         assert!(project.healthcheck("db").is_none());
     }
 
+    #[test]
+    fn test_service_completed_successfully_condition_accepted() {
+        let yaml = r#"
+services:
+  web:
+    image: nginx
+    depends_on:
+      init:
+        condition: service_completed_successfully
+  init:
+    image: busybox
+"#;
+        let config = ComposeConfig::from_yaml_str(yaml).unwrap();
+        let project = ComposeProject::new("myapp", config).unwrap();
+        assert_eq!(project.completed_wait_deps("web"), vec!["init".to_string()]);
+        // `init` itself has no completion wait.
+        assert!(project.completed_wait_deps("init").is_empty());
+    }
+
     #[test]
     fn test_unsupported_depends_on_condition_rejected() {
         let yaml = r#"
@@ -1064,7 +1100,7 @@ services:
     image: nginx
     depends_on:
       db:
-        condition: service_completed_successfully
+        condition: service_bogus_condition
   db:
     image: postgres
 "#;