name: String,

        #[arg(long, help = "Set the repository description")]

        description: Option<String>,

        #[arg(long, help = "Create a public repository (the default)")]

        #[arg(long, help = "Create a public repository")]

        public: bool,

        #[arg(long, help = "Create a private repository")]

        private: bool,

    #[arg(

        long,

        help = "Target harness lane (e.g. ox-alpha, gemini, devin, claude, codex)"

        help = "Target harness lane (e.g. ox-alpha, gemini, devin, claude, codex). Defaults to ox-alpha, which spends this account's grant"

    )]

    pub lane: Option<String>,

                )));

            }

            let is_private = visibility(public, private).unwrap_or(false);

            // Naming neither flag used to create a *public* repository, a

            // default disclosed only in `--public`'s own help text. Publishing

            // a repository is not undoable by the reader who did not know they

            // asked for it, so the omission is refused here — before the

            // create, like the two checks above — rather than resolved in the

            // direction that exposes it.

            let Some(is_private) = visibility(public, private) else {

                fail(

                    "say whether the repository is public or private: \

                     `oa repo create <name> --private` or `--public`",

                );

            };

            let (owner, repository_name) = if name.contains('/') {

                let (owner, repository_name) = or_fail(crate::repo::parse_repository_target(&name));

                (Some(owner), repository_name)

    Finished(Box<ChildWorkerResult>),

}

/// The lane a fan-out runs on when `--lane` names none.

///

/// It is not a neutral choice: `ox-alpha` is this process on the OpenAgents

/// proxy, so every child on it opens a thread and spends this account's grant.

/// The other lanes shell out to a harness the reader installed and pays for

/// themselves. That is why omitting `--lane` is reported at the point of

/// spending rather than left to be inferred from the header — see

/// [`run_delegation`].

pub const DEFAULT_CHILD_LANE: &str = "ox-alpha";

/// Which harness and model a child runs on.

#[derive(Debug, Clone, PartialEq, Eq)]

pub enum ChildLane {

        results.unwrap_or_default()

    }

    /// Where children will work, or why there is nowhere for them to.

    ///

    /// `--dir` names it. It has to exist before a worktree can be prepared

    /// under it, so a path that is not a directory is a refusal rather than a

    /// fan-out that silently ran somewhere else.

    fn workdir(&self) -> Result<PathBuf, String> {

        match &self.directory {

            Some(directory) => {

                if !directory.is_dir() {

                    return Err(format!(

                        "{} is not a directory, so there is nowhere for the children to work.",

                        directory.display()

                    ));

                }

                Ok(directory.clone())

            }

            None => Ok(std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."))),

        }

    }

    /// Work out where every child will go, without building anything yet.

    ///

    /// Separate from the dispatch so a caller can read

    /// [`WorkspacePlan::isolation`] — the isolation children will *actually*

    /// get — before it announces one. `oa delegate` printed the isolation it

    /// was asked for, which outside a git checkout was `worktree` over a run

    /// that gave each child a plain empty directory.

    ///

    /// Nothing is written to disk here; the plan only names a base directory.

    /// [`WorkspacePlan::prepare`] is what creates anything.

    pub async fn plan(&self) -> Result<WorkspacePlan, String> {

        Ok(WorkspacePlan::resolve(self.workdir()?, self.isolation).await)

    }

    /// Run the fan-out, reporting each child as it goes.

    ///

    /// Returns `Err` only when no child could be started at all — a workspace

        prompt: &str,

        events: mpsc::UnboundedSender<ChildEvent>,

        cancel: watch::Receiver<bool>,

    ) -> Result<Vec<ChildWorkerResult>, String> {

        let plan = self.plan().await?;

        self.dispatch_with_plan(plan, prompt, events, cancel).await

    }

    /// The same fan-out, over a plan the caller already resolved.

    ///

    /// A caller that reported the isolation runs the plan it reported, rather

    /// than resolving a second one that could answer differently.

    pub async fn dispatch_with_plan(

        &self,

        plan: WorkspacePlan,

        prompt: &str,

        events: mpsc::UnboundedSender<ChildEvent>,

        cancel: watch::Receiver<bool>,

    ) -> Result<Vec<ChildWorkerResult>, String> {

        let lane = ChildLane::parse(&self.lane);

        // `--dir` names where children work. It has to exist before a worktree

        // can be prepared under it, so a path that is not a directory is a

        // refusal rather than a fan-out that silently ran somewhere else.

        let cwd = match &self.directory {

            Some(directory) => {

                if !directory.is_dir() {

                    return Err(format!(

                        "{} is not a directory, so there is nowhere for the children to work.",

                        directory.display()

                    ));

                }

                directory.clone()

            }

            None => std::env::current_dir().unwrap_or_else(|_| PathBuf::from(".")),

        };

        let plan = WorkspacePlan::resolve(cwd, self.isolation).await;

        let workspaces = plan.prepare(self.count).await?;

        let gate = Arc::new(Semaphore::new(self.max_parallel.max(1)));

            "{requested} children were asked for and this command runs at most {MAX_DELEGATE_COUNT}."

        ));

    }

    let lane_name = args.lane.clone().unwrap_or_else(|| "ox-alpha".to_string());

    let prompt = args

    // Refused before anything is prepared, spawned, or billed. A missing

    // prompt used to become the literal `Analyze workspace and run tests`,

    // which every child then ran: N `git worktree add`s on disk and, on the

    // default lane, N threads and N grants spent on an instruction nobody

    // gave. `describe()` even named the run "delegated task", so the header

    // read plausibly while it happened.

    //

    // The same operation exposed as a model tool already refuses this:

    // `tools.rs` answers `No children were started: \`prompt\` is required and

    // must say what the child does.`, and trims before it decides. A CLI more

    // permissive than the model-facing surface is backwards, so both now

    // answer the omission the same way — whitespace included, which is the

    // same omission with a space in it.

    let Some(prompt) = args

        .prompt

        .clone()

        .unwrap_or_else(|| "Analyze workspace and run tests".to_string());

        .as_deref()

        .map(str::trim)

        .filter(|given| !given.is_empty())

        .map(str::to_string)

    else {

        fail(

            "a delegation runs one prompt in every child, and there is nothing to run \

             without one. Give it one: `oa delegate \"<prompt>\"`, or \

             `oa coder --delegate \"<prompt>\"`",

        );

    };

    // The lane decides who pays. Naming none is not refused — `oa coder`

    // defaults its lane too, and a fan-out with no lane is a reasonable

    // thing to ask for — but it is said out loud, here, before a child

    // exists. The header below names the lane either way and so cannot

    // distinguish a lane that was chosen from one that was assumed.

    let lane_name = match args.lane.clone() {

        Some(named) => named,

        None => {

            say(format!(

                "No --lane given, so children run on {DEFAULT_CHILD_LANE}, which opens a \

                 thread per child and spends this account's grant. Name another with --lane."

            ));

            DEFAULT_CHILD_LANE.to_string()

        }

    };

    if !ChildLane::known(&lane_name) {

        fail(&format!(

    }

    let lane = ChildLane::parse(&lane_name);

    let isolation = match args.isolation.as_deref() {

    let asked_isolation = match args.isolation.as_deref() {

        None => Isolation::Worktree,

        Some(named) => match Isolation::parse(named) {

            Some(isolation) => isolation,

    let description = describe(args.description.as_deref(), &prompt);

    let supervisor = DelegationSupervisor::new(requested, &lane_name, user_token)

        .with_isolation(isolation)

        .with_isolation(asked_isolation)

        .with_max_parallel(args.max_parallel.unwrap_or(requested))

        .keeping_workspaces(args.keep_workspaces)

        .in_directory(args.directory.as_deref().map(PathBuf::from))

        .with_child_options(child);

    // Resolved before the header, and the header reports the resolution.

    // `worktree` outside a git checkout is a plain empty directory per child;

    // this used to print the value that was asked for, so a run announced an

    // isolation it did not have and nothing later said otherwise. The plan is

    // then handed to the dispatch, so what was reported is what runs.

    let plan = match supervisor.plan().await {

        Ok(plan) => plan,

        Err(error) => fail(&format!("no children were started: {error}")),

    };

    let isolation = plan.isolation();

    if isolation != asked_isolation {

        say(format!(

            "`{}` isolation is not available here — this is not a git checkout — so children get \

             `{}` instead.",

            asked_isolation.name(),

            isolation.name(),

        ));

    }

    say(format!(

        "Delegating {}: {} {} on {}, {} at a time, isolation: {}.",

        description,

        }

    });

    let results = match supervisor.dispatch_streaming(&prompt, events, cancel).await {

    let results = match supervisor

        .dispatch_with_plan(plan, &prompt, events, cancel)

        .await

    {

        Ok(results) => results,

        // No child ran at all, so there is nothing to report but the reason.

        Err(error) => fail(&format!("no children were started: {error}")),

    }

}

// ------------------------------------------------- `oa delegate` with no prompt

/// A directory of this test's own, empty, and not a git checkout.

fn scratch(name: &str) -> PathBuf {

    let at = std::env::temp_dir().join(format!(

        "oa-flags-{name}-{}-{}",

        std::process::id(),

        SystemTime::now()

            .duration_since(UNIX_EPOCH)

            .map(|d| d.as_nanos())

            .unwrap_or(0)

    ));

    std::fs::create_dir_all(&at).expect("make a scratch directory");

    at

}

/// Every entry a fan-out left in the temporary directory it was pointed at.

///

/// `WorkspacePlan` lays its children out under `std::env::temp_dir()` as

/// `oa-delegate-<pid>-…`, and `TMPDIR` is what decides where that is. Pointing

/// it at a directory this test owns turns "was a workspace built on disk" into

/// something readable.

fn delegate_workspaces(tmp: &Path) -> Vec<String> {

    let Ok(entries) = std::fs::read_dir(tmp) else {

        return Vec::new();

    };

    let mut found: Vec<String> = entries

        .filter_map(Result::ok)

        .map(|entry| entry.file_name().to_string_lossy().into_owned())

        .filter(|name| name.starts_with("oa-delegate-"))

        .collect();

    found.sort();

    found

}

/// `oa delegate` with no prompt starts no child: no worktree, no thread.

///

/// It used to substitute the literal `Analyze workspace and run tests` and run

/// it in every child — a real `git worktree add` each, and on the default lane

/// a thread and a grant each, spent on an instruction nobody gave. The exit

/// code alone does not catch that; a fan-out that spawns and then fails exits

/// non-zero too. What catches it is the disk and the server, so both are

/// asserted before the status is.

///

/// The same omission is refused through `oa coder --delegate`, which is the

/// other door onto the same engine.

#[test]

fn delegate_without_a_prompt_starts_no_child_and_opens_no_thread() {

    let server = RouteServer::start(coder_routes);

    let origin = server.origin();

    let api_base = format!("{origin}/api/v1");

    let tmp = scratch("delegate-refused");

    let tmp_path = tmp.to_string_lossy().into_owned();

    for bare in [

        vec!["--api-url", origin.as_str(), "delegate"],

        // Whitespace is the same omission with a space in it. Untrimmed, this

        // shipped `   ` to every child.

        vec!["--api-url", origin.as_str(), "delegate", "   "],

        // Two children, so a version that spawns first would leave two

        // workspaces and open two threads rather than one of each.

        vec!["--api-url", origin.as_str(), "delegate", "--agents", "2"],

        vec!["--api-url", origin.as_str(), "coder", "--delegate"],

    ] {

        let run = oa_env(

            &bare,

            &[

                ("OPENAGENTS_TOKEN", "t"),

                ("OPENAGENTS_API_BASE", api_base.as_str()),

                ("TMPDIR", tmp_path.as_str()),

                ("HOME", &isolated_home().to_string_lossy()),

            ],

        );

        assert_eq!(

            delegate_workspaces(&tmp),

            Vec::<String>::new(),

            "{bare:?} built a workspace for a prompt nobody gave"

        );

        let paths: Vec<String> = server.hits().into_iter().map(|hit| hit.path).collect();

        assert!(

            !paths.iter().any(|p| p == "/api/v1/threads"),

            "{bare:?} still opened a thread: {paths:?}"

        );

        assert!(

            !run.stdout.contains("Analyze workspace"),

            "a prompt nobody gave was run anyway: {}",

            run.stdout

        );

        assert_eq!(run.status, Some(2), "{bare:?} stdout: {}", run.stdout);

        assert!(

            run.stderr.contains("<prompt>"),

            "the refusal did not show the form that works: {}",

            run.stderr

        );

    }

    // The control, on the same fixture and the same temporary directory: with

    // a prompt, a child does start. Without this the assertions above would

    // also pass against a binary that could reach neither the server nor the

    // disk.

    let given = oa_env(

        &["--api-url", &origin, "delegate", "hello"],

        &[

            ("OPENAGENTS_TOKEN", "t"),

            ("OPENAGENTS_API_BASE", api_base.as_str()),

            ("TMPDIR", tmp_path.as_str()),

            ("HOME", &isolated_home().to_string_lossy()),

        ],

    );

    assert_eq!(given.status, Some(0), "stderr: {}", given.stderr);

    let paths: Vec<String> = server.hits().into_iter().map(|hit| hit.path).collect();

    assert!(

        paths.iter().any(|p| p == "/api/v1/threads"),

        "the fixture never opens a thread, so the test proves nothing: {paths:?}"

    );

    let _ = std::fs::remove_dir_all(&tmp);

}

// ------------------------------------------- the isolation a fan-out reports

/// The isolation in the header is the one the children got.

///

/// `worktree` outside a git checkout is silently a plain empty directory —

/// [`WorkspacePlan::resolve`]'s only substitution — and the header printed the

/// value that was *asked* for, so the run announced isolation it did not have.

/// Each case below reads two things the binary printed: the header, and the

/// `[child 1] started … in …` line, which names the workspace kind the child

/// was actually handed. A run whose header disagrees with its own child line

/// is the defect.

#[test]

fn the_reported_isolation_is_the_one_the_children_get() {

    let server = RouteServer::start(coder_routes);

    let origin = server.origin();

    let api_base = format!("{origin}/api/v1");

    let tmp = scratch("delegate-isolation");

    let tmp_path = tmp.to_string_lossy().into_owned();

    // Not a git checkout, so `worktree` is not available here.

    let plain = scratch("delegate-plain");

    // A checkout of its own, so it is. Made here rather than borrowed from the

    // repository this test runs in: registering a worktree in that one would

    // leave the developer's `git worktree list` holding this test's children.

    let repo = scratch("delegate-repo");

    for argv in [

        vec!["init", "--quiet", "-b", "main"],

        vec!["config", "user.email", "test@example.test"],

        vec!["config", "user.name", "Test"],

        vec!["commit", "--quiet", "--allow-empty", "-m", "root"],

    ] {

        let done = Command::new("git")

            .args(&argv)

            .current_dir(&repo)

            .output()

            .expect("run git");

        assert!(done.status.success(), "git {argv:?}: {done:?}");

    }

    for (directory, expected, workspace_line) in [

        (&plain, "directory", "in directory "),

        (&repo, "worktree", "in git worktree "),

    ] {

        let run = oa_env(

            &[

                "--api-url",

                &origin,

                "delegate",

                "hello",

                "--dir",

                &directory.to_string_lossy(),

            ],

            &[

                ("OPENAGENTS_TOKEN", "t"),

                ("OPENAGENTS_API_BASE", api_base.as_str()),

                ("TMPDIR", tmp_path.as_str()),

                ("HOME", &isolated_home().to_string_lossy()),

            ],

        );

        assert_eq!(run.status, Some(0), "stderr: {}", run.stderr);

        // What the child was handed, read from the child's own line.

        assert!(

            run.stdout.contains(workspace_line),

            "no child reported a `{workspace_line}` workspace in {}: {}",

            directory.display(),

            run.stdout

        );

        // And what the header claimed, which has to be the same word.

        assert!(

            run.stdout.contains(&format!("isolation: {expected}.")),

            "the header did not report `{expected}` in {}: {}",

            directory.display(),

            run.stdout

        );

        for other in ["directory", "worktree", "none"] {

            if other != expected {

                assert!(

                    !run.stdout.contains(&format!("isolation: {other}.")),

                    "the header reported `{other}` as well as `{expected}`: {}",

                    run.stdout

                );

            }

        }

    }

    // The substitution is not merely reported in the header; it is said out

    // loud, because `--isolation worktree` was asked for by default and was

    // not what happened.

    let run = oa_env(

        &[

            "--api-url",

            &origin,

            "delegate",

            "hello",

            "--dir",

            &plain.to_string_lossy(),

        ],

        &[

            ("OPENAGENTS_TOKEN", "t"),

            ("OPENAGENTS_API_BASE", api_base.as_str()),

            ("TMPDIR", tmp_path.as_str()),

            ("HOME", &isolated_home().to_string_lossy()),

        ],

    );

    assert!(

        run.stdout.contains("not a git checkout"),

        "the run substituted an isolation without saying so: {}",

        run.stdout

    );

    for at in [&tmp, &plain, &repo] {

        let _ = std::fs::remove_dir_all(at);

    }

}

// -------------------------------------------- the lane a fan-out bills

/// A fan-out that was given no `--lane` says which one it chose, and why that

/// matters, before a child exists.

///

/// `ox-alpha` is the one lane that opens a thread per child and spends this

/// account's grant; the others shell out to a harness the reader installed.

/// The header names the lane either way, so it cannot distinguish a lane that

/// was chosen from one that was assumed — this line is what does.

#[test]

fn a_fan_out_with_no_lane_says_which_lane_it_picked() {

    let server = RouteServer::start(coder_routes);

    let origin = server.origin();

    let api_base = format!("{origin}/api/v1");

    let tmp = scratch("delegate-lane");

    let tmp_path = tmp.to_string_lossy().into_owned();

    let plain = scratch("delegate-lane-dir");

    let run = |lane: Option<&str>| {

        let directory = plain.to_string_lossy().into_owned();

        let mut argv = vec![

            "--api-url",

            origin.as_str(),

            "delegate",

            "hello",

            "--dir",

            directory.as_str(),

        ];

        if let Some(lane) = lane {

            argv.extend_from_slice(&["--lane", lane]);

        }

        oa_env(

            &argv,

            &[

                ("OPENAGENTS_TOKEN", "t"),

                ("OPENAGENTS_API_BASE", api_base.as_str()),

                ("TMPDIR", tmp_path.as_str()),

                ("HOME", &isolated_home().to_string_lossy()),

            ],

        )

    };

    let assumed = run(None);

    assert_eq!(assumed.status, Some(0), "stderr: {}", assumed.stderr);

    assert!(

        assumed.stdout.contains("No --lane given")

            && assumed.stdout.contains("spends this account's grant"),

        "the run chose the billing lane without saying so: {}",

        assumed.stdout

    );

    // Named explicitly, it is not a substitution and there is nothing to

    // report — otherwise this line would be noise on every run.

    let named = run(Some("ox-alpha"));

    assert_eq!(named.status, Some(0), "stderr: {}", named.stderr);

    assert!(

        !named.stdout.contains("No --lane given"),

        "a lane the caller named was reported as a default: {}",

        named.stdout

    );

    for at in [&tmp, &plain] {

        let _ = std::fs::remove_dir_all(at);

    }

}

// ----------------------------------------------------------------- `--model`

/// `--model` decides the id sent at thread open; without it the default lane's

        let server = StubServer::start(vec![(201, ready_repository(&full_name))]);

        let origin = server.origin();

        let run = oa(&origin, &["repo", "create", &full_name]);

        let run = oa(&origin, &["repo", "create", &full_name, "--private"]);

        assert_eq!(run.status, Some(0), "stderr: {}", run.stderr);

        let hits = server.hits();

    let server = StubServer::start(vec![(201, ready_repository("octavia/thing"))]);

    let origin = server.origin();

    let run = oa(&origin, &["repo", "create", "thing"]);

    let run = oa(&origin, &["repo", "create", "thing", "--private"]);

    assert_eq!(run.status, Some(0), "stderr: {}", run.stderr);

    let hits = server.hits();

    assert_eq!(hits[0].route(), "POST /api/v1/repos");

    assert_eq!(hits[0].json().get("owner"), None);

}

/// `repo create` will not choose the visibility for you, and what it sends is

/// what you named.

///

/// Naming neither flag used to send `"private": false` — a public repository,

/// on a default disclosed only in `--public`'s help. The exit code alone does

/// not catch that: it is the absence of a request that says nothing was

/// created, and the body of the requests that do go out that says the flags

/// are read rather than merely accepted.

#[test]

fn create_refuses_to_pick_a_visibility_and_sends_the_one_it_was_given() {

    let server = StubServer::start(vec![(201, ready_repository("octavia/thing"))]);

    let origin = server.origin();

    let silent = oa(&origin, &["repo", "create", "thing"]);

    // Asserted first, and about the server rather than the exit code: a

    // create that posts and then fails afterwards exits non-zero too, and the

    // repository is on the server either way.

    let asked_for: Vec<String> = server.hits().iter().map(Hit::route).collect();

    assert_eq!(

        asked_for,

        Vec::<String>::new(),

        "a repository was created without anyone saying whether it is public"

    );

    assert_eq!(silent.status, Some(2), "stdout: {}", silent.stdout);

    assert!(

        silent.stderr.contains("--private") && silent.stderr.contains("--public"),

        "the refusal did not name the two flags that answer it: {}",

        silent.stderr

    );

    // Both flags reach the wire, and they disagree with each other — which is

    // what a test that only asserted "some `private` field was sent" would

    // miss.

    for (flag, expected) in [("--private", true), ("--public", false)] {

        let server = StubServer::start(vec![(201, ready_repository("octavia/thing"))]);

        let origin = server.origin();

        let run = oa(&origin, &["repo", "create", "thing", flag]);

        assert_eq!(run.status, Some(0), "{flag} stderr: {}", run.stderr);

        let hits = server.hits();

        assert_eq!(hits.len(), 1, "{flag}: unexpected requests: {hits:?}");

        assert_eq!(

            hits[0].json()["private"],

            serde_json::json!(expected),

            "{flag} sent the wrong visibility"

        );

    }

}