@irythill/orq 0.6.1 → 0.8.0

package/dist/commands/agent.js

@@ -15,7 +15,8 @@ import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { claudeAccounts } from "../accounts.js";
 import { gateFor } from "../diagnose.js";
-import { argvModel, useThrowaway, agentDef, ALIASES, expandString, expandTemplate, FORMATS } from "../agents.js";
+import { hasVerdict } from "../rounds.js";
+import { argvModel, baseCommit, commitMessage, isCommitBase, stepIns, stepInNote, useThrowaway, agentDef, ALIASES, expandString, expandTemplate, FORMATS } from "../agents.js";
 import { getPath, loadConfig } from "../config.js";
 import { writeAtomic } from "../fsutil.js";
 import { m } from "../i18n.js";
@@ -26,7 +27,9 @@ import { killedRc, killTree, parseSize, resolveMode, runCapped } from "../proces
 import { closeOwnTab, detectHost, launch, screenOpen, shq, typeInto } from "../terminal.js";
 import { ackPrefix } from "../notice.js";
 import { dropWorktree, notify } from "../testrun.js";
-export const USAGE = "orq agent -a <agent> -t <title> -d <dir> -o <prefix> [-g group] [-m model] [-e effort] [-c account] [-i file]... [-b base] [-r] [-R session [-F [-F]]] [-T] -- <prompt.md>   run a child agent";
+export const USAGE = "orq agent -a <agent> -t <title> -d <dir> -o <prefix> [-g group] [-m model] [-e effort] [-c account] [-i file]... [-b base [--base-branch <branch>]] [-r] [-R session [-F [-F]] [--reason review|verify|unblock]] [-T] -- <prompt.md>   run a child agent";
+/** Why a follow-up (-R) runs: only `review` (fixing a reviewer's findings) counts towards policy.max_rounds. */
+export const ROUND_REASONS = ["review", "verify", "unblock"];
 const CLI = fileURLToPath(new URL("../cli.js", import.meta.url));
 const PF = ".herdr-agent-prompt.md"; // prompt_in_dir file name (kept from herdr-agent)
 const git = (dir, ...a) => {
@@ -38,8 +41,8 @@ export async function agent(argv) {
         return runJob(argv[1]);
     if (argv[0] === "--turn")
         return turn(argv[1], argv[2], argv.slice(3));
-    let a = process.env.AGENT || "", g = "", t = "", d = "", o = "", model = "", effort = "", acc = "", resume = "", base = "";
-    let ro = false, tui = false, force = 0, prompt;
+    let a = process.env.AGENT || "", g = "", t = "", d = "", o = "", model = "", effort = "", acc = "", resume = "", base = "", baseBranch = "";
+    let ro = false, tui = false, force = 0, prompt, reason = "review";
     const inc = [];
     for (let i = 0; i < argv.length; i++) {
         const x = argv[i], v = () => argv[++i] ?? "";
@@ -77,6 +80,10 @@ export async function agent(argv) {
             tui = true;
         else if (x === "-F")
             force++;
+        else if (x === "--reason")
+            reason = v();
+        else if (x === "--base-branch")
+            baseBranch = v();
         else if (!x.startsWith("-") && prompt === undefined)
             prompt = x;
         else {
@@ -88,6 +95,14 @@ export async function agent(argv) {
         console.error(m("give the prompt file", "informe o arquivo de prompt"));
         return 2;
     }
+    if (!ROUND_REASONS.includes(reason)) {
+        console.error(m(`--reason must be one of ${ROUND_REASONS.join("|")}`, `--reason deve ser ${ROUND_REASONS.join("|")}`));
+        return 2;
+    }
+    if (reason !== "review" && !resume) {
+        console.error(m("--reason only applies to a follow-up (-R)", "--reason só vale para um follow-up (-R)"));
+        return 2;
+    }
     for (const [f, val] of [["t", t], ["d", d], ["o", o]])
         if (!val) {
             console.error(`${m("missing", "faltou")} -${f}`);
@@ -149,7 +164,14 @@ export async function agent(argv) {
     }
     // Fix rounds: every -R on the same session counts, whatever the prefix is called. policy.max_rounds is enforced here,
     // not left to the conductor to remember (a 7-round fix loop is what burns the tokens). -F = the user said go on.
+    // Only --reason review counts; every follow-up is logged. Written at launch, so a later refusal costs no round.
+    let countRound;
     if (resume) {
+        const lf = join(dirname(O), `.rounds-${resume}.log`);
+        const logRound = () => { mkdirSync(dirname(O), { recursive: true }); appendFileSync(lf, `${new Date().toISOString()} ${reason} ${basename(O)}\n`); };
+        countRound = logRound;
+    }
+    if (resume && reason === "review") {
         const max = Number(getPath(cfg, "policy.max_rounds") ?? 2), cf = join(dirname(O), `.rounds-${resume}`);
         let n = 0;
         try {
@@ -169,8 +191,8 @@ export async function agent(argv) {
                 return 4;
             }
         }
-        mkdirSync(dirname(O), { recursive: true });
-        writeFileSync(cf, String(n + 1));
+        const logRound = countRound;
+        countRound = () => { logRound(); writeFileSync(cf, String(n + 1)); };
     }
     let P = resolve(prompt);
     if (!existsSync(repo)) {
@@ -183,17 +205,32 @@ export async function agent(argv) {
     }
     mkdirSync(dirname(O), { recursive: true });
     // -b <base>: attaches `git diff origin/<base>...HEAD` (review without running git; required for Antigravity).
+    // A base with no origin/<base> but naming a commit (a fix round's round-<n>.sha) attaches `<base>..HEAD`: only that round's delta.
+    // An agent that can't review a commit base (agents.<name>.base_commit) gets the branch base instead: the whole branch.
+    let scopeNote = "";
+    if (base && !baseCommit(def) && isCommitBase(repo, base)) {
+        const branch = baseBranch?.replace(/^origin\//, "") || git(repo, "symbolic-ref", "--short", "refs/remotes/origin/HEAD")?.replace(/^origin\//, "");
+        if (!branch) {
+            console.error(m(`${a} can't review -b ${base} (a commit) and no branch base is known: pass --base-branch <branch>`, `${a} não revisa -b ${base} (um commit) e a base da branch é desconhecida: informe --base-branch <branch>`));
+            return 2;
+        }
+        scopeNote = m(`${a} can't review a commit base (agents.${a}.base_commit = false): reviewing against origin/${branch} instead. The review covers the whole branch, not just the round delta.`, `${a} não revisa uma base que é commit (agents.${a}.base_commit = false): revisando contra origin/${branch}. A revisão cobre a branch inteira, não só o delta da rodada.`);
+        console.log(`[orq agent] ${scopeNote}`);
+        base = branch;
+    }
     if (base) {
-        const r = spawnSync("git", ["-C", repo, "diff", `origin/${base}...HEAD`], { encoding: "utf8", maxBuffer: 1 << 30 });
+        const range = isCommitBase(repo, base) ? `${base}..HEAD` : `origin/${base}...HEAD`;
+        const r = spawnSync("git", ["-C", repo, "diff", range], { encoding: "utf8", maxBuffer: 1 << 30 });
         if (r.status !== 0) {
-            console.error(m(`could not build the diff against origin/${base}`, `não consegui gerar o diff contra origin/${base}`));
+            console.error(m(`could not build the diff ${range}`, `não consegui gerar o diff ${range}`));
             return 2;
         }
         writeFileSync(`${O}.diff`, r.stdout);
         inc.push(`${O}.diff`);
     }
-    if (inc.length) {
-        let text = readFileSync(P, "utf8");
+    const steps = stepIns(def, ro, git(repo, "rev-parse", "--git-dir") !== undefined), note = stepInNote(steps);
+    if (inc.length || note) {
+        let text = readFileSync(P, "utf8") + note;
         for (const f of inc)
             text += `\n--- ${basename(f)} ---\n${readFileSync(f, "utf8")}\n--- end of ${basename(f)} ---\n`;
         writeFileSync(`${O}.prompt.md`, text);
@@ -206,12 +243,19 @@ export async function agent(argv) {
         ackPrefix(O); // a follow-up on the issue: its failure notices were seen
         for (const s of [".done", ".out.md"])
             rmSync(O + s, { force: true });
+        countRound?.();
         typeInto(open, readFileSync(P, "utf8"));
         console.log(`[orq agent] ${t} → ${open} ${m("(follow-up typed into the open screen)", "(follow-up digitado na tela aberta)")}`);
         return 0;
     }
     for (const s of [".done", ".out.md", ".pid"])
         rmSync(O + s, { force: true });
+    // .id is the session this prefix's screen answers for (`--turn codex` drops other threads): an id left by an earlier
+    // run on the prefix (another agent, another session) would drop every turn of this one.
+    if (resume)
+        writeFileSync(`${O}.id`, `${resume}\n`);
+    else
+        rmSync(`${O}.id`, { force: true });
     const throwaway = useThrowaway(def, ro, Boolean(resume), git(repo, "rev-parse", "--git-dir") !== undefined);
     const dir = throwaway ? `${repo}.review-${process.pid}` : repo;
     const gd = git(repo, "rev-parse", "--path-format=absolute", "--git-common-dir");
@@ -254,6 +298,12 @@ export async function agent(argv) {
     const cmd = expandTemplate(tpl, vars);
     if (!tpl.includes("{mode}") && !resume && !tui)
         cmd.push(...vars.mode);
+    // A prompt passed as an argument ({prompt_text}) can be over what the OS takes: refuse now, not with E2BIG in the tab.
+    const tooBig = argvTooBig(cmd);
+    if (tooBig) {
+        console.error(m(`prompt too big for ${a}: ${tooBig}. Attach less with -i (e.g. only the round's diff; the agent can run git diff itself) or use an agent that reads the prompt from stdin or a file. Nothing started.`, `prompt grande demais para ${a}: ${tooBig}. Anexe menos com -i (ex.: só o diff da rodada; o agente pode rodar git diff) ou use um agente que lê o prompt por stdin ou arquivo. Nada foi iniciado.`));
+        return 2;
+    }
     const env = {};
     for (const [k, val] of Object.entries(def.env ?? {}))
         env[k] = expandString(String(val), vars);
@@ -275,10 +325,13 @@ export async function agent(argv) {
         swap: parseSize(mach.agent_swap_max), mode: mach.mem_enforce ?? "auto",
         throwaway, promptInDir: Boolean(def.prompt_in_dir), closeAfter,
         keep: process.env.HERDR_KEEP_TAB === "1" || process.env.ORQ_KEEP_TAB === "1" || closeAfter <= 0, tui,
-        okExit: def.ok_exit, filter: def.filter, noReview: def.no_review, ro,
+        okExit: def.ok_exit, filter: def.filter, noReview: def.no_review, ro, orqCommits: steps.commit, orqFetches: steps.fetch, scopeNote,
+        // A review (-r, prefix review*) must end with a verdict; policy.review_verdict = false turns the check off.
+        review: ro && /^review/i.test(basename(O)) && getPath(cfg, "policy.review_verdict") !== false,
         idleCloseMin: tui ? Number(mach.tui_idle_close_min ?? 30) : undefined,
     };
     writeAtomic(`${O}.job.json`, JSON.stringify(job, null, 1));
+    countRound?.();
     // Readable copy of the command (also what orq stats and herdr-board read).
     writeFileSync(`${O}.run.sh`, `#!/usr/bin/env bash\n# orq agent (generated; the run itself is \`orq agent --run ${O}.job.json\`) --unit=${unit} \n` +
         `cd ${shq(dir)}\n${Object.entries(env).map(([k, val]) => `${k}=${shq(val)} `).join("")}${cmd.map(shq).join(" ")}${job.stdin ? ` < ${shq(P)}` : ""}\n`);
@@ -370,13 +423,14 @@ function turn(file, kind, rest) {
             answer = readFileSync(0, "utf8");
         }
         writeFileSync(`${O}.out.md`, answer);
+        appendFileSync(`${O}.turns`, `${new Date().toISOString()}\n`); // stats: work time ends at the first turn
         if (sid)
             writeFileSync(`${O}.id`, `${sid}\n`);
-        const noReview = noReviewMatch(j.noReview, answer);
-        const st = /\S/.test(answer) && !noReview ? "ok" : "fail";
-        writeAtomic(`${O}.done`, `status=${st} rc=0 at=${new Date().toISOString()} agent=${j.agent} mode=tui\n`);
+        const noReview = noReviewMatch(j.noReview, answer), noVerdict = Boolean(j.review) && /\S/.test(answer) && !hasVerdict(answer);
+        const st = /\S/.test(answer) && !noReview && !noVerdict ? "ok" : "fail", why = noVerdict ? " reason=no-verdict" : "";
+        writeAtomic(`${O}.done`, `status=${st} rc=0${why} at=${new Date().toISOString()} agent=${j.agent} mode=tui\n`);
         if (j.parent)
-            notify(j.parent, `[HERDR-AGENT DONE] ${j.title} status=${st} rc=0 answer: ${O}.out.md`);
+            notify(j.parent, `[HERDR-AGENT DONE] ${j.title} status=${st} rc=0${why} answer: ${O}.out.md`);
     }
     catch (e) {
         console.error(`orq agent --turn: ${e.message}`);
@@ -444,6 +498,29 @@ export function idleExpired(done, idleMs, now = Date.now(), busyAt = 0) {
         return false;
     }
 }
+/** A -T turn ended without its hook: the screen was seen busy (`busyAt`) after the last .done (if any), and has been
+ *  idle since `idleSince` for `graceMs`. All times epoch ms; 0 = never seen. */
+export function missedTurn(done, busyAt, idleSince, graceMs, now = Date.now()) {
+    if (!busyAt || !idleSince || idleSince < busyAt || now - idleSince < graceMs)
+        return false;
+    try {
+        return statSync(done).mtimeMs < busyAt;
+    }
+    catch {
+        return true;
+    }
+}
+const NO_HOOK_GRACE_MS = 60_000;
+/** Signals a -T turn whose end-of-turn hook never fired: .done (status=fail reason=no-hook) and the done line, with the
+ *  screen's last lines as the answer, so the conductor isn't left waiting. A late hook still overwrites both. */
+function noHook(j, pane) {
+    const O = j.prefix;
+    const r = spawnSync("herdr", ["pane", "read", pane, "--lines", "80", "--format", "text"], { encoding: "utf8", timeout: 5_000 });
+    writeFileSync(`${O}.out.md`, `${m("The agent's end-of-turn hook did not fire; its turn looks finished (the screen went idle). Last lines of the screen:", "O hook de fim de turno do agente não disparou; o turno parece terminado (a tela ficou ociosa). Últimas linhas da tela:")}\n\n${r.status === 0 ? r.stdout : ""}`);
+    writeAtomic(`${O}.done`, `status=fail rc=0 reason=no-hook at=${new Date().toISOString()} agent=${j.agent} mode=tui\n`);
+    if (j.parent)
+        notify(j.parent, `[HERDR-AGENT DONE] ${j.title} status=fail rc=0 reason=no-hook answer: ${O}.out.md`);
+}
 /** herdr's view of the agent on a pane: working | blocked | idle | done | unknown; undefined when it can't be read. */
 function paneStatus(pane) {
     const r = spawnSync("herdr", ["pane", "get", pane], { encoding: "utf8", timeout: 5_000 });
@@ -470,6 +547,30 @@ function lines(s, each) {
         s.on("error", () => res());
     });
 }
+/** The answer of a run whose command never started: what failed and what to do, for the conductor. */
+export const spawnFailText = (j, e) => `orq agent: ${j.agent} could not start (${e.code ?? "error"}): ${e.message}\n` +
+    (e.code === "E2BIG" ? "The prompt (with its -i attachments) is too big to pass as an argument: attach less (e.g. the round's diff only) and let the agent read the rest with git.\n"
+        : e.code === "ENOENT" ? `Command not found: ${j.argv[0]}. Is it installed for the current PATH (and Node version)?\n` : "");
+/** Largest command line the OS takes: Linux caps each argument (MAX_ARG_STRLEN, 128 KiB), Windows the whole line. */
+export function argvTooBig(argv, platform = process.platform) {
+    const kb = (n) => `${Math.round(n / 1024)} KB`;
+    if (platform === "win32") {
+        const n = argv.reduce((s, a) => s + a.length + 3, 0);
+        return n > 32_000 ? m(`the command line is ${kb(n)} (Windows takes ~32 KB)`, `a linha de comando tem ${kb(n)} (o Windows aceita ~32 KB)`) : undefined;
+    }
+    const big = Math.max(0, ...argv.map((a) => Buffer.byteLength(a)));
+    if (platform === "linux" && big >= 128 * 1024)
+        return m(`one argument is ${kb(big)} (Linux takes 128 KB per argument)`, `um argumento tem ${kb(big)} (o Linux aceita 128 KB por argumento)`);
+    const total = argv.reduce((s, a) => s + Buffer.byteLength(a) + 1, 0);
+    return total > 1_000_000 ? m(`the command line is ${kb(total)} (over ~1 MB)`, `a linha de comando tem ${kb(total)} (acima de ~1 MB)`) : undefined;
+}
+/** Commits everything in `dir` for an agent that can't; returns the line for its answer. */
+function orqCommit(dir, msg) {
+    const add = spawnSync("git", ["-C", dir, "add", "-A"], { encoding: "utf8" });
+    const c = add.status === 0 ? spawnSync("git", ["-C", dir, "commit", "-q", "-m", msg], { encoding: "utf8" }) : add;
+    return c.status === 0 ? `${git(dir, "rev-parse", "--short", "HEAD")} ${msg}`
+        : `FAILED (exit ${c.status}): ${(c.stderr || c.stdout).trim()}. The changes are still in the worktree.`;
+}
 async function runJob(file) {
     const j = JSON.parse(readFileSync(file, "utf8")), O = j.prefix;
     writeFileSync(`${O}.pid`, String(process.pid));
@@ -494,6 +595,8 @@ async function runJob(file) {
             }
             catch { /* none */ }
         }
+        if (j.orqFetches && spawnSync("git", ["-C", j.dir, "fetch", "-q", "origin"], { stdio: "inherit" }).status !== 0)
+            console.error(m("[orq agent] git fetch origin failed; the agent sees the local origin/* refs", "[orq agent] git fetch origin falhou; o agente vê as refs origin/* locais"));
         if (j.promptInDir) {
             copyFileSync(j.prompt, join(j.dir, PF));
             const ex = git(j.dir, "rev-parse", "--git-path", "info/exclude");
@@ -512,15 +615,18 @@ async function runJob(file) {
         }
         return true;
     };
-    const post = () => {
+    let committed = "";
+    const post = (answer = "") => {
         if (j.promptInDir)
             rmSync(join(j.dir, PF), { force: true });
         if (j.throwaway)
             dropWorktree(j.repo, j.dir);
+        else if (j.orqCommits && existsSync(j.dir) && git(j.dir, "status", "--porcelain"))
+            committed = orqCommit(j.dir, commitMessage(answer, j.title));
     };
     if (j.tui) {
         // The agent's own screen: the terminal is its; answers come from the end-of-turn hook (`--turn`).
-        let ended = false;
+        let ended = false, tuiErr;
         const end = (code, killed = false) => {
             if (ended)
                 return "fail";
@@ -535,9 +641,10 @@ async function runJob(file) {
                     notify(j.parent, `[HERDR-AGENT DONE] ${j.title} status=killed rc=${code} answer: ${O}.out.md`);
             }
             else if (!existsSync(`${O}.done`)) {
-                writeAtomic(`${O}.done`, `status=fail rc=${code} at=${new Date().toISOString()} agent=${j.agent} mode=tui\n`);
+                const why = tuiErr ? ` reason=spawn:${tuiErr.code ?? "error"}` : "";
+                writeAtomic(`${O}.done`, `status=fail rc=${code}${why} at=${new Date().toISOString()} agent=${j.agent} mode=tui\n`);
                 if (j.parent)
-                    notify(j.parent, `[HERDR-AGENT DONE] ${j.title} status=fail rc=${code} answer: ${O}.out.md`);
+                    notify(j.parent, `[HERDR-AGENT DONE] ${j.title} status=fail rc=${code}${why} answer: ${O}.out.md`);
             }
             rmSync(`${O}.pid`, { force: true });
             return killed ? "killed" : ok ? "ok" : "fail";
@@ -558,32 +665,40 @@ async function runJob(file) {
             for (const sig of ["SIGHUP", "SIGTERM"])
                 process.on(sig, gone);
             rc = await runCapped(j.argv[0], j.argv.slice(1), { cap: j.cap, swap: j.swap, mode: j.mode, unit: j.unit, cwd: j.dir, env, quote: true, tty: true,
+                onError: (e) => { tuiErr = e; writeFileSync(`${O}.out.md`, spawnFailText(j, e)); },
                 onSpawn: (c) => {
                     child = c.pid;
                     // A finished agent waits for a follow-up forever and holds its memory: after the idle timeout without a new
                     // turn, kill it; the normal end below cleans up and closes the tab. "New turn" = .done removed (`-R` typed
                     // into the screen removes it) or rewritten (the next end of turn), so idle = .done untouched that long.
-                    const idleMs = (j.idleCloseMin ?? 0) * 60_000;
-                    if (idleMs > 0 && !j.keep) {
-                        // On herdr the pane's agent status also catches a turn typed straight into the screen (.done only changes
-                        // when it ends). Elsewhere (tmux) only .done tells: a turn typed directly into the screen that runs longer
-                        // than the timeout can still be closed.
-                        let busyAt = 0;
-                        const pane = j.host === "herdr" ? process.env.HERDR_PANE_ID : undefined;
-                        idleT = setInterval(() => {
-                            const st = pane ? paneStatus(pane) : undefined;
-                            if (st === "working" || st === "blocked")
-                                busyAt = Date.now();
-                            if (!idleExpired(`${O}.done`, idleMs, Date.now(), busyAt))
-                                return;
-                            clearInterval(idleT);
-                            console.log(m(`[orq agent] no follow-up for ${j.idleCloseMin} min: closing the finished agent`, `[orq agent] sem follow-up há ${j.idleCloseMin} min: fechando o agente que terminou`));
-                            idleClosed = true;
-                            if (child)
-                                killTree(child, false);
-                        }, Math.min(30_000, Math.max(1_000, idleMs / 2)));
-                        idleT.unref();
-                    }
+                    const idleMs = (j.idleCloseMin && !j.keep ? j.idleCloseMin : 0) * 60_000;
+                    // On herdr the pane's agent status also catches a turn typed straight into the screen (.done only changes
+                    // when it ends), and a turn whose hook never fired (busy, then idle, .done not rewritten): that one is
+                    // signalled from here, flagged reason=no-hook, with the screen's tail as the answer. Elsewhere (tmux) only
+                    // .done tells: a turn typed directly into the screen that runs longer than the timeout can still be closed.
+                    const pane = j.host === "herdr" ? process.env.HERDR_PANE_ID : undefined;
+                    if (!pane && idleMs <= 0)
+                        return;
+                    let busyAt = 0, idleSince = 0;
+                    idleT = setInterval(() => {
+                        const st = pane ? paneStatus(pane) : undefined, now = Date.now();
+                        if (st === "working" || st === "blocked") {
+                            busyAt = now;
+                            idleSince = 0;
+                        }
+                        else if (st === "idle" || st === "done")
+                            idleSince ||= now;
+                        if (pane && missedTurn(`${O}.done`, busyAt, idleSince, NO_HOOK_GRACE_MS, now))
+                            noHook(j, pane);
+                        if (!idleExpired(`${O}.done`, idleMs, now, busyAt))
+                            return;
+                        clearInterval(idleT);
+                        console.log(m(`[orq agent] no follow-up for ${j.idleCloseMin} min: closing the finished agent`, `[orq agent] sem follow-up há ${j.idleCloseMin} min: fechando o agente que terminou`));
+                        idleClosed = true;
+                        if (child)
+                            killTree(child, false);
+                    }, pane ? 15_000 : Math.min(30_000, Math.max(1_000, idleMs / 2)));
+                    idleT.unref();
                 } });
             clearInterval(idleT);
             if (idleClosed)
@@ -599,6 +714,7 @@ async function runJob(file) {
         return 0;
     }
     const log = createWriteStream(`${O}.log`);
+    let spawnErr;
     if (!pre())
         rc = 2;
     else {
@@ -627,6 +743,7 @@ async function runJob(file) {
             rc = await runCapped(j.argv[0], j.argv.slice(1), {
                 cap: j.cap, swap: j.swap, mode: j.mode, unit: j.unit, cwd: j.dir, env, quote: true,
                 stdio: [j.stdin ? openSync(j.prompt, "r") : "ignore", "pipe", "pipe"],
+                onError: (e) => { spawnErr = e; log.write(`[orq agent] could not start ${j.argv[0]}: ${e.message}\n`); },
                 onSpawn: (c) => {
                     streams = Promise.all([lines(c.stdout, (l) => onLine(l, true)), lines(c.stderr, (l) => onLine(l, false))]);
                     // OpenCode sometimes doesn't exit after its final event (helpers hold the pipe): stop it after 30 s of quiet.
@@ -650,8 +767,13 @@ async function runJob(file) {
         await Promise.race([streams, sleep(5000)]);
     }
     await new Promise((r) => log.end(r));
-    post();
     const res = fmt.finish(logText, stdout);
+    post(j.answer === "file" ? (existsSync(`${O}.out.md`) ? readFileSync(`${O}.out.md`, "utf8") : "") : res.answer ?? "");
+    if (committed)
+        res.answer = `${res.answer ?? ""}\n## Commit (by orq)\n${committed}\n`;
+    const scope = j.scopeNote ? `\n## Review scope (by orq)\n${j.scopeNote}\n` : "";
+    if (scope)
+        res.answer = `${res.answer ?? ""}${scope}`;
     // Denied commands do not sink a write run that did work: keep the diff and report ok with the denied list in the answer.
     let recovered = false;
     if (res.denied?.length && !j.ro && !j.throwaway && existsSync(j.dir)) {
@@ -679,6 +801,11 @@ async function runJob(file) {
     }
     if (j.answer !== "file")
         writeFileSync(`${O}.out.md`, res.answer ?? "");
+    else if (committed || scope)
+        appendFileSync(`${O}.out.md`, `${committed ? `\n## Commit (by orq)\n${committed}\n` : ""}${scope}`);
+    // The agent never started: say why in the answer (the conductor reads it) instead of leaving it empty.
+    if (spawnErr)
+        writeFileSync(`${O}.out.md`, spawnFailText(j, spawnErr));
     const sid = j.fromLog ? new RegExp(j.fromLog, "m").exec(logText)?.[1] : res.session ?? j.session;
     if (sid)
         writeFileSync(`${O}.id`, `${sid}\n`);
@@ -704,12 +831,14 @@ async function runJob(file) {
     // fallback and the conductor must see it as not run, same as a whitespace-only answer.
     const noReview = noReviewMatch(j.noReview, answer);
     // killed (SIGKILL, memory cap...) is its own status: never ok, even if an ok_exit list or a leftover answer says otherwise.
-    const st = killedRc(rc) ? "killed" : verdict && !noReview && /\S/.test(answer) ? "ok" : "fail"; // whitespace-only answer = failure
-    writeAtomic(`${O}.done`, `status=${st} rc=${rc} at=${new Date().toISOString()} agent=${j.agent}\n`);
+    const noVerdict = !spawnErr && Boolean(j.review) && verdict && !noReview && /\S/.test(answer) && !hasVerdict(answer);
+    const st = spawnErr ? "fail" : killedRc(rc) ? "killed" : verdict && !noReview && !noVerdict && /\S/.test(answer) ? "ok" : "fail"; // whitespace-only answer = failure
+    const why = spawnErr ? ` reason=spawn:${spawnErr.code ?? "error"}` : noVerdict ? " reason=no-verdict" : "";
+    writeAtomic(`${O}.done`, `status=${st} rc=${rc}${why} at=${new Date().toISOString()} agent=${j.agent}\n`);
     rmSync(`${O}.pid`, { force: true });
     state({ status: st, rc, end: new Date().toISOString() });
     if (j.parent)
-        notify(j.parent, `[HERDR-AGENT DONE] ${j.title} status=${st} rc=${rc} answer: ${O}.out.md`);
+        notify(j.parent, `[HERDR-AGENT DONE] ${j.title} status=${st} rc=${rc}${why} answer: ${O}.out.md`);
     console.log(`\n[${j.agent} ${m("finished", "terminou")}: exit ${rc} status=${st}] ${m("answer", "resposta")}: ${O}.out.md`);
     if (j.host !== "plain" && !j.keep) {
         await sleep(j.closeAfter * 1000);

package/dist/commands/board.js

@@ -466,7 +466,7 @@ export function render(s, theme, cols, mode = colorMode(), hideH = HIDE_H) {
     if (top.length)
         out.push(` ${c.mut}${m("role", "papel").padEnd(7)} ${m("agent", "agente").padEnd(12)} ${m("model", "modelo").padEnd(20)} ${"n".padStart(4)} ${"ok%".padStart(5)} ${m("approved%", "aprov%").padStart(10)} ${"min".padStart(6)}${c.r}`);
     for (const x of top)
-        out.push(` ${c.ink2}${x.role.padEnd(7)}${c.r} ${c.ink}${fit(x.agent, 12)}${c.r} ${c.mut}${fit(x.model, 20)}${c.r} ${c.ink}${String(x.n).padStart(4)} ${String(x.ok).padStart(5)} ${(x.approved === null ? "-" : `${x.approved}%`).padStart(10)} ${String(x.min).padStart(6)}${c.r}`);
+        out.push(` ${c.ink2}${x.role.padEnd(7)}${c.r} ${c.ink}${fit(x.agent, 12)}${c.r} ${c.mut}${fit(x.model, 20)}${c.r} ${c.ink}${String(x.n).padStart(4)} ${String(x.ok).padStart(5)} ${(x.approved === null ? "-" : `${x.approved}%`).padStart(10)} ${String(x.min ?? "-").padStart(6)}${c.r}`);
     if (!top.length)
         out.push(` ${c.mut}${m("no runs yet", "nenhuma execução ainda")}${c.r}`);
     out.push("", `${c.rul}${"─".repeat(W - 2)}${c.r}`, ` ${c.mut}${m("q quit · r quota · l language · t theme", "q sai · r cota · l idioma · t tema")}${c.r}`);

package/dist/commands/claim.js

@@ -15,6 +15,12 @@ import { acquire, release } from "../lock.js";
 import { handoffFile } from "../notice.js";
 export const USAGE = `orq claim [-w <workspace>] <ID> | -f <ID> | -r <ID> | -l | --register   issue owner among conductors (exit 1 = someone else's)
 orq claim [-w <workspace>] --from <name> [-f]   a conductor's issues by its name (part of it is enough); -f takes them all`;
+/** The Claude session name of a conductor of `ws` (what ListAgents shows): conductor-<workspace folder>, plus
+ *  :<name> (its herdr label or ORQ_CONDUCTOR_ID, slugged) so several conductors on one workspace can be told apart. */
+export function sessionName(ws, name = "") {
+    const slug = name.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+    return `conductor-${basename(ws)}${slug ? `:${slug}` : ""}`;
+}
 const field = (text, k) => new RegExp(`${k}=(\\S+)`).exec(text)?.[1] ?? "";
 export const nameOf = (text) => / name=(.*)$/m.exec(text)?.[1].trim() ?? "";
 const herdrList = (args) => {
@@ -127,7 +133,8 @@ export async function claim(argv) {
             // The herdr workspace's current label while the pane is alive; the name stored at claim time otherwise
             // (the user may have renamed the workspace since, or it may not be a herdr conductor at all).
             const n = (alive && (field(t, "kind") || "herdr") === "herdr" ? names.get(field(t, "pane")) ?? "" : "") || nameOf(t);
-            console.log(`${d} ${n ? `"${n}" ` : ""}${t.replace(/ name=.*$/, "")} (${alive ? "alive" : "dead"})`);
+            console.log(`${d} ${n ? `"${n}" ` : ""}${t.replace(/ name=.*$/, "")} (${alive ? "alive" : "dead"})`
+                + ` session=${sessionName(ws, n)}`);
         }
         return 0;
     }

package/dist/commands/conductor.js

@@ -2,14 +2,14 @@
 // instructions, the chosen account and model (port of setup/herdr-conductor, for any terminal and OS).
 //   orq conductor [account|-] [model] [-r <session>]
 // Workspace: the current folder if it has .orquestra-conductor.md, else $CONDUCTOR_WS. $CONDUCTOR_FILE overrides the
-// instructions file. The session is named conductor-<workspace folder>.
+// instructions file. The session is named conductor-<workspace folder>:<herdr label or ORQ_CONDUCTOR_ID> (see sessionName).
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { claudeAccounts } from "../accounts.js";
 import { m } from "../i18n.js";
 import { runCapped } from "../process.js";
-import { claim } from "./claim.js";
+import { claim, herdrName, sessionName } from "./claim.js";
 export const USAGE = `orq conductor [account|-] [model] [-r <session>]   open the conductor (Claude) here: instructions, account, model
   model: sonnet | opus | haiku | a full id; "-" as account = default account; -r resumes that conversation`;
 export const MODELS = {
@@ -48,8 +48,8 @@ export function findWorkspace(cwd, env, exists = existsSync) {
 }
 export const instructionsFile = (ws, env) => env.CONDUCTOR_FILE ? resolve(env.CONDUCTOR_FILE) : join(ws, ".orquestra-conductor.md");
 /** The claude command line (without the executable). The instructions go by file, so no shell ever sees their text. */
-export function claudeArgs(ws, a, file) {
-    return [...(a.resume ? ["--resume", a.resume] : []), "-n", `conductor-${basename(ws)}`,
+export function claudeArgs(ws, a, file, name = "") {
+    return [...(a.resume ? ["--resume", a.resume] : []), "-n", sessionName(ws, name),
         ...(a.model ? ["--model", modelId(a.model)] : []), "--append-system-prompt-file", file];
 }
 export async function conductor(argv) {
@@ -100,5 +100,6 @@ export async function conductor(argv) {
         delete process.env.CLAUDE_CONFIG_DIR;
     else
         process.env.CLAUDE_CONFIG_DIR = saved;
-    return runCapped("claude", claudeArgs(ws, a, file), { mode: "off", env, cwd: ws, quote: true, tty: true });
+    const name = (process.env.HERDR_PANE_ID ? herdrName(process.env.HERDR_PANE_ID) : "") || process.env.ORQ_CONDUCTOR_ID || "";
+    return runCapped("claude", claudeArgs(ws, a, file, name), { mode: "off", env, cwd: ws, quote: true, tty: true });
 }

package/dist/commands/pick.js

@@ -5,6 +5,7 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { isCommitBase, missingBinary } from "../agents.js";
 import { loadConfig } from "../config.js";
 import { m } from "../i18n.js";
 import { asArgs, escalate, parseQuota, modelFor, parseWindows, pick as choose } from "../pick.js";
@@ -14,7 +15,7 @@ import { PICK_ROLES, resolveRole, vendorOf } from "../roles.js";
 import { collectRuns, rows } from "../stats.js";
 import { load as loadBlocks } from "./block.js";
 export const USAGE = `orq pick <impl|fix|worker|review|opinion|watchdog> [--level simple|medium|heavy] [--impl-vendor <v>|--impl-agent <a>]
-         [--exclude-agent <a>]... [-w <workspace>] [--explain] [--no-record]
+         [--exclude-agent <a>]... [-w <workspace>] [--base <ref>] [--explain] [--no-record]
 orq pick fix --same <impl pick file>   same agent/model/account as the implementer, effort one level up`;
 // The board refreshes this file; fresher than 10 min → no new quota requests.
 const QCACHE = join(process.env.XDG_RUNTIME_DIR ?? tmpdir(), "herdr-board.quota");
@@ -48,7 +49,7 @@ export async function pick(argv) {
         return 0;
     }
     let level = "medium", implVendor, implAgent, ws;
-    let explain = false, record = true;
+    let explain = false, record = true, base;
     const exclude = new Set();
     for (let i = 1; i < argv.length; i++) {
         const a = argv[i];
@@ -62,6 +63,8 @@ export async function pick(argv) {
             exclude.add(argv[++i]);
         else if (a === "-w")
             ws = expand(argv[++i]);
+        else if (a === "--base")
+            base = argv[++i];
         else if (a === "--explain")
             explain = true;
         else if (a === "--no-record")
@@ -83,7 +86,7 @@ export async function pick(argv) {
         // Eligible, not just declared: an agent that is excluded, blocked or has no model for this role/level can't be picked.
         const blocked = loadBlocks();
         const declared = r.mode === "auto"
-            ? r.pool.filter((n) => agents[n] && !exclude.has(n) && !(n in blocked) && modelFor(agents[n], role, level)) : [];
+            ? r.pool.filter((n) => agents[n] && !exclude.has(n) && !(n in blocked) && !missingBinary(cfg, n) && modelFor(agents[n], role, level)) : [];
         if (declared.length > 1) {
             console.error(`orq pick: ${m(`more than one agent eligible for ${role} (${declared.join(", ")}) before quota checks: pass --impl-agent or --impl-vendor`, `mais de um agente elegível para ${role} (${declared.join(", ")}) antes da checagem de quota: informe --impl-agent ou --impl-vendor`)}`);
             return 2;
@@ -102,7 +105,16 @@ export async function pick(argv) {
     } })
         .filter((p) => p.role === role).slice(-window);
     const qt = await quotaText(cfg);
-    const res = choose({ cfg, role, level, implVendor, implAgent, exclude, stats, quota: parseQuota(qt), windows: parseWindows(qt),
+    // A review of a commit base (a round delta) leaves out agents that can't diff against one (agents.<name>.base_commit).
+    const commitBase = role === "review" && Boolean(base) && isCommitBase((ws ?? cfg._workspace ?? process.cwd()), base);
+    const r0 = resolveRole(cfg, role);
+    const missing = new Map();
+    for (const n of r0.mode === "fixed" ? r0.order : r0.pool) {
+        const why = agents[n] && missingBinary(cfg, n);
+        if (why)
+            missing.set(n, why);
+    }
+    const res = choose({ cfg, role, level, implVendor, implAgent, exclude, commitBase, missing, stats, quota: parseQuota(qt), windows: parseWindows(qt),
         blocks: new Set(Object.keys(loadBlocks())), recent });
     if (!res.best) {
         console.error(`orq pick: ${m("no candidate for ", "nenhum candidato para ")}${role}`

package/dist/commands/rounds.js

@@ -23,6 +23,7 @@ const why = (r) => ({
     at_max: m(`rounds ${r.n} = max_rounds ${r.max}`, `rodadas ${r.n} = max_rounds ${r.max}`),
     same_finding: m(`same finding in ${r.n} reviews`, `mesmo achado em ${r.n} revisões`),
     repeated: m(`${r.n} repeated finding(s)`, `${r.n} achado(s) repetido(s)`),
+    fresh: m(`new heavy findings in fix rounds ${r.rounds?.join(", ")}: split the issue`, `achados graves novos nas rodadas ${r.rounds?.join(", ")}: divida a issue`),
     slow: m(`round ${r.rounds?.join(", ")} much slower than the others`, `rodada ${r.rounds?.join(", ")} bem mais lenta que as outras`),
 })[r.code];
 export async function rounds(argv) {
@@ -65,6 +66,8 @@ export async function rounds(argv) {
     }
     console.log(`${id}  ${mark(x)}  ${m("alert", "alerta")}: ${x.level}${x.reasons.length ? ` (${x.reasons.map(why).join("; ")})` : ""}`);
     console.log(m(`rounds ${x.rounds} of max ${x.max}; total time ${dur(x.secs)}; ${x.findings} finding(s) across reviews`, `rodadas ${x.rounds} de no máx. ${x.max}; tempo total ${dur(x.secs)}; ${x.findings} achado(s) nas revisões`));
+    if (x.followups)
+        console.log(m("follow-ups (only review counts): ", "follow-ups (só review conta): ") + Object.entries(x.followups).map(([k, n]) => `${k} ${n}`).join(", "));
     for (const r of x.perRound)
         console.log(`  ${r.round === 0 ? m("impl + review", "impl + revisão") : m(`fix ${r.round} + review`, `fix ${r.round} + revisão`)}: ${dur(r.secs)}`);
     if (x.repeats.length)

package/dist/commands/setup.js

@@ -9,8 +9,9 @@
 import { spawnSync } from "node:child_process";
 import { copyFileSync, existsSync, readFileSync } from "node:fs";
 import { homedir, totalmem } from "node:os";
-import { delimiter, join } from "node:path";
+import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
+import { onPath } from "../agents.js";
 import { writeAtomic } from "../fsutil.js";
 import { banner, infoLines } from "../banner.js";
 import { getPath, loadConfig } from "../config.js";
@@ -28,11 +29,6 @@ const CLIS = {
     antigravity: { bin: "agy", test: 'agy -p "reply ok"' },
     copilot: { bin: "copilot", test: 'copilot -p "reply ok" -s' },
 };
-/** Is `bin` on PATH? (PATHEXT on Windows: claude.cmd, codex.exe…) */
-export function onPath(bin) {
-    const exts = process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
-    return (process.env.PATH ?? "").split(delimiter).some((d) => d && exts.some((e) => existsSync(join(d, bin + e))));
-}
 export const detect = () => Object.keys(CLIS).filter((n) => onPath(CLIS[n].bin));
 function write(toml) {
     const f = userConfigFile();

package/dist/commands/stats.js

@@ -3,7 +3,7 @@ import { getPath, loadConfig } from "../config.js";
 import { m } from "../i18n.js";
 import { expand } from "../paths.js";
 import { collectRuns, rows } from "../stats.js";
-export const USAGE = "orq stats [-w <workspace>] [--days N] [--json]   scoreboard: delivery, time and tokens per agent";
+export const USAGE = "orq stats [-w <workspace>] [--days N] [--json]   scoreboard per agent and model: delivery, time, tokens";
 const k = (n) => (n === null ? "-" : n >= 1000 ? `${Math.round(n / 1000)}k` : String(n));
 const ORDER = ["impl", "fix", "review", "watchdog", "other"];
 export function stats(argv) {
@@ -35,7 +35,7 @@ export function stats(argv) {
     for (const x of [...rs].sort((a, b) => ORDER.indexOf(a.role) - ORDER.indexOf(b.role) || b.n - a.n)) {
         const ap = x.approved !== null ? `${x.approved}% (${x.n_appr})` : "-";
         console.log(`${x.role.padEnd(7)} ${x.agent.padEnd(12)} ${x.model.slice(0, 22).padEnd(22)} ${String(x.n).padStart(4)} `
-            + `${String(x.ok).padStart(5)} ${ap.padStart(12)} ${String(x.min).padStart(6)} ${k(x.new).padStart(10)} ${k(x.tot).padStart(10)}`);
+            + `${String(x.ok).padStart(5)} ${ap.padStart(12)} ${String(x.min ?? "-").padStart(6)} ${k(x.new).padStart(10)} ${k(x.tot).padStart(10)}`);
     }
     return 0;
 }

package/dist/diagnose.js

@@ -18,6 +18,7 @@ const reason = (r) => ({
     at_max: `rounds ${r.n} reached max_rounds ${r.max}`,
     same_finding: `the same heavy finding came back in ${r.n} reviews`,
     repeated: `${r.n} heavy finding(s) repeated across reviews`,
+    fresh: `the reviews of fix rounds ${r.rounds?.join(", ")} raised new heavy findings outside what was fixed (scope too big?)`,
     slow: `round ${r.rounds?.join(", ")} was much slower than the others`,
 })[r.code];
 const mins = (s) => `${Math.round(s / 60)} min`;
@@ -39,7 +40,8 @@ export function buildPrompt(x, fixes, reviews, cap = DIAG_CAP) {
         `## What to decide`,
         `Look for the real cause, for example: reviewer and implementer disagree about the requirement or the style; the scope is too big for one`,
         `branch; a flaky or environment-dependent test; an ambiguous spec or acceptance criterion; fixes that fix the symptom of each review and`,
-        `introduce the next one; a reviewer that keeps raising new things instead of checking the previous ones.`,
+        `introduce the next one; a reviewer that keeps raising new things instead of checking the previous ones (re-reading the whole branch every
+round: findings outside the fix diff don't make a round, they go to a follow-up list — recommend split, not continue).`,
         ``,
         `## Answer format`,
         `A short diagnosis (at most 15 lines): the cause, with the evidence (which round, which file or finding). Then, as the LAST line, exactly:`,