Coverage for src/ai_jury/cli.py: 99%
1353 statements
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-20 18:15 +0000
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-20 18:15 +0000
1"""Command-line entry point: ``jury``.
3Examples:
4 jury --pr 123 # review a GitHub PR
5 jury --pr 123 --post # ...and post the verdict as a comment
6 jury --diff-file changes.diff # review a local diff file
7 jury --diff-file - # read a diff from stdin
8 jury --mock # offline pipeline demo (no live CLIs)
9 jury --doctor # local readiness diagnostics
10 jury --config-validate # validate jury.toml and exit
11"""
13from __future__ import annotations
15import argparse
16import contextlib
17import io
18import json
19import os
20import shutil
21import sys
22from importlib import resources
23from pathlib import Path
25from . import __version__, configtrust, panel
26from . import doctor as doctor_module
27from .adapters import EFFORT_LEVELS, effort_warnings, make_adapter
28from .ci import evaluate_ci, fail_on_error
29from .classification import classify, label_strings
30from .config import (
31 ConfigError,
32 bound_error,
33 load_config,
34 load_raw_config,
35 validate_config,
36)
37from .github import (
38 apply_labels,
39 issue_body,
40 post_inline_comments,
41 post_issue_comment,
42 post_pr_comment,
43 pr_context,
44 pr_diff,
45)
46from .metadata import (
47 build_run_metadata,
48 claimed_vendors,
49 collapse_reason,
50 resolve_min_vendors,
51)
52from .orchestrator import review_diff, run_jury
53from .policy import PolicyError, load_policy
54from .redaction import redact
55from .report import render, render_footer, render_live_step, render_transcript
57# Hard ceiling on raw diff ingestion. The per-run ``diff.max_bytes`` budget is
58# only applied *after* the full diff is read and split, so an unbounded
59# ``stdin``/``--diff-file`` read could OOM the process before that cap engages
60# (security audit 2026-06-13). This ceiling sits far above any realistic review
61# budget; it exists solely to bound memory against a hostile/huge input.
62_MAX_DIFF_INGEST_BYTES = 64 * 1024 * 1024 # 64 MiB
65def _read_capped(fh, source: str) -> str:
66 """Read from ``fh``, refusing inputs above the ingest ceiling.
68 The cap is enforced on **bytes**, not characters: a text read of N chars can
69 hold up to 4N bytes for multi-byte UTF-8, so a char ceiling would admit
70 several times the intended memory (security audit 2026-06-13, red-team).
71 Callers pass a binary stream for real input (``sys.stdin.buffer`` / a file
72 opened ``"rb"``); a text stream is also accepted (its read is measured by its
73 UTF-8 byte length) so test doubles and unusual streams still work.
74 """
75 data = fh.read(_MAX_DIFF_INGEST_BYTES + 1)
76 if isinstance(data, str):
77 if len(data.encode("utf-8", "replace")) > _MAX_DIFF_INGEST_BYTES:
78 raise SystemExit(
79 f"error: {source} exceeds the {_MAX_DIFF_INGEST_BYTES}-byte ingest limit"
80 )
81 return data
82 if len(data) > _MAX_DIFF_INGEST_BYTES:
83 raise SystemExit(f"error: {source} exceeds the {_MAX_DIFF_INGEST_BYTES}-byte ingest limit")
84 return data.decode("utf-8", errors="replace")
87def _checked_revision(value: str, flag: str) -> str:
88 """Reject a revision that cannot safely reach ``git``'s argv (issue #367).
90 ``run`` uses argv, never a shell, so quoting is not the risk — a value starting
91 with ``-`` is: git would read it as an option rather than a revision. Refused
92 rather than escaped, and ``--`` is passed at the call site as a second guard.
93 Empty is refused too, since it would silently widen the diff.
94 """
95 revision = (value or "").strip()
96 if not revision:
97 raise SystemExit(f"error: {flag} needs a revision")
98 if revision.startswith("-"):
99 raise SystemExit(
100 f"error: {flag} revision {revision!r} may not start with '-' "
101 "(git would read it as an option)"
102 )
103 return revision
106def _git_diff(argv: list[str], label: str) -> str:
107 """Run a read-only git command and return its stdout, or exit with its error."""
108 import subprocess # local: keeps the module importable where git is absent
110 try:
111 proc = subprocess.run(argv, capture_output=True, text=True, timeout=120)
112 except (OSError, subprocess.SubprocessError) as exc:
113 raise SystemExit(f"error: could not run git for {label}: {redact(str(exc))[0]}") from None
114 if proc.returncode != 0:
115 detail = (proc.stderr or "").strip().splitlines()
116 raise SystemExit(
117 f"error: git could not resolve {label}"
118 + (f": {redact(detail[0])[0]}" if detail else "")
119 )
120 if not proc.stdout.strip():
121 raise SystemExit(f"error: {label} produced an empty diff — nothing to review")
122 # Same ingest ceiling every other source honours; _read_capped wants a handle.
123 return _read_capped(io.StringIO(proc.stdout), label)
126def _bundled_sample_diff() -> str:
127 """The offline-demo diff shipped inside the package (issue #21).
129 Read from ``ai_jury/data/sample.diff`` via ``importlib.resources`` so it
130 resolves the same way from a wheel, a zipapp, or a source checkout — no
131 ``examples/`` directory and no repo needed. Kept byte-identical to
132 ``examples/sample.diff`` by a test.
133 """
134 return resources.files("ai_jury").joinpath("data/sample.diff").read_text(encoding="utf-8")
137def _read_diff(args) -> tuple[str, str]:
138 """Return (diff, context)."""
139 if getattr(args, "commit", None):
140 rev = _checked_revision(args.commit, "--commit")
141 # `git show` of a merge commit prints no diff by default; -m picks the
142 # first-parent view so a merge is reviewable rather than silently empty.
143 return _git_diff(
144 ["git", "show", "--format=", "--patch", "-m", "--first-parent", rev, "--"],
145 f"commit {rev}",
146 ), ""
147 if getattr(args, "commits", None):
148 rev = _checked_revision(args.commits, "--commits")
149 return _git_diff(["git", "diff", rev, "--"], f"range {rev}"), ""
150 if args.pr:
151 return pr_diff(args.pr, args.repo), pr_context(args.pr, args.repo)
152 if args.issue:
153 # Issue mode (issue #221): the issue's rendered text takes the diff slot;
154 # there is no separate context block (title/labels are folded into it).
155 return issue_body(args.issue, args.repo), ""
156 if args.diff_file:
157 if args.diff_file == "-":
158 # Prefer the byte stream so the cap is exact; fall back to the text
159 # stream (e.g. a StringIO test double) which lacks ``.buffer``.
160 return _read_capped(getattr(sys.stdin, "buffer", sys.stdin), "stdin"), ""
161 try:
162 with Path(args.diff_file).open("rb") as fh:
163 return _read_capped(fh, args.diff_file), ""
164 except (OSError, UnicodeDecodeError) as exc:
165 raise SystemExit(
166 f"error reading diff file '{args.diff_file}': {redact(str(exc))[0]}"
167 ) from None
168 if getattr(args, "mock", False):
169 # Offline demo (issue #21): `--mock` with no diff source reviews a diff
170 # bundled in the package, so `jury --mock` / `jury --mock --theater`
171 # deliver the deliberation the docs promise on a fresh install — no
172 # checkout, no PR, no network. A real (non-`--mock`) run still requires
173 # an explicit source. Announced on stderr so the payments.py sample is
174 # never mistaken for the caller's own change.
175 print(
176 "no diff source given; reviewing the bundled offline-demo diff. "
177 "Pass --diff-file/--pr/--commit to review your own change.",
178 file=sys.stderr,
179 )
180 return _bundled_sample_diff(), ""
181 raise SystemExit(
182 "error: provide one of --pr, --issue, --diff-file, --commit, --commits "
183 "(or --diff-file - for stdin)"
184 )
187def build_parser() -> argparse.ArgumentParser:
188 p = argparse.ArgumentParser(
189 prog="jury",
190 description="Cross-vendor multi-agent PR review jury.",
191 # The subcommands are argv-intercepts (handled before this parser runs),
192 # so argparse cannot list them on its own — and until #661 nothing in
193 # `--help` mentioned that they exist at all.
194 epilog=(
195 "Subcommands (each takes its own --help): init, config, comment, "
196 "apply, replay, run-agent, cache clear, examples, guide."
197 ),
198 )
199 src = p.add_argument_group("input")
200 src.add_argument("--pr", help="GitHub PR number/URL to review (uses `gh`)")
201 src.add_argument(
202 "--issue",
203 help="GitHub issue number/URL to review for completeness/clarity (uses "
204 "`gh`); runs the full jury with an issue-quality rubric",
205 )
206 src.add_argument("--repo", help="owner/name for --pr/--issue (defaults to current repo)")
207 src.add_argument("--diff-file", help="path to a diff file, or '-' for stdin")
208 src.add_argument("--commit", help="review the diff one commit introduces (needs a git repo)")
209 src.add_argument(
210 "--commits",
211 help="review a commit range, e.g. origin/main..HEAD or HEAD~5..HEAD (needs a git repo)",
212 )
214 p.add_argument("--config", help="path to jury.toml (default: ./jury.toml or built-in)")
215 p.add_argument(
216 "--policy",
217 type=Path,
218 default=None,
219 help="path to an optional repository review policy file (default: "
220 "auto-discover .jury/policy.toml or jury-policy.toml); "
221 "missing policy files are allowed",
222 )
223 p.add_argument(
224 "--context-mode",
225 choices=["diff-only", "expanded"],
226 default=None,
227 help="context policy: diff-only sends only the diff; expanded includes PR context",
228 )
229 p.add_argument(
230 "--redact",
231 dest="redact",
232 action="store_true",
233 default=None,
234 help="redact secrets from prompt text before sending (default: from config)",
235 )
236 p.add_argument(
237 "--no-redact",
238 dest="redact",
239 action="store_false",
240 help="do not redact secrets before sending",
241 )
242 p.add_argument(
243 "--rounds",
244 type=int,
245 help="override number of rounds (1=review, 2=+debate); a fixed value "
246 "disables early-stop for reproducible benchmarking",
247 )
248 p.add_argument(
249 "--max-rounds",
250 type=int,
251 help="ceiling on adaptive rounds when early-stop is on",
252 )
253 p.add_argument(
254 "--early-stop",
255 dest="early_stop",
256 action="store_true",
257 default=None,
258 help="stop after round 1 when reviewers agree; debate only on disagreement",
259 )
260 p.add_argument(
261 "--no-early-stop",
262 dest="early_stop",
263 action="store_false",
264 help="disable adaptive early-stop (honour a fixed number of rounds)",
265 )
266 p.add_argument(
267 "--auto",
268 dest="auto",
269 action="store_true",
270 default=None,
271 help="risk-aware auto-depth: scale rounds/verify to the diff",
272 )
273 p.add_argument(
274 "--no-auto",
275 dest="auto",
276 action="store_false",
277 help="disable auto-depth (use configured/fixed rounds)",
278 )
279 p.add_argument(
280 "--total-timeout",
281 type=int,
282 help="overall wall-clock budget (seconds) for the whole run",
283 )
284 p.add_argument(
285 "--phase-timeout",
286 type=int,
287 help="per-phase wall-clock budget (seconds)",
288 )
289 p.add_argument(
290 "--retries",
291 type=int,
292 help="extra attempts for transient (timeout/rate-limit/spawn) failures",
293 )
294 p.add_argument(
295 "--max-diff-bytes",
296 type=int,
297 help="size budget for the (filtered) diff before chunking/too-large",
298 )
299 p.add_argument(
300 "--chunk",
301 dest="chunk",
302 action="store_true",
303 default=None,
304 help="chunk an over-budget diff by file instead of failing",
305 )
306 p.add_argument(
307 "--no-chunk",
308 dest="chunk",
309 action="store_false",
310 help="disable diff chunking (fail clearly when over budget)",
311 )
312 p.add_argument(
313 "--exclude",
314 action="append",
315 metavar="GLOB",
316 default=None,
317 help="exclude files matching this path glob (repeatable)",
318 )
319 p.add_argument(
320 "--include",
321 action="append",
322 metavar="GLOB",
323 default=None,
324 help="only review files matching this path glob (repeatable)",
325 )
326 p.add_argument(
327 "--seed",
328 type=int,
329 help="run seed for reproducible orchestration; mock runs with the same seed "
330 "produce byte-identical reports (overrides [jury] seed)",
331 )
332 p.add_argument("--chair", help="override the synthesizing chair agent")
333 p.add_argument(
334 "--mock", action="store_true", help="offline demo: use deterministic mock agents"
335 )
336 p.add_argument(
337 "--strict", action="store_true", help="fail if any configured agent CLI is missing"
338 )
339 p.add_argument(
340 "--min-vendors",
341 type=int,
342 default=None,
343 metavar="N",
344 help=(
345 "fail (exit 3) unless at least N distinct vendors contributed a "
346 "review; 0 disables. Default from config ([jury.ci] min_vendors, "
347 "shipped as 2). --strict checks availability at startup, this "
348 "checks participation at the end"
349 ),
350 )
351 p.add_argument(
352 "--no-min-vendors",
353 dest="min_vendors",
354 action="store_const",
355 const=0,
356 help=(
357 "opt out of the cross-vendor guard: accept a run whose panel "
358 "collapsed to a single vendor (same as --min-vendors 0)"
359 ),
360 )
361 p.add_argument(
362 "--min-reviews",
363 type=int,
364 default=None,
365 metavar="N",
366 help=(
367 "require at least N reviews for a downstream consumer (a panel ballot "
368 "that names what it read and votes; neither the chair's synthesis "
369 "record nor an abstaining ballot is one); 0 disables. Checked before "
370 "the panel runs and again on the result (exit 3). "
371 "Default from config ([jury.ci] min_reviews, shipped as 0)"
372 ),
373 )
374 p.add_argument(
375 "--verify",
376 dest="verify",
377 action="store_true",
378 default=None,
379 help="run the verification round (default: from config)",
380 )
381 p.add_argument(
382 "--no-verify",
383 dest="verify",
384 action="store_false",
385 help="skip the verification round",
386 )
387 p.add_argument(
388 "--doctor",
389 action="store_true",
390 help="print a local readiness diagnostics report and exit (no telemetry is collected or sent)",
391 )
392 p.add_argument(
393 "--json",
394 action="store_true",
395 help=(
396 "with --doctor, print the machine-readable provider export "
397 "(schema ai-jury.doctor.v1) as the only thing on stdout"
398 ),
399 )
400 p.add_argument(
401 "--write",
402 help="with --doctor, also write the diagnostics as JSON to this path (secrets redacted)",
403 )
404 p.add_argument(
405 "--effort",
406 choices=list(EFFORT_LEVELS),
407 default=None,
408 help=(
409 "reasoning effort for every agent this run (overrides [[agent]] effort); "
410 "ignored with a warning for agents whose vendor has no effort control"
411 ),
412 )
413 p.add_argument("-o", "--output", help="write the report to a file instead of stdout")
414 p.add_argument(
415 "--metadata-json",
416 metavar="PATH",
417 help="write machine-readable run metadata (durations, status, rounds) as JSON",
418 )
419 p.add_argument(
420 "--events-file",
421 metavar="PATH",
422 help="write the run's progress (panel, each phase result, the end) to PATH as "
423 "NDJSON while it happens, for an observer in another process; metadata only, "
424 "no reviewer output",
425 )
426 p.add_argument(
427 "--format",
428 choices=["markdown", "json", "sarif", "keel-reviews"],
429 default="markdown",
430 help="output format for stdout/--output (default: markdown); "
431 "'keel-reviews' emits one review record per panelist plus the chair",
432 )
433 p.add_argument(
434 "--decision",
435 choices=["chair", "vote"],
436 default=None,
437 help="final verdict: 'chair' synthesis (default) or panel 'vote' (tally "
438 "the reviewers); overrides [jury] decision",
439 )
440 p.add_argument(
441 "--transcript",
442 dest="transcript",
443 action="store_true",
444 default=None,
445 help="render the full play-by-play transcript (each agent's review, the "
446 "debate, and the chair's reasoning) instead of the summary report",
447 )
448 p.add_argument(
449 "--no-transcript",
450 dest="transcript",
451 action="store_false",
452 help="force the summary report even if [jury] transcript is set",
453 )
454 p.add_argument(
455 "--verbose",
456 dest="verbose",
457 action="store_true",
458 help="summary report followed by the full transcript, in one document",
459 )
460 p.add_argument(
461 "--live",
462 dest="live",
463 action="store_true",
464 help="stream each step (review, debate, verdict) to stdout as it happens; "
465 "add --pr --post to also post each step as its own PR comment",
466 )
467 p.add_argument(
468 "--theater",
469 dest="theater",
470 action="store_true",
471 default=None,
472 help="animated deliberation view of the live run (each model seated "
473 "around a table, speaking per phase, panel-vote/chair finale); needs an "
474 "interactive terminal, else falls back to --live. Can be defaulted on in "
475 "jury.toml ([jury] theater = true)",
476 )
477 p.add_argument(
478 "--no-theater",
479 dest="theater",
480 action="store_false",
481 help="disable the theater scene even if jury.toml enables it",
482 )
483 p.add_argument(
484 "--theater-style",
485 dest="theater_style",
486 choices=("flat", "pixel"),
487 default=None,
488 help="--theater scene style: 'flat' (ANSI line scene, default) or "
489 "'pixel' (pixel-art room; needs a truecolor+unicode terminal). Defaults "
490 "from jury.toml ([jury] theater_style)",
491 )
492 p.add_argument(
493 "--post-summary",
494 "--post",
495 dest="post_summary",
496 action="store_true",
497 help="post the report as a single summary comment on --pr",
498 )
499 p.add_argument(
500 "--post-marker",
501 dest="post_marker",
502 action="store_true",
503 help="after a PR review, post a minimal comment carrying only the "
504 "arc-reviewed-sha marker for the head the review started on, so a later "
505 "--incremental run can narrow even when you post the verdict yourself "
506 "(--post-summary already carries the marker). PR only",
507 )
508 p.add_argument(
509 "--no-attribution",
510 dest="attribution",
511 action="store_false",
512 default=None,
513 help="leave the ai-jury footer naming the seats that reviewed off the "
514 "markdown report and posted comments (default from jury.toml "
515 "[jury.output] attribution, on)",
516 )
517 p.add_argument(
518 "--post-inline",
519 dest="post_inline",
520 action="store_true",
521 help="post inline review comments for located findings on --pr",
522 )
523 p.add_argument(
524 "--post-progress",
525 dest="post_progress",
526 action="store_true",
527 help="keep a live, sticky status comment on --pr updated per round/chunk",
528 )
529 p.add_argument(
530 "--post-mode",
531 choices=["single", "phased"],
532 # None is "not passed" (read as 'single'), so a `--post-mode` with no
533 # summary to shape can be told apart from the default and refused.
534 default=None,
535 help="with --post-summary: 'single' (one comment) or 'phased' (separate "
536 "Round 1 / debate / decision comments)",
537 )
538 p.add_argument(
539 "--dry-run",
540 dest="dry_run",
541 action="store_true",
542 help="with --post-inline, print what would be posted without calling GitHub",
543 )
544 p.add_argument(
545 "--label",
546 dest="label",
547 action="store_true",
548 help="apply classification labels (review effort / risk / security) to "
549 "--pr (off by default; never applied automatically)",
550 )
551 p.add_argument(
552 "--ci",
553 action="store_true",
554 help="CI mode: exit non-zero when blocking findings remain",
555 )
556 p.add_argument(
557 "--fail-on",
558 help="comma-separated severities that fail CI (overrides config)",
559 )
560 p.add_argument(
561 "--cache",
562 action="store_true",
563 help="use the local result cache: reuse a cached outcome for an unchanged "
564 "diff+config, else run and store it (off by default)",
565 )
566 p.add_argument(
567 "--clear-cache",
568 action="store_true",
569 help="delete all local cache entries and exit (also: `jury cache clear`)",
570 )
571 p.add_argument(
572 "--cache-dir",
573 help="override the cache directory (default: $JURY_CACHE_DIR or ~/.cache/ai-jury)",
574 )
575 p.add_argument(
576 "--suggest-patches",
577 dest="suggest_patches",
578 action="store_true",
579 help="emit a separate, opt-in suggested-patches section for VERIFIED "
580 "findings (read-only; never applied automatically)",
581 )
582 p.add_argument(
583 "--patches-out",
584 metavar="PATH",
585 help="with --suggest-patches, write the patches to this file instead of "
586 "appending them after the report",
587 )
588 p.add_argument(
589 "--incremental",
590 action="store_true",
591 help="review only the diff since the last jury run on --pr when a prior "
592 "marker exists, else fall back to a full review",
593 )
594 p.add_argument("-q", "--quiet", action="store_true", help="suppress progress logs on stderr")
595 p.add_argument(
596 "--config-validate",
597 action="store_true",
598 help="validate the resolved config and exit (0 valid, 2 invalid)",
599 )
600 p.add_argument(
601 "--strict-config",
602 action="store_true",
603 help="treat configuration warnings as errors",
604 )
605 p.add_argument(
606 "--tiered",
607 action="store_true",
608 help="opt-in risk-aware tiered model routing with frontier anchor (issue #524)",
609 )
610 p.add_argument(
611 "--hints",
612 dest="hints",
613 action="store_true",
614 default=None,
615 help="run local static analysis pre-pass (Ruff/ESLint) to inject hints (issue #523)",
616 )
617 p.add_argument(
618 "--no-hints",
619 dest="hints",
620 action="store_false",
621 help="skip the static analysis pre-pass even if jury.toml enables it",
622 )
623 p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
624 return p
627def _run_apply(rest: list[str]) -> int:
628 """Handle `jury apply` (issue #521): apply verified patch suggestions."""
629 from .patches import (
630 apply_patch_suggestion,
631 parse_patch_suggestions,
632 preview_patch_suggestion,
633 )
635 sub = argparse.ArgumentParser(
636 prog="jury apply", description="Apply verified suggested patches to the repository."
637 )
638 sub.add_argument(
639 "index",
640 nargs="?",
641 default=None,
642 help="1-indexed patch suggestion number to apply, or 'all'. Required — "
643 "applying every suggestion is the wrong default for a command that "
644 "writes to the working tree",
645 )
646 sub.add_argument(
647 "--report",
648 "-r",
649 help="Path to a markdown report file or patch file (defaults to stdin)",
650 )
651 sub.add_argument(
652 "--dry-run",
653 action="store_true",
654 help="Print the paths each suggestion would touch and write nothing",
655 )
656 sub.add_argument(
657 "--yes",
658 "-y",
659 action="store_true",
660 help="Skip the confirmation prompt; required when stdin is not a terminal",
661 )
662 ns = sub.parse_args(rest)
664 content = ""
665 if ns.report:
666 p = Path(ns.report)
667 try:
668 if not p.is_file():
669 print(f"Error: report file not found: {ns.report}", file=sys.stderr)
670 return 2
671 content = p.read_text(encoding="utf-8")
672 except (OSError, UnicodeDecodeError) as exc:
673 print(
674 f"Error reading report file '{ns.report}': {redact(str(exc))[0]}", file=sys.stderr
675 )
676 return 2
677 elif sys.stdin is not None and not sys.stdin.isatty():
678 content = sys.stdin.read()
679 else:
680 print(
681 "Error: provide a report file via --report <file> or pipe a report via stdin",
682 file=sys.stderr,
683 )
684 return 2
686 suggestions = parse_patch_suggestions(content)
687 if not suggestions:
688 print("No verified patch suggestions found in the provided report.", file=sys.stderr)
689 return 1
691 if ns.index is None:
692 print(
693 f"Error: choose what to apply — an index from 1 to {len(suggestions)}, or 'all'.\n"
694 " `jury apply --dry-run all` shows what each one would touch.",
695 file=sys.stderr,
696 )
697 return 2
699 if ns.index.lower() == "all":
700 selected = list(enumerate(suggestions, 1))
701 else:
702 try:
703 target_idx = int(ns.index) - 1
704 except ValueError:
705 print(f"Error: invalid index '{ns.index}'", file=sys.stderr)
706 return 2
707 if not (0 <= target_idx < len(suggestions)):
708 print(
709 f"Error: patch index {ns.index} out of range (found {len(suggestions)} suggestions)",
710 file=sys.stderr,
711 )
712 return 2
713 selected = [(target_idx + 1, suggestions[target_idx])]
715 # Preview before writing, always. The report is derived from a diff that may be
716 # attacker-influenced and its suggestions were written by an LLM, so the
717 # operator gets git's own answer about what would change *before* anything
718 # changes. The old output was printed after the write had happened (#605).
719 print("These suggestions would touch:", file=sys.stderr)
720 for number, suggestion in selected:
721 paths, refusal = preview_patch_suggestion(suggestion)
722 listed = ", ".join(paths) if paths else "(nothing git could read)"
723 print(f" [{number}] {suggestion.file}: {listed}", file=sys.stderr)
724 if refusal is not None:
725 print(f" would be refused: {refusal}", file=sys.stderr)
727 if ns.dry_run:
728 print("Dry run: nothing was written.", file=sys.stderr)
729 return 0
731 if not ns.yes:
732 # Piping a report in is exactly the unattended case, and stdin may already
733 # be consumed by the report itself — so silence is refused rather than read
734 # as consent.
735 if sys.stdin is None or not sys.stdin.isatty():
736 print(
737 "Error: refusing to write without confirmation. Re-run with --yes to "
738 "confirm, or --dry-run to preview.",
739 file=sys.stderr,
740 )
741 return 2
742 answer = input(f"Apply {len(selected)} suggestion(s)? [y/N] ").strip().lower()
743 if answer not in ("y", "yes"):
744 print("Aborted; nothing was written.", file=sys.stderr)
745 return 1
747 success_count = 0
748 total = len(selected)
749 for number, suggestion in selected:
750 ok, msg = apply_patch_suggestion(suggestion)
751 if ok:
752 success_count += 1
753 print(f"✓ [{number}/{total}] {msg}")
754 else:
755 print(f"✗ [{number}/{total}] {msg}", file=sys.stderr)
756 return 0 if success_count > 0 else 1
759def _run_comment_command(rest: list[str]) -> int:
760 """Handle ``jury comment`` (issue #11): parse an allowlisted PR-comment
761 command and either print the resolved jury args or dispatch the run.
763 Returns 2 on a rejected/invalid command (so a workflow can ignore it), else
764 the dispatched run's exit code (or 0 with --print-args).
765 """
766 import shlex
768 from .commands import CommandError, parse_comment
770 sub = argparse.ArgumentParser(prog="jury comment", add_help=True)
771 sub.add_argument("--text", required=True, help="the PR comment body to parse")
772 sub.add_argument("--pr", help="PR number/URL to review and post back to")
773 sub.add_argument("--repo", help="owner/name (defaults to current repo)")
774 sub.add_argument(
775 "--print-args",
776 dest="print_args",
777 action="store_true",
778 help="print the resolved jury args instead of running",
779 )
780 sub.add_argument(
781 "--no-post",
782 dest="no_post",
783 action="store_true",
784 help="do not post the result back as a summary comment",
785 )
786 ns = sub.parse_args(rest)
788 try:
789 parsed = parse_comment(ns.text)
790 except CommandError as exc:
791 print(f"comment command rejected: {redact(str(exc))[0]}", file=sys.stderr)
792 return 2
794 inner = parsed.to_cli_args()
795 if ns.pr:
796 inner += ["--pr", ns.pr]
797 if not ns.no_post:
798 inner += ["--post-summary"]
799 if ns.repo:
800 inner += ["--repo", ns.repo]
802 if ns.print_args:
803 print(" ".join(shlex.quote(a) for a in inner))
804 return 0
805 return main(inner)
808_AGENT_BLURB = {
809 "claude": "Claude Code (Anthropic)",
810 "codex": "Codex CLI (OpenAI)",
811 "agy": "Antigravity (Google) — opt-in only, cannot be confined",
812 "qwen": "local / open-weight via Ollama (free, offline)",
813 "claude-api": "hosted Anthropic API (ANTHROPIC_API_KEY, no CLI needed)",
814 "codex-api": "hosted OpenAI API (OPENAI_API_KEY, no CLI needed)",
815 "gemini-api": "hosted Google Gemini API (GEMINI_API_KEY, no CLI needed)",
816 "openrouter": "hosted OpenRouter API (OPENROUTER_API_KEY)",
817 "deepseek": "hosted DeepSeek API (DEEPSEEK_API_KEY)",
818 "groq": "hosted Groq API (GROQ_API_KEY)",
819 "aider": "generic CLI coding agent (Aider)",
820}
823def _default_init_agents(available: dict) -> list[str]:
824 """The agents an interactive `jury init` pre-fills: detected, never opt-in-only.
826 agy stays listed and can be typed in, but pressing Enter never seats it.
827 """
828 from .scaffold import KNOWN_AGENTS, implicit_choices
830 detected = implicit_choices(n for n in KNOWN_AGENTS if available.get(n))
831 return detected or implicit_choices(KNOWN_AGENTS)
834def _init_available() -> dict:
835 """Map each known agent name to whether it is reachable right now."""
836 from .config import AgentSpec
837 from .scaffold import KNOWN_AGENTS, agent_templates
839 templates = agent_templates()
840 out = {}
841 for name in KNOWN_AGENTS:
842 try:
843 out[name] = make_adapter(AgentSpec(**templates[name])).available()
844 except Exception: # noqa: BLE001 - detection is best-effort
845 out[name] = False
846 return out
849def _stdin_is_terminal() -> bool:
850 """Whether ``jury init`` can prompt: stdin exists and is a terminal.
852 ``sys.stdin`` is ``None`` when the process has no stdin at all (a detached
853 or daemonised launch), and ``None.isatty()`` is an ``AttributeError`` (#897).
854 """
855 return sys.stdin is not None and sys.stdin.isatty()
858def _init_interactive(available: dict, input_fn=input, local_endpoint=None, models_fn=None) -> dict:
859 """Prompt for jury settings; returns kwargs for scaffold.build_config.
861 ``input_fn`` and ``models_fn`` are injectable for testing (the latter lists
862 local models). Defaults are pre-filled from the detected agents/models so
863 pressing Enter accepts a sensible config.
864 """
865 from .scaffold import KNOWN_AGENTS
867 if models_fn is None:
868 from .adapters import list_local_models as models_fn
870 print("Configure a review jury (jury.toml).\n", file=sys.stderr)
871 for name in KNOWN_AGENTS:
872 mark = "available" if available.get(name) else "not found"
873 print(f" - {name}: {_AGENT_BLURB[name]} [{mark}]", file=sys.stderr)
874 default_agents = _default_init_agents(available)
875 raw_agents = input_fn(f"\nAgents to include [default: {','.join(default_agents)}]: ").strip()
876 agents = [a.strip() for a in raw_agents.split(",") if a.strip()] or default_agents
878 rounds_raw = input_fn("Rounds — 1=review, 2=+debate [2]: ").strip()
879 rounds = int(rounds_raw) if rounds_raw.isdigit() else 2
881 chair_default = agents[0] if agents else "claude"
882 chair = input_fn(f"Chair agent [{chair_default}]: ").strip() or chair_default
884 verify = (input_fn("Run verification round? [Y/n]: ").strip().lower() or "y") != "n"
886 local_model = None
887 has_local = any(a in agents for a in ("qwen", "local"))
888 if has_local:
889 from .scaffold import pick_default_model
891 models = models_fn(local_endpoint or "http://localhost:11434/v1")
892 if models:
893 default = pick_default_model(models)
894 print("\nLocal models available on the server:", file=sys.stderr)
895 for i, m in enumerate(models, 1):
896 star = " (default)" if m == default else ""
897 print(f" {i}. {m}{star}", file=sys.stderr)
898 raw = input_fn(f"Pick a local model [number or name, default: {default}]: ").strip()
899 if raw.isdigit() and 1 <= int(raw) <= len(models):
900 local_model = models[int(raw) - 1]
901 elif raw:
902 local_model = raw
903 else:
904 local_model = default
905 else:
906 print(
907 "\n(could not reach the local server to list models; using the default)",
908 file=sys.stderr,
909 )
910 local_model = input_fn("Local model name [qwen2.5-coder:7b]: ").strip() or None
912 # Reasoning effort (issue #662). Skippable: Enter leaves it unset, so
913 # nothing is written and every agent keeps its vendor default. Asked last so
914 # the established question order is unchanged.
915 effort_raw = input_fn("Reasoning effort — low/medium/high [skip]: ").strip().lower()
916 effort = effort_raw if effort_raw in EFFORT_LEVELS else None
918 return {
919 "agents": agents,
920 "rounds": rounds,
921 "chair": chair,
922 "verify": verify,
923 "local_model": local_model,
924 "effort": effort,
925 }
928def _init_wizard(available: dict, input_fn=input, local_endpoint=None, models_fn=None) -> dict:
929 """Guided, numbered-option setup for ``jury init --wizard`` (issue #231).
931 Mirrors :func:`_init_interactive`'s injectable params for offline testing.
932 Every question is SKIPPABLE: pressing Enter leaves the setting unset, so it
933 falls back to the built-in default and is NOT written to ``jury.toml`` (which
934 keeps the generated file minimal). Returns kwargs for ``scaffold.build_config``
935 containing only the values the user explicitly chose.
936 """
937 from .scaffold import KNOWN_AGENTS
939 if models_fn is None:
940 from .adapters import list_local_models as models_fn
942 def ask(prompt: str) -> str:
943 return input_fn(prompt).strip()
945 def choose(prompt: str, options: list[str], default_idx: int) -> int | None:
946 """Print numbered options and read a 1-based pick. Enter -> None (skip)."""
947 print(prompt, file=sys.stderr)
948 for i, label in enumerate(options, 1):
949 star = " (default)" if i - 1 == default_idx else ""
950 print(f" {i}. {label}{star}", file=sys.stderr)
951 raw = ask("Pick a number [Enter to keep default]: ")
952 if not raw:
953 return None
954 if raw.isdigit() and 1 <= int(raw) <= len(options):
955 return int(raw) - 1
956 return None
958 print(
959 "jury init --wizard — guided setup (writes jury.toml).\n"
960 "Every question is optional: press Enter to keep the default and skip it;\n"
961 "skipped settings are left at their built-in defaults (not written).\n",
962 file=sys.stderr,
963 )
965 # Reviewers (always written — like plain init).
966 for name in KNOWN_AGENTS:
967 mark = "available" if available.get(name) else "not found"
968 print(f" - {name}: {_AGENT_BLURB[name]} [{mark}]", file=sys.stderr)
969 default_agents = _default_init_agents(available)
970 raw_agents = ask(f"\nReviewers to include [default: {','.join(default_agents)}]: ")
971 agents = [a.strip() for a in raw_agents.split(",") if a.strip()] or default_agents
973 kwargs: dict = {"agents": agents}
975 # Depth -> rounds / early_stop / auto_depth.
976 depth = choose(
977 "\nDepth:",
978 [
979 "1 round (review only)",
980 "2 rounds + debate",
981 "adaptive (early-stop)",
982 "auto-depth (scale to the diff)",
983 ],
984 default_idx=1,
985 )
986 if depth == 0:
987 kwargs["rounds"] = 1
988 elif depth == 1:
989 kwargs["rounds"] = 2
990 elif depth == 2:
991 kwargs["rounds"] = 2
992 kwargs["early_stop"] = True
993 elif depth == 3:
994 kwargs["auto_depth"] = True
996 # Decision: chair (default) or panel vote. Only written on a non-default.
997 decision = choose("\nDecision:", ["chair synthesis", "panel vote"], default_idx=0)
998 if decision == 1:
999 kwargs["decision"] = "vote"
1001 # Verification (always written — like plain init).
1002 verify_raw = ask("\nRun verification round? [Y/n]: ").lower()
1003 if verify_raw:
1004 kwargs["verify"] = verify_raw != "n"
1006 # Context: diff-only (default) or expanded; redact secrets Y/n.
1007 ctx = choose(
1008 "\nContext sent to reviewers:",
1009 ["diff-only", "expanded (include PR context)"],
1010 default_idx=0,
1011 )
1012 if ctx == 1:
1013 kwargs["context_mode"] = "expanded"
1014 redact_raw = ask("Redact secrets before sending? [Y/n]: ").lower()
1015 if redact_raw == "n":
1016 kwargs["redact_secrets"] = False
1018 # CI gate fail-on. Only write [jury.ci] on a non-default pick.
1019 gate = choose(
1020 "\nCI gate — fail on which severities?",
1021 ["critical,major", "critical only", "skip (never fail CI)"],
1022 default_idx=0,
1023 )
1024 if gate == 1:
1025 kwargs["ci_fail_on"] = ["critical"]
1026 elif gate == 2:
1027 kwargs["ci_fail_on"] = []
1029 # Chair (always written — like plain init; default = first reviewer).
1030 chair_default = agents[0] if agents else "claude"
1031 chair = ask(f"\nChair agent [{chair_default}]: ") or chair_default
1032 kwargs["chair"] = chair
1034 # Local model pick when a local reviewer is chosen (reuse init's logic).
1035 if any(a in agents for a in ("qwen", "local")):
1036 from .scaffold import pick_default_model
1038 models = models_fn(local_endpoint or "http://localhost:11434/v1")
1039 if models:
1040 default = pick_default_model(models)
1041 print("\nLocal models available on the server:", file=sys.stderr)
1042 for i, m in enumerate(models, 1):
1043 star = " (default)" if m == default else ""
1044 print(f" {i}. {m}{star}", file=sys.stderr)
1045 raw = ask(f"Pick a local model [number or name, default: {default}]: ")
1046 if raw.isdigit() and 1 <= int(raw) <= len(models):
1047 kwargs["local_model"] = models[int(raw) - 1]
1048 elif raw:
1049 kwargs["local_model"] = raw
1050 else:
1051 kwargs["local_model"] = default
1052 else:
1053 print(
1054 "\n(could not reach the local server to list models; using the default)",
1055 file=sys.stderr,
1056 )
1057 typed = ask("Local model name [qwen2.5-coder:7b]: ")
1058 if typed:
1059 kwargs["local_model"] = typed
1061 return kwargs
1064def _run_init(rest: list[str]) -> int:
1065 """Handle ``jury init`` (issue #107): scaffold a jury.toml."""
1066 from .config import AGY_OPT_IN_NOTE, ConfigError, validate_config
1067 from .scaffold import (
1068 KNOWN_AGENTS,
1069 OPT_IN_AGENTS,
1070 PRESETS,
1071 agent_templates,
1072 agents_needing_remote_opt_in,
1073 build_config,
1074 implicit_choices,
1075 render_toml,
1076 seat_local_agents,
1077 )
1079 sub = argparse.ArgumentParser(prog="jury init")
1080 sub.add_argument(
1081 "--preset",
1082 choices=sorted(PRESETS),
1083 help="setup preset: offline (local-only), fast (1 round), balanced "
1084 "(debate + early-stop), thorough (all agents + debate + verify)",
1085 )
1086 sub.add_argument(
1087 "--agents",
1088 help="comma-separated: claude,codex,qwen (agy only by name: it cannot be confined)",
1089 )
1090 sub.add_argument("--rounds", type=int, default=None)
1091 sub.add_argument("--chair")
1092 sub.add_argument("--verify", dest="verify", action="store_true", default=None)
1093 sub.add_argument("--no-verify", dest="verify", action="store_false")
1094 sub.add_argument("--local-model", help="model id for a local agent (qwen)")
1095 sub.add_argument("--local-endpoint", help="OpenAI-compatible base URL for a local agent")
1096 sub.add_argument("-o", "--output", default="jury.toml")
1097 sub.add_argument("--force", action="store_true", help="overwrite an existing file")
1098 sub.add_argument("--interactive", action="store_true", help="force interactive prompts")
1099 sub.add_argument(
1100 "--wizard",
1101 action="store_true",
1102 help="guided, numbered-option setup; every question is skippable (Enter "
1103 "keeps the built-in default) and only chosen keys are written",
1104 )
1105 sub.add_argument(
1106 "--list-agents", action="store_true", help="list known agents + availability and exit"
1107 )
1108 sub.add_argument(
1109 "--list-models", action="store_true", help="list local models on the server and exit"
1110 )
1111 ns = sub.parse_args(rest)
1113 # The wizard reads every answer from a terminal. With none — CI, a pipe, an
1114 # agent's shell — its first prompt died as an `EOFError` traceback (#865), so it
1115 # is refused here, before the availability probes spend anything. The listing
1116 # flags answer before the wizard would ever ask, so they are left to do so.
1117 listing = ns.list_models or ns.list_agents
1118 if ns.wizard and not listing and not _stdin_is_terminal():
1119 print(
1120 "error: the wizard needs a terminal; use `jury init --preset <name>`",
1121 file=sys.stderr,
1122 )
1123 return 2
1124 # `--interactive` is the same promise and died the same way (#897): an
1125 # `EOFError` on its first prompt from a pipe, and with no stdin at all an
1126 # `AttributeError` from the TTY test below. Refused where it would prompt —
1127 # `--agents`/`--preset` answer the questions, so it never asks then.
1128 if ns.interactive and not (listing or ns.agents or ns.preset) and not _stdin_is_terminal():
1129 print(
1130 "error: --interactive needs a terminal; use `jury init --preset <name>` "
1131 "or `jury init --agents <list>`",
1132 file=sys.stderr,
1133 )
1134 return 2
1136 from .adapters import list_local_models, local_model_listing
1137 from .redaction import redact_url_userinfo
1139 endpoint = ns.local_endpoint or "http://localhost:11434/v1"
1140 # Strip any userinfo credentials before echoing the endpoint to stdout/CI
1141 # logs (issue #316/L-7, completed in v1.5.0/L-1: structural strip catches
1142 # short and colon-less userinfo the regex missed), mirroring doctor.py.
1143 endpoint_disp = redact_url_userinfo(endpoint)
1145 if ns.list_models:
1146 models = list_local_models(endpoint)
1147 if not models:
1148 print(f"No local models found (is a server reachable at {endpoint_disp}?).")
1149 return 0
1150 print(f"Local models at {endpoint_disp}:")
1151 for m in models:
1152 print(f" - {m}")
1153 return 0
1155 available = _init_available()
1157 if ns.list_agents:
1158 for name in KNOWN_AGENTS:
1159 mark = "available" if available.get(name) else "not found"
1160 print(f"{name:8} {_AGENT_BLURB[name]:45} [{mark}]")
1161 # Show discovered local models so the user sees what they can pick.
1162 models = list_local_models(endpoint)
1163 if models:
1164 print(f"\nlocal models at {endpoint_disp}: {', '.join(models)}")
1165 return 0
1167 preset = PRESETS.get(ns.preset, {})
1168 templates = agent_templates()
1169 # Seats `jury init` writes commented out, under a hint (#864). Only plain init
1170 # fills it; the prompts and the wizard ask the operator instead.
1171 commented: list[dict] = []
1173 def _detected_agents():
1174 # Never an opt-in-only agent (agy): "detected" is a default, not a choice.
1175 return implicit_choices(n for n in KNOWN_AGENTS if available.get(n))
1177 def _selectable_agents():
1178 """Every known agent whose template scaffolds to a *valid* config here.
1180 Three hosted templates point at real vendor hosts, and `config` refuses
1181 a non-loopback endpoint unless `JURY_ALLOW_REMOTE_ENDPOINT` is set. A
1182 preset that silently includes them writes a config `jury init` then
1183 rejects — so `--preset thorough` failed outright rather than producing
1184 something usable. They stay in `--list-agents` and remain selectable by
1185 name; they are only excluded from "all" until the opt-in is present.
1186 """
1187 if os.environ.get("JURY_ALLOW_REMOTE_ENDPOINT"): 1187 ↛ 1188line 1187 didn't jump to line 1188 because the condition on line 1187 was never true
1188 return implicit_choices(KNOWN_AGENTS)
1189 needs_opt_in = set(agents_needing_remote_opt_in())
1190 return implicit_choices(n for n in KNOWN_AGENTS if n not in needs_opt_in)
1192 def _resolve_preset_agents(spec):
1193 if spec == "all":
1194 return _selectable_agents()
1195 if spec == "detected":
1196 return _detected_agents() or _selectable_agents()
1197 return list(spec)
1199 # rounds / verify / early_stop: explicit flag > preset > built-in default.
1200 rounds = ns.rounds if ns.rounds is not None else preset.get("rounds", 2)
1201 verify = ns.verify if ns.verify is not None else preset.get("verify", True)
1202 early_stop = preset.get("early_stop")
1204 # Guided wizard (issue #231): opt-in via --wizard. A numbered-option flow
1205 # where every question is skippable; only explicitly-chosen settings are
1206 # written, so the file stays minimal. Explicit, so it skips the TTY test the
1207 # prompts below use; a missing terminal was refused above instead (#865).
1208 if ns.wizard:
1209 kwargs = _init_wizard(available, local_endpoint=ns.local_endpoint)
1210 kwargs["local_endpoint"] = ns.local_endpoint
1211 if ns.local_model:
1212 kwargs["local_model"] = ns.local_model
1213 # Interactive only when neither --agents nor --preset was given and we're on a
1214 # TTY (or --interactive, refused above without one). Presets/flags are
1215 # non-interactive by design. With no stdin at all, plain init detects (#897).
1216 elif not ns.agents and not ns.preset and (ns.interactive or _stdin_is_terminal()):
1217 kwargs = _init_interactive(available, local_endpoint=ns.local_endpoint)
1218 kwargs["local_endpoint"] = ns.local_endpoint
1219 if ns.local_model:
1220 kwargs["local_model"] = ns.local_model
1221 else:
1222 if ns.agents:
1223 agents = [a.strip() for a in ns.agents.split(",") if a.strip()]
1224 elif ns.preset:
1225 agents = _resolve_preset_agents(preset["agents"])
1226 else:
1227 agents = _detected_agents()
1228 if not agents:
1229 print(
1230 "error: no agents detected and none specified; pass --agents "
1231 "or --preset (e.g. --preset offline), or run interactively.",
1232 file=sys.stderr,
1233 )
1234 if available.get("agy"):
1235 print(f"note: {AGY_OPT_IN_NOTE}.", file=sys.stderr)
1236 return 2
1237 # A local seat names a model its server lists, as the prompts and the wizard
1238 # already did (#864); plain init wrote the template's model and then warned
1239 # about it. Asked only when a local seat is chosen and no model was named.
1240 # `local_model_listing`, not `list_local_models`: only a server that answered
1241 # with no model gets its seat commented out, and a failed listing (None)
1242 # leaves the seat as it was — no evidence is not evidence of a fault (#849).
1243 local_model = ns.local_model
1244 if not local_model and any(templates.get(a, {}).get("vendor") == "local" for a in agents):
1245 agents, local_model, left_out = seat_local_agents(agents, local_model_listing(endpoint))
1246 if left_out and ns.chair in left_out:
1247 # The operator named this chair. Writing it over a commented seat warns
1248 # on every run, and picking another chair overrides them, so neither.
1249 print(
1250 f"error: the chair {ns.chair} is the local seat, but the server at "
1251 f"{endpoint_disp} lists no model; pass --local-model <model> or choose "
1252 "another --chair",
1253 file=sys.stderr,
1254 )
1255 return 2
1256 if left_out:
1257 commented = build_config(left_out, local_endpoint=ns.local_endpoint)["agent"]
1258 print(
1259 f"note: the local server at {endpoint_disp} lists no model, so "
1260 f"{', '.join(repr(a) for a in left_out)} is written commented out; "
1261 "pull one and uncomment it, or pass --local-model.",
1262 file=sys.stderr,
1263 )
1264 kwargs = {
1265 "agents": agents,
1266 "rounds": rounds,
1267 "chair": ns.chair,
1268 "verify": verify,
1269 "early_stop": early_stop,
1270 "local_model": local_model,
1271 "local_endpoint": ns.local_endpoint,
1272 }
1274 try:
1275 config = build_config(**kwargs)
1276 except ValueError as exc:
1277 print(f"error: {redact(str(exc))[0]}", file=sys.stderr)
1278 return 2
1280 # The scaffolded config must itself be valid (fail loudly if a template drifts).
1281 try:
1282 validate_config(config)
1283 except ConfigError as exc:
1284 print(f"error: generated config is invalid: {redact(str(exc))[0]}", file=sys.stderr)
1285 return 2
1287 out_path = Path(ns.output)
1288 if out_path.exists() and not ns.force:
1289 print(
1290 f"error: {out_path} already exists; pass --force to overwrite.",
1291 file=sys.stderr,
1292 )
1293 return 2
1295 out_path.write_text(render_toml(config, commented_agents=commented), encoding="utf-8")
1296 # This config is the operator's own deliberate act, so record it as trusted: the
1297 # ordinary `jury init` → `jury` path then never has to ask (#831).
1298 configtrust.record_trust(out_path, configtrust.content_digest(out_path.read_bytes()))
1299 chosen = ", ".join(a["name"] for a in config["agent"])
1300 print(f"Wrote {out_path} — panel: {chosen} · rounds: {config['jury']['rounds']}")
1301 # Seated by name only, so the operator chose it — say what they chose.
1302 if any(a["name"] in OPT_IN_AGENTS for a in config["agent"]):
1303 print(
1304 "warning: agy cannot be confined (it reads, writes and reaches the network "
1305 "even with --sandbox); do not use it on untrusted diffs. A review run warns "
1306 "about this seat, and `--strict` fails on it.",
1307 file=sys.stderr,
1308 )
1309 # A local seat whose server does not list its model is still a valid config,
1310 # so it is written — but said now, not discovered by the first review as an
1311 # `HTTP 404` (#849). `--list-models` already knew; init never asked. The
1312 # doctor's own diagnosis is reused so the two cannot disagree about a seat.
1313 from types import SimpleNamespace
1315 from .doctor import _local_model_gap
1317 for agent in config["agent"]:
1318 fields = ("name", "vendor", "adapter", "endpoint", "model")
1319 gap = _local_model_gap(SimpleNamespace(**{k: agent.get(k) for k in fields}))
1320 if gap:
1321 print(f"warning: agent '{agent['name']}': {gap[1]}", file=sys.stderr)
1322 print(f"Next: jury --config-validate --config {out_path}")
1323 print("Then: git diff main... | jury --diff-file -")
1324 return 0
1327def _config_read_error(exc: OSError, config_arg) -> str:
1328 """The one line a config that exists but cannot be read is reported with (#893).
1330 Every config load site catches ``ConfigError`` and ``FileNotFoundError``, but an
1331 unreadable ``./jury.toml`` raises ``PermissionError`` and ``--config <directory>``
1332 raises ``IsADirectoryError`` (``PermissionError`` on Windows), and both escaped as a
1333 traceback. The path comes from the exception, so an auto-discovered ``jury.toml`` is
1334 named as well as an explicit one; ``strerror`` is the reason without the errno and
1335 path ``str(exc)`` would repeat.
1336 """
1337 path = exc.filename or config_arg or "jury.toml"
1338 reason = exc.strerror or str(exc)
1339 return redact(f"error: cannot read config {path}: {reason}")[0]
1342def _config_source(config_arg) -> str:
1343 """Human-readable source of the config the jury would load."""
1344 if config_arg:
1345 return str(config_arg)
1346 return "jury.toml" if Path("jury.toml").exists() else "(built-in defaults)"
1349def _render_effective_config(cfg) -> str:
1350 """Render the EFFECTIVE resolved config as a readable summary (config show)."""
1351 on = lambda b: "on" if b else "off" # noqa: E731
1352 lines = []
1353 lines.append(
1354 f"[jury] rounds={cfg.rounds} chair={cfg.chair} verify={on(cfg.verify)} "
1355 f"parallel={on(cfg.parallel)} timeout={cfg.timeout}s"
1356 )
1357 adaptive = f"early_stop={on(cfg.early_stop)} max_rounds={cfg.effective_max_rounds}"
1358 budget = (
1359 f"total_timeout={cfg.total_timeout or '—'} "
1360 f"phase_timeout={cfg.phase_timeout or '—'} retries={cfg.retries}"
1361 )
1362 lines.append(
1363 f" {adaptive} · {budget} · seed={cfg.seed if cfg.seed is not None else '—'}"
1364 )
1365 lines.append(
1366 f"[jury.ci] fail_on={cfg.ci.fail_on} ignore_unverified={on(cfg.ci.ignore_unverified)}"
1367 )
1368 lines.append(
1369 f"[jury.context] mode={cfg.context.mode} redact_secrets={on(cfg.context.redact_secrets)}"
1370 )
1371 d = cfg.diff
1372 lines.append(
1373 f"[jury.diff] max_bytes={d.max_bytes} chunk={on(d.chunk)} "
1374 f"exclude_generated={on(d.exclude_generated)} "
1375 f"exclude={d.exclude or '[]'} include={d.include or '[]'}"
1376 )
1377 lines.append("agents:")
1378 for a in cfg.agents:
1379 flag = "" if a.enabled else " (disabled)"
1380 target = a.endpoint if a.adapter_key == "local" else (a.command or "—")
1381 model = f" model={a.model}" if a.model else ""
1382 # The adapter is shown only when it is not the vendor's own (#705), so
1383 # this line keeps its shape for every configuration that predates the key.
1384 via = f" via {a.adapter_key}" if a.adapter_key != a.vendor else ""
1385 lines.append(f" - {a.name} ({a.vendor}{via}) → {target}{model}{flag}")
1386 return "\n".join(lines)
1389def _run_config(rest: list[str]) -> int:
1390 """Handle ``jury config show|path``."""
1391 from .config import ConfigError, load_config
1393 sub = argparse.ArgumentParser(prog="jury config")
1394 sub.add_argument("action", choices=["show", "path"])
1395 sub.add_argument("--config", help="path to jury.toml (default: ./jury.toml or built-in)")
1396 ns = sub.parse_args(rest)
1398 source = _config_source(ns.config)
1399 if ns.action == "path":
1400 print(source)
1401 return 0
1403 try:
1404 cfg = load_config(ns.config, validate=True)
1405 except (ConfigError, FileNotFoundError) as exc:
1406 print(f"error: {redact(str(exc))[0]}", file=sys.stderr)
1407 return 2
1408 except OSError as exc:
1409 print(_config_read_error(exc, ns.config), file=sys.stderr)
1410 return 2
1411 print(f"source: {source}")
1412 print(_render_effective_config(cfg))
1413 return 0
1416# Cap on a prompt file. An orchestrator's prompt is a few KB of instructions
1417# plus, at most, a diff; this only bounds memory against a pathological file.
1418_MAX_PROMPT_BYTES = 8 * 1024 * 1024
1421def _read_prompt(path: str) -> tuple[str, str | None]:
1422 """Read a prompt file (or stdin for ``-``). Returns ``(text, error)``."""
1423 if path == "-":
1424 stream = sys.stdin.buffer if sys.stdin is not None else None
1425 if stream is None:
1426 return "", "cannot read the prompt from stdin: stdin is not available"
1427 raw = stream.read(_MAX_PROMPT_BYTES + 1)
1428 else:
1429 target = Path(path)
1430 if not target.is_file():
1431 return "", f"prompt file not found: {path}"
1432 try:
1433 raw = target.read_bytes()[: _MAX_PROMPT_BYTES + 1]
1434 except OSError as exc:
1435 return "", f"could not read prompt file '{path}': {redact(str(exc))[0]}"
1436 if len(raw) > _MAX_PROMPT_BYTES:
1437 return "", f"prompt exceeds the {_MAX_PROMPT_BYTES}-byte limit"
1438 text = raw.decode("utf-8", errors="replace")
1439 if not text.strip():
1440 return "", "empty prompt — nothing to send to the agent"
1441 return text, None
1444def _run_agent_parser() -> argparse.ArgumentParser:
1445 """The ``jury run-agent`` flag surface (built separately so it can be tested)."""
1446 from . import runagent
1448 sub = argparse.ArgumentParser(
1449 prog="jury run-agent",
1450 description="Run ONE configured agent for one role and print a JSON "
1451 "result with attribution. The integration point for an orchestrator "
1452 "(keel's `keel delegate run`) or a CI script that needs a single "
1453 "agent rather than the whole panel.",
1454 )
1455 sub.add_argument(
1456 "--agent",
1457 help="agent to run: a [[agent]] name from jury.toml, or a built-in "
1458 f"vendor ({', '.join(runagent.BUILTIN_AGENTS)}); append ':<model>' to "
1459 "override the model (e.g. codex:gpt-5.2)",
1460 )
1461 sub.add_argument(
1462 "--role",
1463 help="what the agent is being asked to do: "
1464 f"{'|'.join(runagent.ROLES)}. "
1465 f"{'/'.join(runagent.READ_ONLY_ROLES)} always run read-only; "
1466 f"{'/'.join(sorted(runagent.WRITE_ROLES))} need --allow-write",
1467 )
1468 sub.add_argument("--prompt-file", help="path to the prompt to send, or '-' for stdin")
1469 sub.add_argument(
1470 "--cwd",
1471 help="directory a write role (implement/fix) runs in (default: the current one); "
1472 "read-only roles on claude/codex/agy start in an empty temporary directory",
1473 )
1474 sub.add_argument(
1475 "--timeout",
1476 type=int,
1477 help="seconds before the AGENT is killed (default: the agent's configured "
1478 "timeout). This bounds the agent, never the wait — see --wait-timeout",
1479 )
1480 sub.add_argument(
1481 "--effort",
1482 choices=list(EFFORT_LEVELS),
1483 help="reasoning effort for vendors that support one (see `jury --doctor --json`)",
1484 )
1485 sub.add_argument(
1486 "--allow-write",
1487 action="store_true",
1488 help="grant the vendor's write/tool mode; required by the implement and "
1489 "fix roles, ignored by the read-only ones",
1490 )
1491 sub.add_argument(
1492 "--format",
1493 choices=["json", "text"],
1494 default="json",
1495 help="json: the full result document (default); text: only the agent's text",
1496 )
1497 sub.add_argument(
1498 "--detach",
1499 action="store_true",
1500 help="start the run in the background and print its run id immediately",
1501 )
1502 sub.add_argument(
1503 "--run-id",
1504 help="id for a detached run: letters, digits, '.', '_' or '-', max 64 "
1505 "characters (default: a random one). Only meaningful with --detach",
1506 )
1507 sub.add_argument("--wait", metavar="RUN_ID", help="block until a detached run finishes")
1508 sub.add_argument(
1509 "--wait-timeout",
1510 type=int,
1511 metavar="SECONDS",
1512 help="seconds --wait will block before giving up (default: the run's own "
1513 f"timeout + {runagent.WAIT_GRACE_S}s, else {runagent.DEFAULT_WAIT_TIMEOUT_S}s)",
1514 )
1515 sub.add_argument("--status", action="store_true", help="list detached runs and exit")
1516 sub.add_argument("--config", help="path to jury.toml (default: ./jury.toml or built-in)")
1517 sub.add_argument(
1518 "--cache-dir",
1519 help="where detached-run state lives (default: $JURY_CACHE_DIR or ~/.cache/ai-jury)",
1520 )
1521 sub.add_argument(
1522 "--mock", action="store_true", help="run the offline mock adapter instead of a real agent"
1523 )
1524 sub.add_argument(
1525 "--strict",
1526 action="store_true",
1527 help="refuse (exit 2) a read-only role whose seat draws a least-privilege "
1528 "warning, as a panel run with --strict does",
1529 )
1530 # The detached child re-enters this same command; the flag only tells it to
1531 # record its result in the run's state file. Hidden: it is not a surface
1532 # anyone should call directly.
1533 sub.add_argument("--_child", dest="child", action="store_true", help=argparse.SUPPRESS)
1534 return sub
1537def _child_argv(ns, run_id: str, python: str) -> list[str]:
1538 """The argv of the background child a ``--detach`` run spawns (pure)."""
1539 argv = [
1540 python,
1541 "-m",
1542 "ai_jury",
1543 "run-agent",
1544 "--agent",
1545 ns.agent,
1546 "--role",
1547 ns.role,
1548 "--prompt-file",
1549 str(Path(ns.prompt_file).resolve()),
1550 "--run-id",
1551 run_id,
1552 "--_child",
1553 ]
1554 if ns.cwd:
1555 argv += ["--cwd", str(Path(ns.cwd).resolve())]
1556 if ns.timeout is not None:
1557 argv += ["--timeout", str(ns.timeout)]
1558 if ns.effort:
1559 argv += ["--effort", ns.effort]
1560 if ns.allow_write:
1561 argv.append("--allow-write")
1562 if ns.config:
1563 argv += ["--config", str(Path(ns.config).resolve())]
1564 if ns.cache_dir:
1565 argv += ["--cache-dir", str(Path(ns.cache_dir).resolve())]
1566 if ns.mock:
1567 argv.append("--mock")
1568 if ns.strict:
1569 argv.append("--strict")
1570 return argv
1573def _run_run_agent(rest: list[str], spawn=None, sleep=None, clock=None) -> int:
1574 """Handle ``jury run-agent`` (issue #661): one agent, one role, one JSON result.
1576 Exit codes: ``0`` the agent ran and produced output, ``1`` it ran and
1577 failed (the JSON says why — same fail-soft vocabulary as a panel run),
1578 ``2`` the request itself was refused (bad role, missing write grant,
1579 unknown agent, unreadable prompt).
1580 """
1581 import dataclasses
1582 import time
1584 from . import runagent
1585 from .adapters import effort_args, make_adapter
1587 ns = _run_agent_parser().parse_args(rest)
1589 # Validate every id the caller supplies BEFORE it can reach a path. The
1590 # library refuses an unsafe one on its own (runagent.run_path), so this is
1591 # about the error the operator sees, not about whether the write is safe.
1592 for flag, value in (("--run-id", ns.run_id), ("--wait", ns.wait)):
1593 if value is not None:
1594 problem = runagent.check_run_id(value)
1595 if problem:
1596 print(f"error: {flag}: {problem}", file=sys.stderr)
1597 return 2
1598 if ns.run_id and not (ns.detach or ns.child):
1599 # It named nothing and recorded nothing — silently ignoring it would let
1600 # a script believe it had a handle it could later --wait on.
1601 print(
1602 "error: --run-id only applies to a detached run; add --detach, or "
1603 "drop --run-id to run in the foreground",
1604 file=sys.stderr,
1605 )
1606 return 2
1608 if ns.status:
1609 print(json.dumps({"runs": runagent.list_runs(ns.cache_dir)}, indent=2))
1610 return 0
1612 if ns.wait:
1613 if ns.wait_timeout is not None and ns.wait_timeout <= 0:
1614 print("error: --wait-timeout must be a positive number of seconds", file=sys.stderr)
1615 return 2
1616 # `--detach` reserves the id by writing the state file BEFORE it returns,
1617 # so a run with no state file was never started — a typo, or the wrong
1618 # --cache-dir. Say so now instead of blocking until a deadline expires.
1619 known = runagent.read_state(ns.wait, ns.cache_dir)
1620 if known is None:
1621 print(f"error: no such run '{ns.wait}'", file=sys.stderr)
1622 return 2
1623 # The deadline comes from what the run was actually given (its own
1624 # timeout plus head-room to write its state file), so a long agent run
1625 # is not cut short and a dead one is not waited on forever.
1626 deadline = ns.wait_timeout
1627 if deadline is None:
1628 deadline = runagent.default_wait_timeout(known)
1629 # When liveness cannot be determined, a run that has already died can
1630 # only be noticed when the deadline expires. Say so once, so a long
1631 # silence reads as a known limitation rather than a hung command. The
1632 # opening is cause-neutral and the reason names which case it is —
1633 # "this platform cannot probe" is false on POSIX for a run that simply
1634 # has not been claimed yet. The deadline always applies regardless, so
1635 # the wait is bounded either way.
1636 unknown = runagent.liveness_unknown_reason(known)
1637 if unknown:
1638 print(
1639 f"warning: cannot tell whether run '{ns.wait}' is still alive — "
1640 f"{unknown}; waiting up to {deadline:g}s for it to report",
1641 file=sys.stderr,
1642 )
1643 state, timed_out = runagent.wait_for_run(
1644 ns.wait,
1645 cache_dir=ns.cache_dir,
1646 timeout=deadline,
1647 sleep=sleep or time.sleep,
1648 clock=clock or time.monotonic,
1649 )
1650 if timed_out:
1651 print(
1652 f"error: run '{ns.wait}' did not finish within {deadline:g}s",
1653 file=sys.stderr,
1654 )
1655 return 2
1656 if state is None:
1657 # The file vanished while we waited (a `jury cache clear`, a manual
1658 # rm). Distinguished from "never existed", which returned above.
1659 print(f"error: run '{ns.wait}' disappeared while waiting", file=sys.stderr)
1660 return 2
1661 if state.get("status") == runagent.STATUS_LOST:
1662 # Returned as soon as the pid was seen gone, not at the deadline:
1663 # there is no result coming, and blocking for one is just delay.
1664 print(
1665 f"error: run '{ns.wait}' was lost — its process is gone and it "
1666 f"never recorded a result (see {runagent.output_path(ns.wait, ns.cache_dir)})",
1667 file=sys.stderr,
1668 )
1669 print(json.dumps(state, indent=2))
1670 return 0 if state.get("ok") else 1
1672 missing = [
1673 flag
1674 for flag, value in (
1675 ("--agent", ns.agent),
1676 ("--role", ns.role),
1677 ("--prompt-file", ns.prompt_file),
1678 )
1679 if not value
1680 ]
1681 if missing:
1682 print(
1683 f"error: {', '.join(missing)} required (or use --wait <run-id> / --status)",
1684 file=sys.stderr,
1685 )
1686 return 2
1688 # Role policy first: an implement run without --allow-write must be refused
1689 # before a prompt is read, a config is loaded, or a child is spawned.
1690 policy = runagent.role_policy(ns.role, ns.allow_write)
1691 if policy.refusal:
1692 print(f"error: {policy.refusal}", file=sys.stderr)
1693 return 2
1694 if policy.warning:
1695 print(f"warning: {policy.warning}", file=sys.stderr)
1697 if ns.cwd and not Path(ns.cwd).is_dir():
1698 print(f"error: --cwd is not a directory: {ns.cwd}", file=sys.stderr)
1699 return 2
1700 if ns.cwd and not policy.write:
1701 # Said, not silently dropped: a read-only role on a native CLI starts in an
1702 # empty directory, so a checkout's project settings cannot reach it.
1703 print(
1704 f"note: --cwd applies to write roles; the read-only role '{policy.role}' "
1705 f"starts in an empty temporary directory (claude/codex/agy).",
1706 file=sys.stderr,
1707 )
1709 # Validated as the panel validates it (#903): an `endpoint` on a CLI seat, a
1710 # `command` path rule, an unknown adapter — each refused here as it is by a
1711 # review, `--config-validate`, `jury config` and `--doctor`, rather than
1712 # reaching the spawner as a config the rest of the tool rejects.
1713 try:
1714 config = load_config(ns.config, validate=True)
1715 except (ConfigError, FileNotFoundError) as exc:
1716 print(redact(f"error: {exc}")[0], file=sys.stderr)
1717 return 2
1718 except OSError as exc:
1719 print(_config_read_error(exc, ns.config), file=sys.stderr)
1720 return 2
1722 # run-agent runs a config-defined command too, and a discovered config can even shadow
1723 # a built-in name (`--agent claude` with `command = "sh"`), so it needs the same trust
1724 # gate as a review (#831).
1725 try:
1726 configtrust.enforce(ns.config, config, mock=ns.mock)
1727 except configtrust.ConfigTrustError as exc:
1728 print(f"error: {exc}", file=sys.stderr)
1729 return 2
1731 spec, error = runagent.resolve_agent(config, ns.agent)
1732 if error is not None:
1733 print(f"error: {error}", file=sys.stderr)
1734 return 2
1735 if ns.timeout is not None:
1736 if ns.timeout <= 0:
1737 print("error: --timeout must be a positive number of seconds", file=sys.stderr)
1738 return 2
1739 spec = dataclasses.replace(spec, timeout=ns.timeout)
1740 if ns.effort:
1741 spec = dataclasses.replace(spec, effort=ns.effort)
1742 warning = effort_args(spec.adapter_key, ns.effort, spec.model).warning
1743 if warning:
1744 print(f"warning: {warning}", file=sys.stderr)
1746 # The panel's least-privilege audit, for this one seat (#903). A read-only
1747 # role is spawned with the argv a panel review uses, so it is audited the
1748 # same way, and `--strict` refuses it the same way. A write role is not: it
1749 # asked for write access with `--allow-write`, and the audit describes the
1750 # read-only argv, which is not the one that role runs. Before `--detach`, so a
1751 # refused seat never starts a background run.
1752 if not policy.write:
1753 from .privilege import audit_agent
1755 privilege_warnings = audit_agent(spec)
1756 for w in privilege_warnings:
1757 print(f"warning: least-privilege: {w}", file=sys.stderr)
1758 if ns.strict and privilege_warnings:
1759 print(
1760 "error: least-privilege check failed (--strict): " + "; ".join(privilege_warnings),
1761 file=sys.stderr,
1762 )
1763 return 2
1765 if ns.detach:
1766 return _detach_run_agent(ns, spec, policy, spawn=spawn)
1768 prompt, error = _read_prompt(ns.prompt_file)
1769 if error is not None:
1770 print(f"error: {error}", file=sys.stderr)
1771 return 2
1773 # The adapter name is also checked where it is used (#708). Unreachable today:
1774 # validation above refuses an unknown adapter (#903), and a built-in agent
1775 # names none. Kept so a future path that skips validation fails with the
1776 # config error, not a traceback.
1777 try:
1778 adapter = make_adapter(spec, mock=ns.mock)
1779 except ConfigError as exc: # pragma: no cover - see above
1780 print(redact(f"error: {exc}")[0], file=sys.stderr)
1781 return 2
1782 print(
1783 f"run-agent: {spec.name} ({spec.vendor}) role={policy.role} "
1784 f"{'write' if policy.write else 'read-only'}",
1785 file=sys.stderr,
1786 )
1787 started = time.time()
1788 record = _child_recorder(ns, spec, policy, started) if ns.child and ns.run_id else None
1789 if record is not None:
1790 # Claim the run with our OWN pid before doing any work. Every write to
1791 # this state file now comes from this process, in order, so nothing can
1792 # overwrite the terminal document the way the parent's post-spawn write
1793 # used to. Until this lands the run has no pid, which reads as
1794 # "liveness unknown" — reported as running, never as lost.
1795 record(runagent.initial_state(ns.run_id, spec, policy.role, started), terminal=False)
1796 try:
1797 if ns.cwd:
1798 with contextlib.chdir(ns.cwd):
1799 result = adapter.run(prompt, phase=policy.role, role_policy=policy)
1800 else:
1801 result = adapter.run(prompt, phase=policy.role, role_policy=policy)
1802 # The second (and last) place a seat is invoked, so it records the id it
1803 # sent exactly as the orchestrator's does (#709).
1804 result.model = adapter.resolved_model()
1805 document = runagent.result_dict(spec, policy.role, result)
1806 except BaseException as exc:
1807 # A detached child that dies without writing leaves its run at
1808 # "running" forever, and a `--wait` on it can only time out. Adapters
1809 # are fail-soft, so reaching here means something unexpected — a
1810 # KeyboardInterrupt, a bug — and the run must still end in a terminal
1811 # state that says so. Re-raised: this records the death, it does not
1812 # swallow it.
1813 if record is not None: 1813 ↛ 1815line 1813 didn't jump to line 1815 because the condition on line 1813 was always true
1814 record(_crash_document(spec, policy.role, started, exc))
1815 raise
1817 if record is not None:
1818 record(document)
1819 if ns.format == "text":
1820 print(document["text"])
1821 else:
1822 print(json.dumps(document, indent=2))
1823 return 0 if document["ok"] else 1
1826def _crash_document(spec, role: str, started: float, exc: BaseException) -> dict:
1827 """A result document for a child that died before producing one (#661)."""
1828 import time
1830 from . import runagent
1831 from .adapters import ERR_UNKNOWN, AgentResult
1833 reason = f"{type(exc).__name__}: {redact(str(exc))[0]}"
1834 return runagent.result_dict(
1835 spec,
1836 role,
1837 AgentResult(
1838 spec.name,
1839 spec.vendor,
1840 False,
1841 "",
1842 max(0.0, time.time() - started),
1843 f"run-agent exited before the agent finished: {reason}",
1844 error_code=ERR_UNKNOWN,
1845 ),
1846 )
1849def _child_recorder(ns, spec, policy, started: float):
1850 """A callable that writes a detached child's state file (issue #661).
1852 Called twice: once at the top with ``terminal=False`` to claim the run with
1853 this process's pid, and once at the end — from the success path or the
1854 crash handler — with the result document. Both writes come from the child,
1855 which is what keeps them ordered: the parent writes only before the spawn,
1856 so no stale copy can land on top of the finished document.
1858 Fail-soft: a child that cannot write its state must still print its
1859 document to the log, since the log is then the only record.
1860 """
1861 from . import runagent
1863 del spec, policy
1865 def record(document: dict, terminal: bool = True) -> None:
1866 state = dict(document)
1867 state.update(
1868 {
1869 "run_id": ns.run_id,
1870 "status": runagent.STATUS_DONE if terminal else runagent.STATUS_RUNNING,
1871 # `started_at` travels with the pid so a reader can see how old
1872 # the claim is — see runagent.pid_alive on why a pid alone is
1873 # not proof of identity.
1874 "started_at": started,
1875 "pid": os.getpid(),
1876 }
1877 )
1878 try:
1879 runagent.write_state(ns.run_id, state, ns.cache_dir)
1880 except (OSError, ValueError) as exc:
1881 print(f"warning: could not record run state: {redact(str(exc))[0]}", file=sys.stderr)
1883 return record
1886def _detach_run_agent(ns, spec, policy, spawn=None) -> int:
1887 """Start a ``run-agent`` call in the background and print its run id."""
1888 import time
1890 from . import runagent
1892 if ns.prompt_file == "-":
1893 print(
1894 "error: --detach needs a prompt FILE; the background run has no stdin to read from",
1895 file=sys.stderr,
1896 )
1897 return 2
1898 if not Path(ns.prompt_file).is_file():
1899 print(f"error: prompt file not found: {ns.prompt_file}", file=sys.stderr)
1900 return 2
1902 # An operator-supplied id was already validated at parse time, and a
1903 # generated one is valid by construction — `runagent.run_path` refuses an
1904 # unsafe id regardless, so there is nothing left to re-check here.
1905 run_id = ns.run_id or runagent.new_run_id()
1906 if runagent.state_path(run_id, ns.cache_dir).exists():
1907 print(
1908 f"error: run '{run_id}' already exists; choose another --run-id",
1909 file=sys.stderr,
1910 )
1911 return 2
1913 state = runagent.initial_state(run_id, spec, policy.role, time.time())
1914 try:
1915 # Reserve the id BEFORE spawning, so a duplicate is refused rather than
1916 # discovered by two children racing for the same state file.
1917 runagent.write_state(run_id, state, ns.cache_dir)
1918 out_path = runagent.output_path(run_id, ns.cache_dir)
1919 argv = _child_argv(ns, run_id, sys.executable)
1920 launch = spawn or _spawn_detached
1921 pid = launch(argv, out_path)
1922 except (OSError, ValueError) as exc:
1923 print(f"error: could not start the detached run: {redact(str(exc))[0]}", file=sys.stderr)
1924 return 2
1926 # The parent writes the state file EXACTLY ONCE, before the spawn. It used
1927 # to write a second time afterwards to record the pid, from the stale dict
1928 # it still held — and a child that finished during launch had its terminal
1929 # document overwritten with `status: running`, losing the answer entirely.
1930 # The child records its own pid instead (see `_child_running_state`), so
1931 # every write after this one comes from the child, in order.
1932 print(
1933 json.dumps(
1934 {
1935 # The pid is the parent's own knowledge, reported for the
1936 # operator's benefit; it is deliberately NOT written to the
1937 # state file from here.
1938 **runagent.run_summary(state),
1939 "pid": pid if isinstance(pid, int) else None,
1940 "state_file": str(runagent.state_path(run_id, ns.cache_dir)),
1941 "output_file": str(runagent.output_path(run_id, ns.cache_dir)),
1942 },
1943 indent=2,
1944 )
1945 )
1946 return 0
1949#: Deliberately-unreaped background children (see :func:`_spawn_detached`). The
1950#: parent is a short-lived CLI invocation, so this holds at most one entry per
1951#: `--detach` in a process that is about to exit.
1952_DETACHED_CHILDREN: list = []
1955def _spawn_detached(argv: list[str], out_path: Path) -> int:
1956 """Start the background child, streaming its stdout+stderr to ``out_path``.
1958 Its own session, so the child outlives the shell that launched it — the
1959 whole point of ``--detach`` for an orchestrator that dispatches work and
1960 comes back for it later. Returns the child's pid, which the caller records
1961 so ``--status`` can later tell a live run from an abandoned one.
1962 """
1963 import subprocess
1965 kwargs: dict = {}
1966 if hasattr(os, "setsid"): 1966 ↛ 1970line 1966 didn't jump to line 1970 because the condition on line 1966 was always true
1967 kwargs["start_new_session"] = True
1968 # 0600 like the state file: the log holds the agent's full output, which is
1969 # derived from the prompt and is no less sensitive than the diff a review sees.
1970 fd = os.open(out_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
1971 with os.fdopen(fd, "wb") as out:
1972 proc = subprocess.Popen( # noqa: S603 - argv is built here, never shell-parsed
1973 argv,
1974 stdin=subprocess.DEVNULL,
1975 stdout=out,
1976 stderr=subprocess.STDOUT,
1977 **kwargs,
1978 )
1979 # Not waiting for this child is the whole point, but a dropped Popen warns
1980 # ("subprocess N is still running") when it is collected, and the parent
1981 # exits moments later so there is nothing to reap. Hold the reference
1982 # instead of lying about the return code or reaching into private state.
1983 _DETACHED_CHILDREN.append(proc)
1984 return proc.pid
1987def _run_replay(rest: list[str]) -> int:
1988 """Handle ``jury replay <outcome.json>`` (issue #449).
1990 Replays a saved run in the deliberation theater — or, off a TTY / without
1991 ``--theater``, as the same plain step stream ``--live`` prints. Pure
1992 presentation: no orchestration, no network, no agents.
1993 """
1994 from .replay import ReplayError, load_outcome, replay_events, replay_into
1996 sub = argparse.ArgumentParser(
1997 prog="jury replay",
1998 description="Replay a saved jury outcome (a result-cache entry or a "
1999 "serialized outcome dict) in the deliberation theater. No agents run.",
2000 )
2001 sub.add_argument(
2002 "outcome",
2003 help="path to a saved outcome JSON (cache entry or outcome dict)",
2004 )
2005 sub.add_argument(
2006 "--theater",
2007 action="store_true",
2008 help="replay in the animated deliberation scene (needs a wide TTY; "
2009 "falls back to plain transcript lines otherwise)",
2010 )
2011 sub.add_argument(
2012 "--theater-style",
2013 choices=["flat", "pixel"],
2014 default="flat",
2015 help="--theater scene style: 'flat' (ANSI line scene, default) or "
2016 "'pixel' (half-block pixel-art room)",
2017 )
2018 sub.add_argument(
2019 "--decision",
2020 choices=["chair", "vote"],
2021 default="chair",
2022 help="finale mode: 'chair' shows the stored synthesis verdict (default); "
2023 "'vote' re-tallies the panel ballots for the vote finale",
2024 )
2025 sub.add_argument(
2026 "--mode",
2027 choices=["code", "issue"],
2028 default="code",
2029 help="vote vocabulary for --decision vote (the serialized outcome does "
2030 "not record the run mode): 'code' (APPROVE/COMMENT/REQUEST CHANGES, "
2031 "default) or 'issue' (READY/UNCLEAR/NEEDS-INFO)",
2032 )
2033 ns = sub.parse_args(rest)
2035 try:
2036 outcome = load_outcome(Path(ns.outcome))
2037 except ReplayError as exc:
2038 print(f"error: {redact(str(exc))[0]}", file=sys.stderr)
2039 return 2
2041 # Panel-vote finale (mirrors the live path): re-tally from the stored
2042 # groups/reviews — deterministic, no agents involved.
2043 vote = None
2044 if ns.decision == "vote":
2045 from .voting import is_abstention, tally_votes
2047 voters = [
2048 r.agent for r in outcome.reviews if r.ok and not is_abstention(getattr(r, "output", ""))
2049 ]
2050 vote = tally_votes(outcome.groups, voters, mode=ns.mode)
2052 # Same TTY gate as the live path: the scene needs a wide TTY, otherwise
2053 # degrade to the plain --live step stream.
2054 court = None
2055 if ns.theater:
2056 from . import theater as _theater
2058 if _theater.supports_scene(sys.stdout):
2059 seats: dict[str, str] = {}
2060 for r in outcome.reviews:
2061 seats.setdefault(r.agent, r.vendor)
2062 court = _theater.Courtroom(
2063 list(seats.items()),
2064 outcome.chair or "chair",
2065 case=Path(ns.outcome).name,
2066 decision=ns.decision,
2067 style=ns.theater_style,
2068 )
2070 if court is not None:
2071 replay_into(court, outcome, vote=vote)
2072 else:
2073 for kind, result, round_no in replay_events(outcome):
2074 title, body = render_live_step(kind, result, round_no)
2075 print(f"## {title}\n\n{body}\n", flush=True)
2076 if vote is not None:
2077 # The vote finale must survive the transcript fallback too (review
2078 # finding: --decision vote was computed then silently dropped here).
2079 print("## Panel vote\n", flush=True)
2080 for ballot in vote.ballots:
2081 print(f"- {ballot.reviewer}: {ballot.vote} ({ballot.reason})", flush=True)
2082 print(f"\nVerdict: {vote.verdict}\n", flush=True)
2083 return 0
2086_PROGRESS_PREFIXES = (
2087 "round ",
2088 "reviewing chunk",
2089 "verification",
2090 "synthesis",
2091 "diff size",
2092 "early stop",
2093 "auto-depth",
2094)
2097def _is_progress_milestone(msg: str) -> bool:
2098 """Whether a log line is a coarse milestone worth a sticky-comment update."""
2099 return msg.startswith(_PROGRESS_PREFIXES)
2102#: Every CLI flag that writes a `[jury]` setting `validate_config` puts a bound
2103#: on, as `(flag, argparse dest, setting)` (issue #748). The settings are keys
2104#: of `config._NUMERIC_BOUNDS`, so the rule and the message are the config
2105#: path's own; only the `where` differs, naming the flag the operator typed
2106#: rather than a key they may never have written.
2107#:
2108#: The flags NOT here were checked against the same table and belong nowhere
2109#: else: `--seed` has no bound to break (a malformed `[jury] seed` is read as
2110#: "no seed" on purpose, not as an error); `--chunk`, `--early-stop`,
2111#: `--verify`, `--redact`, `--auto` and `--hints` are booleans; `--effort`,
2112#: `--decision`, `--context-mode` and `--format` are argparse `choices`, which
2113#: already refuse a value outside the vocabulary; and `--fail-on` has shared its
2114#: rule with the validator since #718.
2115_BOUNDED_FLAGS = (
2116 ("--rounds", "rounds", "rounds"),
2117 ("--max-rounds", "max_rounds", "max_rounds"),
2118 ("--total-timeout", "total_timeout", "total_timeout"),
2119 ("--phase-timeout", "phase_timeout", "phase_timeout"),
2120 ("--retries", "retries", "retries"),
2121 ("--max-diff-bytes", "max_diff_bytes", "diff.max_bytes"),
2122 # The fail-closed guards (docs audit 2026-09-29): they used to be clamped to
2123 # >= 0, so `--min-vendors -5` read as `0` — the documented opt-out — and the
2124 # cross-vendor guard was off with exit 0. `--no-min-vendors` writes 0, which
2125 # passes.
2126 ("--min-vendors", "min_vendors", "ci.min_vendors"),
2127 ("--min-reviews", "min_reviews", "ci.min_reviews"),
2128)
2131def _override_bound_error(args) -> str | None:
2132 """The first CLI override breaking a bound ``validate_config`` enforces.
2134 ``None`` is "the flag was not passed" and leaves the config value — which
2135 the validator has already checked — standing; it is never a value to range
2136 check, so an unset flag can never be mistaken for a zero.
2137 """
2138 for flag, dest, setting in _BOUNDED_FLAGS:
2139 value = getattr(args, dest, None)
2140 if value is None:
2141 continue
2142 message = bound_error(setting, value, where=flag)
2143 if message:
2144 return message
2145 return None
2148def _maybe_add_local_fallback(config, args, log):
2149 """Append a local agent when nothing else can run, offline (issue: zero-config).
2151 Only fires in the safe "fresh user" case: no explicit `--config`, no
2152 `./jury.toml`, not `--mock`, none of the configured agents are available,
2153 and a local OpenAI-compatible server is reachable with at least one model.
2154 Mutates ``config`` in place and points the chair at the local agent.
2156 Returns the seat it added, or ``None``. The built-in seats stay in the config,
2157 so the report still lists them as not found, but none of them can review: the
2158 panel this run can form is the local seat alone, and the caller scopes the
2159 default cross-vendor guard to that (#863). The decision is
2160 :func:`scaffold.zero_config_local_seat`, which ``jury --doctor`` also asks.
2161 """
2162 from .adapters import list_local_models, make_adapter
2163 from .scaffold import zero_config_local_seat
2165 seat = zero_config_local_seat(
2166 args.config,
2167 args.mock,
2168 Path("jury.toml").exists(),
2169 lambda: any(make_adapter(s).available() for s in config.enabled_agents),
2170 list_local_models,
2171 )
2172 if seat is None:
2173 return None
2174 model = seat.model
2175 config.agents.append(seat)
2176 config.chair = "local"
2177 named = getattr(args, "min_vendors", None)
2178 if named is None:
2179 guard = "so the default cross-vendor guard (min_vendors) does not apply to it"
2180 elif named <= 0:
2181 guard = "with the cross-vendor guard off (--no-min-vendors)"
2182 else:
2183 guard = f"held to the --min-vendors {named} you named"
2184 log(
2185 f"no agent CLIs found; using local model '{model}' (offline, $0) as a single-vendor panel, {guard}"
2186 )
2187 # An agy-only machine lands here too: say why its one CLI sat out.
2188 from .config import agy_opt_in_hint
2190 hint = agy_opt_in_hint((s.adapter_key for s in config.agents), shutil.which)
2191 if hint:
2192 log(f"note: {hint}")
2193 return seat
2196def _force_utf8_output() -> None:
2197 """Ensure stdout/stderr can emit the report's Unicode (emoji, arrows).
2199 On Windows the console defaults to a legacy code page (e.g. cp1252) that
2200 can't encode the report's `🏛️`/`⇄` characters, so `print(report)` raises
2201 `UnicodeEncodeError`. Reconfigure the real streams to UTF-8 when possible;
2202 `reconfigure` is absent on replaced streams (tests' StringIO, some pipes),
2203 so this is a best-effort no-op there.
2204 """
2205 for stream in (sys.stdout, sys.stderr):
2206 reconfigure = getattr(stream, "reconfigure", None)
2207 if reconfigure is not None:
2208 with contextlib.suppress(ValueError, OSError):
2209 reconfigure(encoding="utf-8")
2212_OVERVIEW = """\
2213🏛️ ai-jury — a cross-vendor multi-agent review jury.
2215It runs several coding-agent CLIs (Claude, Codex, Antigravity) plus an optional
2216local model over the same diff, PR, or issue; they cross-examine and verify each
2217other, and a chair (or a panel vote) synthesizes one verdict.
2219Common commands:
2220 jury init --wizard guided setup — writes a jury.toml (skippable)
2221 jury --pr 123 review a pull request
2222 jury --issue 42 review an issue for completeness
2223 git diff | jury --diff-file - review the current branch's diff
2224 jury examples more example commands
2225 jury guide a short end-to-end walkthrough
2226 jury --help every option
2228Docs: https://github.com/berkayturanci/ai-jury"""
2230_EXAMPLES = """\
2231ai-jury — example commands
2233Setup
2234 jury init --wizard guided setup (writes jury.toml)
2235 jury init --preset thorough non-interactive preset
2236 jury config show print the effective, resolved config
2237 jury --doctor check which agents/CLIs are available
2239Review
2240 jury --pr 123 review a pull request
2241 jury --issue 42 review an issue for completeness
2242 git diff | jury --diff-file - review the current branch's diff
2243 jury --diff-file changes.patch review a saved patch
2244 jury --pr 123 --verbose full play-by-play (rounds + transcript)
2246Decide & gate
2247 jury --pr 123 --decision vote verdict by panel vote (not a single chair)
2248 jury --pr 123 --ci exit non-zero on a blocking finding (CI gate)
2250Post results back to GitHub
2251 jury --pr 123 --post-summary post one rollup comment
2252 jury --pr 123 --post-inline post line-level review comments
2253 jury --issue 42 --post-summary post the triage verdict on the issue
2255Run `jury guide` for a walkthrough, or `jury --help` for every option."""
2257_GUIDE = """\
2258ai-jury — a short walkthrough
22601. Install the agent CLIs you have (any subset works): Claude Code, Codex,
2261 Antigravity. Optionally run a local model via Ollama for a free panelist.
2262 Check what's available:
2263 jury --doctor
22652. Create a config (picks reviewers, rounds, chair/vote, verify):
2266 jury init --wizard
2267 Every question is skippable — Enter keeps the built-in default.
22693. Run your first review:
2270 jury --pr 123 # a pull request
2271 jury --issue 42 # an issue's completeness
2272 git diff | jury --diff-file - # the current branch
2274 The panel reviews independently, cross-examines (debate), the chair verifies
2275 candidate findings to cut false positives, then synthesizes one verdict.
22774. Post the verdict back to GitHub (optional):
2278 jury --pr 123 --post-summary # one rollup comment
2279 jury --pr 123 --post-inline # line-level comments
22815. Gate CI on blocking findings (optional):
2282 jury --pr 123 --ci # non-zero exit on critical/major
2284Reviewers run sandboxed/read-only over attacker-controlled diffs by default.
2285See `jury examples` for more, or `jury --help` for every option.
2286Docs: https://github.com/berkayturanci/ai-jury"""
2289def _events_dir_for(args: argparse.Namespace) -> Path | None:
2290 """The directory this run writes its own events file to, if any.
2292 ``$JURY_EVENTS_DIR`` decides when it is set (``off`` included). Unset, the run
2293 writes to ``<cache dir>/events`` only if a watcher left its ``.watched`` marker
2294 there reading ``on``: the jury-progress mod does, because a mod cannot put a
2295 variable into the environment of the commands its session runs. The cache dir is
2296 ``$JURY_CACHE_DIR`` or the XDG default, as the watcher computes it, not a per-run
2297 ``--cache-dir``.
2299 A ``--mock`` run (a test, a demo) is no review anyone watches: it stays out of the
2300 directory, so a test suite run where the variable is set neither shows up there
2301 nor prunes the runs that do.
2302 """
2303 from . import events as _events
2305 if args.mock:
2306 return None
2307 value = os.environ.get(_events.ENV_DIR)
2308 if value is not None:
2309 return _events.events_dir(value)
2310 from .cache import default_cache_dir
2312 return _events.watched_dir(default_cache_dir() / "events")
2315def _seat_model(spec) -> str | None:
2316 """The model id a seat will be asked for, for the events file; None when unknown."""
2317 try:
2318 from .ballots import requested_model
2320 return requested_model(spec) or None
2321 except Exception: # noqa: BLE001 - a side channel: the run never fails for it
2322 return None
2325def _cwd_or_none() -> str | None:
2326 """The working directory, or ``None`` when it was removed under the run."""
2327 try:
2328 return str(Path.cwd())
2329 except OSError:
2330 return None
2333def _run_target(args: argparse.Namespace) -> str:
2334 """What this run reviews, as the theater's case title and the events file name it."""
2335 if args.pr:
2336 return f"PR #{args.pr}"
2337 if args.issue:
2338 return f"issue #{args.issue}"
2339 if getattr(args, "commit", None):
2340 return f"commit {args.commit}"
2341 if getattr(args, "commits", None):
2342 return f"range {args.commits}"
2343 return "local diff"
2346def main(argv: list[str] | None = None) -> int:
2347 _force_utf8_output()
2348 raw = list(sys.argv[1:] if argv is None else argv)
2350 # First-impression UX (#265): a newcomer running bare `jury` in a terminal
2351 # gets a friendly overview and exits 0 — not the argparse error. The strict
2352 # "provide one of --pr/--issue/--diff-file" error + non-zero exit is kept for
2353 # non-interactive use (piped/CI), so scripts that forget an input still fail.
2354 # `sys.stdin` can be None when stdin is detached (e.g. a background process),
2355 # so guard before calling isatty().
2356 if not raw and sys.stdin is not None and sys.stdin.isatty():
2357 print(_OVERVIEW)
2358 return 0
2360 # Plain-language command overview / walkthrough (#265), argv-intercepts like
2361 # the other subcommands so the main flag surface stays flat. Each has its own
2362 # small parser, so `--help` describes the subcommand the epilogue promises it
2363 # does (it printed the main help), and trailing junk (`jury examples foo`)
2364 # is an error rather than silently ignored.
2365 if raw[:1] in (["examples"], ["guide"]):
2366 argparse.ArgumentParser(
2367 prog=f"jury {raw[0]}",
2368 description=(
2369 "Print example commands." if raw[0] == "examples" else "Print a short walkthrough."
2370 ),
2371 ).parse_args(raw[1:])
2372 print(_EXAMPLES if raw[0] == "examples" else _GUIDE)
2373 return 0
2374 # Documented `jury cache clear` UX (issue #33): handled before argparse so
2375 # the rest of the CLI keeps its flat flag surface (no subcommands). Parsed
2376 # by its own parser BEFORE anything is deleted: `jury cache clear --help`
2377 # used to clear the cache, because every argument but `--cache-dir` was
2378 # ignored — the one command here that destroys data took a request for help
2379 # as a request to run.
2380 if raw[:2] == ["cache", "clear"]:
2381 from .cache import Cache
2383 sub = argparse.ArgumentParser(
2384 prog="jury cache clear",
2385 description="Delete every local review-cache entry and rotate the cache key.",
2386 )
2387 sub.add_argument(
2388 "--cache-dir", default=None, help="cache directory (default: the user cache dir)"
2389 )
2390 ns = sub.parse_args(raw[2:])
2391 removed = Cache(ns.cache_dir).clear()
2392 print(f"Cleared {removed} cache entr{'y' if removed == 1 else 'ies'}.")
2393 return 0
2395 # Comment-command mode (issue #11): `jury comment --text "/jury review"`
2396 # parses an allowlisted PR-comment command and dispatches a safe jury run.
2397 # Handled before the main parser so the comment text is never confused with
2398 # the jury's own flags, and never reaches a shell.
2399 if raw[:1] == ["comment"]:
2400 return _run_comment_command(raw[1:])
2402 # Config scaffolding (issue #107): `jury init` writes a jury.toml from
2403 # detected agents / flags / interactive prompts. Intercepted before the main
2404 # parser so it keeps its own small flag surface.
2405 if raw[:1] == ["init"]:
2406 return _run_init(raw[1:])
2408 # Config introspection: `jury config show` prints the EFFECTIVE resolved
2409 # config + its source so you can see exactly what will run; `config path`
2410 # prints just the source.
2411 if raw[:1] == ["config"]:
2412 return _run_config(raw[1:])
2414 # Apply verified suggested patches (issue #521): `jury apply` applies
2415 # suggested patches directly to the working directory.
2416 if raw[:1] == ["apply"]:
2417 return _run_apply(raw[1:])
2419 # Single-agent role dispatch (issue #661): `jury run-agent` runs ONE agent
2420 # for one role and prints a JSON result with attribution — the integration
2421 # point for an orchestrator. Intercepted like the other subcommands.
2422 if raw[:1] == ["run-agent"]:
2423 return _run_run_agent(raw[1:])
2425 # Theater replay (issue #449): `jury replay <outcome.json>` re-drives the
2426 # deliberation scene from a saved outcome — no agents, no network.
2427 # Intercepted before the main parser like the other subcommands.
2428 if raw[:1] == ["replay"]:
2429 return _run_replay(raw[1:])
2431 args = build_parser().parse_args(argv)
2433 # Checked before any short-circuiting branch below, so `--json` is rejected
2434 # wherever it is misplaced rather than only on the paths that reach the end.
2435 if args.json and not args.doctor:
2436 print(
2437 "error: --json applies to --doctor; use --format json for the review report.",
2438 file=sys.stderr,
2439 )
2440 return 2
2442 # Same vocabulary check `validate_config` applies to `[jury.ci] fail_on`,
2443 # reported with the same message (issue #718). Checked here, beside the
2444 # other flag guards, so a misspelled gate is refused before an agent is
2445 # paid for — and refused even without `--ci`, where the flag is inert:
2446 # otherwise the typo surfaces only on the run it was supposed to gate.
2447 if args.fail_on:
2448 message = fail_on_error(args.fail_on.split(","), "--fail-on")
2449 if message:
2450 print(f"error: {message}", file=sys.stderr)
2451 return 2
2453 if args.clear_cache:
2454 from .cache import Cache
2456 removed = Cache(args.cache_dir).clear()
2457 print(f"Cleared {removed} cache entr{'y' if removed == 1 else 'ies'}.")
2458 return 0
2460 if args.doctor:
2461 # `--doctor` resolves the cross-vendor threshold from `--min-vendors` too
2462 # (#863), so every bounded flag given here holds as it does on a run —
2463 # `--min-reviews` included, not only the one the prediction reads.
2464 message = _override_bound_error(args)
2465 if message:
2466 print(f"error: {message}", file=sys.stderr)
2467 return 2
2468 # Model discovery costs a probe per agent and only the JSON export
2469 # renders it; the human report must not pay for a field it never prints.
2470 diagnostics = doctor_module.build_diagnostics(
2471 args.config, probe_models=args.json, min_vendors=args.min_vendors
2472 )
2473 if args.json:
2474 # Exactly ONE JSON document on stdout, and nothing else: the export
2475 # is meant to be piped straight into `jq` / an orchestrator, so any
2476 # human chatter (including the --write confirmation below) goes to
2477 # stderr.
2478 print(json.dumps(doctor_module.doctor_report_dict(diagnostics), indent=2))
2479 else:
2480 print(doctor_module.render_report(diagnostics))
2481 if args.write:
2482 try:
2483 Path(args.write).write_text(
2484 json.dumps(diagnostics, indent=2) + "\n", encoding="utf-8"
2485 )
2486 except OSError as exc:
2487 print(f"error: {redact(str(exc))[0]}", file=sys.stderr)
2488 return 2
2489 stream = sys.stderr if args.json else sys.stdout
2490 print(f"\nWrote diagnostics to {args.write}", file=stream)
2491 return 0
2493 if args.config_validate:
2494 source = args.config or "jury.toml (or built-in defaults)"
2495 try:
2496 data = load_raw_config(args.config)
2497 warnings = validate_config(data, strict=args.strict_config)
2498 except (ConfigError, FileNotFoundError) as exc:
2499 print(redact(f"Config invalid ({source}): {exc}")[0], file=sys.stderr)
2500 return 2
2501 except OSError as exc:
2502 print(_config_read_error(exc, args.config), file=sys.stderr)
2503 return 2
2504 if warnings:
2505 print(f"Config valid with warnings ({source}):")
2506 for w in warnings:
2507 print(f" - {w}")
2508 else:
2509 print(f"Config valid ({source}).")
2510 return 0
2512 try:
2513 config = load_config(args.config, validate=True, strict=args.strict_config)
2514 except (ConfigError, FileNotFoundError) as exc:
2515 # A missing --config path raises FileNotFoundError; the other load sites already catch
2516 # both, so a bad path prints `Config invalid: …` instead of a traceback (#831).
2517 print(f"Config invalid: {redact(str(exc))[0]}", file=sys.stderr)
2518 return 2
2519 except OSError as exc:
2520 # It exists but cannot be read: an unreadable ./jury.toml, or --config naming
2521 # a directory. Neither is a FileNotFoundError, so both were a traceback (#893).
2522 print(_config_read_error(exc, args.config), file=sys.stderr)
2523 return 2
2524 # An auto-discovered ./jury.toml that runs local commands must be trusted before those
2525 # commands run — the checkout may be one this operator did not write (#831).
2526 try:
2527 configtrust.enforce(args.config, config, mock=args.mock)
2528 except configtrust.ConfigTrustError as exc:
2529 print(f"error: {exc}", file=sys.stderr)
2530 return 2
2531 # One value, one field, one answer, whichever surface it was written on
2532 # (issue #748). The overrides below are assigned straight onto the config
2533 # AFTER `validate_config` has run, so until now nothing range-checked them:
2534 # `--rounds 0` was accepted, ran a full Round 1 and exited 0 while `rounds =
2535 # 0` in `jury.toml` was a hard error, on a flag `docs/parameters.md`
2536 # documents as `≥ 1`. An operator who wrote `--rounds 0` meaning "no
2537 # debate" got a complete review round, a report, and nothing anywhere
2538 # saying the number they passed had been ignored.
2539 #
2540 # Refused here — before the diff is read and long before an agent is paid
2541 # for — with exit 2, like every other bad-input exit on this path.
2542 override_error = _override_bound_error(args)
2543 if override_error:
2544 print(f"error: {override_error}", file=sys.stderr)
2545 return 2
2546 if args.rounds is not None:
2547 config.rounds = args.rounds
2548 # A fixed --rounds is a hard override: it disables adaptive early-stop so
2549 # the run is reproducible fixed-N (issue #40), unless --early-stop is also
2550 # passed explicitly (handled below).
2551 config.early_stop = False
2552 if args.max_rounds is not None:
2553 config.max_rounds = args.max_rounds
2554 if args.early_stop is not None:
2555 config.early_stop = args.early_stop
2556 if args.total_timeout is not None:
2557 config.total_timeout = args.total_timeout
2558 if args.phase_timeout is not None:
2559 config.phase_timeout = args.phase_timeout
2560 if args.retries is not None:
2561 # Assigned as written: the `max(0, …)` clamp that used to stand here was
2562 # the second rule for one value (#748). It silently turned `--retries
2563 # -1` into 0 while `retries = -1` in `jury.toml` was a hard error, and
2564 # is unreachable now that the same bound refuses the flag above.
2565 config.retries = args.retries
2566 if args.seed is not None:
2567 config.seed = args.seed
2568 if args.chair:
2569 # Refused, not silently replaced (docs audit 2026-09-29): an unknown
2570 # `--chair` used to exit 0 with the first usable agent chairing, so the
2571 # operator's choice of synthesizer was ignored without a word. Checked
2572 # against the enabled seats, before anything is fetched or spent.
2573 enabled = [a.name for a in config.enabled_agents]
2574 if args.chair != "rotate" and args.chair not in enabled:
2575 print(
2576 f"error: --chair {args.chair!r} is not an enabled agent (enabled: "
2577 f"{', '.join(enabled) or 'none'}); name one of them, or 'rotate'.",
2578 file=sys.stderr,
2579 )
2580 return 2
2581 config.chair = args.chair
2582 # Applied to the config (rather than resolved late like --min-vendors)
2583 # because the pre-run half of this gate lives in the orchestrator: it has to
2584 # be able to refuse a bench that is too small BEFORE the panel is paid for.
2585 if args.min_reviews is not None:
2586 # Assigned as written: the bound above refuses a negative (docs audit
2587 # 2026-09-29), where a `max(0, …)` clamp here used to turn it into "off".
2588 config.ci.min_reviews = args.min_reviews
2589 # --effort is a whole-panel override: it wins over every [[agent]] effort so
2590 # one flag raises (or lowers) the depth of the entire run.
2591 if args.effort is not None:
2592 for agent in config.agents:
2593 agent.effort = args.effort
2594 # Warn ONCE per run per distinct message, before any agent is invoked, for
2595 # every panelist whose vendor cannot act on the requested effort. Real
2596 # adapters are passed only outside --mock, so an offline demo never spawns a
2597 # vendor CLI to check a model listing.
2598 for warning in effort_warnings(
2599 config.enabled_agents, adapter_factory=None if args.mock else make_adapter
2600 ):
2601 print(f"warning: {warning}", file=sys.stderr)
2602 if args.verify is not None:
2603 config.verify = args.verify
2604 if args.context_mode is not None:
2605 config.context.mode = args.context_mode
2606 if args.redact is not None:
2607 config.context.redact_secrets = args.redact
2608 if args.max_diff_bytes is not None:
2609 config.diff.max_bytes = args.max_diff_bytes
2610 if args.chunk is not None:
2611 config.diff.chunk = args.chunk
2612 if args.exclude:
2613 config.diff.exclude = list(config.diff.exclude) + list(args.exclude)
2614 if args.include:
2615 config.diff.include = list(config.diff.include) + list(args.include)
2617 try:
2618 policy = load_policy(args.policy)
2619 except PolicyError as exc:
2620 print(f"error: {redact(str(exc))[0]}", file=sys.stderr)
2621 return 2
2623 # Issue mode (issue #221) reviews prose, not a diff, so the PR/diff-only
2624 # concepts below have no meaning. Reject them up front with a clear message
2625 # rather than silently ignoring them.
2626 # Exactly one source (issue #367). Listed rather than pairwise so adding a
2627 # source cannot quietly skip the check.
2628 _sources = [
2629 ("--pr", args.pr),
2630 ("--issue", args.issue),
2631 ("--diff-file", args.diff_file),
2632 ("--commit", getattr(args, "commit", None)),
2633 ("--commits", getattr(args, "commits", None)),
2634 ]
2635 _given = [flag for flag, value in _sources if value]
2636 if len(_given) > 1:
2637 raise SystemExit(f"error: choose one input source, got {', '.join(_given)}")
2638 if args.issue:
2639 for flag, on in (
2640 ("--post-inline", args.post_inline),
2641 ("--post-progress", args.post_progress),
2642 ("--label", args.label),
2643 ("--incremental", args.incremental),
2644 ("--post-marker", args.post_marker),
2645 # The issue path posts one summary and never reads the mode (docs
2646 # audit 2026-09-29): accepted, `phased` was silently ignored.
2647 ("--post-mode", args.post_mode is not None),
2648 ):
2649 if on:
2650 raise SystemExit(
2651 f"error: {flag} is not supported with --issue (it is a PR/diff concept)"
2652 )
2654 # A posting flag with nowhere to post is a usage error, so it is refused here with
2655 # the rest of the argument checks. It used to be refused after the review, when
2656 # every seat had already run and been paid for (#866). `--post-summary` also posts
2657 # to an issue; the others are PR-only and `--issue` rejected them above.
2658 for flag, on, has_target in (
2659 ("--post-summary", args.post_summary, args.pr or args.issue),
2660 ("--post-inline", args.post_inline, args.pr),
2661 ("--post-marker", args.post_marker, args.pr),
2662 ("--label", args.label, args.pr),
2663 ):
2664 if on and not has_target:
2665 raise SystemExit(f"error: {flag} requires --pr")
2666 # `--post-mode` shapes the summary comment, so without one it shapes nothing
2667 # (docs audit 2026-09-29): `--post-mode phased` alone exited 0 and posted
2668 # nothing, which docs/parameters.md has always said it requires.
2669 if args.post_mode is not None and not args.post_summary:
2670 raise SystemExit("error: --post-mode requires --post-summary (or --post)")
2672 # Live progress on the PR (issue #125): a single sticky comment updated at
2673 # each round/chunk milestone. Opt-in and requires --pr.
2674 progress = None
2675 if args.post_progress:
2676 if not args.pr:
2677 raise SystemExit("error: --post-progress requires --pr")
2678 from .github import ProgressReporter
2680 progress = ProgressReporter(args.pr, args.repo)
2682 def log(msg: str) -> None:
2683 if not args.quiet:
2684 print(f"[jury] {msg}", file=sys.stderr)
2685 if progress is not None and _is_progress_milestone(msg):
2686 progress.update(msg)
2688 # Smart offline fallback: with NO config file and NO usable agent CLI, but a
2689 # local model server reachable, add a local agent so `jury` just works
2690 # offline out of the box (issue: easier zero-config). Never overrides an
2691 # explicit config or a working CLI panel.
2692 local_fallback = _maybe_add_local_fallback(config, args, log)
2694 # The head the review STARTS on (#977). Read once, before the diff and the seats, so
2695 # the incremental marker names what was actually reviewed: a push landing mid-run
2696 # must not get marked as reviewed. Read when anything will use it.
2697 head_sha = ""
2698 if args.pr and (args.incremental or args.post_summary or args.post_marker):
2699 from .github import pr_head_sha
2701 head_sha = pr_head_sha(args.pr, args.repo)
2703 try:
2704 diff, context = _read_diff(args)
2705 except RuntimeError as exc:
2706 # `--pr` shells out to `gh`; a missing or failing `gh` raises RuntimeError, which was
2707 # otherwise uncaught here and printed a Python traceback (#831).
2708 print(f"error: {redact(str(exc))[0]}", file=sys.stderr)
2709 return 2
2711 # Incremental review (issue #9): when --incremental and a prior jury
2712 # marker exists, narrow the diff to the range since the last reviewed SHA;
2713 # otherwise fall back safely to the full diff. The reviewed head SHA is also
2714 # recorded on the posted summary so a later run can go incremental.
2715 review_scope = None
2716 if args.incremental:
2717 if not args.pr:
2718 raise SystemExit("error: --incremental requires --pr")
2719 from . import incremental as inc
2720 from .github import compare_diff, compare_meta, pr_comment_bodies
2722 prev_sha = inc.parse_reviewed_sha(pr_comment_bodies(args.pr, args.repo))
2723 mode, reason = inc.decide_review(prev_sha, head_sha)
2724 if mode == inc.MODE_INCREMENTAL:
2725 # #974: marker...head is the PR's own delta only on a plain fast-forward.
2726 # A merged base branch (or rebase) would put other PRs' changes in it.
2727 full_why = inc.range_full_reason(compare_meta(prev_sha, head_sha, args.repo))
2728 if full_why:
2729 mode, reason = inc.MODE_FULL, f"{full_why} — full review of the PR's own diff"
2730 if mode == inc.MODE_INCREMENTAL:
2731 inc_diff = compare_diff(prev_sha, head_sha, args.repo)
2732 if inc_diff.strip():
2733 diff = inc_diff
2734 else:
2735 mode, reason = inc.MODE_FULL, "incremental range unavailable — full review"
2736 review_scope = inc.scope_note(mode, reason)
2737 log(reason)
2739 if not diff.strip():
2740 raise SystemExit("error: empty diff — nothing to review")
2742 # Risk-aware auto-depth (issue #120): scale rounds/verify to the diff when
2743 # enabled. Explicit --rounds/--verify/--early-stop always win; the panel is
2744 # never trimmed. Off unless --auto or [jury] auto_depth.
2745 if args.auto if args.auto is not None else config.auto_depth:
2746 from .diffprofile import depth_for, describe, profile_diff
2748 prof = profile_diff(diff)
2749 rounds, verify, early_stop = depth_for(prof.risk)
2750 if args.rounds is None:
2751 config.rounds = rounds
2752 if args.early_stop is None:
2753 config.early_stop = early_stop
2754 if args.verify is None:
2755 config.verify = verify
2756 log(describe(prof))
2758 if getattr(args, "tiered", False):
2759 config.routing = "tiered"
2760 if config.routing == "tiered" and getattr(args, "min_vendors", None) is not None:
2761 # The routed panel keeps at least the vendor floor the gate will apply
2762 # (#714); a `--min-vendors` override has to reach the plan, not only the
2763 # gate that runs after the panel has been paid for.
2764 config.ci.min_vendors = int(args.min_vendors)
2765 # ``--hints`` / ``--no-hints`` override ``[jury] hints`` in BOTH directions;
2766 # the sentinel (None) means "not passed", so the config value stands (#715).
2767 hints_override = getattr(args, "hints", None)
2768 if hints_override is not None:
2769 config.hints = hints_override
2771 # The pre-pass block is carried SEPARATELY from the user context (#715).
2772 # Appending it to ``context`` here made it invisible under the default
2773 # context mode: ``run_jury`` clears ``context`` when the mode is "diff-only",
2774 # so the linters ran, this line was logged, and the panel saw nothing. The
2775 # orchestrator joins the block into the Round 1 prompt after that filter.
2776 #
2777 # The linters see the CHANGED files and nothing else (#737). The paths come
2778 # from the same plan ``review_diff`` builds below — ``plan_for`` is pure, so
2779 # the ``kept`` list here is the one the panel is shown — which means a file
2780 # dropped by ``[jury.diff] include/exclude`` never contributes a hint about a
2781 # diff the reviewers cannot read. ``--issue`` reviews prose and has no
2782 # changed paths at all, so it gets no block. When the change touches nothing
2783 # Ruff or ESLint handles, ``collect_static_hints`` returns "" rather than
2784 # falling back to the working tree.
2785 hints_block = ""
2786 if config.hints:
2787 from .hints import collect_static_hints
2788 from .orchestrator import plan_for
2790 changed_paths = [] if args.issue else [p for p in plan_for(config, diff).kept_paths if p]
2791 sh = collect_static_hints(changed_paths)
2792 if sh:
2793 hints_block = sh
2794 log(f"injected static analysis hints for {len(changed_paths)} changed file(s)")
2796 # Optional local result cache (issue #33): a hit skips the run entirely; a
2797 # miss runs the jury and stores the outcome. The key covers the diff,
2798 # effective config, prompt version, package version, context policy, the
2799 # context text that policy admits (#738), the static-analysis block the
2800 # linters produced (#745), and seed. ``context`` is passed straight through from
2801 # ``_read_diff`` and ``hints_block`` is the string resolved just above — both
2802 # are the ones ``run_jury`` gets, so the key is a function of what the panel
2803 # is shown and not of a second reading of the config.
2804 cache = None
2805 cache_k = None
2806 outcome = None
2807 if args.cache:
2808 from .cache import Cache, cache_key
2810 cache = Cache(args.cache_dir)
2811 cache_k = cache_key(
2812 config,
2813 diff,
2814 context=context,
2815 hints=hints_block,
2816 mock=args.mock,
2817 policy=policy,
2818 mode=("issue" if args.issue else "code"),
2819 )
2820 outcome = cache.load(cache_k)
2821 if outcome is not None:
2822 log(f"cache hit ({cache_k[:12]}…) — reusing stored outcome")
2823 else:
2824 log(f"cache miss ({cache_k[:12]}…) — running jury")
2826 # Live play-by-play (issue #210, #229): stream each step as it happens. Prints
2827 # a titled block to stdout the moment a phase result lands. Posting each step to
2828 # the PR/issue is OPT-IN — it requires BOTH a target (--pr or --issue) AND
2829 # --post (a bare target only selects the source, never auto-posts), so `--live`
2830 # alone just streams locally. Posting is best-effort: a GitHub hiccup is logged
2831 # and never aborts the run.
2832 live_target = args.pr or args.issue
2833 # Theater defaults can come from jury.toml (issue #364); the CLI flags
2834 # (--theater / --no-theater, --theater-style) override per run. Sentinels
2835 # (None) distinguish "not passed" from an explicit choice.
2836 theater_on = args.theater if args.theater is not None else config.theater
2837 theater_style = args.theater_style or config.theater_style
2838 live_posts = bool((args.live or theater_on) and args.post_summary and live_target)
2839 live_post = post_issue_comment if args.issue else post_pr_comment
2840 # Opt-in animated "courtroom" scene (--theater): an interactive TTY view of
2841 # the REAL run (each model seated, speaking per phase, gavel/vote finale). It
2842 # needs a wide TTY and an actual run (a cache hit has nothing to replay), so
2843 # it falls back to the plain --live step stream otherwise. The structured
2844 # outcome / report / CI gate are untouched — this is a side channel.
2845 court = None
2846 if theater_on and outcome is None and not args.quiet:
2847 from . import theater as _theater
2849 if _theater.supports_scene(sys.stdout): 2849 ↛ 2872line 2849 didn't jump to line 2872 because the condition on line 2849 was always true
2850 # Display-only chair label for the scene title. The run resolves the
2851 # REAL chair internally (resolve_chair needs the usable/reviewer sets
2852 # and run RNG, which don't exist yet here), so use a best-effort name.
2853 chair_name = (
2854 config.chair
2855 if config.chair and config.chair != "rotate"
2856 else (config.agents[0].name if config.agents else "chair")
2857 )
2858 court = _theater.Courtroom(
2859 [(a.name, a.vendor) for a in config.agents],
2860 chair_name,
2861 case=_run_target(args),
2862 mode=("issue" if args.issue else "code"),
2863 decision=(args.decision or config.decision),
2864 style=theater_style,
2865 )
2866 court.open()
2868 # Progress events for an observer in another process (--events-file, or a file of
2869 # this run's own under $JURY_EVENTS_DIR): the same on_event stream as --live,
2870 # written as metadata-only NDJSON. A side channel like the theater: the outcome,
2871 # report and CI gate never read it.
2872 from . import events as _events
2874 events = None
2875 if args.events_file:
2876 try:
2877 events = _events.EventsWriter(
2878 args.events_file,
2879 # The path is operator text and the OSError repeats it: both are
2880 # redacted, as every other path this CLI prints is.
2881 on_error=lambda msg: print(f"warning: {redact(msg)[0]}", file=sys.stderr),
2882 )
2883 except OSError as exc:
2884 # An unwritable path is a user error, reported before the panel is paid for.
2885 message = f"cannot write --events-file {args.events_file}: {exc}"
2886 print(f"error: {redact(message)[0]}", file=sys.stderr)
2887 if court is not None: 2887 ↛ 2888line 2887 didn't jump to line 2888 because the condition on line 2887 was never true
2888 court.close()
2889 return 2
2890 elif (events_dir := _events_dir_for(args)) is not None:
2891 # Nobody asked this run for a file by name, so a directory that cannot be
2892 # written warns and the run goes on without events.
2893 events = _events.open_dir_writer(
2894 events_dir,
2895 on_error=lambda msg: print(f"warning: {redact(msg)[0]}", file=sys.stderr),
2896 )
2897 if events is not None:
2898 events.write(
2899 _events.start_record(
2900 # The seats that will speak: a disabled agent is never run.
2901 [(a.name, a.vendor, _seat_model(a)) for a in config.enabled_agents],
2902 chair=config.chair if config.chair and config.chair != "rotate" else None,
2903 target=_run_target(args),
2904 mode=("issue" if args.issue else "code"),
2905 decision=(args.decision or config.decision),
2906 cached=outcome is not None,
2907 pid=os.getpid(),
2908 cwd=_cwd_or_none(),
2909 )
2910 )
2912 on_event = None
2913 if args.live or theater_on or events is not None:
2915 def on_event(kind, result, round_no=None):
2916 if events is not None:
2917 events.write(_events.step_record(kind, result, round_no))
2918 if court is not None:
2919 court.step(kind, result, round_no)
2920 elif args.live or theater_on:
2921 # plain step stream (--live, or --theater fallback off a TTY)
2922 title, body = render_live_step(kind, result, round_no)
2923 print(f"## {title}\n\n{body}\n", flush=True)
2924 if live_posts:
2925 try:
2926 title, body = render_live_step(kind, result, round_no)
2927 live_post(live_target, f"## {title}\n\n{body}", args.repo)
2928 except Exception as exc: # noqa: BLE001 - best-effort, never crash
2929 log(f"live: failed to post step to #{live_target}: {redact(str(exc))[0]}")
2931 # We stream live only when actually running the jury; a cache hit has nothing
2932 # to replay, so the consolidated report is still printed in that case.
2933 live_streamed = bool(args.live or theater_on) and outcome is None
2935 if outcome is None:
2936 try:
2937 if args.issue:
2938 # Issue prose bypasses large-diff planning (filter/size/chunk is
2939 # meaningless for an issue body); run the jury directly with the
2940 # issue-quality rubric.
2941 outcome = run_jury(
2942 config,
2943 diff,
2944 context=context,
2945 hints=hints_block,
2946 mock=args.mock,
2947 strict=args.strict,
2948 policy=policy,
2949 log=log,
2950 on_event=on_event,
2951 mode="issue",
2952 )
2953 else:
2954 outcome, _plan = review_diff(
2955 config,
2956 diff,
2957 context=context,
2958 hints=hints_block,
2959 mock=args.mock,
2960 strict=args.strict,
2961 policy=policy,
2962 log=log,
2963 on_event=on_event,
2964 )
2965 except KeyboardInterrupt:
2966 # Graceful cancellation (issue #30): a jury run can be long, so
2967 # Ctrl-C should exit cleanly with the conventional 130 rather than
2968 # dumping a traceback. Work already completed is not partially
2969 # rendered here because the orchestrator returns atomically; we just
2970 # report the cancellation.
2971 print("\n[jury] cancelled (interrupted) — no report produced", file=sys.stderr)
2972 if events is not None:
2973 events.write(_events.end_record("cancelled"))
2974 events.close()
2975 return 130
2976 except RuntimeError as exc:
2977 # Large-diff "too large / nothing to review" (issue #31) and "no
2978 # usable agents" are actionable user errors, not crashes.
2979 print(f"error: {redact(str(exc))[0]}", file=sys.stderr)
2980 if events is not None:
2981 events.write(_events.end_record("error"))
2982 events.close()
2983 return 2
2984 if cache is not None and cache_k is not None:
2985 cache.store(cache_k, outcome)
2986 log(f"cached outcome ({cache_k[:12]}…)")
2988 # Final-verdict mode (issue #220): a panel vote (tally the reviewers) vs the
2989 # chair's synthesis. Rendering-only — the outcome is identical; the severity-
2990 # based CI gate below is unaffected. Effective = CLI flag else config.
2991 decision = args.decision or config.decision
2992 vote = None
2993 if decision == "vote":
2994 from .voting import is_abstention, tally_votes
2996 # A reviewer that abstained (empty reply or a refusal) is excluded from
2997 # the tally — a non-answer must not count as a "clear" vote (issue #251).
2998 voters = [
2999 r.agent for r in outcome.reviews if r.ok and not is_abstention(getattr(r, "output", ""))
3000 ]
3001 vote = tally_votes(
3002 outcome.groups,
3003 voters,
3004 mode=("issue" if args.issue else "code"),
3005 )
3007 # Close the courtroom scene (after the vote is tallied, so the panel-vote
3008 # finale can show the ballots/verdict).
3009 if court is not None:
3010 if vote is not None:
3011 court.set_vote(vote)
3012 court.close()
3014 if events is not None:
3015 from .ballots import chair_verdict, reviewer_ballots
3017 try:
3018 ballots = _events.ballot_entries(
3019 reviewer_ballots(
3020 outcome, config, vote=vote, mode=("issue" if args.issue else "code")
3021 )
3022 )
3023 except Exception: # noqa: BLE001 - a side channel: the run never fails for it
3024 ballots = None
3025 events.write(
3026 _events.end_record(
3027 "done",
3028 findings=len(outcome.findings),
3029 verdict=chair_verdict(outcome, vote),
3030 ballots=ballots,
3031 )
3032 )
3033 events.close()
3035 # Ballot vocabulary follows the review mode, exactly as the vote tally does:
3036 # an issue review votes on completeness (READY/UNCLEAR/NEEDS_INFO), not on a
3037 # diff's correctness. Resolved BEFORE the metadata, which now derives the
3038 # ballots to count them (#700, round 2) and must derive the same ones the
3039 # report renders.
3040 ballot_mode = "issue" if args.issue else "code"
3042 # Whether this run's panel is the zero-config fallback's one local seat (#863):
3043 # recorded in the metadata and stated in the report, not only on stderr, which
3044 # `--quiet` silences.
3045 zero_config = local_fallback is not None
3046 metadata = build_run_metadata(
3047 outcome,
3048 config,
3049 decision=decision,
3050 vote=vote,
3051 mode=ballot_mode,
3052 zero_config_fallback=zero_config,
3053 )
3055 # The attribution footer (issue #911): on unless `--no-attribution` or
3056 # `[jury.output] attribution = false`. Appended below, once the markdown
3057 # report is complete; `transcript_mode` picks the transcript's wording.
3058 attribution_on = args.attribution if args.attribution is not None else config.output.attribution
3059 transcript_mode = False
3061 if args.format == "json":
3062 from .formats import to_json
3064 report = to_json(
3065 outcome,
3066 config,
3067 decision=decision,
3068 vote=vote,
3069 mode=ballot_mode,
3070 zero_config_fallback=zero_config,
3071 )
3072 elif args.format == "sarif":
3073 from .formats import to_sarif
3075 report = to_sarif(outcome, config)
3076 elif args.format == "keel-reviews":
3077 from .formats import to_keel_reviews
3079 report = to_keel_reviews(outcome, config, vote=vote, mode=ballot_mode)
3080 else:
3081 # Output mode (issue: full transcript). --verbose => summary + transcript;
3082 # --transcript (or [jury] transcript, unless --no-transcript) => the
3083 # chronological play-by-play; otherwise the consensus-first summary.
3084 # Rendering-only — the orchestration/outcome is identical either way.
3085 transcript_default = args.transcript if args.transcript is not None else config.transcript
3086 transcript_mode = bool(args.verbose or transcript_default)
3087 if transcript_mode:
3088 report = render_transcript(
3089 outcome.reviews,
3090 outcome.debate,
3091 outcome.synthesis,
3092 chair=outcome.chair,
3093 findings=outcome.findings,
3094 warnings=outcome.warnings,
3095 groups=outcome.groups,
3096 verify=outcome.verify,
3097 context_mode=outcome.context_mode,
3098 redact_secrets=outcome.redact_secrets,
3099 redaction_count=outcome.redaction_count,
3100 excluded_files=outcome.excluded_files,
3101 metadata=metadata,
3102 review_scope=review_scope,
3103 lead_with_summary=bool(args.verbose),
3104 vote=vote,
3105 footer=False,
3106 )
3107 else:
3108 report = render(
3109 outcome.reviews,
3110 outcome.debate,
3111 outcome.synthesis,
3112 chair=outcome.chair,
3113 findings=outcome.findings,
3114 warnings=outcome.warnings,
3115 groups=outcome.groups,
3116 verify=outcome.verify,
3117 context_mode=outcome.context_mode,
3118 redact_secrets=outcome.redact_secrets,
3119 redaction_count=outcome.redaction_count,
3120 excluded_files=outcome.excluded_files,
3121 metadata=metadata,
3122 review_scope=review_scope,
3123 vote=vote,
3124 footer=False,
3125 )
3127 if args.metadata_json:
3128 with Path(args.metadata_json).open("w", encoding="utf-8") as fh:
3129 fh.write(json.dumps(metadata, indent=2) + "\n")
3130 log(f"metadata written to {redact(args.metadata_json)[0]}")
3132 ci_exit = 0
3133 # A run whose panel collapsed is a different thing wearing the same output
3134 # (#625/#682). `--strict` fails when a configured CLI is *missing*; this
3135 # fails when one was present, probed fine, and returned nothing — which is
3136 # how a three-vendor panel silently becomes one. It FAILS CLOSED by default
3137 # (`[jury.ci] min_vendors`, shipped as 2) and is scoped to runs that claimed
3138 # cross-vendor consensus, so a single-vendor install is untouched; exit 3, so
3139 # it is distinguishable from a findings failure.
3140 #
3141 # The zero-config local fallback (#863) seats one local reviewer beside the
3142 # built-in seats it found missing — it fires only when none of them can run —
3143 # so the panel it forms is that seat alone and never claimed cross-vendor
3144 # consensus. Counting the missing seats as configured vendors failed the
3145 # documented `jury --diff-file -` offline path with exit 3 on every run. A
3146 # threshold named on the command line is still enforced as asked.
3147 required, explicit = resolve_min_vendors(getattr(args, "min_vendors", None), config)
3148 collapsed = collapse_reason(
3149 outcome.reviews,
3150 required,
3151 None if explicit else claimed_vendors(config.enabled_agents, local_fallback),
3152 )
3153 if collapsed:
3154 log(collapsed)
3155 # A runner with claude + agy and no codex lands here since agy left the
3156 # default panel: name the second vendor it already has, and why it sat out.
3157 from .config import agy_opt_in_hint
3159 hint = agy_opt_in_hint((s.adapter_key for s in config.agents), shutil.which)
3160 if hint:
3161 log(f"note: {hint}; or install another vendor's CLI, or lower --min-vendors")
3162 ci_exit = 3
3163 # No seat returned anything (#849). One local seat pointed at a model its
3164 # server does not have failed every call with `HTTP 404`, and the run still
3165 # exited 0 with a report of nothing. The collapse guard above is scoped to
3166 # runs that claimed cross-vendor consensus and `min_reviews` is off by default,
3167 # so neither saw it. This is narrower than both on purpose: not "too few
3168 # reviews" — a seat that answered "looks good" is an abstention, and a clean
3169 # single-seat run must stay green — but "every seat failed to return a result
3170 # at all". A run that reviewed nothing is not a pass.
3171 ran = metadata.get("panel") or {}
3172 configured_seats = int(ran.get("configured") or 0)
3173 if configured_seats and int(ran.get("failed") or 0) == configured_seats:
3174 log(
3175 f"no reviewer returned a result: all {configured_seats} seat(s) failed, so "
3176 f"nothing was reviewed. A run with no review is not a pass — see each "
3177 f"seat's error above, and `jury --doctor` (e.g. a local model not pulled)."
3178 )
3179 ci_exit = 3
3180 # The other half of the #699 gate. The orchestrator refuses a bench that is
3181 # too small before spending it; this catches the two cases a pre-flight
3182 # cannot predict — an agent that was present, ran, and returned nothing, and
3183 # one that answered with prose naming nothing a reader could check. Both are
3184 # recorded as abstentions and neither is a review, so the number the consumer
3185 # will accept can fall below its minimum while every seat "answered" (#700,
3186 # round 2: `--min-reviews 3` used to be satisfied by three "Looks good to me"
3187 # replies). Exit 3, the same family as a collapsed panel: the panel, not the
3188 # findings, is what fell short. Evaluated on cached outcomes too, which is
3189 # why `min_reviews` is kept out of the cache key.
3190 panel_meta = metadata.get("panel") or {}
3191 short_panel = panel.shortfall(
3192 panel_meta.get("reviews_supplied") or 0,
3193 config.ci.min_reviews,
3194 stage="after the panel ran",
3195 # Every cause the metadata publishes, passed by the one mapping that
3196 # names them: a call site listing two of the four printed the other two
3197 # under a cause their own ballots contradicted (#700, round 5).
3198 **{key: panel_meta.get(key) or 0 for key in panel.PANEL_METADATA_KEYS.values()},
3199 )
3200 if short_panel:
3201 log(short_panel)
3202 ci_exit = 3
3203 if args.ci:
3204 fail_on = config.ci.fail_on
3205 if args.fail_on:
3206 fail_on = [s.strip().lower() for s in args.fail_on.split(",") if s.strip()]
3207 gate_exit, ci_reason = evaluate_ci(
3208 outcome.groups,
3209 fail_on,
3210 config.ci.ignore_unverified,
3211 pre_existing=config.pre_existing,
3212 )
3213 # A collapsed panel outranks the severity gate: `evaluate_ci` reports on
3214 # findings the panel did or did not raise, and a panel that never formed
3215 # is not evidence either way. Before #682 this assignment overwrote the
3216 # collapse exit, so `--ci --min-vendors 2` reported a clean pass on a
3217 # single-vendor run — the exact failure the flag was added for.
3218 ci_exit = ci_exit or gate_exit
3219 # Only the markdown report carries the human-readable CI gate section;
3220 # json/sarif documents stay machine-clean. The exit code is unchanged.
3221 if args.format == "markdown":
3222 report += f"\n\n## CI gate\n\n{ci_reason}\n"
3224 # Suggested patches (issue #10): opt-in and kept separate from the default
3225 # report. Written to a file with --patches-out, else appended after the
3226 # markdown report under its own heading. The default flow stays read-only.
3227 if args.suggest_patches:
3228 from .patches import render_patch_suggestions
3230 patches_section = render_patch_suggestions(outcome.groups)
3231 if not patches_section:
3232 log("no verified findings with a suggested fix — no patches emitted")
3233 elif args.patches_out:
3234 Path(args.patches_out).write_text(patches_section, encoding="utf-8")
3235 log(f"suggested patches written to {redact(args.patches_out)[0]}")
3236 elif args.format == "markdown":
3237 report += "\n\n" + patches_section.rstrip()
3238 else:
3239 log("--suggest-patches needs markdown output or --patches-out; skipped")
3241 # The attribution footer (issue #911) closes the markdown report: the tool and
3242 # the seats that returned a review. The renderers were asked to leave it off so
3243 # it can go here, AFTER the CI gate and patch sections appended above, and the
3244 # report ends with exactly one footer. JSON/SARIF/keel-reviews are machine
3245 # documents and never get it. Posting appends the hidden SHA marker after it.
3246 if attribution_on and args.format == "markdown":
3247 report += "\n" + render_footer(outcome.reviews, transcript=transcript_mode)
3249 # Turn the live progress comment into the final verdict (issue #125).
3250 if progress is not None:
3251 progress.finish(report)
3252 log(f"progress comment finalized on PR #{args.pr}")
3254 if args.output:
3255 # By the time this write runs the panel has been invoked, the debate is
3256 # over and the verdict is rendered: the run is paid for. An unwritable
3257 # path used to come out of `open()` as a raw `FileNotFoundError`
3258 # traceback (issue #749) — an implementation detail where a sentence
3259 # naming the path belongs, and one that took the report with it, because
3260 # `-o` is exactly what suppresses the stdout copy below.
3261 #
3262 # So it is reported the way the `--doctor --write` failure a few hundred
3263 # lines up is (named path, redacted reason, exit 2), and the report falls
3264 # back to STDOUT rather than to another file. A fallback file would put
3265 # the run somewhere the operator never named — a second surprise on top
3266 # of the first, able to clobber, and no more likely to succeed when the
3267 # cause is a full or read-only filesystem — while stdout is where this
3268 # exact document would have gone had `-o` not been passed at all. It is
3269 # redirectable and greppable, so the run survives; exit 2 keeps a caller
3270 # from reading the delivery as a success.
3271 try:
3272 with Path(args.output).open("w", encoding="utf-8") as fh:
3273 fh.write(report + "\n")
3274 except OSError as exc:
3275 print(
3276 f"error: could not write the report to "
3277 f"'{redact(args.output)[0]}': {redact(str(exc))[0]}",
3278 file=sys.stderr,
3279 )
3280 print(
3281 "error: the review is complete and is printed on stdout instead; "
3282 "redirect it to keep the report.",
3283 file=sys.stderr,
3284 )
3285 print(report)
3286 return 2
3287 log(f"report written to {redact(args.output)[0]}")
3288 elif not (live_streamed and args.format == "markdown"):
3289 # In --live markdown mode the step stream WAS the stdout output; don't also
3290 # dump the consolidated report (it would duplicate everything just shown).
3291 # For json/sarif the stream is human-readable markdown, so the requested
3292 # machine-readable document must still go to stdout.
3293 print(report)
3295 # The read side of `gh` has been guarded since #836; the write side was not (#844).
3296 # By the time control reaches here the panel has run and the verdict is already on
3297 # stdout, so a `gh` failure — missing CLI, bad token, no write permission, a deleted
3298 # PR, a timeout, a refused spawn — must not replace a finished review with a traceback
3299 # and exit 1. The two kinds are deliberately different:
3300 #
3301 # * `--post-summary` is a contract. Asking for the verdict to be posted and not
3302 # posting it is a failure of the run, so it exits 2 like every other user error.
3303 # * `--post-inline` and `--label` are additions to a review that has already been
3304 # delivered. They report the failure and leave `ci_exit` — the gate's own answer
3305 # about the code — intact, because losing it would turn "the code is fine, GitHub
3306 # hiccuped" into "the gate failed".
3307 def _post(action: str, call, *, contractual: bool) -> bool:
3308 """Run *call*, reporting a `gh` failure instead of letting it escape.
3310 Returns **whether the post landed**, so no caller can log a success that
3311 did not happen. An earlier version returned `2 if contractual else None`,
3312 which made failure and success indistinguishable for the non-contractual
3313 callers — both were `None` — and `--post-inline` printed the error and the
3314 "posted inline comments" line one after the other.
3315 """
3316 try:
3317 call()
3318 except RuntimeError as exc:
3319 # `contractual` is the severity: failing a promise is an error, failing
3320 # an addition to a verdict that did land is a warning. Printing both as
3321 # `error:` while exiting 0 told the reader the opposite of the exit code.
3322 prefix = "error" if contractual else "warning"
3323 print(f"{prefix}: could not {action}: {redact(str(exc))[0]}", file=sys.stderr)
3324 return False
3325 return True
3327 def _reviewed_head() -> str:
3328 """The head SHA the review started on, for the incremental marker (#977).
3330 Always the SHA read at run start, never a fresh read: a push between start and
3331 post would otherwise be marked reviewed without a seat ever seeing it. The head
3332 is read once more here only to tell the operator it moved.
3333 """
3334 if not head_sha:
3335 return ""
3336 from .github import pr_head_sha
3338 now = pr_head_sha(args.pr, args.repo)
3339 if now and now != head_sha:
3340 print(
3341 f"notice: PR #{args.pr} head moved during the review ({head_sha[:7]} -> "
3342 f"{now[:7]}); the marker names the reviewed {head_sha[:7]}, so the next "
3343 "--incremental run picks up the new commits",
3344 file=sys.stderr,
3345 )
3346 return head_sha
3348 if args.post_summary:
3349 if args.issue:
3350 # Plain issues use `gh issue comment`; phased/SHA-marker posting is
3351 # PR-only, so the issue path posts the single rendered report.
3352 if not _post(
3353 f"post the verdict to issue #{args.issue}",
3354 lambda: post_issue_comment(args.issue, report, args.repo),
3355 contractual=True,
3356 ):
3357 return 2
3358 log(f"posted verdict to issue #{args.issue}")
3359 return ci_exit
3360 # Record the reviewed head SHA as a hidden marker so a later
3361 # --incremental run can review only the new range (issue #9).
3362 from .incremental import reviewed_sha_marker
3364 # A missing marker costs a later `--incremental` run its narrowing; it is not
3365 # worth refusing to post the verdict over, so this one degrades rather than exits.
3366 marker_sha = _reviewed_head()
3367 if not marker_sha:
3368 print(
3369 "warning: could not read the PR head sha, so this review will not "
3370 "carry an incremental marker",
3371 file=sys.stderr,
3372 )
3373 marker = f"\n\n{reviewed_sha_marker(marker_sha)}" if marker_sha else ""
3375 if args.post_mode == "phased":
3376 # Post the flow as separate, readable comments (issue #127):
3377 # Round 1 → debate → decision. The SHA marker rides the last one.
3378 from .report import render_sections
3380 sections = render_sections(
3381 outcome.reviews,
3382 outcome.debate,
3383 outcome.synthesis,
3384 chair=outcome.chair,
3385 findings=outcome.findings,
3386 warnings=outcome.warnings,
3387 groups=outcome.groups,
3388 verify=outcome.verify,
3389 vote=vote,
3390 )
3391 # The sections are markdown whatever `--format` says, so the footer
3392 # follows the opt-out alone here.
3393 phased_footer = f"\n\n{render_footer(outcome.reviews)}" if attribution_on else ""
3394 for i, (title, body) in enumerate(sections):
3395 # The last comment carries the footer (render_sections has none),
3396 # then the SHA marker, which must stay last.
3397 tail = f"{phased_footer}{marker}" if i == len(sections) - 1 else ""
3398 if not _post(
3399 f"post phased comment {i + 1} of {len(sections)} to PR #{args.pr}",
3400 lambda t=title, b=body, x=tail: post_pr_comment(
3401 args.pr, f"## {t}\n\n{b}{x}", args.repo
3402 ),
3403 contractual=True,
3404 ):
3405 return 2
3406 log(f"posted {len(sections)} phased comments to PR #{args.pr}")
3407 else:
3408 if not _post(
3409 f"post the verdict to PR #{args.pr}",
3410 lambda: post_pr_comment(args.pr, f"{report}{marker}", args.repo),
3411 contractual=True,
3412 ):
3413 return 2
3414 log(f"posted verdict to PR #{args.pr}")
3416 if args.post_marker and not args.post_summary:
3417 # --post-summary's comment already carries the marker; this is for callers that
3418 # post their own verdict (#977). Only the marker and one human-readable line.
3419 from .incremental import reviewed_sha_marker
3421 marker_sha = _reviewed_head()
3422 if not marker_sha:
3423 print(
3424 "warning: --post-marker skipped: could not read the PR head sha at the "
3425 "start of the review",
3426 file=sys.stderr,
3427 )
3428 elif args.dry_run:
3429 log(f"dry-run: would post the review marker for {marker_sha[:7]} to PR #{args.pr}")
3430 elif _post(
3431 f"post the review marker to PR #{args.pr}",
3432 lambda: post_pr_comment(
3433 args.pr,
3434 f"ai-jury reviewed {marker_sha[:7]} (incremental-review marker; the verdict "
3435 f"is posted separately).\n\n{reviewed_sha_marker(marker_sha)}",
3436 args.repo,
3437 ),
3438 contractual=False,
3439 ):
3440 log(f"posted review marker for {marker_sha[:7]} to PR #{args.pr}")
3442 if args.post_inline and _post(
3443 f"post inline comments to PR #{args.pr}",
3444 lambda: post_inline_comments(
3445 args.pr, outcome.findings, repo=args.repo, dry_run=args.dry_run
3446 ),
3447 contractual=False,
3448 ):
3449 log(f"posted inline comments to PR #{args.pr}")
3451 # Optional GitHub labels (issue #7): OFF by default. Only applied when
3452 # --label is passed AND a --pr target exists; never automatic.
3453 if args.label:
3454 labels = label_strings(classify(outcome))
3455 if _post(
3456 f"apply labels to PR #{args.pr}",
3457 lambda: apply_labels(args.pr, labels, args.repo),
3458 contractual=False,
3459 ):
3460 log(f"applied labels to PR #{args.pr}: {', '.join(labels)}")
3462 return ci_exit
3465if __name__ == "__main__":
3466 raise SystemExit(main())