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

1"""Command-line entry point: ``jury``. 

2 

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""" 

12 

13from __future__ import annotations 

14 

15import argparse 

16import contextlib 

17import io 

18import json 

19import os 

20import shutil 

21import sys 

22from importlib import resources 

23from pathlib import Path 

24 

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 

56 

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 

63 

64 

65def _read_capped(fh, source: str) -> str: 

66 """Read from ``fh``, refusing inputs above the ingest ceiling. 

67 

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") 

85 

86 

87def _checked_revision(value: str, flag: str) -> str: 

88 """Reject a revision that cannot safely reach ``git``'s argv (issue #367). 

89 

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 

104 

105 

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 

109 

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) 

124 

125 

126def _bundled_sample_diff() -> str: 

127 """The offline-demo diff shipped inside the package (issue #21). 

128 

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") 

135 

136 

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 ) 

185 

186 

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 ) 

213 

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 

625 

626 

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 ) 

634 

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) 

663 

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 

685 

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 

690 

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 

698 

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])] 

714 

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) 

726 

727 if ns.dry_run: 

728 print("Dry run: nothing was written.", file=sys.stderr) 

729 return 0 

730 

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 

746 

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 

757 

758 

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. 

762 

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 

767 

768 from .commands import CommandError, parse_comment 

769 

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) 

787 

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 

793 

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] 

801 

802 if ns.print_args: 

803 print(" ".join(shlex.quote(a) for a in inner)) 

804 return 0 

805 return main(inner) 

806 

807 

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} 

821 

822 

823def _default_init_agents(available: dict) -> list[str]: 

824 """The agents an interactive `jury init` pre-fills: detected, never opt-in-only. 

825 

826 agy stays listed and can be typed in, but pressing Enter never seats it. 

827 """ 

828 from .scaffold import KNOWN_AGENTS, implicit_choices 

829 

830 detected = implicit_choices(n for n in KNOWN_AGENTS if available.get(n)) 

831 return detected or implicit_choices(KNOWN_AGENTS) 

832 

833 

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 

838 

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 

847 

848 

849def _stdin_is_terminal() -> bool: 

850 """Whether ``jury init`` can prompt: stdin exists and is a terminal. 

851 

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() 

856 

857 

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. 

860 

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 

866 

867 if models_fn is None: 

868 from .adapters import list_local_models as models_fn 

869 

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 

877 

878 rounds_raw = input_fn("Rounds — 1=review, 2=+debate [2]: ").strip() 

879 rounds = int(rounds_raw) if rounds_raw.isdigit() else 2 

880 

881 chair_default = agents[0] if agents else "claude" 

882 chair = input_fn(f"Chair agent [{chair_default}]: ").strip() or chair_default 

883 

884 verify = (input_fn("Run verification round? [Y/n]: ").strip().lower() or "y") != "n" 

885 

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 

890 

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 

911 

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 

917 

918 return { 

919 "agents": agents, 

920 "rounds": rounds, 

921 "chair": chair, 

922 "verify": verify, 

923 "local_model": local_model, 

924 "effort": effort, 

925 } 

926 

927 

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). 

930 

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 

938 

939 if models_fn is None: 

940 from .adapters import list_local_models as models_fn 

941 

942 def ask(prompt: str) -> str: 

943 return input_fn(prompt).strip() 

944 

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 

957 

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 ) 

964 

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 

972 

973 kwargs: dict = {"agents": agents} 

974 

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 

995 

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" 

1000 

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" 

1005 

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 

1017 

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"] = [] 

1028 

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 

1033 

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 

1037 

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 

1060 

1061 return kwargs 

1062 

1063 

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 ) 

1078 

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) 

1112 

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 

1135 

1136 from .adapters import list_local_models, local_model_listing 

1137 from .redaction import redact_url_userinfo 

1138 

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) 

1144 

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 

1154 

1155 available = _init_available() 

1156 

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 

1166 

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] = [] 

1172 

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)) 

1176 

1177 def _selectable_agents(): 

1178 """Every known agent whose template scaffolds to a *valid* config here. 

1179 

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) 

1191 

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) 

1198 

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") 

1203 

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 } 

1273 

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 

1279 

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 

1286 

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 

1294 

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 

1314 

1315 from .doctor import _local_model_gap 

1316 

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 

1325 

1326 

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). 

1329 

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] 

1340 

1341 

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)" 

1347 

1348 

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) 

1387 

1388 

1389def _run_config(rest: list[str]) -> int: 

1390 """Handle ``jury config show|path``.""" 

1391 from .config import ConfigError, load_config 

1392 

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) 

1397 

1398 source = _config_source(ns.config) 

1399 if ns.action == "path": 

1400 print(source) 

1401 return 0 

1402 

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 

1414 

1415 

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 

1419 

1420 

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 

1442 

1443 

1444def _run_agent_parser() -> argparse.ArgumentParser: 

1445 """The ``jury run-agent`` flag surface (built separately so it can be tested).""" 

1446 from . import runagent 

1447 

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 

1535 

1536 

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 

1571 

1572 

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. 

1575 

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 

1583 

1584 from . import runagent 

1585 from .adapters import effort_args, make_adapter 

1586 

1587 ns = _run_agent_parser().parse_args(rest) 

1588 

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 

1607 

1608 if ns.status: 

1609 print(json.dumps({"runs": runagent.list_runs(ns.cache_dir)}, indent=2)) 

1610 return 0 

1611 

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 

1671 

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 

1687 

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) 

1696 

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 ) 

1708 

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 

1721 

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 

1730 

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) 

1745 

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 

1754 

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 

1764 

1765 if ns.detach: 

1766 return _detach_run_agent(ns, spec, policy, spawn=spawn) 

1767 

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 

1772 

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 

1816 

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 

1824 

1825 

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 

1829 

1830 from . import runagent 

1831 from .adapters import ERR_UNKNOWN, AgentResult 

1832 

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 ) 

1847 

1848 

1849def _child_recorder(ns, spec, policy, started: float): 

1850 """A callable that writes a detached child's state file (issue #661). 

1851 

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. 

1857 

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 

1862 

1863 del spec, policy 

1864 

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) 

1882 

1883 return record 

1884 

1885 

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 

1889 

1890 from . import runagent 

1891 

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 

1901 

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 

1912 

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 

1925 

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 

1947 

1948 

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 = [] 

1953 

1954 

1955def _spawn_detached(argv: list[str], out_path: Path) -> int: 

1956 """Start the background child, streaming its stdout+stderr to ``out_path``. 

1957 

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 

1964 

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 

1985 

1986 

1987def _run_replay(rest: list[str]) -> int: 

1988 """Handle ``jury replay <outcome.json>`` (issue #449). 

1989 

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 

1995 

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) 

2034 

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 

2040 

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 

2046 

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) 

2051 

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 

2057 

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 ) 

2069 

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 

2084 

2085 

2086_PROGRESS_PREFIXES = ( 

2087 "round ", 

2088 "reviewing chunk", 

2089 "verification", 

2090 "synthesis", 

2091 "diff size", 

2092 "early stop", 

2093 "auto-depth", 

2094) 

2095 

2096 

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) 

2100 

2101 

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) 

2129 

2130 

2131def _override_bound_error(args) -> str | None: 

2132 """The first CLI override breaking a bound ``validate_config`` enforces. 

2133 

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 

2146 

2147 

2148def _maybe_add_local_fallback(config, args, log): 

2149 """Append a local agent when nothing else can run, offline (issue: zero-config). 

2150 

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. 

2155 

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 

2164 

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 

2189 

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 

2194 

2195 

2196def _force_utf8_output() -> None: 

2197 """Ensure stdout/stderr can emit the report's Unicode (emoji, arrows). 

2198 

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") 

2210 

2211 

2212_OVERVIEW = """\ 

2213🏛️ ai-jury — a cross-vendor multi-agent review jury. 

2214 

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. 

2218 

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 

2227 

2228Docs: https://github.com/berkayturanci/ai-jury""" 

2229 

2230_EXAMPLES = """\ 

2231ai-jury — example commands 

2232 

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 

2238 

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) 

2245 

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) 

2249 

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 

2254 

2255Run `jury guide` for a walkthrough, or `jury --help` for every option.""" 

2256 

2257_GUIDE = """\ 

2258ai-jury — a short walkthrough 

2259 

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 

2264 

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. 

2268 

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 

2273 

2274 The panel reviews independently, cross-examines (debate), the chair verifies 

2275 candidate findings to cut false positives, then synthesizes one verdict. 

2276 

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 

2280 

22815. Gate CI on blocking findings (optional): 

2282 jury --pr 123 --ci # non-zero exit on critical/major 

2283 

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""" 

2287 

2288 

2289def _events_dir_for(args: argparse.Namespace) -> Path | None: 

2290 """The directory this run writes its own events file to, if any. 

2291 

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``. 

2298 

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 

2304 

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 

2311 

2312 return _events.watched_dir(default_cache_dir() / "events") 

2313 

2314 

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 

2319 

2320 return requested_model(spec) or None 

2321 except Exception: # noqa: BLE001 - a side channel: the run never fails for it 

2322 return None 

2323 

2324 

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 

2331 

2332 

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" 

2344 

2345 

2346def main(argv: list[str] | None = None) -> int: 

2347 _force_utf8_output() 

2348 raw = list(sys.argv[1:] if argv is None else argv) 

2349 

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 

2359 

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 

2382 

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 

2394 

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:]) 

2401 

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:]) 

2407 

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:]) 

2413 

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:]) 

2418 

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:]) 

2424 

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:]) 

2430 

2431 args = build_parser().parse_args(argv) 

2432 

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 

2441 

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 

2452 

2453 if args.clear_cache: 

2454 from .cache import Cache 

2455 

2456 removed = Cache(args.cache_dir).clear() 

2457 print(f"Cleared {removed} cache entr{'y' if removed == 1 else 'ies'}.") 

2458 return 0 

2459 

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 

2492 

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 

2511 

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) 

2616 

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 

2622 

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 ) 

2653 

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)") 

2671 

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 

2679 

2680 progress = ProgressReporter(args.pr, args.repo) 

2681 

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) 

2687 

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) 

2693 

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 

2700 

2701 head_sha = pr_head_sha(args.pr, args.repo) 

2702 

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 

2710 

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 

2721 

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) 

2738 

2739 if not diff.strip(): 

2740 raise SystemExit("error: empty diff — nothing to review") 

2741 

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 

2747 

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)) 

2757 

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 

2770 

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 

2789 

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)") 

2795 

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 

2809 

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") 

2825 

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 

2848 

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() 

2867 

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 

2873 

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 ) 

2911 

2912 on_event = None 

2913 if args.live or theater_on or events is not None: 

2914 

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]}") 

2930 

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 

2934 

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]}…)") 

2987 

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 

2995 

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 ) 

3006 

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() 

3013 

3014 if events is not None: 

3015 from .ballots import chair_verdict, reviewer_ballots 

3016 

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() 

3034 

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" 

3041 

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 ) 

3054 

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 

3060 

3061 if args.format == "json": 

3062 from .formats import to_json 

3063 

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 

3074 

3075 report = to_sarif(outcome, config) 

3076 elif args.format == "keel-reviews": 

3077 from .formats import to_keel_reviews 

3078 

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 ) 

3126 

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]}") 

3131 

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 

3158 

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" 

3223 

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 

3229 

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") 

3240 

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) 

3248 

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}") 

3253 

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) 

3294 

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. 

3309 

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 

3326 

3327 def _reviewed_head() -> str: 

3328 """The head SHA the review started on, for the incremental marker (#977). 

3329 

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 

3337 

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 

3347 

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 

3363 

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 "" 

3374 

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 

3379 

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}") 

3415 

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 

3420 

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}") 

3441 

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}") 

3450 

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)}") 

3461 

3462 return ci_exit 

3463 

3464 

3465if __name__ == "__main__": 

3466 raise SystemExit(main())