monochromatic-git-policy-cli 0.5.33

//! What:
//!  Run the auto-push's real `git push` (and its fetch and Git LFS upload) until it ends, or stops showing any sign of work
//!  with no connection to a remote open.
//! Why:
//!  A push that shows nothing and holds no connection would otherwise hold the service's push of that branch forever,
//!  and every later push of the repository would wait behind it.
//!  Such a push is stopped when its stall window passes,
//!  the commit stays saved locally,
//!  and the failure is reported like any other failed push.
//!  A push whose connection to the remote is open is never stopped for time (owner, 2026-11-03: "Wait while connected
//!  (Recommended)"; pick 5 of `doc/planning/cli-git-shipped-limits-audit.md`, the coordinator's under the owner's delegation and
//!  open to the owner's veto): it has no ceiling, and the wrapper sets no low-speed abort for it.
//!
//! In TS you'd write (pseudocode):
//! ```ts
//! const { exitCode, output } = await nanoSpawn(gitPath, pushArgs, { cwd, signal: AbortSignal.timeout(deadlineMs) });
//! ```

/// The attempt record a finished or stopped push produces.
use crate::auto_push_single_flight::{PushAttempt, SingleFlightError};
/// The diagnostic log of the wrapper.
use crate::diagnostic_log::{debug, warn};
/// How to allow a push longer, in the words of the program that runs it.
use crate::push_deadline_advice::extend_clause;
/// The clock that stops a push on a stall, and the wait it lets pass instead.
use crate::push_progress::{Clock, WaitReport};
/// The helpers and hooks a stopped push leaves running.
use crate::process_tree::{TreeMember, descendants_of, kill_members, member_of, still_running, terminate_members};
/// The lock files a stopped push leaves, and the ledger that finds them.
use crate::stopped_git_locks::LockLedger;
/// Starts that ride out a short shortage of processes.
/// The anonymous output file of the push, made in the per-user scratch directory.
use crate::scratch_location::scratch_file;
use crate::start_retry::RetryStart;
/// Owned OS strings of the child environment.
use std::ffi::{OsStr, OsString};
/// `File` is the shared anonymous output file; `Read`, `Seek` and `SeekFrom` read it back from its start.
use std::fs::File;
use std::io::{Read, Seek, SeekFrom};
/// `Child` is the running push; `Command` describes it; `Stdio` connects its streams.
use std::process::{Child, Command, ExitStatus, Stdio};
/// Time spans and the monotonic clock.
use std::time::{Duration, Instant};

/// Tag used for diagnostics from this module.
const TAG: &str = "cli-git";

/// What a person is told when a push is ended for showing no progress: the owner's answer of 2026-11-03, "Bound it, keep retrying
///  (Recommended)", is that the service's retry plan keeps the push and tries it again, and the line says so.
pub const PUSH_QUEUED_LINE: &str = "The push is queued: the commit service keeps it in its retry plan and tries it again.";

/// Environment variable that sets the push deadline in whole seconds.
pub const PUSH_DEADLINE_VARIABLE: &str = "CLI_GIT_PUSH_DEADLINE_SECONDS";

/// How long a push with no connection to a remote open may go without any sign of work (the stall window) when the variable is
///  absent or unusable. Where no progress can be measured, it is how long the push may run in all.
///  Citation: no measurement or owner decision determines 30 seconds. The owner decided the rule, "Stop only on no progress
///  (Recommended)", and not the number. The journal of the commit service (read-only, 794 pushes that landed since 2026-10-20) holds
///  whole-push times, p50 3.5 s, p99 26.4 s, maximum 72.4 s, which include connected time and so are not a measure of silence
///  without a connection; no silence of a disconnected push is logged anywhere. The number is an open question for the owner
///  (`doc/planning/cli-git-shipped-limits-audit.md`, "Push stall window, 30 seconds").
pub const DEFAULT_PUSH_DEADLINE: Duration = Duration::from_secs(30);

/// How long a stopped push gets to end after the polite stop signal before it is killed.
///  Citation: partial. The helpers of a stopped push were measured on 2026-11-03 to outlive it for 60 seconds, and a `git-lfs` that
///  never answers for good, and empty tracking-ref locks appeared about 37 seconds after a stop; those justify the kill that
///  follows the grace and the sweep, not five seconds, and no measurement of how long Git takes to remove its own locks on a
///  polite stop exists. An open question for the owner.
pub const STOP_GRACE: Duration = Duration::from_secs(5);

/// The most output bytes kept from one push;
///  a push that writes more is stopped.
///  Citation: none yet. The owner decided "Keep all lines" for push output, which this cap limits, and no measurement of the
///  size of a push's output is logged; the audit lists it as a memory bound to be measured.
pub const MAX_PUSH_OUTPUT: u64 = 4 * 1024 * 1024;

/// Exit code recorded for a push that this wrapper stopped,
///  the convention of `timeout(1)`.
pub const STOPPED_EXIT_CODE: i64 = 124;

/// What the line a push's output gains has after the name of the program, when it waited with its connection open.
pub const WAIT_NOTE_PHRASE: &str = "is waiting for the server";

/// Pause between two looks at the running push.
const POLL_PAUSE: Duration = Duration::from_millis(10);

/// What:
///  Read a positive whole number of seconds from one environment value.
/// Why:
///   A zero, negative, fractional, empty or non-text value is no setting at all,
///  never "no limit",
///  so a typo cannot remove a bound.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// const seconds = Number(value); return Number.isInteger(seconds) && seconds > 0 ? seconds * 1000 : undefined;
/// ```
pub fn positive_seconds(name: &str, value: &OsStr) -> Option<Duration> {
    let parsed: Option<u64> = match value.to_str() {
        Some(text) => text.trim().parse::<u64>().ok(),
        None => None,
    };
    return match parsed {
        Some(count) if count > 0 => Some(Duration::from_secs(count)),
        Some(_) | None => {
            debug(
                TAG,
                &format!("{name} is not a positive whole number; ignoring it"),
            );
            None
        }
    };
}

/// What:
///  Read a positive whole number of seconds from the child environment.
/// Why:
///   The last of repeated entries wins,
///  as in an environment block.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// positiveSeconds(env[name])
/// ```
fn seconds_variable(environment: &[(OsString, OsString)], name: &str) -> Option<Duration> {
    let mut found: Option<&OsString> = None;
    for (key, value) in environment {
        if key.to_str() == Some(name) {
            found = Some(value);
        }
    }
    let value: &OsString = found?;
    return positive_seconds(name, value.as_os_str());
}

/// What:
///  The push deadline: the environment's value, or the default.
/// Why:
///   A person may need a longer deadline on a slow link or a shorter one on a flaky one.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// const deadlineMs = secondsOf(env.CLI_GIT_PUSH_DEADLINE_SECONDS) ?? DEFAULT_MS;
/// ```
pub fn push_deadline(environment: &[(OsString, OsString)]) -> Duration {
    return seconds_variable(environment, PUSH_DEADLINE_VARIABLE).unwrap_or(DEFAULT_PUSH_DEADLINE);
}

/// What:
///  How long a bounded child may take: a fixed time, or a time without any sign of work and without an open connection.
/// Why:
///   A slow push that keeps moving data is working and should finish, and one whose connection to a remote is open is waiting
///  for the remote and should wait too; one that shows nothing and holds no connection is stuck and should stop fast. A query has
///  no transfer to measure and keeps a fixed bound.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// type Patience = { kind: 'fixed'; ms: number } | { kind: 'progress'; stallMs: number };
/// ```
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum Patience {
    /// Stop after this long, whatever the child does.
    Fixed(Duration),
    /// Stop after `stall` without data moved, processor time used, or a task at work, by the child and everything it started,
    ///  unless a process of them holds an open connection to a remote: that is waited for, however long it takes.
    Progress {
        /// How long the child may show nothing while no connection is open.
        stall: Duration,
    },
}

/// The patience of a push from the environment: the stall window.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// ({ kind: 'progress', stallMs: pushDeadline(env) })
/// ```
pub fn push_patience(environment: &[(OsString, OsString)]) -> Patience {
    return Patience::Progress { stall: push_deadline(environment) };
}

/// Remove exactly one trailing `\n` or `\r\n`, as the captured output of the incumbent does.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// output.endsWith('\n') ? output.slice(0, output.endsWith('\r\n') ? -2 : -1) : output
/// ```
pub fn strip_one_line_break(text: &str) -> &str {
    let without_lf = match text.strip_suffix('\n') {
        Some(stripped) => stripped,
        None => return text,
    };
    return without_lf.strip_suffix('\r').unwrap_or(without_lf);
}

/// Ask a running push to end,
///  so Git can stop the helper processes it started.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// child.kill('SIGTERM');
/// ```
#[cfg(unix)]
fn ask_to_stop(child: &Child) {
    let Ok(pid) = libc::pid_t::try_from(child.id()) else {
        return;
    };
    // SAFETY: `kill` sends one signal to the PID of a child this module started and has not reaped;
    // a failure is ignored because the child may have ended.
    unsafe { libc::kill(pid, libc::SIGTERM) };
}

/// Platforms without a polite stop signal go straight to the kill.
// UNTESTED ON WINDOWS: no gate compiles or runs this branch (the crate does not build for Windows; README, Requirements).
#[cfg(not(unix))]
fn ask_to_stop(_child: &Child) {}

/// Whether part of the grace is still left after the stop request.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// asked < grace
/// ```
fn grace_remains(asked: Duration, grace: Duration) -> bool {
    return asked < grace;
}

/// Whether an output of this size is a flood: only a size past the cap is.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// size > MAX_PUSH_OUTPUT
/// ```
fn is_flood(size: u64) -> bool {
    return size > MAX_PUSH_OUTPUT;
}

/// Wait, bounded by `grace`, until every member of a stopped tree has ended.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// await Promise.race([allEnded(tree), delay(graceMs)]);
/// ```
fn wait_for_tree(tree: &[TreeMember], grace: Duration) {
    let waited: Instant = Instant::now();
    while grace_remains(waited.elapsed(), grace) && tree.iter().any(still_running) {
        std::thread::sleep(POLL_PAUSE);
    }
}

/// What:
///  Collect a killed child that the kernel has not released, and sweep the locks it leaves, on a thread of its own.
/// Why:
///   A killed process in an uninterruptible call (a stalled disk or file system) ends only when the kernel lets it go,
///  and on its way out it can create a lock file that nothing will remove (measured on 2026-11-03: empty tracking-ref
///  locks born about 37 seconds after the stop). The push is reported at its deadline and does not wait for that, so
///  the child is collected here, and its locks are swept when it is gone. The thread holds no lock and ends with the child.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// void child.exited.then(() => locks.sweep(tree));
/// ```
pub fn sweep_after_exit(mut child: Child, tree: Vec<TreeMember>, locks: LockLedger) -> Option<std::thread::JoinHandle<()>> {
    return std::thread::Builder::new()
        .name(String::from("cli-git-lock-sweep"))
        .spawn(move || {
            // The exit status is not reported: the push was reported at its deadline.
            let _status = child.wait();
            // Nothing waits for this thread, so it waits for the rest of the tree as long as that runs.
            while tree.iter().any(still_running) {
                std::thread::sleep(POLL_PAUSE);
            }
            locks.sweep(tree.as_slice());
        })
        .inspect_err(|error| {
            debug(TAG, &format!("could not start the thread that sweeps a stopped push's locks: {error}"));
        })
        .ok();
}

/// What:
///  Stop a running push: ask politely,
///  wait the grace,
///  then kill and collect it,
///  and judge the reference locks it may have left.
/// Why:
///   Git's own signal handling ends the helpers it started and removes its lock files,
///  and a push that ignores the request cannot outlive the kill.
///  A killed push leaves its lock files, which fail every later Git command on the same refs, so once the push and
///  what it started are gone the locks they hold are swept.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// child.kill('SIGTERM'); await Promise.race([exited, delay(graceMs)]) || child.kill('SIGKILL'); locks.sweep(tree.as_slice());
/// ```
pub fn stop_push(mut child: Child, grace: Duration, locks: LockLedger) {
    // Read before the push is signalled: once it has exited, its helpers and hooks no longer point to it.
    let below: Vec<TreeMember> = i32::try_from(child.id()).map(descendants_of).unwrap_or_default();
    let mut tree: Vec<TreeMember> = i32::try_from(child.id()).ok().and_then(member_of).into_iter().collect();
    tree.extend(below.iter().cloned());
    ask_to_stop(&child);
    terminate_members(below.as_slice());
    let asked: Instant = Instant::now();
    let mut ended: bool = false;
    while !ended && grace_remains(asked.elapsed(), grace) {
        match child.try_wait() {
            Ok(Some(_)) | Err(_) => ended = true,
            Ok(None) => std::thread::sleep(POLL_PAUSE),
        }
    }
    let mut collected: bool = ended;
    if !ended {
        // The child is being abandoned; its exit is not reported, only the cause.
        let _killed = child.kill();
        // A killed process that sits in uninterruptible I/O (a stalled disk or network file system) cannot be
        //  collected until the kernel releases it, so the wait is bounded by the grace again and the child is then
        //  left to be collected on a thread of its own, instead of holding the service's push for as long as the stall.
        let killed_at: Instant = Instant::now();
        while grace_remains(killed_at.elapsed(), grace) {
            match child.try_wait() {
                Ok(Some(_)) | Err(_) => {
                    collected = true;
                    break;
                }
                Ok(None) => std::thread::sleep(POLL_PAUSE),
            }
        }
    }
    // What the push started outlives it: its transport helper holds the connection and its hook may never exit
    // (measured: 60 seconds for a helper, for good for a `git-lfs` that never answers). They were asked to end with
    // the push, so they get what is left of the grace and are then killed.
    while grace_remains(asked.elapsed(), grace) && below.iter().any(still_running) {
        std::thread::sleep(POLL_PAUSE);
    }
    kill_members(below.as_slice());
    let _sweeper = settle_locks(child, collected, tree, locks, grace);
}

/// What:
///  Remove the locks of a stopped tree now when it has ended, or on a thread of its own when it has not.
/// Why:
///   A killed process ends only when the kernel has run it once more, which a loaded or stalled host may not do within the
///  grace; a sweep before that finds the tree running and removes nothing, and nothing would try again. The thread waits for
///  the whole tree and then sweeps. Returns the thread, if one was started.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// if (collected && allEnded(tree)) { locks.sweep(tree.as_slice()); return undefined; } return sweepAfterExit(child, tree, locks);
/// ```
pub fn settle_locks(child: Child, collected: bool, tree: Vec<TreeMember>, locks: LockLedger, grace: Duration) -> Option<std::thread::JoinHandle<()>> {
    if collected {
        wait_for_tree(tree.as_slice(), grace);
        if tree.iter().all(|member| { return !still_running(member); }) {
            locks.sweep(tree.as_slice());
            return None;
        }
    }
    return sweep_after_exit(child, tree, locks);
}

/// Read the shared output file back from its start,
///  keeping at most the output cap so a flood is never held in memory.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// await readFile(outputPath, 'utf8')
/// ```
fn read_output(file: &mut File) -> Result<String, SingleFlightError> {
    file.seek(SeekFrom::Start(0))
        .map_err(SingleFlightError::Start)?;
    let mut bytes: Vec<u8> = Vec::new();
    file.take(MAX_PUSH_OUTPUT)
        .read_to_end(&mut bytes)
        .map_err(SingleFlightError::Start)?;
    return Ok(String::from_utf8_lossy(&bytes).into_owned());
}

/// What a stop reports: the limit that was hit, what the push had moved and how long it had run.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct StopReport {
    /// The limit that was hit: the stall window.
    pub limit: Duration,
    /// The bytes the push and everything it started had read and written.
    pub moved: u64,
    /// How long the push had run.
    pub elapsed: Duration,
}

/// Why a push or query was stopped.
pub enum StopCause {
    /// The fixed deadline passed.
    Deadline,
    /// The push moved no data for the stall window.
    Stalled(StopReport),
    /// The output grew past the cap.
    Flood,
}

/// What:
///  Look at a running read-only query until it ends, stalls or floods its output, and say how quiet it got.
/// Why:
///   `std` has no timed wait,
///  so the parent looks with `try_wait`,
///  which never blocks; the clock reads the signs of work a few times a second. A query that works is waited for however
///  long it takes: it has no wall-clock bound (owner, 2026-11-03: "Stop only on no progress"; the coordinator's scope addition
///  to picks 4 and 9 of `doc/planning/cli-git-shipped-limits-audit.md`, open to the owner's veto), and on a system that counts
///  nothing it is never judged stalled. `quiet` receives the longest quiet gap seen, for the ledger, and nothing where the system counts nothing.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// await Promise.race([exited, stalled, flood]); // never by elapsed time
/// ```
pub fn wait_until_done(
    child: &mut Child,
    outputs: &[&File],
    patience: Patience,
    quiet: &mut Option<Duration>,
) -> Result<Result<ExitStatus, StopCause>, SingleFlightError> {
    let mut waits: Vec<WaitReport> = Vec::new();
    let clock: Clock = Clock::start(child.id(), patience).without_wall_fallback();
    return wait_with_clock(child, outputs, clock, "git", &mut waits, quiet);
}

/// What:
///  The same wait as `wait_until_done` for a push, handing over the wait of a push that is waiting for its remote with the
///  connection open.
/// Why:
///   The push is not stopped while it waits; the caller says so once, in a line, and the wait ends the way any other does.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// await Promise.race([exited, stalled, flood]); // waits.push(report) when the push begins to wait for the server
/// ```
pub fn wait_until_done_noting(
    child: &mut Child,
    outputs: &[&File],
    patience: Patience,
    label: &str,
    waits: &mut Vec<WaitReport>,
) -> Result<Result<ExitStatus, StopCause>, SingleFlightError> {
    let clock: Clock = Clock::start(child.id(), patience);
    let mut unused: Option<Duration> = None;
    return wait_with_clock(child, outputs, clock, label, waits, &mut unused);
}

/// The loop of both waits, over a clock the caller made.
fn wait_with_clock(
    child: &mut Child,
    outputs: &[&File],
    mut clock: Clock,
    label: &str,
    waits: &mut Vec<WaitReport>,
    quiet: &mut Option<Duration>,
) -> Result<Result<ExitStatus, StopCause>, SingleFlightError> {
    // Nothing is kept where the clock reads nothing: its figure would be the elapsed time, not a quiet gap.
    let kept = |watched: &Clock| -> Option<Duration> { return watched.measures().then(|| { return watched.longest_quiet(); }); };
    loop {
        if let Some(status) = child.try_wait().map_err(SingleFlightError::Start)? {
            *quiet = kept(&clock);
            return Ok(Ok(status));
        }
        for output in outputs {
            let size: u64 = match output.metadata() {
                Ok(metadata) => metadata.len(),
                Err(_) => u64::MAX,
            };
            if is_flood(size) {
                *quiet = kept(&clock);
                return Ok(Err(StopCause::Flood));
            }
        }
        if let Some(cause) = clock.check() {
            *quiet = kept(&clock);
            return Ok(Err(cause));
        }
        if let Some(report) = clock.take_wait_note() {
            // Said as the wait begins, so a long wait is read while it lasts (the service's log, or the person's terminal).
            warn(TAG, &wait_line(label, &report));
            waits.push(report);
        }
        std::thread::sleep(POLL_PAUSE);
    }
}

/// What:
///  The name a run goes by in the lines about it: the program's file name and its first word that is not an option, as in
///  `git push`, `git fetch` or `git-lfs push`.
/// Why:
///   The wait line must say which of the wrapper's network runs is waiting, and the command is the only thing that knows. The
///  values of Git's `-c` and `-C` options are skipped with them.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// const [program, ...args] = command; return [basename(program), args.find((word) => !word.startsWith('-'))].join(' ');
/// ```
pub fn command_label(command: &Command) -> String {
    let program: String = command.get_program().to_string_lossy().rsplit('/').next().unwrap_or_default().to_owned();
    let mut arguments = command.get_args();
    while let Some(argument) = arguments.next() {
        let word: String = argument.to_string_lossy().into_owned();
        // `-c name=value` and `-C directory` take the next word as their value.
        if word == "-c" || word == "-C" {
            let _value = arguments.next();
            continue;
        }
        if word.starts_with('-') {
            continue;
        }
        return format!("{program} {word}");
    }
    return program;
}

/// What:
///  The line that names a run's wait for its remote.
/// Why:
///   The person or the journal reads that the run is not stuck: the connection to the remote is open, and what ends the wait.
///  No time ends it: only the remote's answer, the connection closing or TCP giving up.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// `cli-git: ${label} ${WAIT_NOTE_PHRASE}: the connection to the remote is open (silent ${silent} seconds)`
/// ```
fn wait_line(label: &str, report: &WaitReport) -> String {
    return format!(
        "cli-git: {label} {WAIT_NOTE_PHRASE}: the connection to the remote is open, and nothing has moved for {} seconds \
         (elapsed_seconds={}); the remote may be checking the push or preparing its answer. It is waited for until it answers or \
         the connection closes; no time limit applies while the connection is open.",
        report.silent.as_secs(),
        report.elapsed.as_secs(),
    );
}

/// What:
///  Run a push command to its end or its deadline and capture its interleaved output, after the reference locks that a
///  killed Git left in its repository have been cleared when their holder is proven gone.
/// Why:
///   Every start of the wrapper's own fetch and push, the repetitions of a push included, goes through here
///  (`push_lock_clearing.rs`).
///
/// In TS you'd write (pseudocode):
/// ```ts
/// async function runBoundedPush({ command, patience, grace, environment }): Promise<PushAttempt>;
/// ```
pub fn run_bounded_push(
    command: Command,
    patience: Patience,
    grace: Duration,
    environment: &[(OsString, OsString)],
) -> Result<PushAttempt, SingleFlightError> {
    return crate::push_lock_clearing::run_clearing_locks(command, patience, grace, environment, &crate::stale_ref_lock_judge::Judge::here());
}

/// What:
///  Run a push command to its end or its deadline and capture its interleaved output.
/// Why:
///   Both streams share one anonymous file so lines keep the order Git wrote them,
///  and a file needs no reader thread that a stuck helper could keep alive.
///  A stopped push becomes a failed attempt that says so,
///  so the commit stays saved and the failure is recorded for later invocations.
///
/// In TS you'd write (pseudocode):
/// ```ts
/// async function runBoundedPush({ command, deadlineMs, graceMs }): Promise<PushAttempt>;
/// ```
pub fn run_bounded_push_once(
    mut command: Command,
    patience: Patience,
    grace: Duration,
    environment: &[(OsString, OsString)],
) -> Result<PushAttempt, SingleFlightError> {
    let mut output: File = scratch_file(environment).map_err(SingleFlightError::Start)?;
    let for_stdout: File = output.try_clone().map_err(SingleFlightError::Start)?;
    let for_stderr: File = output.try_clone().map_err(SingleFlightError::Start)?;
    command
        .stdin(Stdio::null())
        .stdout(Stdio::from(for_stdout))
        .stderr(Stdio::from(for_stderr));
    // Taken before the push starts, so a lock born earlier is never taken for the push's.
    let locks: LockLedger = LockLedger::before_start(&command);
    let label: String = command_label(&command);
    let mut child: Child = command.spawn_retrying().map_err(SingleFlightError::Start)?;
    drop(command);
    let mut waits: Vec<WaitReport> = Vec::new();
    let ended: Result<ExitStatus, StopCause> = wait_until_done_noting(&mut child, &[&output], patience, label.as_str(), &mut waits)?;
    if ended.is_err() {
        stop_push(child, grace, locks);
    }
    let captured: String = read_output(&mut output)?;
    let mut shown_text: String = strip_one_line_break(captured.as_str()).to_owned();
    // A wait is said once more, in the push's own output (the journal's `pushed` entry and the person's terminal carry it).
    for report in &waits {
        let line: String = wait_line(label.as_str(), report);
        if !shown_text.is_empty() {
            shown_text.push('\n');
        }
        shown_text.push_str(line.as_str());
    }
    let shown: &str = shown_text.as_str();
    return Ok(match ended {
        Ok(status) => PushAttempt {
            exit_code: i64::from(status.code().unwrap_or(1)),
            output: shown.to_owned(),
        },
        Err(cause) => {
            let reason: String = match cause {
                StopCause::Deadline => format!(
                    "cli-git: git push did not finish within {} seconds and was stopped (limit=deadline); \
                     {}. {PUSH_QUEUED_LINE} Hint: if you were pushing over a slow or \
                     offline connection, your commit is already saved; push again when the connection works.",
                    match patience {
                        Patience::Fixed(limit) => limit.as_secs(),
                        Patience::Progress { stall } => stall.as_secs(),
                    },
                    extend_clause()
                ),
                StopCause::Stalled(report) => format!(
                    "cli-git: git push made no progress for {} seconds and was stopped (limit=stall, bytes_moved={}, \
                     elapsed_seconds={}); {}. {PUSH_QUEUED_LINE} Hint: if you were pushing over a slow or \
                     offline connection, your commit is already saved; push again when the connection works.",
                    report.limit.as_secs(),
                    report.moved,
                    report.elapsed.as_secs(),
                    extend_clause()
                ),
                StopCause::Flood => format!(
                    "cli-git: git push wrote more than {MAX_PUSH_OUTPUT} bytes of output and was stopped. Hint: if a hook or the \
                     remote prints this much, run `git ls-remote` to see whether your commits arrived, and read the \
                     hook's own output by running it directly before pushing again."
                ),
            };
            debug(TAG, &reason);
            let joined: String = if shown.is_empty() {
                reason
            } else {
                format!("{shown}\n{reason}")
            };
            PushAttempt {
                exit_code: STOPPED_EXIT_CODE,
                output: joined,
            }
        }
    });
}

/// Bounded push behavior is controlled in the test module.
#[cfg(test)]
#[path = "bounded_push_tests.rs"]
mod tests;