feat: unify agent task execution budgets (#8199)

Author: chubes4

docs/commands/agent-task.md

@@ -71,6 +71,22 @@ ordering and output bindings belong in the existing single-run `fanout submit` /
 
 ### Cook/Review
 
+### Provider Execution Budgets
+
+Each dispatched plan carries one versioned `execution_budget`: total provider
+executions, same-provider retries, and provider rotations. The total cap applies
+before either category cap, so retry and rotation cannot multiply executions.
+
+```bash
+homeboy agent-task dispatch --prompt @task.md --max-provider-executions 1
+homeboy agent-task dispatch --prompt @task.md --max-provider-executions 2 --max-same-provider-retries 1
+homeboy agent-task dispatch --prompt @task.md --max-provider-executions 2 --max-provider-rotations 1
+```
+
+`--attempts` remains a deprecated alias for the total. It cannot be combined
+with explicit budget fields and resolves both category limits to `N - 1`.
+Status previews the resolved budget without changing durable run data.
+
 | Subcommand | Purpose |
 |---|---|
 | `cook` | Run one workspace task through the patch-artifact handoff workflow. |

src/commands/agent_task/fanout.rs

@@ -29,6 +29,9 @@ use super::args::{
 };
 use super::command_json_value;
 
+const AGENT_TASK_BATCH_COOK_FANOUT_PLAN_SCHEMA_V2: &str =
+    "homeboy/agent-task-batch-cook-fanout-plan/v2";
+
 pub(super) fn fanout(args: AgentTaskFanoutArgs) -> CmdResult<Value> {
     match args.command {
         AgentTaskFanoutCommand::CookBatch(cook_batch_args) => cook_batch(cook_batch_args),
@@ -329,7 +332,11 @@ fn load_batch_cook_fanout_plan(args: &AgentTaskFanoutInputArgs) -> Result<BatchC
     BatchCookFanoutPlan::from_value(value, args)
 }
 
+// v1 has no flattened or extension-bearing fields, so strict decoding preserves
+// its concrete contract while rejecting misspelled budget fields. v2 makes the
+// budget-capable schema explicit for new producers.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(deny_unknown_fields)]
 struct BatchCookFanoutPlan {
     #[serde(default = "batch_cook_fanout_plan_schema")]
     schema: String,
@@ -342,6 +349,16 @@ struct BatchCookFanoutPlan {
 impl BatchCookFanoutPlan {
     fn from_value(value: Value, args: &AgentTaskFanoutInputArgs) -> Result<Self> {
         reject_generic_fanout_inputs(&value)?;
+        let attempts_explicit = value
+            .get("cooks")
+            .and_then(Value::as_array)
+            .map(|cooks| {
+                cooks
+                    .iter()
+                    .map(|cook| cook.get("attempts").is_some())
+                    .collect::<Vec<_>>()
+            })
+            .unwrap_or_default();
         let mut plan: BatchCookFanoutPlan = serde_json::from_value(value).map_err(|error| {
             Error::validation_invalid_argument(
                 "input",
@@ -352,12 +369,17 @@ impl BatchCookFanoutPlan {
                 ]),
             )
         })?;
+        for (cook, attempts_explicit) in plan.cooks.iter_mut().zip(attempts_explicit) {
+            cook.attempts_explicit = attempts_explicit;
+        }
         if let Some(fanout_id) = &args.fanout_id {
             plan.fanout_id = fanout_id.clone();
         }
-        if plan.schema != AGENT_TASK_BATCH_COOK_FANOUT_PLAN_SCHEMA {
+        if plan.schema != AGENT_TASK_BATCH_COOK_FANOUT_PLAN_SCHEMA
+            && plan.schema != AGENT_TASK_BATCH_COOK_FANOUT_PLAN_SCHEMA_V2
+        {
             return Err(invalid_fanout(
-                "agent-task fanout requires homeboy/agent-task-batch-cook-fanout-plan/v1",
+                "agent-task fanout requires homeboy/agent-task-batch-cook-fanout-plan/v1 or /v2",
             ));
         }
         if plan.fanout_id.trim().is_empty() {
@@ -378,6 +400,7 @@ impl BatchCookFanoutPlan {
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(deny_unknown_fields)]
 struct BatchCookSpec {
     cook_id: String,
     #[serde(default, skip_serializing_if = "Option::is_none")]
@@ -404,6 +427,14 @@ struct BatchCookSpec {
     secret_env: Vec<String>,
     #[serde(default = "one")]
     attempts: u32,
+    #[serde(skip)]
+    attempts_explicit: bool,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    max_provider_executions: Option<u32>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    max_same_provider_retries: Option<u32>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    max_provider_rotations: Option<u32>,
     #[serde(default = "one_usize")]
     concurrency: usize,
     #[serde(default, skip_serializing_if = "Option::is_none")]
@@ -516,6 +547,10 @@ impl BatchCookSpec {
                 provider_config: self.provider_config.clone(),
                 client_context: Some(merged_client_context(plan, self)),
                 attempts: self.attempts,
+                attempts_explicit: self.attempts_explicit,
+                max_provider_executions: self.max_provider_executions,
+                max_same_provider_retries: self.max_same_provider_retries,
+                max_provider_rotations: self.max_provider_rotations,
                 queue_only: false,
                 timeout_ms: None,
                 resolved_provider_policy: None,
@@ -663,6 +698,10 @@ fn build_cook_batch_plan(args: &AgentTaskFanoutCookBatchArgs) -> Result<BatchCoo
             model: args.model.clone(),
             secret_env: args.secret_env.clone(),
             attempts: 1,
+            attempts_explicit: false,
+            max_provider_executions: None,
+            max_same_provider_retries: None,
+            max_provider_rotations: None,
             concurrency: 1,
             provider_config: args.provider_config.clone(),
             client_context: Some(
@@ -1075,6 +1114,47 @@ mod tests {
         });
     }
 
+    #[test]
+    fn v2_budget_fields_round_trip_and_reject_typos() {
+        let plan = BatchCookFanoutPlan::from_value(
+            json!({
+                "schema": AGENT_TASK_BATCH_COOK_FANOUT_PLAN_SCHEMA_V2,
+                "fanout_id": "fanout/budget",
+                "cooks": [{
+                    "cook_id": "budget",
+                    "prompt": "fix budget",
+                    "to_worktree": "homeboy@budget",
+                    "verify": ["true"],
+                    "max_provider_executions": 3
+                }]
+            }),
+            &args(),
+        )
+        .expect("v2 plan");
+        let invocation = plan.cooks[0]
+            .to_cook_invocation(&plan)
+            .expect("v2 invocation");
+        assert_eq!(invocation.dispatch.core.max_provider_executions, Some(3));
+        assert!(!invocation.dispatch.core.attempts_explicit);
+
+        let error = BatchCookFanoutPlan::from_value(
+            json!({
+                "schema": AGENT_TASK_BATCH_COOK_FANOUT_PLAN_SCHEMA_V2,
+                "fanout_id": "fanout/budget",
+                "cooks": [{
+                    "cook_id": "budget",
+                    "prompt": "fix budget",
+                    "to_worktree": "homeboy@budget",
+                    "verify": ["true"],
+                    "max_provider_execution": 3
+                }]
+            }),
+            &args(),
+        )
+        .expect_err("v2 typo rejected");
+        assert!(error.message.contains("max_provider_execution"));
+    }
+
     #[test]
     fn generic_fanout_inputs_are_rejected_from_public_contract() {
         let error = BatchCookFanoutPlan::from_value(

src/commands/agent_task/status.rs

@@ -48,6 +48,15 @@ pub(super) fn status(args: StatusArgs) -> CmdResult<Value> {
         }
         Err(error) => return Err(error),
     };
+    // A future durable budget is incompatible, not an absent optional preview.
+    if let Err(error) = agent_task_lifecycle::load_plan(&args.run_id) {
+        if error
+            .message
+            .contains("unsupported agent-task execution budget version")
+        {
+            return Err(error);
+        }
+    }
     let mut value = serde_json::to_value(&record).unwrap_or(Value::Null);
     enrich_with_diagnostic_summary(&mut value, &args.run_id)?;
     if args.full {
@@ -1051,6 +1060,7 @@ fn compact_status_summary(record: &Value, run_id: &str) -> Value {
         "risk_flags": risk_flags,
         "execution_location": execution_location(record),
         "queue_visibility": queue_visibility(record),
+        "execution_budget": plan.as_ref().map(|plan| &plan.options.execution_budget),
         "liveness": liveness_summary(record),
         "full_command": format!("homeboy agent-task status {run_id} --full"),
     });

src/commands/agent_task/tests/dispatch.rs

@@ -329,6 +329,58 @@ fn cook_dispatch_provider_id_alias_maps_to_selector() {
     assert_eq!(args.dispatch.model, None);
 }
 
+#[test]
+fn execution_budget_flags_accept_explicit_values_and_reject_legacy_attempts_mix() {
+    let cli = Cli::try_parse_from([
+        "homeboy",
+        "agent-task",
+        "cook",
+        "--to-worktree",
+        "homeboy@execution-budget",
+        "--verify",
+        "true",
+        "--backend",
+        "sample-backend",
+        "--prompt",
+        "cook",
+        "--max-provider-executions",
+        "2",
+        "--max-same-provider-retries",
+        "1",
+        "--max-provider-rotations",
+        "0",
+    ])
+    .expect("execution budget flags parse");
+    let Commands::AgentTask(agent_task) = cli.command else {
+        panic!("expected agent-task command");
+    };
+    let AgentTaskCommand::Cook(args) = agent_task.command else {
+        panic!("expected cook command");
+    };
+    assert_eq!(args.dispatch.core.max_provider_executions, Some(2));
+    assert_eq!(args.dispatch.core.max_same_provider_retries, Some(1));
+    assert_eq!(args.dispatch.core.max_provider_rotations, Some(0));
+
+    assert!(Cli::try_parse_from([
+        "homeboy",
+        "agent-task",
+        "cook",
+        "--to-worktree",
+        "homeboy@execution-budget",
+        "--verify",
+        "true",
+        "--backend",
+        "sample-backend",
+        "--prompt",
+        "cook",
+        "--attempts",
+        "2",
+        "--max-provider-executions",
+        "2",
+    ])
+    .is_err());
+}
+
 #[test]
 fn agent_task_timeout_ms_flags_parse_for_cook_run_and_run_plan() {
     let cook = Cli::try_parse_from([

src/commands/agent_task/tests/promotion_review.rs

@@ -138,7 +138,10 @@ fn cook_returns_durable_id_when_promotion_provider_is_missing() {
                         tasks_json: None,
                         provider_config: None,
                         client_context: None,
-                        attempts: 1,
+                        attempts: Some(1),
+                        max_provider_executions: None,
+                        max_same_provider_retries: None,
+                        max_provider_rotations: None,
                         queue_only: false,
                         timeout_ms: None,
                         resolved_provider_policy: None,
@@ -332,7 +335,10 @@ fn cook_applies_executor_commit_from_source_repo_to_distinct_target_repo() {
                         tasks_json: None,
                         provider_config: None,
                         client_context: None,
-                        attempts: 1,
+                        attempts: Some(1),
+                        max_provider_executions: None,
+                        max_same_provider_retries: None,
+                        max_provider_rotations: None,
                         queue_only: false,
                         timeout_ms: None,
                         resolved_provider_policy: None,

src/commands/agent_task_dispatch.rs

@@ -21,9 +21,21 @@ pub struct DispatchCoreArgs {
     #[arg(long = "client-context", value_name = "JSON")]
     pub client_context: Option<String>,
 
-    /// Attempts per task, including the first attempt.
-    #[arg(long, default_value_t = 1, value_name = "N")]
-    pub attempts: u32,
+    /// Deprecated total provider-execution budget. Use --max-provider-executions.
+    #[arg(long, value_name = "N", conflicts_with_all = ["max_provider_executions", "max_same_provider_retries", "max_provider_rotations"])]
+    pub attempts: Option<u32>,
+
+    /// Total provider executions per task, including the first attempt.
+    #[arg(long, value_name = "N")]
+    pub max_provider_executions: Option<u32>,
+
+    /// Same-provider retries allowed after the first execution.
+    #[arg(long, value_name = "N")]
+    pub max_same_provider_retries: Option<u32>,
+
+    /// Cross-provider rotations allowed after the first execution.
+    #[arg(long, value_name = "N")]
+    pub max_provider_rotations: Option<u32>,
 
     /// Persist the run for a daemon/runner but do not execute immediately.
     #[arg(long)]
@@ -56,7 +68,11 @@ impl From<DispatchCoreArgs> for DispatchCoreInputs {
             tasks_json: args.tasks_json,
             provider_config: args.provider_config,
             client_context: args.client_context,
-            attempts: args.attempts,
+            attempts: args.attempts.unwrap_or(1),
+            attempts_explicit: args.attempts.is_some(),
+            max_provider_executions: args.max_provider_executions,
+            max_same_provider_retries: args.max_same_provider_retries,
+            max_provider_rotations: args.max_provider_rotations,
             queue_only: args.queue_only,
             timeout_ms: args.timeout_ms,
             resolved_provider_policy: args.resolved_provider_policy,
@@ -257,7 +273,10 @@ mod tests {
                     tasks_json: None,
                     provider_config: None,
                     client_context: None,
-                    attempts: 1,
+                    attempts: Some(1),
+                    max_provider_executions: None,
+                    max_same_provider_retries: None,
+                    max_provider_rotations: None,
                     queue_only: false,
                     timeout_ms: None,
                     resolved_provider_policy: None,
@@ -292,7 +311,10 @@ mod tests {
                     tasks_json: None,
                     provider_config: None,
                     client_context: None,
-                    attempts: 1,
+                    attempts: Some(1),
+                    max_provider_executions: None,
+                    max_same_provider_retries: None,
+                    max_provider_rotations: None,
                     queue_only: false,
                     timeout_ms: None,
                     resolved_provider_policy: None,
@@ -398,11 +420,14 @@ mod tests {
                 tasks_json: overrides.core.tasks_json,
                 provider_config: overrides.core.provider_config,
                 client_context: overrides.core.client_context,
-                attempts: if overrides.core.attempts == 0 {
+                attempts: Some(if overrides.core.attempts == 0 {
                     1
                 } else {
                     overrides.core.attempts
-                },
+                }),
+                max_provider_executions: overrides.core.max_provider_executions,
+                max_same_provider_retries: overrides.core.max_same_provider_retries,
+                max_provider_rotations: overrides.core.max_provider_rotations,
                 queue_only: overrides.core.queue_only,
                 timeout_ms: overrides.core.timeout_ms,
                 resolved_provider_policy: overrides.core.resolved_provider_policy,

src/core/agent_task_controller_service/request.rs

@@ -50,6 +50,10 @@ pub fn controller_request_dispatch_command(
             provider_config: optional_string(dispatch, "provider_config"),
             client_context: optional_string(dispatch, "client_context"),
             attempts: optional_u32(dispatch, "attempts")?.unwrap_or(1),
+            attempts_explicit: dispatch.get("attempts").is_some(),
+            max_provider_executions: optional_u32(dispatch, "max_provider_executions")?,
+            max_same_provider_retries: optional_u32(dispatch, "max_same_provider_retries")?,
+            max_provider_rotations: optional_u32(dispatch, "max_provider_rotations")?,
             queue_only: optional_bool(dispatch, "queue_only").unwrap_or(false),
             timeout_ms: optional_u64(dispatch, "timeout_ms")?,
             resolved_provider_policy: None,