@irythill/orq 0.6.0 → 0.7.0

package/dist/commands/agent.js

@@ -15,17 +15,21 @@ 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";
 import { alive } from "../lock.js";
+import { agyToken, humanReset, learnExhausted } from "../quota.js";
 import { stateDir } from "../paths.js";
 import { killedRc, killTree, parseSize, resolveMode, runCapped } from "../process.js";
 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) => {
@@ -37,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] ?? "";
@@ -76,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 {
@@ -87,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}`);
@@ -148,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 {
@@ -168,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)) {
@@ -182,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);
@@ -205,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");
@@ -253,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);
@@ -274,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`);
@@ -342,6 +396,12 @@ function turn(file, kind, rest) {
                 return 0;
             answer = String(e["last-assistant-message"] ?? "");
             sid = e["thread-id"];
+            // Codex also runs internal turns (e.g. generating the tab title) and notifies for them: only the main thread counts.
+            const known = existsSync(`${O}.id`) ? readFileSync(`${O}.id`, "utf8").trim() : "";
+            if (known && sid && sid !== known)
+                return 0;
+            if (isTitleOnly(answer))
+                return 0;
         }
         else if (kind === "claude") {
             const e = JSON.parse(readFileSync(0, "utf8"));
@@ -363,19 +423,30 @@ 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}`);
     }
     return 0;
 }
+/** The `{"title": "..."}` answer of Codex's session-title turn (a JSON object whose only key is `title`). */
+function isTitleOnly(answer) {
+    try {
+        const o = JSON.parse(answer);
+        return typeof o === "object" && o !== null && !Array.isArray(o) && Object.keys(o).length === 1 && "title" in o;
+    }
+    catch {
+        return false;
+    }
+}
 /** The last text Claude wrote, from its transcript (older Stop hooks have no last_assistant_message). */
 function lastClaudeText(transcript) {
     let text = "";
@@ -427,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 });
@@ -453,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));
@@ -477,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");
@@ -495,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";
@@ -518,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";
@@ -541,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)
@@ -582,6 +714,7 @@ async function runJob(file) {
         return 0;
     }
     const log = createWriteStream(`${O}.log`);
+    let spawnErr;
     if (!pre())
         rc = 2;
     else {
@@ -610,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.
@@ -633,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)) {
@@ -647,8 +786,26 @@ async function runJob(file) {
         else
             res.answer = `${res.answer ?? ""}\nNo changes were made in the worktree.\n`;
     }
+    // Out of quota: not a code failure. Learn the model's bucket (orq quota / pick see it) and say why, so the conductor re-picks.
+    if (res.exhausted) {
+        const model = argvModel(j.argv);
+        let until = "";
+        if (res.exhausted.secs !== undefined) {
+            const at = Date.now() + res.exhausted.secs * 1000;
+            if (model)
+                learnExhausted("antigravity", model, res.exhausted.secs, agyToken()?.acct);
+            until = ` ${m("until", "até")} ${humanReset(Math.floor(at / 1000))} (${new Date(at).toISOString()})`;
+        }
+        res.answer = `quota exhausted: ${model ?? j.agent}${until}\n\n${res.exhausted.message}\n`;
+        res.rc = res.rc || 3;
+    }
     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`);
@@ -674,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/gc.js

@@ -4,6 +4,7 @@ import { existsSync, readdirSync, readFileSync, realpathSync, rmSync } from "nod
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { loadConfig } from "../config.js";
 import { m } from "../i18n.js";
+import { issueFromName, issuePattern, issuesWithLiveAgent } from "../issue.js";
 import { alive } from "../lock.js";
 import { stateDir } from "../paths.js";
 import { aliveOwner } from "./claim.js";
@@ -69,10 +70,11 @@ export async function gc(argv, clock = Date.now) {
             return 2;
         }
     }
-    const { cfg } = loadConfig(ws), rows = [];
+    const { cfg } = loadConfig(ws), rows = [], issuePat = issuePattern(ws);
     let ghUnavailable = false, fetchWarned = false;
     const root = join(ws, ".worktrees");
     const orq = join(ws, ".orquestra");
+    const liveAgents = issuesWithLiveAgent();
     const issues = existsSync(orq) ? readdirSync(orq).filter((x) => !x.startsWith(".")) : [];
     for (const repoName of readdirSync(ws, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)) {
         const repo = join(ws, repoName);
@@ -102,8 +104,8 @@ export async function gc(argv, clock = Date.now) {
             const branch = wt.branch?.replace(/^refs\/heads\//, "") ?? "";
             if (!branch)
                 continue;
-            // The branch carries the ID in lowercase (plane-abc-123); .orquestra/ keeps it as written (ABC-123).
-            const id = /^.*?plane-(.+)$/.exec(branch)?.[1];
+            // The branch carries the ID in lowercase (abc-123, maybe with a prefix or -suffix); .orquestra/ keeps it as written (ABC-123).
+            const id = issueFromName(branch, issuePat);
             const issue = id && issues.find((d) => d.toLowerCase() === id.toLowerCase());
             const status = output(path, "status", "--porcelain");
             const unpushed = output(repo, "rev-list", branch, "--not", "--remotes");
@@ -117,14 +119,10 @@ export async function gc(argv, clock = Date.now) {
                 verdict = "KEEP";
                 reason = m("issue has a live owner", "issue tem um responsável ativo");
             }
-            // A .pane/.id without a same-stem .done is treated as a running child.
-            const issueDir = issue && join(ws, ".orquestra", issue);
-            if (verdict !== "KEEP" && issueDir && existsSync(issueDir)) {
-                const files = readdirSync(issueDir), running = files.some((f) => /\.(pane|id)$/.test(f) && !existsSync(join(issueDir, `${f.replace(/\.(pane|id)$/, "")}.done`)));
-                if (running) {
-                    verdict = "KEEP";
-                    reason = m("child agent may still be running", "um agente filho pode estar em execução");
-                }
+            // A child agent of the issue whose state says running and whose pid is alive (the board's rule).
+            if (verdict !== "KEEP" && issue && liveAgents.has(issue)) {
+                verdict = "KEEP";
+                reason = m("child agent may still be running", "um agente filho pode estar em execução");
             }
             let merged = false;
             if (verdict !== "KEEP") {