@agentsdance/codejury 0.1.0 → 0.1.2

package/README.md

@@ -21,6 +21,13 @@ head commit, reviews an isolated temporary checkout, and pushes accepted fixes
 back to the source branch. It is safe to invoke from `master` or from outside
 the target repository; the caller's working tree is not switched or modified.
 
+GitLab and compatible self-hosted services are supported through
+`/merge_requests/<id>` URLs. Jury clones with Git and fetches the standard
+`refs/merge-requests/<id>/head` ref, so existing Git credentials are used. If
+the source branch is not uniquely visible on the target remote (commonly a
+fork), use `--no-push` for a read-only review or check out the source branch
+locally and pass `--dir`.
+
 Node 20 or newer. The reviewers are separate CLIs you install yourself — `jury` spawns whatever you
 have and skips the rest:
 
@@ -34,6 +41,17 @@ used. The former `cr.config.json` and `macr.config.json` names remain readable f
 
 The former `cr` command remains available as a compatibility alias.
 
+## Working and state directory
+
+With no `--dir`, Jury keeps the current directory when it is a Git worktree. From anywhere else it
+uses `~/.jury` and creates that directory automatically. An explicitly empty `--dir ""` also selects
+`~/.jury`; a non-empty explicit path always wins. `~` is expanded consistently for review, web,
+runs, findings, and reply commands.
+
+Run records live in `<dir>/runs`. For example, `jury runs --dir ""` and `jury web --dir ""` read
+`~/.jury/runs`, while a review launched from a repository continues to use that repository's
+`runs` directory.
+
 ## The loop
 
 ```
@@ -76,12 +94,21 @@ standalone, against runs that already exist.
 
 ## Who writes, and who only reads
 
-Exactly one agent has role `main` — **Claude Code**, the session driving the loop. It owns the working
-tree and the commit, triages every finding, and is the only writer. Its registry entry carries an
-empty `argv` because it is never spawned; `jury agents` shows it as in-process:
+Exactly one agent has role `main`; it is the default **judge**. The built-in default is Claude Code.
+The judge owns the working tree and commit, triages every finding, and is the only writer. Choose a
+different enabled agent for one run with `--judge`; without that flag Claude remains the default:
+
+```bash
+jury https://github.com/owner/repo/pull/1                 # Claude judges
+jury --judge codex https://github.com/owner/repo/pull/1   # Codex judges
+```
+
+`--judge` accepts exactly one agent name. The selected judge is removed from that run's reviewer
+pool, so it never reviews its own work.
+`jury agents` shows the configured roles:
 
 ```
-ok      claude   main     (in-process)
+ok      claude   main     /usr/local/bin/claude
 ok      codex    reviewer /usr/local/bin/codex
 ok      agy      reviewer /usr/local/bin/agy
 ```
@@ -89,7 +116,7 @@ ok      agy      reviewer /usr/local/bin/agy
 Reviewers only read and report. A registry with two `main` entries is refused outright — two agents
 both believing they own the commit corrupts a run rather than merely failing it.
 
-The main agent then holds **one conversation per reviewer**, concurrently, each about that reviewer's
+The judge then holds **one conversation per reviewer**, concurrently, each about that reviewer's
 own findings and nothing else:
 
 ```

package/bin/jury.js

@@ -10,16 +10,17 @@ import { execFile } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { promisify } from "node:util";
 import path from "node:path";
-import { loadConfig, reviewers, mainAgent } from "../lib/config.js";
+import { loadConfig, reviewers, judgeAgent } from "../lib/config.js";
 import { runAgent, probe } from "../lib/agents.js";
 import { threadFor, buildReply, replyArgv } from "../lib/reply.js";
 import { buildPrompt } from "../lib/prompt.js";
 import { serve } from "../lib/server.js";
 import { appendEvent, writeRun, readEvents, foldEvents, slugFor, attemptStamp, runsDir, writeArtifact, openArtifact } from "../lib/store.js";
 import { findingsIn, gate, settledList, VERDICTS } from "../lib/findings.js";
-import { MAX_TURNS, turnsFor, outstanding, deadlocked, refreshSettled, replyRound, record, sessionsIn, openFindings } from "../lib/loop.js";
+import { MAX_TURNS, turnsFor, outstanding, deadlocked, refreshSettled, replyRound, record, sessionsIn, openFindings, currentJudge } from "../lib/loop.js";
 import { triageOne } from "../lib/triage.js";
-import { assertPrCheckout, resolvePrCheckout } from "../lib/repository.js";
+import { assertPrCheckout, repositoryFromPrUrl, resolvePrCheckout } from "../lib/repository.js";
+import { resolveJuryDirectory } from "../lib/directories.js";
 import * as st from "../lib/style.js";
 
 const run = promisify(execFile);
@@ -50,10 +51,11 @@ const USAGE = `jury — run a pull request past several AI reviewers until they
 
 Common flags
 
+  --dir <path>             working/state root      (default: Git cwd or ~/.jury)
   --rounds <n>             stop after n rounds            (default 10)
   --agents codex,grok      only these reviewers           (default: all installed)
+  --judge codex            one agent that triages and fixes       (default: claude)
   --no-push                fix locally, do not push
-  --dry-run                exercise the pipeline, spawn nothing
 
 Other commands
 
@@ -67,7 +69,7 @@ Other commands
 
 const USAGE_FULL = `jury — multi-agent code review
 
-  jury <pr-url>             review a PR: rounds until convergence, one conversation per reviewer
+  jury <pr-url>             review a PR until every reviewer approves, one conversation per reviewer
   jury review-once [flags]  a single round, no triage or reply
   jury web [flags]          serve the console (default http://127.0.0.1:3080)
   jury finding <cmd>        list | reproduce | resolve | settled — appends events, enforces the gate
@@ -80,39 +82,46 @@ review                           (drives itself; no operator between rounds)
   jury https://github.com/owner/repo/pull/1
   jury --rounds 3                  the current branch, no PR
 
-  --dir <path>       repo/worktree                            (default .)
+  --dir <path>       repo/worktree      (default: cwd if Git, otherwise ~/.jury)
   --pr <url>         same as the positional argument
   --trunk <branch>   diff base branch          (default: the remote's own HEAD)
   --title <text>     what the change does         (default: read from the PR)
   --summary <text>   intent, passed to reviewers  (default: the PR description)
   --rounds <n>       maximum rounds                           (default 10)
   --agents a,b       only these reviewers            (default: all installed)
+  --judge <agent>    one agent that triages and fixes       (default: claude)
   --resume <slug>    continue an existing run instead of starting a new one
   --web              open the console on this run          (stays up when it ends)
   --port <n>         console port, with --web              (default 3080)
   --no-push          commit fixes to the worktree without pushing
-  --dry-run          exercise the pipeline, spawn nothing
+  --dry-run          (internal) exercise the pipeline, spawn no agents. Always
+                     reports clean and triages nothing, so it says whether the
+                     plumbing runs and never whether the code is good.
 
 review-once flags
-  --dir <path>       repo/worktree the reviewers read        (default .)
+  --dir <path>       repo/worktree       (default: cwd if Git, otherwise ~/.jury)
   --pr <url>         pull request URL, recorded on the run
   --title <text>     what the change does, shown in the console
   --summary <text>   a few lines of intent, passed to reviewers
   --trunk <branch>   diff base branch                        (default master)
   --round <n>        round number                            (default: next)
   --agents a,b       only these reviewers                    (default: all enabled)
-  --max-rounds <n>   keep going until convergence, at most n (default 1)
-  --dry-run          do not spawn anything; exercise the pipeline
+  --max-rounds <n>   keep going until every reviewer approves, at most n (default 1)
 
 web flags
+  --dir <path>       run-state root       (default: cwd if Git, otherwise ~/.jury)
   --port <n>         default 3080, walks forward if busy
   --open             open a browser
 
-finding commands                                (--run <slug> picks the run)
+finding commands                     (--dir picks state root; --run picks run)
   jury finding list
   jury finding reproduce <id> --evidence <text> [--test <text>]
   jury finding resolve <id> --verdict <${VERDICTS.join("|")}> [--reason <text>] [--test <text>]
   jury finding settled                          print the regenerated settled list
+
+state commands
+  jury runs [--dir <path>]
+  jury reply [--dir <path>] [--run <slug>]
 `;
 
 let [, , cmd, ...rest] = process.argv;
@@ -147,7 +156,7 @@ try {
     case "web": await cmdWeb(rest); break;
     case "finding": case "findings": await cmdFinding(rest); break;
     case "reply": await cmdReply(rest); break;
-    case "runs": await cmdRuns(); break;
+    case "runs": await cmdRuns(rest); break;
     case "agents": await cmdAgents(); break;
     case "version": case "-v": case "--version": console.log(`jury ${VERSION}`); break;
     case "help": case "-h": case "--help": case undefined:
@@ -168,11 +177,49 @@ try {
   process.exit(1);
 }
 
+/** Resolve an explicit reviewer list or explain each ineligible name. */
+function selectReviewers(cfg, requested, judge = null) {
+  const eligible = reviewers(cfg).filter((a) => a.name !== judge);
+  if (!requested) return eligible;
+
+  const names = [...new Set(requested.split(",").map((s) => s.trim()).filter(Boolean))];
+  if (!names.length) throw new Error("--agents needs at least one reviewer name");
+
+  const byName = new Map(cfg.agents.map((a) => [a.name, a]));
+  const allowed = new Set(eligible.map((a) => a.name));
+  const problems = names.filter((name) => !allowed.has(name)).map((name) => {
+    const agent = byName.get(name);
+    if (name === judge) return `"${name}" is the selected judge and cannot review its own work`;
+    if (agent) return `"${name}" has role "${agent.role ?? "reviewer"}", not "reviewer"`;
+    return `"${name}" is not configured or is disabled`;
+  });
+  if (problems.length) {
+    const available = eligible.map((a) => a.name).join(", ") || "none";
+    throw new Error(
+      `requested reviewer ${problems.join("; ")}. Add or enable it with role "reviewer" in ${path.basename(cfg.configFile)}. Available enabled reviewers: ${available}`,
+    );
+  }
+  return eligible.filter((a) => names.includes(a.name));
+}
+
+async function commandDirectory(value) {
+  return resolveJuryDirectory(value, {
+    isUsable: async (dir) => {
+      try {
+        await run("git", ["-C", dir, "rev-parse", "--is-inside-work-tree"]);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  });
+}
+
 async function cmdReview(argv) {
   const { values } = parseArgs({
     args: argv, allowPositionals: false,
     options: {
-      dir: { type: "string", default: "." },
+      dir: { type: "string" },
       pr: { type: "string" },
       title: { type: "string" },
       summary: { type: "string", default: "" },
@@ -189,14 +236,9 @@ async function cmdReview(argv) {
     throw new Error("--max-rounds must be a positive integer");
   }
 
-  const worktree = path.resolve(values.dir);
+  const worktree = await commandDirectory(values.dir);
   const cfg = await loadConfig(worktree);
-  let pool = reviewers(cfg);
-  if (values.agents) {
-    const want = new Set(values.agents.split(",").map((s) => s.trim()));
-    pool = pool.filter((a) => want.has(a.name));
-    if (!pool.length) throw new Error(`no configured reviewer matches "${values.agents}"`);
-  }
+  const pool = selectReviewers(cfg, values.agents);
 
   const git = await describe(worktree, values.trunk);
   if (values.pr) assertPrCheckout(values.pr, git.remote, worktree);
@@ -214,7 +256,7 @@ async function cmdReview(argv) {
     stateNote: "",
   };
 
-  const dir = path.join(runsDir(), slugFor(target));
+  const dir = path.join(runsDir(worktree), slugFor(target));
   const prior = await readEvents(dir);
   const firstRound = values.round
     ? Number(values.round)
@@ -223,7 +265,7 @@ async function cmdReview(argv) {
   console.log(`target   ${target.repo} ${target.id}`);
   console.log(`worktree ${worktree} @ ${git.sha}`);
   console.log(`agents   ${pool.map((a) => a.name).join(", ")}${values["dry-run"] ? "  (dry run)" : ""}`);
-  if (maxRounds > 1) console.log(`rounds   ${firstRound}..${firstRound + maxRounds - 1} (until convergence)`);
+  if (maxRounds > 1) console.log(`rounds   ${firstRound}..${firstRound + maxRounds - 1} (until every reviewer approves)`);
   console.log("");
 
   for (let i = 0; i < maxRounds; i++) {
@@ -243,7 +285,7 @@ async function cmdReview(argv) {
 }
 
 /** One round: prompt, launch every reviewer, record what they said. */
-async function runRound({ dir, round, pool, cfg, target, worktree, values, sha }) {
+async function runRound({ dir, round, pool, cfg, target, worktree, values, sha, announceCompletion = true }) {
   const git = { sha };
   console.log(st.info(st.bold(`round ${round}`)));
 
@@ -384,13 +426,17 @@ async function runRound({ dir, round, pool, cfg, target, worktree, values, sha }
   // The state the run was launched with says "review", which stops being true
   // the moment the round ends. Restate it, or the console keeps asserting a
   // review is running after it converged.
-  const state = errored.length ? "human" : clean ? "converged" : "review";
+  const state = errored.length ? "human" : clean && announceCompletion ? "converged" : "review";
   const stateNote = errored.length
     ? `${errored.length} reviewer(s) failed to run`
     : clean
-      ? `converged on ${git.sha}`
+      ? announceCompletion ? "Review complete" : `round ${round} clean — checking outstanding findings`
       : `round ${round} — ${raised || "unparsed"} finding(s) to triage`;
-  await appendEvent(dir, { t: "target", target: { ...target, state, stateNote } });
+  const reviewedCommit = clean && !errored.length && announceCompletion ? git.sha : "";
+  await appendEvent(dir, {
+    t: "target",
+    target: { ...target, state, stateNote, ...(reviewedCommit ? { reviewedCommit } : {}) },
+  });
   await appendEvent(dir, { t: "round.end", n: round });
   await publish();
 
@@ -410,8 +456,10 @@ async function runRound({ dir, round, pool, cfg, target, worktree, values, sha }
     console.log(st.bad(`${st.count(errored.length, "reviewer")} failed to run — see the reports below.`));
   }
   console.log(clean && !errored.length
-    ? st.ok(`CONVERGED — every reviewer emitted the stop token on ${git.sha}.`)
-    : st.warn(`NOT converged. Triage, fix what reproduces, push, then round ${round + 1}.`));
+    ? announceCompletion
+      ? `${st.ok("REVIEW COMPLETE — every reviewer approved.")}\n${st.muted(`Reviewed commit ${git.sha}.`)}`
+      : `${st.ok("ROUND CLEAN — every reviewer approved this commit.")}\n${st.muted(`Reviewed commit ${git.sha}.`)}`
+    : st.warn(`REVIEW INCOMPLETE — triage findings, fix what reproduces, push, then run round ${round + 1}.`));
   console.log(st.muted(`recorded: ${path.relative(process.cwd(), dir)}`));
 
   // Every reviewer's report, including the clean ones: a sign-off still says
@@ -446,16 +494,19 @@ async function runRound({ dir, round, pool, cfg, target, worktree, values, sha }
  *   the round cap      --rounds, default 10
  */
 async function cmdAgent(argv) {
+  const judgeFlags = argv.filter((a) => a === "--judge" || a.startsWith("--judge="));
+  if (judgeFlags.length > 1) throw new Error("--judge accepts exactly one agent");
   const { values, positionals } = parseArgs({
     args: argv, allowPositionals: true,
     options: {
-      dir: { type: "string", default: "." },
+      dir: { type: "string" },
       pr: { type: "string" },
       title: { type: "string" },
       summary: { type: "string" },
       trunk: { type: "string" },
       rounds: { type: "string", default: "10" },
       agents: { type: "string" },
+      judge: { type: "string" },
       push: { type: "boolean", default: true },
       "no-push": { type: "boolean", default: false },
       resume: { type: "string" },
@@ -464,6 +515,7 @@ async function cmdAgent(argv) {
       port: { type: "string", default: "3080" },
     },
   });
+  if (values.judge?.includes(",")) throw new Error("--judge accepts exactly one agent, not a list");
 
   // The PR link is the argument. `--pr` still works, but a flag for the one
   // thing every invocation names is ceremony: `jury agent <url>` is what
@@ -481,9 +533,9 @@ async function cmdAgent(argv) {
   }
 
   values.push = values.push && !values["no-push"];
-  const requestedWorktree = path.resolve(values.dir);
+  const requestedWorktree = await commandDirectory(values.dir);
   const resolved = values.pr
-    ? await resolvePrCheckout(values.pr, { allowPush: values.push })
+    ? await resolvePrCheckout(values.pr, { allowPush: values.push, dir: requestedWorktree })
     : null;
   const worktree = resolved?.worktree ?? requestedWorktree;
   resolvedCheckoutCleanup = resolved?.cleanup ?? null;
@@ -491,21 +543,6 @@ async function cmdAgent(argv) {
   // A local ignored config belongs to the requested checkout. An automatic
   // clone intentionally starts from the repository's committed/default config.
   const cfg = await loadConfig(resolved ? worktree : requestedWorktree);
-  const main = mainAgent(cfg);
-  if (!main) {
-    // A run with no main agent has no one to triage or fix — every finding
-    // would stay open and every round would re-raise it. Better to say so than
-    // to burn ten rounds discovering it.
-    throw new Error('no agent has role "main" — the loop has nobody to triage or fix');
-  }
-
-  let pool = reviewers(cfg);
-  if (values.agents) {
-    const want = new Set(values.agents.split(",").map((s) => s.trim()));
-    pool = pool.filter((a) => want.has(a.name));
-  }
-  if (!pool.length) throw new Error("no reviewers configured — nothing would review anything");
-
   const git = await describe(worktree);
 
   // Both asked for rather than assumed: the trunk from the remote's own HEAD,
@@ -550,20 +587,41 @@ async function cmdAgent(argv) {
   // into rounds 1-5 of a single run, and a killed run's open rounds interleaved
   // with the next one's.
   target.attempt = values.resume ? "" : attemptStamp();
+  const stateBase = runsDir(requestedWorktree);
   const dir = values.resume
-    ? path.join(runsDir(), path.basename(values.resume))
-    : path.join(runsDir(), slugFor(target));
+    ? path.join(stateBase, path.basename(values.resume))
+    : path.join(stateBase, slugFor(target));
   const prior = await readEvents(dir);
   if (values.resume && !prior.length) {
-    throw new Error(`no run at ${path.relative(process.cwd(), dir)} — check \`jury runs\``);
+    throw new Error(
+      `no run at ${dir} — pass --dir <root-that-contains-runs>, then check \`jury runs --dir <root>\``,
+    );
+  }
+  const priorJudge = [...prior].reverse()
+    .find((e) => e.t === "target" && e.target?.judge)?.target.judge;
+  const requestedJudge = values.judge ?? (values.resume ? priorJudge : null);
+  const judge = judgeAgent(cfg, requestedJudge);
+  if (!judge) {
+    const available = cfg.agents.map((a) => a.name).join(", ") || "none";
+    if (requestedJudge) {
+      throw new Error(`judge "${requestedJudge}" is not an enabled configured agent — available: ${available}`);
+    }
+    throw new Error('no agent has role "main" — configure one or pass --judge <agent>');
   }
+  target.judge = judge.name;
+
+  // A judge cannot independently review its own work. Other configured main
+  // agents stay out of the pool rather than being silently demoted to writers
+  // with a read-only prompt.
+  const pool = selectReviewers(cfg, values.agents, judge.name);
+  if (!pool.length) throw new Error("no reviewers configured after excluding the judge");
   const first = Math.max(0, ...prior.filter((e) => e.t === "round.start").map((e) => e.n)) + 1;
 
   console.log(st.field("target", `${target.repo} ${st.bold(target.id)}`));
   console.log(st.field("worktree", st.muted(`${worktree} @ ${git.sha} (${resolved?.branch ?? git.branch})`)));
   console.log(st.field("trunk", `${trunk}${trunkGiven ? st.muted("  (detected)") : ""}`));
   if (target.title) console.log(st.field("title", target.title.slice(0, 72)));
-  console.log(st.field("main", st.agent(main.name)));
+  console.log(st.field("judge", st.agent(judge.name)));
   console.log(st.field("agents", pool.map((a) => st.agent(a.name)).join(", ")
     + (values["dry-run"] ? st.warn("  (dry run)") : "")));
   console.log(st.field("rounds", st.muted(`${first}..${first + maxRounds - 1}, ${MAX_TURNS} turns per finding`)));
@@ -594,6 +652,9 @@ async function cmdAgent(argv) {
     const head = await describe(worktree, values.trunk);
     const converged = await runRound({
       dir, round, pool, cfg, target, worktree, values, sha: head.sha,
+      // A clean round is not necessarily a complete review: an earlier finding
+      // can still be open. This loop announces completion only after checking.
+      announceCompletion: false,
     });
     if (converged) {
       // Clean is not enough on its own. A finding left open by the previous
@@ -605,7 +666,11 @@ async function cmdAgent(argv) {
       // convergence.
       const open = await openFindings(dir);
       if (!open.length) {
-        console.log(st.ok(`\nCONVERGED after ${st.count(round - first + 1, "round")}.`));
+        console.log(st.ok(`\nREVIEW COMPLETE after ${st.count(round - first + 1, "round")}.`));
+        console.log(st.muted(`Reviewed commit ${head.sha}.`));
+        await publishRun(dir, {
+          ...target, state: "converged", stateNote: "Review complete", reviewedCommit: head.sha,
+        });
         return;
       }
       console.log(st.warn(`\nevery reviewer is clean, but ${st.count(open.length, "finding")} from earlier ${open.length === 1 ? "is" : "are"} still open.`));
@@ -625,7 +690,7 @@ async function cmdAgent(argv) {
       return;
     }
 
-    console.log(`\n${st.rule(`triage · ${st.count(todo.length, "finding")} → ${main.name}`)}`);
+    console.log(`\n${st.rule(`triage · ${st.count(todo.length, "finding")} → ${judge.name}`)}`);
     let fixed = 0;
     for (const f of todo) {
       // The turn limit ends an argument the loop cannot win. Both positions are
@@ -635,6 +700,7 @@ async function cmdAgent(argv) {
         const r = await record(dir, findings, f.id, {
           verdict: "deferred",
           reason: `argued ${MAX_TURNS} turns without agreement; both positions are in the log`,
+          who: judge.name,
         });
         console.log(`  ${st.muted(f.id)}  ${st.verdict("deferred")} ${st.muted(`(turn limit)${r.ok ? "" : ` — ${r.why}`}`)}`);
         continue;
@@ -648,10 +714,10 @@ async function cmdAgent(argv) {
       // Tagged with the reviewer whose finding this is: threads are per
       // reviewer, and a heartbeat filed under "claude" opened a claude thread
       // of its own, splitting one conversation in two.
-      const heart = beat(dir, main.name, round, f.agent);
+      const heart = beat(dir, judge.name, round, f.agent);
       let v;
       try {
-        v = await triageOne(main, f, {
+        v = await triageOne(judge, f, {
           worktree, trunk, stopToken: cfg.stopToken, dryRun: values["dry-run"],
           onLog: (m) => console.log(`          ${st.muted(m)}`),
         });
@@ -672,6 +738,7 @@ async function cmdAgent(argv) {
       if (v.reproduced) {
         await appendEvent(dir, {
           t: "finding.reproduced", id: f.id, evidence: v.reproduced, test: v.test ?? null,
+          who: judge.name,
         });
       }
       // Refold BEFORE recording, not after. gate() checks the finding it is
@@ -681,7 +748,7 @@ async function cmdAgent(argv) {
       // described the right order; the code did not implement it.
       findings = await findingsIn(dir);
       const res = await record(dir, findings, f.id, {
-        verdict: v.verdict, reason: v.reason, test: v.test,
+        verdict: v.verdict, reason: v.reason, test: v.test, who: judge.name,
       });
       if (!res.ok) {
         // The gate refusing is the gate working. Downgrade rather than crash:
@@ -698,6 +765,7 @@ async function cmdAgent(argv) {
       if (c?.sha) {
         await appendEvent(dir, {
           t: "commit.pushed", sha: c.sha, pushed: c.pushed, subject: `round ${round} fixes`,
+          who: judge.name,
         });
         console.log(`commit   ${c.sha}${
           c.pushed === null ? "" : c.pushed ? ` → pushed to ${pushTarget.branch}` : "  (NOT pushed)"}`);
@@ -712,7 +780,7 @@ async function cmdAgent(argv) {
     // concede or push back.
     const after = await findingsIn(dir);
     const answers = await replyRound({
-      dir, pool, cfg, worktree, sha: head.sha, round, findings: after,
+      dir, pool, cfg, worktree, sha: head.sha, round, findings: after, judge: judge.name,
       sessions: sessionsIn(await readEvents(dir)),
       dryRun: values["dry-run"],
       // Prefixed like the launch line: without a name this printed a bare
@@ -739,17 +807,18 @@ async function cmdAgent(argv) {
     const stillOpen = [...settled.values()].filter((f) => f.status === "open");
     const broke = answers.filter((a) => a.failed);
     if (answers.every((a) => a.clean) && !stillOpen.length && !broke.length && !pushFailed) {
-      console.log(st.ok(st.bold(`\nCONVERGED — every reviewer signed off after round ${round}.`)));
+      console.log(st.ok(st.bold(`\nREVIEW COMPLETE — every reviewer approved after round ${round}.`)));
+      console.log(st.muted(`Reviewed commit ${head.sha}.`));
       await publishRun(dir, {
-        ...target, state: "converged", stateNote: `converged after round ${round}`,
+        ...target, state: "converged", stateNote: "Review complete", reviewedCommit: head.sha,
       });
       return;
     }
     if (stillOpen.length) {
-      console.log(st.warn(`\n${st.count(stillOpen.length, "finding")} still open — not convergence.`));
+      console.log(st.warn(`\n${st.count(stillOpen.length, "finding")} still open — review incomplete.`));
     }
     if (broke.length) {
-      console.log(st.bad(`${broke.map((a) => a.agent).join(", ")} could not run — this run cannot converge.`));
+      console.log(st.bad(`${broke.map((a) => a.agent).join(", ")} could not run — this review cannot complete.`));
     }
     if (pushFailed) {
       console.log(st.bad("a push failed — the reviewers are reading code the PR does not have."));
@@ -826,11 +895,16 @@ async function cleanupResolvedCheckout() {
 async function cmdWeb(argv) {
   const { values } = parseArgs({
     args: argv, allowPositionals: false,
-    options: { port: { type: "string", default: "3080" }, open: { type: "boolean", default: false } },
+    options: {
+      dir: { type: "string" },
+      port: { type: "string", default: "3080" },
+      open: { type: "boolean", default: false },
+    },
   });
-  const { url, port } = await serve({ port: Number(values.port) });
+  const root = await commandDirectory(values.dir);
+  const { url, port } = await serve({ port: Number(values.port), cwd: root });
   console.log(`console: ${url}`);
-  console.log(`runs:    ${path.relative(process.cwd(), runsDir()) || "runs"}/`);
+  console.log(`runs:    ${runsDir(root)}/`);
   if (values.open) openBrowser(url);
   process.on("SIGINT", () => { console.log("\nstopped"); process.exit(0); });
   return new Promise(() => {}); // serve until interrupted
@@ -854,6 +928,7 @@ async function cmdFinding(argv) {
     args: rest, allowPositionals: true,
     options: {
       run: { type: "string" },
+      dir: { type: "string" },
       evidence: { type: "string" },
       test: { type: "string" },
       verdict: { type: "string" },
@@ -861,7 +936,10 @@ async function cmdFinding(argv) {
     },
   });
 
-  const dir = await resolveRun(values.run);
+  const root = await commandDirectory(values.dir);
+  const dir = await resolveRun(values.run, root);
+  const events = await readEvents(dir);
+  const judge = currentJudge(events);
   const findings = await findingsIn(dir);
   const id = positionals[0];
 
@@ -881,7 +959,7 @@ async function cmdFinding(argv) {
       if (!findings.has(id)) throw new Error(`no such finding: ${id}`);
       if (!values.evidence) throw new Error("--evidence is required: what demonstrated the finding");
       await appendEvent(dir, {
-        t: "finding.reproduced", id, evidence: values.evidence, test: values.test,
+        t: "finding.reproduced", id, evidence: values.evidence, test: values.test, who: judge,
       });
       await republish(dir);
       console.log(`${id}: reproduction recorded`);
@@ -895,7 +973,7 @@ async function cmdFinding(argv) {
       // survives the operator deciding to skip it.
       if (why) throw new Error(`refused: ${why}`);
       await appendEvent(dir, {
-        t: "finding.resolved", id, verdict: values.verdict, reason: values.reason ?? "", test: values.test,
+        t: "finding.resolved", id, verdict: values.verdict, reason: values.reason ?? "", test: values.test, who: judge,
       });
       await republish(dir);
       console.log(`${id}: ${values.verdict}`);
@@ -927,23 +1005,21 @@ async function cmdReply(argv) {
     args: argv, allowPositionals: false,
     options: {
       run: { type: "string" },
-      dir: { type: "string", default: "." },
+      dir: { type: "string" },
       agents: { type: "string" },
       "dry-run": { type: "boolean", default: false },
     },
   });
 
-  const cfg = await loadConfig();
-  const dir = await resolveRun(values.run);
+  const worktree = await commandDirectory(values.dir);
+  const cfg = await loadConfig(worktree);
+  const dir = await resolveRun(values.run, worktree);
+  const events = await readEvents(dir);
+  const judge = currentJudge(events);
   const findings = await findingsIn(dir);
-  const worktree = path.resolve(values.dir);
   const { sha } = await describe(worktree, "master");
 
-  let pool = reviewers(cfg);
-  if (values.agents) {
-    const want = new Set(values.agents.split(",").map((s) => s.trim()));
-    pool = pool.filter((a) => want.has(a.name));
-  }
+  let pool = selectReviewers(cfg, values.agents, judge);
   // Only reviewers that actually said something, and only once you have
   // answered them: a reply that says "still open" for every item is noise.
   pool = pool.filter((a) => {
@@ -952,8 +1028,7 @@ async function cmdReply(argv) {
   });
   if (!pool.length) throw new Error("nothing to reply about — resolve some findings first");
 
-  const main = mainAgent(cfg);
-  console.log(`main     ${main?.name ?? "(unset)"}`);
+  console.log(`judge    ${judge}`);
   console.log(`replying ${pool.map((a) => a.name).join(", ")}  (separate conversations)`);
   console.log("");
 
@@ -976,7 +1051,7 @@ async function cmdReply(argv) {
 
     if (values["dry-run"]) return;
 
-    await appendEvent(dir, { t: "reply.sent", agent: a.name, sha, resumed: resumable, promptFile: file });
+    await appendEvent(dir, { t: "reply.sent", agent: a.name, sha, resumed: resumable, promptFile: file, who: judge });
     const spec = { ...a, argv: replyArgv(a, { promptText: text, worktree }).argv };
     const replyRaw = `reply.${a.name}.stdout.txt`;
     const sink = await openArtifact(dir, replyRaw);
@@ -996,8 +1071,8 @@ async function cmdReply(argv) {
 }
 
 /** Which run a finding command applies to; unambiguous by default. */
-async function resolveRun(slug) {
-  const base = runsDir();
+async function resolveRun(slug, root = process.cwd()) {
+  const base = runsDir(root);
   if (slug) return path.join(base, slug);
   const { readdir } = await import("node:fs/promises");
   let dirs = [];
@@ -1020,9 +1095,14 @@ async function republish(dir) {
  * optional, so there has to be a way to see the slugs that does not require
  * triggering the ambiguity error to find them out.
  */
-async function cmdRuns() {
+async function cmdRuns(argv) {
+  const { values } = parseArgs({
+    args: argv, allowPositionals: false,
+    options: { dir: { type: "string" } },
+  });
+  const root = await commandDirectory(values.dir);
   const { listRuns } = await import("../lib/store.js");
-  const { runs, skipped } = await listRuns(runsDir());
+  const { runs, skipped } = await listRuns(runsDir(root));
   if (!runs.length) {
     // Report the unreadable ones even when nothing succeeded: "no runs yet"
     // over a directory full of broken runs is a lie that reads as "nothing was
@@ -1139,7 +1219,7 @@ async function describe(dir, trunk) {
 // Declarations, not const arrows: the dispatch switch above runs at module
 // top level, so anything it reaches must be hoisted.
 function repoFromUrl(u) {
-  return u.match(/\/([^/]+\/[^/]+)\/(?:merge_requests|pull)\//)?.[1] ?? "";
+  return repositoryFromPrUrl(u)?.path ?? "";
 }
 
 function idFromUrl(u) {