ag_session/

orchestration.rs

//! Orchestration and orchestration-task lifecycle states.
//!
//! One orchestration groups the child sessions proposed by a single controller
//! plan. The orchestration row tracks whether that plan is still awaiting the
//! user's approval, actively fanning out, or settled; each task row tracks one
//! child session through creation, execution, and settlement.

use std::collections::HashSet;
use std::fmt;
use std::str::FromStr;

use crate::SessionStatus;

/// Maximum number of automatic focused-review remediation turns per managed
/// worker settlement wave.
pub const MAX_AUTOMATED_REVIEW_ITERATIONS: i64 = 3;

/// Execution behavior for one persisted orchestration task.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub enum OrchestrationTaskKind {
    /// Produces branch changes that proceed through review and integration.
    #[default]
    Implementation,
    /// Produces a read-only report whose temporary worktree is discarded.
    Research,
}

impl fmt::Display for OrchestrationTaskKind {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        let value = match self {
            OrchestrationTaskKind::Implementation => "Implementation",
            OrchestrationTaskKind::Research => "Research",
        };

        formatter.write_str(value)
    }
}

impl FromStr for OrchestrationTaskKind {
    type Err = String;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        match value {
            "Implementation" => Ok(OrchestrationTaskKind::Implementation),
            "Research" => Ok(OrchestrationTaskKind::Research),
            _ => Err(format!("Unknown orchestration task kind: {value}")),
        }
    }
}

/// Lifecycle state for one controller-owned orchestration.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum OrchestrationStatus {
    /// The plan is persisted and parked on the campaign approval board.
    AwaitingApproval,
    /// The plan is approved and its tasks are fanning out.
    Running,
    /// Cancellation is blocking new fan-out while active children stop.
    Canceling,
    /// Every task settled and the controller is verifying the results.
    Verifying,
    /// Verification passed and user integration approval is required.
    AwaitingIntegration,
    /// Verified tasks are being merged or published in plan order.
    Integrating,
    /// Every verified task integrated and the campaign was archived.
    Done,
    /// The user canceled the orchestration or its controller session.
    Canceled,
}

impl OrchestrationStatus {
    /// Returns whether the orchestration is still open.
    ///
    /// An open plan blocks another plan from being persisted for the same
    /// controller, including while it waits for approval.
    pub fn is_active(self) -> bool {
        matches!(
            self,
            OrchestrationStatus::AwaitingApproval
                | OrchestrationStatus::Running
                | OrchestrationStatus::Canceling
                | OrchestrationStatus::Verifying
                | OrchestrationStatus::AwaitingIntegration
                | OrchestrationStatus::Integrating
        )
    }
}

impl fmt::Display for OrchestrationStatus {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        let value = match self {
            OrchestrationStatus::AwaitingApproval => "AwaitingApproval",
            OrchestrationStatus::Running => "Running",
            OrchestrationStatus::Canceling => "Canceling",
            OrchestrationStatus::Verifying => "Verifying",
            OrchestrationStatus::AwaitingIntegration => "AwaitingIntegration",
            OrchestrationStatus::Integrating => "Integrating",
            OrchestrationStatus::Done => "Done",
            OrchestrationStatus::Canceled => "Canceled",
        };

        formatter.write_str(value)
    }
}

impl FromStr for OrchestrationStatus {
    type Err = String;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        match value {
            "AwaitingApproval" => Ok(OrchestrationStatus::AwaitingApproval),
            "Running" => Ok(OrchestrationStatus::Running),
            "Canceling" => Ok(OrchestrationStatus::Canceling),
            "Verifying" => Ok(OrchestrationStatus::Verifying),
            "AwaitingIntegration" => Ok(OrchestrationStatus::AwaitingIntegration),
            "Integrating" => Ok(OrchestrationStatus::Integrating),
            "Done" => Ok(OrchestrationStatus::Done),
            "Canceled" => Ok(OrchestrationStatus::Canceled),
            _ => Err(format!("Unknown orchestration status: {value}")),
        }
    }
}

/// User-selected destination for verified orchestration task branches.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum IntegrationApproach {
    /// Merge each verified child branch into the campaign base locally.
    LocalMerge,
    /// Publish each verified child branch as a forge review request.
    ReviewRequest,
}

impl fmt::Display for IntegrationApproach {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        let value = match self {
            IntegrationApproach::LocalMerge => "LocalMerge",
            IntegrationApproach::ReviewRequest => "ReviewRequest",
        };

        formatter.write_str(value)
    }
}

impl FromStr for IntegrationApproach {
    type Err = String;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        match value {
            "LocalMerge" => Ok(IntegrationApproach::LocalMerge),
            "ReviewRequest" => Ok(IntegrationApproach::ReviewRequest),
            _ => Err(format!("Unknown integration approach: {value}")),
        }
    }
}

/// Lifecycle state for one orchestration task and its child session.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum OrchestrationTaskStatus {
    /// Follow-up scope proposed by the controller and awaiting approval.
    Proposed,
    /// Persisted with the proposed plan, not yet approved or fanned out.
    Planned,
    /// The child session is being created and started.
    Creating,
    /// The child session is running its turn.
    Running,
    /// Focused review is running or awaiting a persisted result.
    Reviewing,
    /// The coordinator is applying one focused-review suggestion set.
    ReviewApplying,
    /// The child session parked on clarification questions.
    WaitingForInput,
    /// The child session finished and is ready for review or integration.
    Ready,
    /// A research child returned its report and its worktree was discarded.
    Reported,
    /// Approved feedback is being delivered to the existing managed child.
    ContinuationPending,
    /// Verification passed and this task awaits its integration gate.
    AwaitingIntegration,
    /// The coordinator has started branch merge or publication.
    Merging,
    /// Branch work was merged locally successfully.
    Integrated,
    /// The child branch was published and is waiting for its forge review
    /// request to merge.
    ReviewRequested,
    /// Integration failed and requires attention.
    IntegrationFailed,
    /// Ownership permanently transferred from the coordinator to the user.
    Detached,
    /// The child session failed, or a straggler was canceled out of band.
    Failed,
    /// The task was canceled as part of a cascade cancel.
    Canceled,
}

impl OrchestrationTaskStatus {
    /// Maps one observed child-session status into the task state owned by
    /// orchestration.
    pub fn from_child_status(status: SessionStatus) -> Self {
        match status {
            SessionStatus::Draft
            | SessionStatus::InProgress
            | SessionStatus::Queued
            | SessionStatus::Rebasing
            | SessionStatus::Merging => Self::Running,
            SessionStatus::Question => Self::WaitingForInput,
            SessionStatus::Review | SessionStatus::AgentReview => Self::Reviewing,
            SessionStatus::Merged | SessionStatus::Done => Self::Ready,
            SessionStatus::Canceled => Self::Failed,
        }
    }

    /// Returns whether the task reached a state that fan-in treats as settled.
    ///
    /// A canceled straggler counts as settled so out-of-band cancellation
    /// unblocks the roll-up instead of stalling it.
    pub fn is_settled(self) -> bool {
        matches!(
            self,
            OrchestrationTaskStatus::Ready
                | OrchestrationTaskStatus::Reported
                | OrchestrationTaskStatus::Integrated
                | OrchestrationTaskStatus::ReviewRequested
                | OrchestrationTaskStatus::IntegrationFailed
                | OrchestrationTaskStatus::Failed
                | OrchestrationTaskStatus::Canceled
                | OrchestrationTaskStatus::Detached
        )
    }

    /// Returns the concise user-facing label shown in campaign status output.
    pub fn campaign_label(self) -> &'static str {
        self.labels().1
    }

    /// Returns whether the task currently occupies a parallelism slot.
    ///
    /// A task waiting for user input still holds its child session and
    /// worktree, so it keeps consuming a slot until the user answers.
    pub fn occupies_parallelism_slot(self) -> bool {
        matches!(
            self,
            OrchestrationTaskStatus::Creating
                | OrchestrationTaskStatus::Running
                | OrchestrationTaskStatus::Reviewing
                | OrchestrationTaskStatus::ReviewApplying
                | OrchestrationTaskStatus::WaitingForInput
                | OrchestrationTaskStatus::ContinuationPending
                | OrchestrationTaskStatus::Merging
        )
    }

    /// Returns whether a transition to `next` is valid.
    ///
    /// Retry re-enters `Creating` from a settled state with the same task key,
    /// which is what makes replying "retry the failed tasks" a clean respawn
    /// rather than a duplicate fan-out.
    pub fn can_transition_to(self, next: OrchestrationTaskStatus) -> bool {
        if self == next {
            return true;
        }

        matches!(
            (self, next),
            (
                OrchestrationTaskStatus::Proposed,
                OrchestrationTaskStatus::Planned
            ) | (
                OrchestrationTaskStatus::Planned
                    | OrchestrationTaskStatus::Ready
                    | OrchestrationTaskStatus::Failed
                    | OrchestrationTaskStatus::Canceled
                    | OrchestrationTaskStatus::IntegrationFailed,
                OrchestrationTaskStatus::Creating
            ) | (
                OrchestrationTaskStatus::Creating | OrchestrationTaskStatus::WaitingForInput,
                OrchestrationTaskStatus::Running
            ) | (
                OrchestrationTaskStatus::Running,
                OrchestrationTaskStatus::Reviewing | OrchestrationTaskStatus::WaitingForInput
            ) | (
                OrchestrationTaskStatus::Running
                    | OrchestrationTaskStatus::Reviewing
                    | OrchestrationTaskStatus::WaitingForInput,
                OrchestrationTaskStatus::Ready | OrchestrationTaskStatus::Reported
            ) | (
                OrchestrationTaskStatus::Reviewing,
                OrchestrationTaskStatus::ReviewApplying
            ) | (
                OrchestrationTaskStatus::ReviewApplying,
                OrchestrationTaskStatus::Reviewing
                    | OrchestrationTaskStatus::WaitingForInput
                    | OrchestrationTaskStatus::Failed
            ) | (
                OrchestrationTaskStatus::Ready,
                OrchestrationTaskStatus::AwaitingIntegration
                    | OrchestrationTaskStatus::ContinuationPending
                    | OrchestrationTaskStatus::Detached
            ) | (
                OrchestrationTaskStatus::AwaitingIntegration,
                OrchestrationTaskStatus::Merging
                    | OrchestrationTaskStatus::ContinuationPending
                    | OrchestrationTaskStatus::Detached
            ) | (
                OrchestrationTaskStatus::IntegrationFailed,
                OrchestrationTaskStatus::ContinuationPending | OrchestrationTaskStatus::Detached
            ) | (
                OrchestrationTaskStatus::ContinuationPending,
                OrchestrationTaskStatus::Ready
                    | OrchestrationTaskStatus::WaitingForInput
                    | OrchestrationTaskStatus::Failed
            ) | (
                OrchestrationTaskStatus::Merging,
                OrchestrationTaskStatus::Integrated
                    | OrchestrationTaskStatus::ReviewRequested
                    | OrchestrationTaskStatus::IntegrationFailed
            ) | (
                OrchestrationTaskStatus::ReviewRequested,
                OrchestrationTaskStatus::Integrated | OrchestrationTaskStatus::IntegrationFailed
            ) | (
                OrchestrationTaskStatus::Planned
                    | OrchestrationTaskStatus::Creating
                    | OrchestrationTaskStatus::Running
                    | OrchestrationTaskStatus::Reviewing
                    | OrchestrationTaskStatus::ReviewApplying
                    | OrchestrationTaskStatus::WaitingForInput,
                OrchestrationTaskStatus::Failed | OrchestrationTaskStatus::Canceled
            )
        )
    }

    /// Returns whether this task no longer needs integration work.
    pub fn is_integration_settled(self) -> bool {
        matches!(
            self,
            OrchestrationTaskStatus::Integrated
                | OrchestrationTaskStatus::Detached
                | OrchestrationTaskStatus::Canceled
                | OrchestrationTaskStatus::Failed
        )
    }

    fn labels(self) -> (&'static str, &'static str) {
        match self {
            OrchestrationTaskStatus::Proposed => ("Proposed", "awaiting approval"),
            OrchestrationTaskStatus::Planned => ("Planned", "waiting"),
            OrchestrationTaskStatus::Creating => ("Creating", "starting"),
            OrchestrationTaskStatus::Running => ("Running", "running"),
            OrchestrationTaskStatus::Reviewing => ("Reviewing", "reviewing"),
            OrchestrationTaskStatus::ReviewApplying => ("ReviewApplying", "applying review"),
            OrchestrationTaskStatus::WaitingForInput => ("WaitingForInput", "waiting on you"),
            OrchestrationTaskStatus::Ready => ("Ready", "ready"),
            OrchestrationTaskStatus::Reported => ("Reported", "reported"),
            OrchestrationTaskStatus::ContinuationPending => ("ContinuationPending", "continuing"),
            OrchestrationTaskStatus::AwaitingIntegration => {
                ("AwaitingIntegration", "awaiting integration")
            }
            OrchestrationTaskStatus::Merging => ("Merging", "integrating"),
            OrchestrationTaskStatus::Integrated => ("Integrated", "integrated"),
            OrchestrationTaskStatus::ReviewRequested => ("ReviewRequested", "review requested"),
            OrchestrationTaskStatus::IntegrationFailed => {
                ("IntegrationFailed", "integration failed")
            }
            OrchestrationTaskStatus::Detached => ("Detached", "detached"),
            OrchestrationTaskStatus::Failed => ("Failed", "failed"),
            OrchestrationTaskStatus::Canceled => ("Canceled", "canceled"),
        }
    }
}

/// Pure scheduling decision derived from one orchestration task snapshot.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct OrchestrationScheduleDecision {
    /// Number of planned tasks that may claim a parallelism slot.
    pub spawn_count: usize,
    /// Whether every non-empty task has settled and roll-up can be claimed.
    pub should_submit: bool,
}

/// Pure orchestration policy over typed task observations.
pub struct OrchestrationPolicy;

impl OrchestrationPolicy {
    /// Decides fan-out capacity and roll-up readiness without persistence or
    /// runtime dependencies.
    pub fn schedule(
        max_parallelism: usize,
        task_statuses: &[Option<OrchestrationTaskStatus>],
    ) -> OrchestrationScheduleDecision {
        let occupied_slots = task_statuses
            .iter()
            .filter(|status| status.is_some_and(OrchestrationTaskStatus::occupies_parallelism_slot))
            .count();
        let planned_tasks = task_statuses
            .iter()
            .filter(|status| **status == Some(OrchestrationTaskStatus::Planned))
            .count();
        let spawn_count = max_parallelism
            .saturating_sub(occupied_slots)
            .min(planned_tasks);
        let should_submit = !task_statuses.is_empty()
            && task_statuses
                .iter()
                .all(|status| status.is_some_and(OrchestrationTaskStatus::is_settled));

        OrchestrationScheduleDecision {
            spawn_count,
            should_submit,
        }
    }
}

/// Protocol-independent snapshot of one task proposed by an orchestration
/// controller.
#[derive(Clone)]
pub struct OrchestrationPlanTask {
    /// Observable conditions checked during settlement verification.
    pub acceptance_criteria: Vec<String>,
    /// Whether the task implements changes or returns research findings.
    pub kind: OrchestrationTaskKind,
    /// Standalone task prompt delivered to the child session.
    pub prompt: String,
    /// Stable kebab-case identity used for retries.
    pub task_key: String,
    /// Short user-facing task title.
    pub title: String,
    /// Best-effort repository-relative files or directories expected to change.
    pub touched_areas: Vec<String>,
}

/// Validates one proposed subtask set before application code persists it.
///
/// # Errors
///
/// Returns a user-facing reason when the plan is too small, incomplete, or uses
/// invalid task keys or planning paths.
pub fn validate_subtasks(subtasks: &[OrchestrationPlanTask], is_retry: bool) -> Result<(), String> {
    let is_research_wave = !subtasks.is_empty()
        && subtasks
            .iter()
            .all(|subtask| subtask.kind == OrchestrationTaskKind::Research);
    let has_research = subtasks
        .iter()
        .any(|subtask| subtask.kind == OrchestrationTaskKind::Research);
    if has_research && !is_research_wave {
        return Err(
            "research and implementation tasks must be proposed in separate waves.".to_string(),
        );
    }
    if subtasks.len() < 2 && !is_retry && !is_research_wave {
        return Err("a meaningful orchestration requires at least two subtasks.".to_string());
    }
    let mut task_keys = HashSet::new();
    for subtask in subtasks {
        if !is_kebab_case_task_key(&subtask.task_key)
            || !task_keys.insert(subtask.task_key.as_str())
        {
            return Err("every subtask needs a unique kebab-case task key.".to_string());
        }
        if subtask.prompt.trim().is_empty()
            || subtask.title.trim().is_empty()
            || subtask
                .acceptance_criteria
                .iter()
                .all(|criterion| criterion.trim().is_empty())
        {
            return Err(format!(
                "subtask `{}` needs a title, standalone prompt, and acceptance criteria.",
                subtask.task_key
            ));
        }
        for area in subtask
            .touched_areas
            .iter()
            .filter(|_| subtask.kind == OrchestrationTaskKind::Implementation)
        {
            normalized_scope(area).map_err(|reason| {
                format!(
                    "subtask `{}` has invalid touched area `{area}`: {reason}.",
                    subtask.task_key
                )
            })?;
        }
    }

    Ok(())
}

fn is_kebab_case_task_key(task_key: &str) -> bool {
    !task_key.is_empty()
        && task_key.split('-').all(|segment| {
            !segment.is_empty()
                && segment
                    .bytes()
                    .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit())
        })
}

fn normalized_scope(area: &str) -> Result<String, &'static str> {
    let normalized = area.trim().trim_start_matches("./").trim_end_matches('/');
    if normalized.is_empty()
        || normalized.starts_with('/')
        || normalized.split('/').any(|part| part == "..")
    {
        return Err("use a non-empty repository-relative path");
    }
    if normalized.contains(['*', '?', '[', ']', '{', '}']) {
        return Err("use a literal file or directory path; wildcard patterns are not supported");
    }

    Ok(normalized.to_string())
}

impl fmt::Display for OrchestrationTaskStatus {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str(self.labels().0)
    }
}

impl FromStr for OrchestrationTaskStatus {
    type Err = String;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        match value {
            "Proposed" => Ok(OrchestrationTaskStatus::Proposed),
            "Planned" => Ok(OrchestrationTaskStatus::Planned),
            "Creating" => Ok(OrchestrationTaskStatus::Creating),
            "Running" => Ok(OrchestrationTaskStatus::Running),
            "Reviewing" => Ok(OrchestrationTaskStatus::Reviewing),
            "ReviewApplying" => Ok(OrchestrationTaskStatus::ReviewApplying),
            "WaitingForInput" => Ok(OrchestrationTaskStatus::WaitingForInput),
            "Ready" => Ok(OrchestrationTaskStatus::Ready),
            "Reported" => Ok(OrchestrationTaskStatus::Reported),
            "ContinuationPending" => Ok(OrchestrationTaskStatus::ContinuationPending),
            "AwaitingIntegration" => Ok(OrchestrationTaskStatus::AwaitingIntegration),
            "Merging" => Ok(OrchestrationTaskStatus::Merging),
            "Integrated" => Ok(OrchestrationTaskStatus::Integrated),
            "ReviewRequested" => Ok(OrchestrationTaskStatus::ReviewRequested),
            "IntegrationFailed" => Ok(OrchestrationTaskStatus::IntegrationFailed),
            "Detached" => Ok(OrchestrationTaskStatus::Detached),
            "Failed" => Ok(OrchestrationTaskStatus::Failed),
            "Canceled" => Ok(OrchestrationTaskStatus::Canceled),
            _ => Err(format!("Unknown orchestration task status: {value}")),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    /// Round-trips every orchestration status through its persisted form.
    fn test_orchestration_status_round_trips_persisted_values() {
        // Arrange
        let statuses = [
            OrchestrationStatus::AwaitingApproval,
            OrchestrationStatus::Running,
            OrchestrationStatus::Canceling,
            OrchestrationStatus::Verifying,
            OrchestrationStatus::AwaitingIntegration,
            OrchestrationStatus::Integrating,
            OrchestrationStatus::Done,
            OrchestrationStatus::Canceled,
        ];

        // Act
        let round_tripped = statuses.map(|status| {
            status
                .to_string()
                .parse::<OrchestrationStatus>()
                .expect("status should parse")
        });

        // Assert
        assert_eq!(round_tripped, statuses);
        assert!("Unknown".parse::<OrchestrationStatus>().is_err());
    }

    #[test]
    fn integration_approach_round_trips_persisted_values() {
        // Arrange
        let approaches = [
            IntegrationApproach::LocalMerge,
            IntegrationApproach::ReviewRequest,
        ];

        // Act
        let round_tripped = approaches.map(|approach| {
            approach
                .to_string()
                .parse::<IntegrationApproach>()
                .expect("approach should parse")
        });

        // Assert
        assert_eq!(round_tripped, approaches);
        assert!("Unknown".parse::<IntegrationApproach>().is_err());
    }

    #[test]
    fn orchestration_task_kind_round_trips_persisted_values() {
        // Arrange
        let kinds = [
            OrchestrationTaskKind::Implementation,
            OrchestrationTaskKind::Research,
        ];

        // Act
        let round_tripped = kinds.map(|kind| {
            kind.to_string()
                .parse::<OrchestrationTaskKind>()
                .expect("kind should parse")
        });

        // Assert
        assert_eq!(round_tripped, kinds);
        assert_eq!(OrchestrationTaskKind::default(), kinds[0]);
        assert!("Unknown".parse::<OrchestrationTaskKind>().is_err());
    }

    #[test]
    /// Restricts restart re-linking to orchestrations that still need work.
    fn test_only_unsettled_orchestrations_are_active() {
        // Arrange / Act / Assert
        assert!(OrchestrationStatus::AwaitingApproval.is_active());
        assert!(OrchestrationStatus::Running.is_active());
        assert!(OrchestrationStatus::Canceling.is_active());
        assert!(OrchestrationStatus::Verifying.is_active());
        assert!(OrchestrationStatus::AwaitingIntegration.is_active());
        assert!(OrchestrationStatus::Integrating.is_active());
        assert!(!OrchestrationStatus::Done.is_active());
        assert!(!OrchestrationStatus::Canceled.is_active());
    }

    #[test]
    /// Round-trips every task status through its persisted form.
    fn test_orchestration_task_status_round_trips_persisted_values() {
        // Arrange
        let statuses = [
            OrchestrationTaskStatus::Proposed,
            OrchestrationTaskStatus::Planned,
            OrchestrationTaskStatus::Creating,
            OrchestrationTaskStatus::Running,
            OrchestrationTaskStatus::Reviewing,
            OrchestrationTaskStatus::ReviewApplying,
            OrchestrationTaskStatus::WaitingForInput,
            OrchestrationTaskStatus::Ready,
            OrchestrationTaskStatus::Reported,
            OrchestrationTaskStatus::ContinuationPending,
            OrchestrationTaskStatus::AwaitingIntegration,
            OrchestrationTaskStatus::Merging,
            OrchestrationTaskStatus::Integrated,
            OrchestrationTaskStatus::ReviewRequested,
            OrchestrationTaskStatus::IntegrationFailed,
            OrchestrationTaskStatus::Detached,
            OrchestrationTaskStatus::Failed,
            OrchestrationTaskStatus::Canceled,
        ];

        // Act
        let round_tripped = statuses.map(|status| {
            status
                .to_string()
                .parse::<OrchestrationTaskStatus>()
                .expect("status should parse")
        });

        // Assert
        assert_eq!(round_tripped, statuses);
        assert!("Unknown".parse::<OrchestrationTaskStatus>().is_err());
    }

    #[test]
    /// Treats a canceled straggler as settled so fan-in is not blocked by
    /// out-of-band cancellation.
    fn test_settled_task_statuses_include_cancellation() {
        // Arrange / Act / Assert
        assert!(OrchestrationTaskStatus::Ready.is_settled());
        assert!(OrchestrationTaskStatus::Reported.is_settled());
        assert!(OrchestrationTaskStatus::Integrated.is_settled());
        assert!(OrchestrationTaskStatus::ReviewRequested.is_settled());
        assert!(OrchestrationTaskStatus::IntegrationFailed.is_settled());
        assert!(OrchestrationTaskStatus::Failed.is_settled());
        assert!(OrchestrationTaskStatus::Canceled.is_settled());
        assert!(!OrchestrationTaskStatus::Planned.is_settled());
        assert!(!OrchestrationTaskStatus::Creating.is_settled());
        assert!(!OrchestrationTaskStatus::Running.is_settled());
        assert!(!OrchestrationTaskStatus::Reviewing.is_settled());
        assert!(!OrchestrationTaskStatus::ReviewApplying.is_settled());
        assert!(!OrchestrationTaskStatus::WaitingForInput.is_settled());
    }

    #[test]
    /// Counts a task waiting for user input against the parallelism cap
    /// because it still owns a live child session and worktree.
    fn test_parallelism_slots_cover_every_live_child() {
        // Arrange / Act / Assert
        assert!(OrchestrationTaskStatus::Creating.occupies_parallelism_slot());
        assert!(OrchestrationTaskStatus::Running.occupies_parallelism_slot());
        assert!(OrchestrationTaskStatus::Reviewing.occupies_parallelism_slot());
        assert!(OrchestrationTaskStatus::ReviewApplying.occupies_parallelism_slot());
        assert!(OrchestrationTaskStatus::WaitingForInput.occupies_parallelism_slot());
        assert!(!OrchestrationTaskStatus::Planned.occupies_parallelism_slot());
        assert!(!OrchestrationTaskStatus::Ready.occupies_parallelism_slot());
        assert!(!OrchestrationTaskStatus::Failed.occupies_parallelism_slot());
        assert!(!OrchestrationTaskStatus::Canceled.occupies_parallelism_slot());
    }

    #[test]
    /// Allows the fan-out, question, settle, and retry transitions the
    /// coordinator drives, and rejects skipping creation.
    fn test_task_status_transitions_cover_fan_out_and_retry() {
        // Arrange / Act / Assert
        assert!(
            OrchestrationTaskStatus::Planned.can_transition_to(OrchestrationTaskStatus::Creating)
        );
        assert!(
            OrchestrationTaskStatus::Creating.can_transition_to(OrchestrationTaskStatus::Running)
        );
        assert!(
            OrchestrationTaskStatus::Running
                .can_transition_to(OrchestrationTaskStatus::WaitingForInput)
        );
        assert!(
            OrchestrationTaskStatus::WaitingForInput
                .can_transition_to(OrchestrationTaskStatus::Running)
        );
        assert!(OrchestrationTaskStatus::Running.can_transition_to(OrchestrationTaskStatus::Ready));
        assert!(
            OrchestrationTaskStatus::Running.can_transition_to(OrchestrationTaskStatus::Reported)
        );
        assert!(
            OrchestrationTaskStatus::Running.can_transition_to(OrchestrationTaskStatus::Reviewing)
        );
        assert!(
            OrchestrationTaskStatus::Reviewing
                .can_transition_to(OrchestrationTaskStatus::ReviewApplying)
        );
        assert!(
            OrchestrationTaskStatus::ReviewApplying
                .can_transition_to(OrchestrationTaskStatus::Reviewing)
        );
        assert!(
            OrchestrationTaskStatus::Running.can_transition_to(OrchestrationTaskStatus::Canceled)
        );
        assert!(
            OrchestrationTaskStatus::Failed.can_transition_to(OrchestrationTaskStatus::Creating)
        );
        assert!(OrchestrationTaskStatus::Ready.can_transition_to(OrchestrationTaskStatus::Ready));
        assert!(
            !OrchestrationTaskStatus::Planned.can_transition_to(OrchestrationTaskStatus::Running)
        );
        assert!(
            !OrchestrationTaskStatus::Canceled.can_transition_to(OrchestrationTaskStatus::Ready)
        );
    }

    #[test]
    fn integration_settlement_waits_for_review_request_merge() {
        // Arrange
        let settled = [
            OrchestrationTaskStatus::Integrated,
            OrchestrationTaskStatus::Detached,
            OrchestrationTaskStatus::Canceled,
            OrchestrationTaskStatus::Failed,
        ];
        // Act / Assert
        assert!(
            settled
                .into_iter()
                .all(OrchestrationTaskStatus::is_integration_settled)
        );
        assert!(!OrchestrationTaskStatus::Reported.is_integration_settled());
        assert!(!OrchestrationTaskStatus::AwaitingIntegration.is_integration_settled());
        assert!(!OrchestrationTaskStatus::ReviewRequested.is_integration_settled());
        assert!(
            OrchestrationTaskStatus::Merging
                .can_transition_to(OrchestrationTaskStatus::ReviewRequested)
        );
        assert!(
            OrchestrationTaskStatus::ReviewRequested
                .can_transition_to(OrchestrationTaskStatus::Integrated)
        );
        assert!(
            OrchestrationTaskStatus::ReviewRequested
                .can_transition_to(OrchestrationTaskStatus::IntegrationFailed)
        );
    }

    #[test]
    fn campaign_labels_cover_every_task_status() {
        // Arrange
        let statuses = [
            OrchestrationTaskStatus::Proposed,
            OrchestrationTaskStatus::Planned,
            OrchestrationTaskStatus::Creating,
            OrchestrationTaskStatus::Running,
            OrchestrationTaskStatus::Reviewing,
            OrchestrationTaskStatus::ReviewApplying,
            OrchestrationTaskStatus::WaitingForInput,
            OrchestrationTaskStatus::Ready,
            OrchestrationTaskStatus::Reported,
            OrchestrationTaskStatus::ContinuationPending,
            OrchestrationTaskStatus::AwaitingIntegration,
            OrchestrationTaskStatus::Merging,
            OrchestrationTaskStatus::Integrated,
            OrchestrationTaskStatus::ReviewRequested,
            OrchestrationTaskStatus::IntegrationFailed,
            OrchestrationTaskStatus::Detached,
            OrchestrationTaskStatus::Failed,
            OrchestrationTaskStatus::Canceled,
        ];

        // Act
        let labels = statuses.map(OrchestrationTaskStatus::campaign_label);

        // Assert
        assert_eq!(
            labels,
            [
                "awaiting approval",
                "waiting",
                "starting",
                "running",
                "reviewing",
                "applying review",
                "waiting on you",
                "ready",
                "reported",
                "continuing",
                "awaiting integration",
                "integrating",
                "integrated",
                "review requested",
                "integration failed",
                "detached",
                "failed",
                "canceled",
            ]
        );
    }

    #[test]
    fn validation_allows_one_research_task_and_ignores_its_touched_areas() {
        // Arrange
        let plan = [OrchestrationPlanTask {
            acceptance_criteria: vec!["Architecture questions are answered".to_string()],
            kind: OrchestrationTaskKind::Research,
            prompt: "Inspect the architecture".to_string(),
            task_key: "architecture".to_string(),
            title: "Architecture research".to_string(),
            touched_areas: vec!["**".to_string()],
        }];

        // Act
        let result = validate_subtasks(&plan, false);

        // Assert
        assert_eq!(result, Ok(()));
    }

    #[test]
    fn validation_rejects_one_implementation_task_and_invalid_implementation_scope() {
        // Arrange
        let single = [OrchestrationPlanTask {
            acceptance_criteria: vec!["Feature is complete".to_string()],
            kind: OrchestrationTaskKind::Implementation,
            prompt: "Implement the feature".to_string(),
            task_key: "feature".to_string(),
            title: "Feature".to_string(),
            touched_areas: Vec::new(),
        }];
        let invalid_scope = [
            OrchestrationPlanTask {
                touched_areas: vec!["crates/one/**".to_string()],
                ..single[0].clone()
            },
            OrchestrationPlanTask {
                task_key: "tests".to_string(),
                touched_areas: Vec::new(),
                ..single[0].clone()
            },
        ];
        let mixed = [
            OrchestrationPlanTask {
                kind: OrchestrationTaskKind::Research,
                ..single[0].clone()
            },
            OrchestrationPlanTask {
                task_key: "implementation".to_string(),
                ..single[0].clone()
            },
        ];

        // Act
        let single_result = validate_subtasks(&single, false);
        let empty_result = validate_subtasks(&[], false);
        let scope_result = validate_subtasks(&invalid_scope, false);
        let mixed_result = validate_subtasks(&mixed, false);

        // Assert
        assert_eq!(
            single_result,
            Err("a meaningful orchestration requires at least two subtasks.".to_string())
        );
        assert_eq!(
            empty_result,
            Err("a meaningful orchestration requires at least two subtasks.".to_string())
        );
        assert!(scope_result.is_err_and(|reason| reason.contains("wildcard patterns")));
        assert_eq!(
            mixed_result,
            Err(
                "research and implementation tasks must be proposed in separate waves.".to_string()
            )
        );
    }

    #[test]
    /// Derives fan-out capacity and roll-up readiness from typed task states.
    fn test_orchestration_policy_schedules_available_slots_and_settlement() {
        // Arrange
        let active_statuses = [
            Some(OrchestrationTaskStatus::Running),
            Some(OrchestrationTaskStatus::WaitingForInput),
            Some(OrchestrationTaskStatus::Planned),
            Some(OrchestrationTaskStatus::Planned),
        ];
        let settled_statuses = [
            Some(OrchestrationTaskStatus::Ready),
            Some(OrchestrationTaskStatus::Failed),
            Some(OrchestrationTaskStatus::Canceled),
        ];
        let invalid_statuses = [Some(OrchestrationTaskStatus::Ready), None];

        // Act
        let active_decision = OrchestrationPolicy::schedule(3, &active_statuses);
        let settled_decision = OrchestrationPolicy::schedule(3, &settled_statuses);
        let empty_decision = OrchestrationPolicy::schedule(3, &[]);
        let invalid_decision = OrchestrationPolicy::schedule(3, &invalid_statuses);

        // Assert
        assert_eq!(
            active_decision,
            OrchestrationScheduleDecision {
                spawn_count: 1,
                should_submit: false,
            }
        );
        assert_eq!(
            settled_decision,
            OrchestrationScheduleDecision {
                spawn_count: 0,
                should_submit: true,
            }
        );
        assert_eq!(
            empty_decision,
            OrchestrationScheduleDecision {
                spawn_count: 0,
                should_submit: false,
            }
        );
        assert!(!invalid_decision.should_submit);
    }

    #[test]
    /// Maps every child-session lifecycle family into orchestration policy.
    fn test_task_status_from_child_status_covers_session_lifecycle() {
        // Arrange
        let cases = [
            (SessionStatus::Draft, OrchestrationTaskStatus::Running),
            (SessionStatus::InProgress, OrchestrationTaskStatus::Running),
            (SessionStatus::Queued, OrchestrationTaskStatus::Running),
            (SessionStatus::Rebasing, OrchestrationTaskStatus::Running),
            (SessionStatus::Merging, OrchestrationTaskStatus::Running),
            (
                SessionStatus::Question,
                OrchestrationTaskStatus::WaitingForInput,
            ),
            (SessionStatus::Review, OrchestrationTaskStatus::Reviewing),
            (
                SessionStatus::AgentReview,
                OrchestrationTaskStatus::Reviewing,
            ),
            (SessionStatus::Merged, OrchestrationTaskStatus::Ready),
            (SessionStatus::Done, OrchestrationTaskStatus::Ready),
            (SessionStatus::Canceled, OrchestrationTaskStatus::Failed),
        ];

        // Act / Assert
        for (session_status, expected_task_status) in cases {
            assert_eq!(
                OrchestrationTaskStatus::from_child_status(session_status),
                expected_task_status
            );
        }
    }
}