Merge pull request #13 from escoffier-labs/feat/brigade-runs-latest

feat: show latest brigade run

Author: solomonneas

CHANGELOG.md

@@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Successful `--handoff` runs now record the written handoff path in `run.json`.
 - `brigade run --handoff` to write a Memory Handoff for successful runs, with `--handoff-inbox` override.
 - `brigade runs list` to print recent run artifact directories from `.brigade/runs`.
+- `brigade runs latest` to show the newest run summary without copying a run path from `brigade runs list`.
 - `brigade runs show <run-dir>` to print a readable summary of one run artifact directory.
 - Roster-level and per-agent `timeout_seconds` controls for bounded CLI calls.
 - `brigade run --read-only` prompt policy for planning and review runs that should inspect and recommend only, with native `codex exec --sandbox read-only` enforcement for Codex agents.

README.md

@@ -157,6 +157,7 @@ Inspect a completed run without opening each JSON file:
 
 ```bash
 brigade runs list --cwd /path/to/repo
+brigade runs latest --cwd /path/to/repo
 brigade runs show .brigade/runs/<run-id>
 ```
 

src/brigade/cli.py

@@ -194,6 +194,19 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Explicit runs directory. Defaults to .brigade/runs under --cwd.",
     )
     p_runs_list.add_argument("--limit", type=int, default=10, help="Maximum number of runs to show.")
+    p_runs_latest = runs_sub.add_parser("latest", help="Show the most recent Brigade run.")
+    p_runs_latest.add_argument(
+        "--cwd",
+        type=Path,
+        default=Path("."),
+        help="Workspace whose default .brigade/runs directory should be inspected.",
+    )
+    p_runs_latest.add_argument(
+        "--runs-dir",
+        type=Path,
+        default=None,
+        help="Explicit runs directory. Defaults to .brigade/runs under --cwd.",
+    )
     p_runs_show = runs_sub.add_parser("show", help="Show a readable summary of one run directory.")
     p_runs_show.add_argument("run_dir", type=Path, help="Path to a Brigade run artifact directory.")
 
@@ -419,6 +432,8 @@ def main(argv=None) -> int:
 
         if args.runs_command == "list":
             return runs_cmd.list_runs(cwd=args.cwd, runs_dir=args.runs_dir, limit=args.limit)
+        if args.runs_command == "latest":
+            return runs_cmd.show_latest(cwd=args.cwd, runs_dir=args.runs_dir)
         if args.runs_command == "show":
             return runs_cmd.show(args.run_dir)
         parser.error(f"unknown runs command: {args.runs_command}")

src/brigade/runs_cmd.py

@@ -118,20 +118,7 @@ def _run_sort_key(item: tuple[Path, dict[str, Any]]) -> str:
     return str(value) if value else path.name
 
 
-def list_runs(*, cwd: Path, runs_dir: Path | None = None, limit: int = 10) -> int:
-    if limit < 1:
-        print("error: --limit must be a positive integer", file=sys.stderr)
-        return 2
-
-    cwd = cwd.expanduser().resolve()
-    if not cwd.is_dir():
-        print(f"error: --cwd is not a directory: {cwd}", file=sys.stderr)
-        return 2
-    root = runs_dir.expanduser() if runs_dir is not None else cwd / ".brigade" / "runs"
-    if not root.is_dir():
-        print(f"error: runs directory not found: {root}", file=sys.stderr)
-        return 2
-
+def _collect_runs(root: Path) -> tuple[list[tuple[Path, dict[str, Any]]], int]:
     runs: list[tuple[Path, dict[str, Any]]] = []
     skipped = 0
     for child in root.iterdir():
@@ -146,8 +133,25 @@ def list_runs(*, cwd: Path, runs_dir: Path | None = None, limit: int = 10) -> in
             skipped += 1
             continue
         runs.append((child, meta))
-
     runs.sort(key=_run_sort_key, reverse=True)
+    return runs, skipped
+
+
+def list_runs(*, cwd: Path, runs_dir: Path | None = None, limit: int = 10) -> int:
+    if limit < 1:
+        print("error: --limit must be a positive integer", file=sys.stderr)
+        return 2
+
+    cwd = cwd.expanduser().resolve()
+    if not cwd.is_dir():
+        print(f"error: --cwd is not a directory: {cwd}", file=sys.stderr)
+        return 2
+    root = runs_dir.expanduser() if runs_dir is not None else cwd / ".brigade" / "runs"
+    if not root.is_dir():
+        print(f"error: runs directory not found: {root}", file=sys.stderr)
+        return 2
+
+    runs, skipped = _collect_runs(root)
     for path, meta in runs[:limit]:
         status = meta.get("status", "unknown")
         started = meta.get("started_at", path.name)
@@ -167,6 +171,25 @@ def list_runs(*, cwd: Path, runs_dir: Path | None = None, limit: int = 10) -> in
     return 0
 
 
+def show_latest(*, cwd: Path, runs_dir: Path | None = None) -> int:
+    cwd = cwd.expanduser().resolve()
+    if not cwd.is_dir():
+        print(f"error: --cwd is not a directory: {cwd}", file=sys.stderr)
+        return 2
+    root = runs_dir.expanduser() if runs_dir is not None else cwd / ".brigade" / "runs"
+    if not root.is_dir():
+        print(f"error: runs directory not found: {root}", file=sys.stderr)
+        return 2
+
+    runs, skipped = _collect_runs(root)
+    if skipped:
+        print(f"skipped {skipped} invalid run director{'y' if skipped == 1 else 'ies'}", file=sys.stderr)
+    if not runs:
+        print(f"error: no runs found in {root}", file=sys.stderr)
+        return 1
+    return show(runs[0][0])
+
+
 def show(run_dir: Path) -> int:
     run_dir = run_dir.expanduser()
     if not run_dir.is_dir():

tests/test_runs_cmd.py

@@ -190,3 +190,39 @@ def test_runs_list_cli_with_explicit_runs_dir(tmp_path, capsys):
     out = capsys.readouterr().out
     assert "cli task" in out
     assert "dry-run" in out
+
+
+def test_runs_latest_shows_newest_run(tmp_path, capsys):
+    runs_root = tmp_path / ".brigade" / "runs"
+    _write_minimal_run(
+        runs_root / "older",
+        task="older task",
+        status="failed",
+        started_at="2026-05-26T13:00:00Z",
+    )
+    newest = runs_root / "newer"
+    _write_run_artifacts(newest)
+
+    assert runs_cmd.show_latest(cwd=tmp_path) == 0
+    out = capsys.readouterr().out
+    assert f"run: {newest}" in out
+    assert "task: build feature" in out
+    assert "final:" in out
+
+
+def test_runs_latest_reports_no_runs(tmp_path, capsys):
+    runs_root = tmp_path / ".brigade" / "runs"
+    runs_root.mkdir(parents=True)
+
+    assert runs_cmd.show_latest(cwd=tmp_path) == 1
+    assert "no runs found" in capsys.readouterr().err
+
+
+def test_runs_latest_cli_with_explicit_runs_dir(tmp_path, capsys):
+    runs_root = tmp_path / "runs"
+    runs_root.mkdir()
+    run_dir = runs_root / "one"
+    _write_run_artifacts(run_dir)
+
+    assert cli.main(["runs", "latest", "--cwd", str(tmp_path), "--runs-dir", str(runs_root)]) == 0
+    assert f"run: {run_dir}" in capsys.readouterr().out