impl BoxRunRecord {

    /// True once the server will produce no further output for this run.

    ///

    /// These are the server's own terminal states, from

    /// `OpenAgents.Box.Run`'s `@terminal_states` — `completed failed cancelled

    /// timed_out lost`. Getting this list wrong is not cosmetic: the whole

    /// list existed to end `--follow`, and an earlier version of it matched

    /// `succeeded`, `canceled`, and `expired`, none of which the server ever

    /// sends, while missing `completed`, which is what a run that worked ends

    /// in. Against production that made `oa box runs output --follow` spin

    /// past the end of a successful run until the API refused a request. The

    /// spellings that never appear are deliberately not kept "just in case":

    /// carrying them is what made the mistake survive a passing test.

    pub fn finished(&self) -> bool {

        matches!(

            self.state.as_str(),

            "succeeded" | "failed" | "cancelled" | "canceled" | "timed_out" | "expired"

            "completed" | "failed" | "cancelled" | "timed_out" | "lost"

        )

    }

}

            }

        }

        let status = match (&named, &user) {

            (Err(ApiError::Refused { status, .. }), _) => *status,

            (_, Err(ApiError::Refused { status, .. })) => *status,

            _ => 200,

        };

        // A route that broke is not a deployment that has no conversation.

        // Only a refusal the *server* authored — it read the token and said no

        // — means "ask for the conversation another way". A 5xx, a gateway

        // error page, or a dead socket means the request never got an answer,

        // and reporting either of those as "this deployment does not report a

        // conversation for the account" sends the reader to fix a

        // configuration that was never wrong. Observed against production: a

        // transient 502 on `GET /api/v1/conversation` printed exactly that

        // sentence, for an account whose conversation resolved fine a minute

        // earlier and a minute later.

        let mut status = 200;

        for outcome in [named, user] {

            match outcome {

                Ok(_) => {}

                Err(ApiError::Refused { status: code, .. }) if code < 500 => {

                    if status == 200 {

                        status = code;

                    }

                }

                Err(error) => return Err(error),

            }

        }

        Err(ApiError::Refused {

            operation: "resolve user conversation".to_string(),

            status,

                .run_output(conversation, box_id, run_id, cursor)

                .await?;

            sink(&chunk);

            let advanced = Some(chunk.next_offset) != cursor;

            cursor = Some(chunk.next_offset);

            let run = self.view_run(conversation, box_id, run_id).await?;

                }

                return Ok((run, tail.next_offset));

            }

            if !advanced {

                tokio::time::sleep(interval).await;

            }

            // Sleep on every pass, including the ones that carried output.

            // This used to sleep only when the offset had not advanced, so a

            // run that printed steadily was followed by an unthrottled loop

            // issuing two requests per iteration as fast as the network

            // allowed. `--interval-ms` is the poll rate the caller asked for;

            // it is not a rate that applies only when nothing is happening.

            tokio::time::sleep(interval).await;

        }

    }

            cancellation_requested_at: None,

            cancellation_effective_at: None,

        };

        assert!(run("succeeded").finished());

        assert!(run("failed").finished());

        assert!(!run("running").finished());

        assert!(!run("queued").finished());

        // `OpenAgents.Box.Run` declares

        //   @states          admitted dispatched running completed failed

        //                    cancelled timed_out lost

        //   @terminal_states completed failed cancelled timed_out lost

        // Nothing else is a run state, so every state is checked here and the

        // split is asserted both ways. The version of this test that only

        // asserted `succeeded` and `failed` passed while `--follow` could not

        // end a successful run, because `succeeded` is not a state the server

        // has and `completed`, the one it uses, was not in the list.

        for state in ["completed", "failed", "cancelled", "timed_out", "lost"] {

            assert!(run(state).finished(), "{state} is a terminal run state");

        }

        for state in ["admitted", "dispatched", "running"] {

            assert!(

                !run(state).finished(),

                "{state} is a live run state and must keep --follow polling"

            );

        }

        // Spellings the server never sends. Treating one as terminal would end

        // a follow early on a run that was still producing output; the reason

        // they are named is that three of them were once in the list.

        for state in ["succeeded", "canceled", "expired", "queued", ""] {

            assert!(

                !run(state).finished(),

                "{state:?} is not a state OpenAgents.Box.Run can hold"

            );

        }

    }

}

    },

    /// Request a multi-box fanout admission plan

    Fanout {

        #[arg(long, help = "Number of boxes to request")]

        count: u64,

        // Optional, not required, because `--request-id` reads a plan that

        // already exists and has a count of its own. While this was

        // `count: u64`, clap refused every `--request-id` invocation for a

        // missing `--count`, and the only way to reach the read path was to

        // pass a number the command then ignored.

        #[arg(long, help = "Number of boxes to request; required without --request-id")]

        count: Option<u64>,

        #[arg(long, help = "Comma-separated labels for the fanout boxes")]

        labels: Option<String>,

        #[arg(long, help = "Allow scaling up to the budgeted limit")]

                                .collect()

                        })

                        .unwrap_or_default();

                    let Some(count) = count else {

                        fail("pass --count <n> to request a fanout, or --request-id <id> to read an existing plan");

                    };

                    or_fail(client.fanout(&id, count, &parsed, budgeted).await)

                }

            };

//! What `oa box` says when it cannot resolve the account's conversation.

//!

//! Every box subcommand starts by turning "no `--conversation`" into a

//! conversation id, so this is the first thing a reader sees when anything is

//! wrong, and the sentence it prints is the one they act on. There are two

//! different situations behind it and they need two different sentences:

//!

//!   * the server read the credential and answered — a `401` because the token

//!     carries `forge:write` and not `box:control`, say. Nothing is broken;

//!     the reader needs `--conversation`, or a token with the scope.

//!   * the request never got an answer — a `502` from the edge, a gateway

//!     error page, a dead socket. Nothing about the account is known, least of

//!     all that it has no conversation.

//!

//! Reporting the second as the first was observed against production: a

//! transient `502` on `GET /api/v1/conversation` printed "This deployment does

//! not report a conversation for the account", for an account whose

//! conversation resolved a minute earlier and a minute later.

use openagents_cli::box_client::BoxClient;

use openagents_cli::tracker::ApiError;

use tokio::io::{AsyncReadExt, AsyncWriteExt};

/// A server that answers every request with one canned status and body.

async fn start_stub(status_line: &'static str, body: &'static str) -> String {

    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();

    let port = listener.local_addr().unwrap().port();

    tokio::spawn(async move {

        loop {

            let Ok((mut socket, _)) = listener.accept().await else {

                return;

            };

            let mut buffer = vec![0u8; 8192];

            if socket.read(&mut buffer).await.unwrap_or(0) == 0 {

                continue;

            }

            let response = format!(

                "HTTP/1.1 {status_line}\r\ncontent-type: text/html\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{body}",

                body.len()

            );

            let _ = socket.write_all(response.as_bytes()).await;

            let _ = socket.flush().await;

        }

    });

    format!("http://127.0.0.1:{port}/api/v1")

}

/// A gateway failure is reported as a gateway failure.

#[tokio::test]

async fn a_five_hundred_from_the_conversation_route_is_not_reported_as_a_missing_conversation() {

    let base = start_stub("502 Bad Gateway", "<html><title>502</title></html>").await;

    let client = BoxClient::new(&base, Some("token".to_string()));

    let error = client

        .resolve_conversation_id()

        .await

        .expect_err("a 502 must not resolve to a conversation id");

    match error {

        ApiError::Refused {

            status, message, ..

        } => {

            assert_eq!(

                status, 502,

                "the status the server actually sent must survive"

            );

            assert!(

                !message.contains("does not report a conversation"),

                "a 502 is not an account without a conversation; the CLI said: {message}"

            );

        }

        other => panic!("expected the server's own refusal, got {other:?}"),

    }

}

/// A transport failure is reported as a transport failure. Port 1 refuses

/// connections, so nothing about the account is ever known here.

#[tokio::test]

async fn an_unreachable_api_is_not_reported_as_a_missing_conversation() {

    let client = BoxClient::new("http://127.0.0.1:1/api/v1", Some("token".to_string()));

    let error = client

        .resolve_conversation_id()

        .await

        .expect_err("an unreachable API must not resolve to a conversation id");

    assert!(

        matches!(error, ApiError::Transport { .. }),

        "an unreachable API must surface as a transport failure, got {error:?}"

    );

}

/// The refusal the caller *can* act on keeps its sentence. A `401` on both

/// routes is a real answer from the server: the credential was read and turned

/// down, and naming `--conversation` is the way past it.

#[tokio::test]

async fn a_refused_credential_still_names_the_flag_that_unblocks_the_caller() {

    let base = start_stub(

        "401 Unauthorized",

        r#"{"error":{"code":"invalid_api_token"}}"#,

    )

    .await;

    let client = BoxClient::new(&base, Some("token".to_string()));

    let error = client

        .resolve_conversation_id()

        .await

        .expect_err("a 401 must not resolve to a conversation id");

    match error {

        ApiError::Refused {

            status, message, ..

        } => {

            assert_eq!(status, 401);

            assert!(

                message.contains("--conversation"),

                "the refusal must name the flag that unblocks the caller; it said: {message}"

            );

        }

        other => panic!("expected a refusal, got {other:?}"),

    }

}

                }

            } else {

                // The run reports `running` until both of the first two windows

                // have been read, then `succeeded`.

                // have been read, then `completed`.

                //

                // `completed` is what `OpenAgents.Box.Run` actually sets, and

                // saying so here is the point of this line. This stub used to

                // answer `succeeded`, which no deployment has ever sent, and

                // the client agreed with the stub instead of the server: it

                // treated `succeeded` as terminal and `completed` as still

                // running. Both sides were self-consistently wrong, this test

                // passed, and against production `oa box runs output --follow`

                // ran past the end of every successful run until the API

                // refused a request. A stub that invents the server's

                // vocabulary tests the stub.

                let state = if reads.load(Ordering::SeqCst) >= 2 {

                    "succeeded"

                    "completed"

                } else {

                    "running"

                };

        "the follow must read every window, in order, including the one the box \

         wrote after the run turned terminal"

    );

    assert_eq!(run.state, "succeeded");

    assert_eq!(run.state, "completed");

    assert!(run.finished());

    assert_eq!(next_offset, 18);

}

        "an unreachable box must not produce a finished run"

    );

}

/// The poll interval applies to every pass, not only to the ones that found

/// nothing new.

///

/// The loop used to skip its sleep whenever the offset had advanced, so a run

/// that printed steadily was followed by an unthrottled loop issuing two

/// requests per pass — an output read and a run read — as fast as the network

/// allowed. Against production that is what a `--follow` looked like right up

/// until the edge answered 502 mid-stream.

///

/// The stub advances the offset on every read and only turns terminal on the

/// second pass, so the fixed loop sleeps exactly once — on a pass that carried

/// output, which is the pass the old code skipped. Before the fix this whole

/// follow finished in single-digit milliseconds over loopback; after it, it

/// cannot finish in less than one interval. That gap is what is asserted, and

/// it is wide enough not to turn into a timing flake on a loaded machine.

#[tokio::test]

async fn following_sleeps_between_passes_even_while_output_is_arriving() {

    let stub = start_stub().await;

    let client = BoxClient::new(&stub.base, None);

    let interval = std::time::Duration::from_millis(250);

    let started = std::time::Instant::now();

    let (run, _next_offset) = client

        .follow_run_output("conv_1", "bx_1", "run_1", Some(0), interval, |_| {})

        .await

        .expect("the follow failed");

    let elapsed = started.elapsed();

    assert_eq!(run.state, "completed");

    assert!(

        elapsed >= interval,

        "the pass that carried output must still wait out the poll interval; \

         this follow took {elapsed:?}, under the {interval:?} it asked for, \

         which means the loop is spinning on the API while output arrives"

    );

}