pitboss 0.2.0

CLI that orchestrates coding agents (Claude Code and others) through a phased implementation plan, with automatic test/commit loops and a TUI dashboard
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
//! Project test runner detection and execution.
//!
//! Despite the module name, this is *not* the crate's integration test
//! directory (that lives at `<crate-root>/tests/`). It's the per-project test
//! runner the pitboss runner invokes after each phase to decide whether the
//! agent's changes pass.
//!
//! ## Surface
//!
//! [`detect`] probes the workspace for a recognized project layout and returns
//! a [`TestRunner`] preconfigured to invoke the right command. The probe is
//! best-effort; config.toml's `[tests] command = "..."` overrides detection
//! entirely, in which case the configured command is used verbatim.
//!
//! [`TestRunner::run`] executes the runner, tees combined stdout+stderr to a
//! per-phase log file, and returns a [`TestOutcome`] with a short summary
//! suitable for surfacing in CLI output and feeding into the fixer prompt.
//!
//! ## Detection priority
//!
//! 1. `Cargo.toml`             → `cargo test`
//! 2. `package.json` (with a `test` script) → `npm` / `pnpm` / `yarn` `test`
//!    (chosen by the lock file present)
//! 3. `pyproject.toml` or `setup.py` → `pytest`
//! 4. `go.mod`                 → `go test ./...`
//!
//! Detection stops at the first match. A workspace with both `Cargo.toml` and
//! `package.json` resolves to cargo — pick whichever language is canonical and
//! set `[tests] command = "..."` to override.

use std::fs;
use std::path::{Path, PathBuf};
use std::process::Stdio;

use anyhow::{Context, Result};
use tokio::fs::OpenOptions;
use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
use tokio::process::Command;

/// Maximum number of trailing log lines included in [`TestOutcome::summary`]
/// when a test run fails. Keeps prompts and CLI output bounded; the full log
/// is always available at [`TestOutcome::log_path`].
const FAILURE_TAIL_LINES: usize = 40;

/// Result of executing a [`TestRunner`].
///
/// `summary` is a short, human-readable description suitable for CLI output
/// and fixer prompts. The full transcript is at `log_path`.
#[derive(Debug, Clone)]
pub struct TestOutcome {
    /// `true` when the underlying process exited with status 0.
    pub passed: bool,
    /// Short description of the run. On success: `"<runner>: passed (N lines
    /// captured)"`. On failure: `"<runner>: failed (exit C)\n<last K lines>"`.
    pub summary: String,
    /// Path to the combined stdout+stderr log written during the run.
    pub log_path: PathBuf,
}

/// Which built-in detector matched, if any.
///
/// Independent of `program`/`args` because callers occasionally want to log or
/// branch on the kind without re-parsing the command line. [`TestRunnerKind::Override`]
/// signals that the runner came from `config.toml` rather than detection.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TestRunnerKind {
    /// `cargo test` — chosen when `Cargo.toml` is present.
    Cargo,
    /// `npm test` — JS workspace with no other lock file.
    Npm,
    /// `pnpm test` — JS workspace with `pnpm-lock.yaml`.
    Pnpm,
    /// `yarn test` — JS workspace with `yarn.lock`.
    Yarn,
    /// `pytest` — Python workspace (`pyproject.toml` or `setup.py`).
    Pytest,
    /// `go test ./...` — Go workspace (`go.mod`).
    Go,
    /// User-supplied `[tests] command = "..."`. Bypassed detection.
    Override,
}

impl TestRunnerKind {
    /// Short name used in summaries and log lines.
    pub fn label(self) -> &'static str {
        match self {
            TestRunnerKind::Cargo => "cargo test",
            TestRunnerKind::Npm => "npm test",
            TestRunnerKind::Pnpm => "pnpm test",
            TestRunnerKind::Yarn => "yarn test",
            TestRunnerKind::Pytest => "pytest",
            TestRunnerKind::Go => "go test",
            TestRunnerKind::Override => "tests",
        }
    }
}

/// A resolved test invocation: program, arguments, and the workspace to run
/// it from. Construct via [`detect`] (or [`TestRunner::from_override`] when
/// the user has supplied an explicit command).
#[derive(Debug, Clone)]
pub struct TestRunner {
    /// Detector that produced this runner, or `Override` for user-supplied.
    pub kind: TestRunnerKind,
    /// Program to spawn (e.g., `"cargo"`, `"sh"` if the user wrapped it).
    pub program: String,
    /// Arguments passed to the program.
    pub args: Vec<String>,
    /// Working directory the process is spawned in.
    pub workdir: PathBuf,
    /// Extra env vars layered on top of pitboss's inherited environment.
    /// Used by parallel-session verify cycles to point `CARGO_TARGET_DIR`
    /// at the main workspace's `target/` so each worktree doesn't pay a
    /// full rebuild cost. Empty by default; merge via
    /// [`TestRunner::with_env`].
    pub env: std::collections::HashMap<String, String>,
}

impl TestRunner {
    /// Layer additional env vars onto the runner. Existing keys are
    /// overwritten; unrelated keys are left intact. Returns `self` so the
    /// call site can chain.
    pub fn with_env(mut self, env: std::collections::HashMap<String, String>) -> Self {
        self.env.extend(env);
        self
    }
}

impl TestRunner {
    /// Build a runner from a user-supplied shell-style command line.
    ///
    /// The command is whitespace-split into program + args; shell features
    /// (pipes, env-var assignments, glob expansion) require an explicit
    /// `sh -c "..."` wrapper. Returns `None` when the command is empty or
    /// contains only whitespace.
    pub fn from_override(command: &str, workdir: impl Into<PathBuf>) -> Option<Self> {
        let mut parts = command.split_whitespace().map(str::to_string);
        let program = parts.next()?;
        let args: Vec<String> = parts.collect();
        Some(Self {
            kind: TestRunnerKind::Override,
            program,
            args,
            workdir: workdir.into(),
            env: std::collections::HashMap::new(),
        })
    }

    /// Spawn the configured command, tee combined stdout+stderr to `log_path`,
    /// and wait for it to exit. Returns a [`TestOutcome`] describing the run.
    ///
    /// `log_path`'s parent directory is created if missing. The log file is
    /// truncated on each call so a re-run produces a clean transcript;
    /// callers wanting per-attempt logs must vary the path.
    pub async fn run(&self, log_path: impl Into<PathBuf>) -> Result<TestOutcome> {
        let log_path = log_path.into();
        if let Some(parent) = log_path.parent() {
            if !parent.as_os_str().is_empty() {
                tokio::fs::create_dir_all(parent)
                    .await
                    .with_context(|| format!("tests: create log dir {:?}", parent))?;
            }
        }
        let mut log_file = OpenOptions::new()
            .create(true)
            .write(true)
            .truncate(true)
            .open(&log_path)
            .await
            .with_context(|| format!("tests: open log {:?}", log_path))?;

        // Header line so the log file is self-describing — useful when an
        // oncall is reading just `phase-NN.log` without other context.
        let header = format!(
            "$ {}{}{} (cwd: {})\n",
            self.program,
            if self.args.is_empty() { "" } else { " " },
            self.args.join(" "),
            self.workdir.display(),
        );
        log_file
            .write_all(header.as_bytes())
            .await
            .with_context(|| format!("tests: write header {:?}", log_path))?;

        let mut cmd = Command::new(&self.program);
        cmd.args(&self.args)
            .current_dir(&self.workdir)
            .stdin(Stdio::null())
            .stdout(Stdio::piped())
            .stderr(Stdio::piped())
            .kill_on_drop(true);
        if !self.env.is_empty() {
            cmd.envs(self.env.iter());
        }

        let mut child = cmd
            .spawn()
            .with_context(|| format!("tests: spawn {:?}", self.program))?;
        let stdout = child.stdout.take().expect("piped stdout");
        let stderr = child.stderr.take().expect("piped stderr");

        let mut stdout_reader = BufReader::new(stdout).lines();
        let mut stderr_reader = BufReader::new(stderr).lines();

        // Single-tasked merge: tokio::select! over both readers so we keep
        // strict relative ordering from each stream while writing serially to
        // the log file. Captures every line (no truncation) so the tail-on-
        // failure summary has the real terminal output to draw from.
        let mut line_count: usize = 0;
        let mut tail: std::collections::VecDeque<String> =
            std::collections::VecDeque::with_capacity(FAILURE_TAIL_LINES);
        let mut stdout_done = false;
        let mut stderr_done = false;

        loop {
            tokio::select! {
                line = stdout_reader.next_line(), if !stdout_done => {
                    match line {
                        Ok(Some(l)) => {
                            log_file.write_all(l.as_bytes()).await.ok();
                            log_file.write_all(b"\n").await.ok();
                            push_tail(&mut tail, l);
                            line_count += 1;
                        }
                        Ok(None) | Err(_) => stdout_done = true,
                    }
                }
                line = stderr_reader.next_line(), if !stderr_done => {
                    match line {
                        Ok(Some(l)) => {
                            log_file.write_all(b"[stderr] ").await.ok();
                            log_file.write_all(l.as_bytes()).await.ok();
                            log_file.write_all(b"\n").await.ok();
                            push_tail(&mut tail, format!("[stderr] {l}"));
                            line_count += 1;
                        }
                        Ok(None) | Err(_) => stderr_done = true,
                    }
                }
                else => break,
            }
        }

        let status = child.wait().await.context("tests: waiting for child")?;
        log_file.flush().await.ok();

        let passed = status.success();
        let summary = if passed {
            format!(
                "{}: passed ({} lines captured)",
                self.kind.label(),
                line_count
            )
        } else {
            let exit = status
                .code()
                .map(|c| c.to_string())
                .unwrap_or_else(|| "signal".to_string());
            let mut s = format!(
                "{}: failed (exit {}, {} lines captured)",
                self.kind.label(),
                exit,
                line_count
            );
            if !tail.is_empty() {
                s.push('\n');
                for line in &tail {
                    s.push_str(line);
                    s.push('\n');
                }
            }
            s
        };

        Ok(TestOutcome {
            passed,
            summary,
            log_path,
        })
    }
}

/// Bounded ring of trailing lines used to build the failure summary.
fn push_tail(tail: &mut std::collections::VecDeque<String>, line: String) {
    if tail.len() == FAILURE_TAIL_LINES {
        tail.pop_front();
    }
    tail.push_back(line);
}

/// Pick a [`TestRunner`] for `workdir`.
///
/// `override_command` is consulted first: when `Some`, the result is built via
/// [`TestRunner::from_override`] without any filesystem probing. When `None`
/// (or when the override is empty), the function probes the workspace in the
/// order listed in the module docs and returns the first match.
///
/// Returns `None` only when no override is given and no recognized layout is
/// present — the runner treats that as "tests skipped" rather than a failure.
pub fn detect(workdir: impl AsRef<Path>, override_command: Option<&str>) -> Option<TestRunner> {
    let workdir = workdir.as_ref();
    if let Some(cmd) = override_command {
        if let Some(runner) = TestRunner::from_override(cmd, workdir) {
            return Some(runner);
        }
    }

    if workdir.join("Cargo.toml").is_file() {
        return Some(TestRunner {
            kind: TestRunnerKind::Cargo,
            program: "cargo".into(),
            args: vec!["test".into()],
            workdir: workdir.to_path_buf(),
            env: std::collections::HashMap::new(),
        });
    }

    if let Some(runner) = detect_node(workdir) {
        return Some(runner);
    }

    if workdir.join("pyproject.toml").is_file() || workdir.join("setup.py").is_file() {
        return Some(TestRunner {
            kind: TestRunnerKind::Pytest,
            program: "pytest".into(),
            args: Vec::new(),
            workdir: workdir.to_path_buf(),
            env: std::collections::HashMap::new(),
        });
    }

    if workdir.join("go.mod").is_file() {
        return Some(TestRunner {
            kind: TestRunnerKind::Go,
            program: "go".into(),
            args: vec!["test".into(), "./...".into()],
            workdir: workdir.to_path_buf(),
            env: std::collections::HashMap::new(),
        });
    }

    None
}

/// Detect a JS/TS workspace. Requires `package.json` with a `scripts.test`
/// entry; without one we have no command to invoke. The package manager is
/// chosen from the lock file present (pnpm > yarn > npm), defaulting to npm.
fn detect_node(workdir: &Path) -> Option<TestRunner> {
    let pkg = workdir.join("package.json");
    if !pkg.is_file() {
        return None;
    }
    if !package_json_has_test_script(&pkg) {
        return None;
    }

    let (kind, program) = if workdir.join("pnpm-lock.yaml").is_file() {
        (TestRunnerKind::Pnpm, "pnpm")
    } else if workdir.join("yarn.lock").is_file() {
        (TestRunnerKind::Yarn, "yarn")
    } else {
        (TestRunnerKind::Npm, "npm")
    };

    // npm uniquely requires `--` to forward extra flags; no extras here so
    // the bare `npm test` form is fine. pnpm and yarn use `<pm> test`.
    let args = vec!["test".into()];

    Some(TestRunner {
        kind,
        program: program.into(),
        args,
        workdir: workdir.to_path_buf(),
        env: std::collections::HashMap::new(),
    })
}

/// `true` when `package.json` parses as JSON and contains a non-empty
/// `scripts.test` string. A malformed `package.json` is treated as "no
/// recognizable test script" rather than a hard error — detection stays
/// best-effort.
fn package_json_has_test_script(path: &Path) -> bool {
    let Ok(text) = fs::read_to_string(path) else {
        return false;
    };
    let Ok(value) = serde_json::from_str::<serde_json::Value>(&text) else {
        return false;
    };
    value
        .get("scripts")
        .and_then(|s| s.get("test"))
        .and_then(|t| t.as_str())
        .map(|s| !s.trim().is_empty())
        .unwrap_or(false)
}

#[cfg(test)]
#[allow(clippy::module_inception)]
mod tests {
    use super::*;
    use tempfile::tempdir;

    fn touch(dir: &Path, rel: &str) {
        let path = dir.join(rel);
        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent).unwrap();
        }
        std::fs::write(path, b"").unwrap();
    }

    fn write(dir: &Path, rel: &str, contents: &str) {
        let path = dir.join(rel);
        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent).unwrap();
        }
        std::fs::write(path, contents).unwrap();
    }

    #[test]
    fn detect_returns_none_for_unrecognized_layout() {
        let dir = tempdir().unwrap();
        assert!(detect(dir.path(), None).is_none());
    }

    #[test]
    fn detect_cargo_when_cargo_toml_present() {
        let dir = tempdir().unwrap();
        touch(dir.path(), "Cargo.toml");
        let runner = detect(dir.path(), None).unwrap();
        assert_eq!(runner.kind, TestRunnerKind::Cargo);
        assert_eq!(runner.program, "cargo");
        assert_eq!(runner.args, vec!["test".to_string()]);
        assert_eq!(runner.workdir, dir.path());
    }

    #[test]
    fn detect_pytest_via_pyproject_toml() {
        let dir = tempdir().unwrap();
        touch(dir.path(), "pyproject.toml");
        let runner = detect(dir.path(), None).unwrap();
        assert_eq!(runner.kind, TestRunnerKind::Pytest);
        assert_eq!(runner.program, "pytest");
        assert!(runner.args.is_empty());
    }

    #[test]
    fn detect_pytest_via_setup_py_when_pyproject_missing() {
        let dir = tempdir().unwrap();
        touch(dir.path(), "setup.py");
        let runner = detect(dir.path(), None).unwrap();
        assert_eq!(runner.kind, TestRunnerKind::Pytest);
    }

    #[test]
    fn detect_go_when_go_mod_present() {
        let dir = tempdir().unwrap();
        touch(dir.path(), "go.mod");
        let runner = detect(dir.path(), None).unwrap();
        assert_eq!(runner.kind, TestRunnerKind::Go);
        assert_eq!(runner.program, "go");
        assert_eq!(runner.args, vec!["test".to_string(), "./...".to_string()]);
    }

    #[test]
    fn detect_npm_when_package_json_has_test_script() {
        let dir = tempdir().unwrap();
        write(dir.path(), "package.json", r#"{"scripts":{"test":"jest"}}"#);
        let runner = detect(dir.path(), None).unwrap();
        assert_eq!(runner.kind, TestRunnerKind::Npm);
        assert_eq!(runner.program, "npm");
        assert_eq!(runner.args, vec!["test".to_string()]);
    }

    #[test]
    fn detect_pnpm_when_pnpm_lock_present() {
        let dir = tempdir().unwrap();
        write(
            dir.path(),
            "package.json",
            r#"{"scripts":{"test":"vitest"}}"#,
        );
        touch(dir.path(), "pnpm-lock.yaml");
        let runner = detect(dir.path(), None).unwrap();
        assert_eq!(runner.kind, TestRunnerKind::Pnpm);
        assert_eq!(runner.program, "pnpm");
    }

    #[test]
    fn detect_yarn_when_yarn_lock_present_but_no_pnpm() {
        let dir = tempdir().unwrap();
        write(dir.path(), "package.json", r#"{"scripts":{"test":"jest"}}"#);
        touch(dir.path(), "yarn.lock");
        let runner = detect(dir.path(), None).unwrap();
        assert_eq!(runner.kind, TestRunnerKind::Yarn);
        assert_eq!(runner.program, "yarn");
    }

    #[test]
    fn detect_pnpm_wins_over_yarn_when_both_lockfiles_present() {
        let dir = tempdir().unwrap();
        write(
            dir.path(),
            "package.json",
            r#"{"scripts":{"test":"vitest"}}"#,
        );
        touch(dir.path(), "pnpm-lock.yaml");
        touch(dir.path(), "yarn.lock");
        let runner = detect(dir.path(), None).unwrap();
        assert_eq!(runner.kind, TestRunnerKind::Pnpm);
    }

    #[test]
    fn detect_skips_node_when_no_test_script() {
        let dir = tempdir().unwrap();
        write(dir.path(), "package.json", r#"{"scripts":{"build":"tsc"}}"#);
        // No fallback in this layout, so detection returns None entirely.
        assert!(detect(dir.path(), None).is_none());
    }

    #[test]
    fn detect_skips_node_when_test_script_is_empty_string() {
        let dir = tempdir().unwrap();
        write(dir.path(), "package.json", r#"{"scripts":{"test":"   "}}"#);
        assert!(detect(dir.path(), None).is_none());
    }

    #[test]
    fn detect_treats_malformed_package_json_as_no_match() {
        let dir = tempdir().unwrap();
        write(dir.path(), "package.json", "{ not valid json");
        assert!(detect(dir.path(), None).is_none());
    }

    #[test]
    fn detect_priority_cargo_over_node() {
        let dir = tempdir().unwrap();
        touch(dir.path(), "Cargo.toml");
        write(dir.path(), "package.json", r#"{"scripts":{"test":"jest"}}"#);
        let runner = detect(dir.path(), None).unwrap();
        assert_eq!(runner.kind, TestRunnerKind::Cargo);
    }

    #[test]
    fn override_bypasses_detection_entirely() {
        let dir = tempdir().unwrap();
        // Cargo would otherwise win.
        touch(dir.path(), "Cargo.toml");
        let runner = detect(dir.path(), Some("make check")).unwrap();
        assert_eq!(runner.kind, TestRunnerKind::Override);
        assert_eq!(runner.program, "make");
        assert_eq!(runner.args, vec!["check".to_string()]);
    }

    #[test]
    fn override_with_only_whitespace_falls_back_to_detection() {
        let dir = tempdir().unwrap();
        touch(dir.path(), "Cargo.toml");
        // Empty/whitespace override yields no runner, so detection runs.
        let runner = detect(dir.path(), Some("   ")).unwrap();
        assert_eq!(runner.kind, TestRunnerKind::Cargo);
    }

    #[test]
    fn override_with_no_args_uses_program_only() {
        let runner = TestRunner::from_override("./run-tests", "/tmp").unwrap();
        assert_eq!(runner.program, "./run-tests");
        assert!(runner.args.is_empty());
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn run_succeeds_for_zero_exit() {
        let dir = tempdir().unwrap();
        let runner = TestRunner::from_override("/bin/sh -c true", dir.path()).unwrap();
        let outcome = runner.run(dir.path().join("test.log")).await.unwrap();
        assert!(outcome.passed);
        assert!(outcome.summary.contains("passed"));
        assert!(outcome.log_path.is_file());
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn run_fails_with_tail_summary_for_nonzero_exit() {
        let dir = tempdir().unwrap();
        // Built directly because shell-style quoting can't survive the
        // whitespace-split heuristic in `from_override`.
        let runner = TestRunner {
            kind: TestRunnerKind::Override,
            program: "/bin/sh".into(),
            args: vec!["-c".into(), "echo failure-marker; exit 7".into()],
            workdir: dir.path().to_path_buf(),
            env: std::collections::HashMap::new(),
        };
        let outcome = runner.run(dir.path().join("test.log")).await.unwrap();
        assert!(!outcome.passed);
        assert!(outcome.summary.contains("failed"));
        assert!(
            outcome.summary.contains("failure-marker"),
            "summary should include tail; got: {}",
            outcome.summary
        );
        assert!(outcome.summary.contains("exit 7"));
        // Log file contains the same line.
        let log = std::fs::read_to_string(&outcome.log_path).unwrap();
        assert!(log.contains("failure-marker"));
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn run_logs_header_with_command_and_cwd() {
        let dir = tempdir().unwrap();
        let runner = TestRunner::from_override("/bin/sh -c true", dir.path()).unwrap();
        let log_path = dir.path().join("nested").join("test.log");
        runner.run(&log_path).await.unwrap();
        let log = std::fs::read_to_string(&log_path).unwrap();
        assert!(log.starts_with("$ /bin/sh -c true"));
        assert!(log.contains(&format!("cwd: {}", dir.path().display())));
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn run_truncates_existing_log_file() {
        let dir = tempdir().unwrap();
        let log_path = dir.path().join("test.log");
        std::fs::write(&log_path, "stale contents from prior run\n").unwrap();
        let runner = TestRunner::from_override("/bin/sh -c true", dir.path()).unwrap();
        runner.run(&log_path).await.unwrap();
        let log = std::fs::read_to_string(&log_path).unwrap();
        assert!(
            !log.contains("stale contents"),
            "log not truncated: {log:?}"
        );
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn run_failure_summary_is_bounded_to_tail_lines() {
        // Emit many more lines than FAILURE_TAIL_LINES; the summary tail must
        // include only the final FAILURE_TAIL_LINES and never grow unbounded.
        let dir = tempdir().unwrap();
        let lines_to_emit = FAILURE_TAIL_LINES + 50;
        let script = format!(
            "for i in $(seq 1 {n}); do echo line-$i; done; exit 1",
            n = lines_to_emit
        );
        let runner = TestRunner {
            kind: TestRunnerKind::Override,
            program: "/bin/sh".into(),
            args: vec!["-c".into(), script],
            workdir: dir.path().to_path_buf(),
            env: std::collections::HashMap::new(),
        };
        let outcome = runner.run(dir.path().join("test.log")).await.unwrap();
        assert!(!outcome.passed);
        // Last line ("line-N") must appear; an early line ("line-1") must not.
        assert!(outcome.summary.contains(&format!("line-{}", lines_to_emit)));
        assert!(
            !outcome.summary.contains("line-1\n"),
            "summary should not include the very first line"
        );
        // Sanity: the summary contains a bounded number of newline-delimited
        // lines (header + tail), well below the total emitted.
        let summary_lines = outcome.summary.lines().count();
        assert!(summary_lines <= FAILURE_TAIL_LINES + 4);
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn run_captures_stderr_with_marker() {
        let dir = tempdir().unwrap();
        let runner = TestRunner {
            kind: TestRunnerKind::Override,
            program: "/bin/sh".into(),
            args: vec!["-c".into(), "echo on-stderr 1>&2; exit 1".into()],
            workdir: dir.path().to_path_buf(),
            env: std::collections::HashMap::new(),
        };
        let outcome = runner.run(dir.path().join("test.log")).await.unwrap();
        assert!(!outcome.passed);
        let log = std::fs::read_to_string(&outcome.log_path).unwrap();
        assert!(
            log.contains("[stderr] on-stderr"),
            "log should mark stderr lines: {log:?}"
        );
    }

    #[tokio::test]
    async fn run_surfaces_spawn_failure() {
        let dir = tempdir().unwrap();
        let runner = TestRunner {
            kind: TestRunnerKind::Override,
            program: "/this/binary/does/not/exist".into(),
            args: Vec::new(),
            workdir: dir.path().to_path_buf(),
            env: std::collections::HashMap::new(),
        };
        let err = runner.run(dir.path().join("test.log")).await.unwrap_err();
        assert!(
            format!("{err:#}").contains("spawn"),
            "expected spawn failure, got: {err:#}"
        );
    }
}