@irythill/orq 0.4.0 → 0.5.0

package/README.md

@@ -146,13 +146,13 @@ roles  = ["review"]                      # here it only reviews; for someone els
 [agents.opencode.models.review]
 default = "minimax/MiniMax-M3"
 
-[agents.corvus]                          # a review tool, not a chat: no prompt, no session
+[agents.revtool]                          # a review tool, not a chat: no prompt, no session
 vendor  = "minimax"                      # the vendor of the model it runs, for the cross-vendor rule
 roles   = ["review"]
-run     = "corvus --markdown -b {base}"  # {base} = orq agent -b; it reads the diff itself
+run     = "revtool --markdown -b {base}"  # {base} = orq agent -b; it reads the diff itself
 write   = false
 ok_exit = [0, 1]                         # exit 1 = findings, still a verdict
-no_review = "Nada para revisar"          # matched on the answer's first line (or a short answer): not a verdict, status=fail
+no_review = "Nothing to review"          # matched on the answer's first line (or a short answer): not a verdict, status=fail
 # filter = "jq -r '...'"                 # optional: its output → [blocker]/[suggestion] lines
 
 [conductor]
@@ -216,6 +216,12 @@ To see everything at once, keep **`orq board`** open in a tab or window (any ter
 test queue, running agents (model, memory against the cap, last action), conductors and their issues, memory, quota,
 CI/CD per claimed issue, blocks and the 7-day scoreboard. `--once` prints it once, `--json` for scripts. With
 `ui.toast.delivery = "system"` in herdr's config, each finished step also pops up a native OS notification.
+A failure (tests red, agent `status=fail`, CI red) is also **loud**: besides the line typed into the conductor's pane
+(delivered by orq with retries and a log, `orq notice`), you get a herdr notification with sound, a `✗` title on the
+conductor's pane and, on Linux, a desktop notification (`[ui] desktop_notify = false` turns that one off; needs
+`notify-send`). Successes are quiet. The board's red top line lists failures from the last hour whose notice was not
+delivered or that the conductor has not yet acted on (it clears when the conductor runs `orq wait`, `orq verify` or
+`orq agent` for the issue).
 For quota without opening the board, `orq quota --line` fits herdr's tab bar (a `tab_bar_right` command entry,
 [docs/herdr.md](docs/herdr.md#quota-in-the-tab-bar)). `orq ci` shows each claimed issue's PR checks (queued, running,
 passed, failed or none, read from `gh` right then — it is a status check the user asked for, so unlike the board's
@@ -242,6 +248,7 @@ off the same issue. Details, shortcuts and scenarios: [docs/herdr.md](docs/herdr
 |---|---|
 | `orq agent -a <agent> ...` (`herdr-agent`) | Runs an agent with a memory cap in a herdr tab, a tmux window or the background; `-r` read only, `-R <id>` continue the session, `-i` attach a file, `-b <base>` attach the diff, `-T` the agent's own screen (herdr or tmux; `-R` with it open types the follow-up into it) |
 | `orq instructions claude\|agents` | Writes the `/issue` playbook as `SKILL.md` (Claude Code) or into `AGENTS.md` (Codex, OpenCode…) |
+| `orq notice [--list] [-n N]` | The delivery log of notices to conductors: each attempt, retry and failure (`<state>/notices.jsonl`) |
 | `orq wait <prefix>...` | Blocks until those agents finish; prints `status=` and the answer file (any conductor, any terminal) |
 | `orq verify ...` (`herdr-verify`) | Tests related to the diff, queued and memory-capped; failures that also fail on the base count as pre-existing |
 | `orq board` (`herdr-board`) | Live board: queue, agents, conductors, quota, blocks, scoreboard |
@@ -251,7 +258,7 @@ off the same issue. Details, shortcuts and scenarios: [docs/herdr.md](docs/herdr
 | `orq baseline ...` (`herdr-baseline`) | Manual snapshot of the tests failing on the base (outside the flow) |
 | `orq gc [-w <workspace>] [--yes] [--days N] [--json]` | Lists issue worktrees that are safe to remove (PR merged, or content already in the base, squash merges included); `--yes` removes them. Never touches uncommitted work, unpushed commits, a live claim or a running agent. Optional daily `orq-gc.timer` |
 | `orq ci [-w <workspace>] [--json]` | CI/CD status per claimed issue with a PR: queued, running, passed, failed or none, collected live via `gh` right then (the cache it fills is what `orq board`'s CI column reads, never blocking on the network). A run turning red or green pops a herdr notification, and a failure also pings the owning conductor |
-| `orq rounds <ID> [-w <workspace>] [--json]` | Watchdog without an LLM: fix rounds vs `policy.max_rounds`, time per round, reviewer findings repeated across rounds, alert ok / warn / stop. The board marks each issue (`r2/2 ⚠`) |
+| `orq rounds <ID> [-w <workspace>] [--json] [--diagnose]` | Watchdog: `--diagnose` (warn/stop only) has a cheap read only agent of another vendor (pick role `watchdog`, falls back to `opinion`, then `review`) diagnose why rounds don't converge → `.orquestra/<ID>/diagnosis-<n>.md`, advisory; `orq agent -R -F` past `max_rounds` needs it (`-F -F` bypasses). Without it, no LLM: fix rounds vs `policy.max_rounds`, time per round, reviewer findings repeated across rounds, alert ok / warn / stop. The board marks each issue (`r2/2 ⚠`) |
 | `orq quota --line` | One line of quota for a status bar (`work 64 · home 94! · codex 81`), from the board's cache, never the network |
 | `orq setup` | First configuration and install: environment, skills for Claude, config, conductor workspace |
 | `orq completion bash\|zsh\|fish\|powershell` | Prints the shell completion script (see Install) |

package/README.pt-BR.md

@@ -208,7 +208,13 @@ Para ver tudo de uma vez, deixe o **`orq board`** aberto numa aba ou janela (qua
 `herdr-board` o chama): fila de testes, agentes rodando (modelo, memória contra o limite, última ação), conductors e
 suas issues, memória, quota, CI/CD de cada issue reivindicada, bloqueios e o placar de 7 dias. `--once` imprime uma
 vez, `--json` para scripts. Com `ui.toast.delivery = "system"` na config do herdr, cada etapa concluída também gera
-uma notificação nativa do sistema. Para ver a cota sem abrir o board, o `orq quota --line` cabe na barra de abas do
+uma notificação nativa do sistema. Uma falha (testes vermelhos, agente `status=fail`, CI vermelho) também é **barulhenta**: além da linha digitada no pane do
+conductor (entregue pelo orq com novas tentativas e log, `orq notice`), você recebe uma notificação do herdr com som, um
+título `✗` no pane do conductor e, no Linux, uma notificação de desktop (`[ui] desktop_notify = false` desliga essa;
+precisa do `notify-send`). Sucessos ficam quietos. A linha vermelha no topo do board lista as falhas da última hora
+cujo aviso não foi entregue ou que o conductor ainda não tratou (some quando ele roda `orq wait`, `orq verify` ou
+`orq agent` para a issue).
+Para ver a cota sem abrir o board, o `orq quota --line` cabe na barra de abas do
 herdr (uma entrada `command` no `tab_bar_right`, [docs/pt-BR/herdr.md](docs/pt-BR/herdr.md#cota-na-barra-de-abas)).
 O `orq ci` mostra os checks do PR de cada issue reivindicada (na fila, rodando, passou, falhou ou nenhum, lido via
 `gh` na hora — é uma consulta que o usuário pediu agora, então, diferente da coluna de CI do board, não lê só o
@@ -235,6 +241,7 @@ dois conductors peguem a mesma issue. Detalhes, atalhos e cenários: [docs/pt-BR
 |---|---|
 | `orq agent -a <agent> ...` (`herdr-agent`) | Roda um agente com limite de memória numa aba do herdr, numa janela do tmux ou em segundo plano; `-r` só leitura, `-R <id>` continua a sessão, `-i` anexa um arquivo, `-b <base>` anexa o diff, `-T` a tela do próprio agente (herdr ou tmux; `-R` com ela aberta digita o follow-up nela) |
 | `orq instructions claude\|agents` | Escreve o playbook do `/issue` como `SKILL.md` (Claude Code) ou dentro do `AGENTS.md` (Codex, OpenCode…) |
+| `orq notice [--list] [-n N]` | O log de entrega dos avisos aos conductors: cada tentativa, nova tentativa e falha (`<state>/notices.jsonl`) |
 | `orq wait <prefixo>...` | Bloqueia até esses agentes terminarem; imprime `status=` e o arquivo da resposta (qualquer conductor, qualquer terminal) |
 | `orq verify ...` (`herdr-verify`) | Testes relacionados ao diff, em fila e com limite de memória; falhas que também falham na base contam como pré-existentes |
 | `orq board` (`herdr-board`) | Painel ao vivo: fila, agentes, conductors, cota, bloqueios, placar |
@@ -244,7 +251,7 @@ dois conductors peguem a mesma issue. Detalhes, atalhos e cenários: [docs/pt-BR
 | `orq baseline ...` (`herdr-baseline`) | Snapshot manual dos testes que falham na base (fora do fluxo) |
 | `orq gc [-w <workspace>] [--yes] [--days N] [--json]` | Lista worktrees de issues que podem ser removidas (PR mergeado, ou conteúdo já na base, inclusive squash merge); `--yes` as remove. Nunca mexe em trabalho não commitado, commit fora do remote, claim ativo ou agente rodando. `orq-gc.timer` diário opcional |
 | `orq ci [-w <workspace>] [--json]` | Status de CI/CD de cada issue reivindicada com PR: na fila, rodando, passou, falhou ou nenhum, coletado na hora via `gh` (o cache que ele preenche é o que a coluna de CI do `orq board` lê, sem nunca travar na rede). Quando vira verde ou vermelho sai uma notificação do herdr, e uma falha também avisa o conductor dono |
-| `orq rounds <ID> [-w <workspace>] [--json]` | Watchdog sem LLM: rodadas de fix vs `policy.max_rounds`, tempo por rodada, achados do revisor repetidos entre rodadas, alerta ok / warn / stop. O board marca cada issue (`r2/2 ⚠`) |
+| `orq rounds <ID> [-w <workspace>] [--json] [--diagnose]` | Watchdog: `--diagnose` (só warn/stop) pede a um agente barato, somente leitura e de outro fornecedor (papel de pick `watchdog`, cai para `opinion`, depois `review`) o diagnóstico de por que as rodadas não convergem → `.orquestra/<ID>/diagnosis-<n>.md`, consultivo; `orq agent -R -F` além de `max_rounds` exige (`-F -F` ignora). Sem ele, sem LLM: rodadas de fix vs `policy.max_rounds`, tempo por rodada, achados do revisor repetidos entre rodadas, alerta ok / warn / stop. O board marca cada issue (`r2/2 ⚠`) |
 | `orq quota --line` | Uma linha de cota para barra de status (`work 64 · home 94! · codex 81`), do cache do board, nunca da rede |
 | `orq setup` | Primeira configuração e instalação: ambiente, skills do Claude, config, workspace do conductor |
 | `orq completion bash\|zsh\|fish\|powershell` | Imprime o script de autocompletar do shell (veja Instalação) |

package/dist/agents.js

@@ -1,4 +1,8 @@
 import { m } from "./i18n.js";
+/** Does the agent's command take the prompt (stdin, a file in its folder or a {prompt*} placeholder)? A review tool like revtool does not. */
+export const usesPrompt = (a) => Boolean(a.stdin || a.prompt_in_dir || /\{prompt(_text|_hint)?\}/.test(a.run ?? ""));
+/** Read only runs of a `throwaway` agent get a worktree copy of HEAD, but only where there is a git repo to copy. */
+export const useThrowaway = (def, ro, resume, inGit) => Boolean(def.throwaway && ro && !resume && inGit);
 const NOMCP_CODEX = "-c mcp_servers.plane.enabled=false -c mcp_servers.shadcn.enabled=false";
 const CLAUDE = "claude -p --strict-mcp-config --output-format stream-json --verbose [--model {model}] --effort {effort:low}";
 const CLAUDE_TUI = "claude --strict-mcp-config [--model {model}] --effort {effort:low}";
@@ -212,3 +216,9 @@ export const FORMATS = {
         },
     },
 };
+/** The model in an agent's argv (-m / --model / --model=x), without the provider prefix. */
+export function argvModel(a) {
+    const i = a.findIndex((x) => x === "-m" || x === "--model");
+    const v = i >= 0 ? a[i + 1] : a.find((x) => x.startsWith("--model="))?.slice(8);
+    return v?.split("/").pop();
+}

package/dist/ci.js

@@ -203,7 +203,7 @@ function notifyDesktop(issue, repo, state) {
  */
 export function collectCi(ws, hooks = {}) {
     // Detached: collectCi() must never block on a conductor stuck in a dialog (herdr-notify waits up to 30 min).
-    const desktop = hooks.desktop ?? notifyDesktop, toOwner = hooks.owner ?? ((pane, line) => notify(pane, line, true)), notice = hooks.notice ?? ((l) => console.log(l));
+    const desktop = hooks.desktop ?? notifyDesktop, toOwner = hooks.owner ?? ((pane, line) => notify(pane, line)), notice = hooks.notice ?? ((l) => console.log(l));
     const now = Date.now(), worktrees = listWorktrees(ws);
     const found = claimedIssues(ws).flatMap(({ id, owner, kind }) => issueBranches(ws, id, worktrees).map(({ repo, branch }) => ({ id, owner, kind, repo, branch, ...prStatus(join(ws, repo), branch) })));
     const toNotify = [];
@@ -225,7 +225,9 @@ export function collectCi(ws, hooks = {}) {
         return mine;
     });
     for (const { owner, kind, id, repo, state, sha } of toNotify) {
-        desktop(id, repo, state);
+        // A failure the owner is told about already pops up (src/notice.ts signals it loudly): no second popup.
+        if (!(state === "failed" && owner && kind === "herdr"))
+            desktop(id, repo, state);
         if (state === "failed" && owner) {
             const line = `[ORQ CI] ${id} ${repo} failed (${sha.slice(0, 7)})`;
             if (kind === "herdr")

package/dist/cli.js

@@ -18,6 +18,7 @@ import { handoff, USAGE as HANDOFF } from "./commands/handoff.js";
 import { instructions, USAGE as INSTRUCTIONS } from "./commands/instructions.js";
 import { lang, USAGE as LANG } from "./commands/lang.js";
 import { lock, USAGE as LOCK } from "./commands/lock.js";
+import { noticeCmd, USAGE as NOTICE } from "./notice.js";
 import { pick, USAGE as PICK } from "./commands/pick.js";
 import { quota, USAGE as QUOTA } from "./commands/quota.js";
 import { rounds, USAGE as ROUNDS } from "./commands/rounds.js";
@@ -27,7 +28,7 @@ import { setup, USAGE as SETUP } from "./commands/setup.js";
 import { stats, USAGE as STATS } from "./commands/stats.js";
 import { verify, USAGE as VERIFY } from "./commands/verify.js";
 import { wait, USAGE as WAIT } from "./commands/wait.js";
-const COMMANDS = { config, set, board, lang, block, quota, pick, stats, rounds, setup, lock, claim, deps, gc, ci, handoff, run, agent, wait, instructions, verify, baseline,
+const COMMANDS = { config, set, board, lang, block, quota, pick, stats, rounds, setup, lock, claim, deps, gc, ci, handoff, run, agent, wait, instructions, verify, baseline, notice: noticeCmd,
     completion: (a) => completion(a, Object.keys(COMMANDS)) };
 const usage = () => `orq <command> [args]
 
@@ -48,6 +49,7 @@ ${HANDOFF}
 ${VERIFY}
 ${BASELINE}
 ${INSTRUCTIONS}
+${NOTICE}
 ${CLAIM}
 ${DEPS}
 ${GC}

package/dist/commands/agent.js

@@ -2,7 +2,7 @@
 // under its memory cap (src/process.ts), in a herdr tab, a tmux window or the background (src/terminal.ts).
 // Writes <prefix>.out.md (final answer) / .log / .id (session, for -R) / .pane / .done ("status=ok|fail rc=N at=...").
 // Returns at once; `orq wait <prefix>` blocks until .done. A conductor in herdr (HERDR_PANE_ID) also gets ONE line
-// "[HERDR-AGENT DONE] <title> status=... answer: <prefix>.out.md" typed into its pane by herdr-notify.
+// "[HERDR-AGENT DONE] <title> status=... answer: <prefix>.out.md" typed into its pane by src/notice.ts.
 // The launcher writes <prefix>.job.json and starts `orq agent --run <job>` on the terminal host; that runner does the rest.
 // -T (or machine.tui / HERDR_AGENT_TUI=1): the agent's own screen (its `tui` template) in a herdr tab or tmux window,
 // same cap and files. The agent calls `orq agent --turn <job> <kind>` at every end of turn, which writes .out.md/.id/
@@ -14,7 +14,8 @@ import { appendFileSync, copyFileSync, createWriteStream, existsSync, mkdirSync,
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { claudeAccounts } from "../accounts.js";
-import { agentDef, ALIASES, expandString, expandTemplate, FORMATS } from "../agents.js";
+import { gateFor } from "../diagnose.js";
+import { argvModel, 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";
@@ -22,8 +23,9 @@ import { alive } from "../lock.js";
 import { stateDir } from "../paths.js";
 import { 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]] [-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] [-r] [-R session [-F [-F]]] [-T] -- <prompt.md>   run a child agent";
 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) => {
@@ -35,8 +37,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 || "codex", g = "", t = "", d = "", o = "", model = "", effort = "", acc = "", resume = "", base = "";
-    let ro = false, tui = false, force = false, prompt;
+    let a = process.env.AGENT || "", g = "", t = "", d = "", o = "", model = "", effort = "", acc = "", resume = "", base = "";
+    let ro = false, tui = false, force = 0, prompt;
     const inc = [];
     for (let i = 0; i < argv.length; i++) {
         const x = argv[i], v = () => argv[++i] ?? "";
@@ -73,7 +75,7 @@ export async function agent(argv) {
         else if (x === "-T")
             tui = true;
         else if (x === "-F")
-            force = true;
+            force++;
         else if (!x.startsWith("-") && prompt === undefined)
             prompt = x;
         else {
@@ -90,6 +92,11 @@ export async function agent(argv) {
             console.error(`${m("missing", "faltou")} -${f}`);
             return 2;
         }
+    // No default agent: an empty $(orq pick ...) means no candidate, and must not start anything.
+    if (!a) {
+        console.error(m("missing -a (if it came from orq pick, it found no candidate): nothing started", "faltou -a (se veio do orq pick, ele não achou candidato): nada foi iniciado"));
+        return 2;
+    }
     a = ALIASES[a] ?? a;
     const { cfg } = loadConfig();
     const def = agentDef(cfg, a);
@@ -133,9 +140,18 @@ export async function agent(argv) {
         }
         catch { /* first follow-up */ }
         if (n >= max && !force) {
-            console.error(m(`round limit: session ${resume} already had ${n} follow-up(s) (policy.max_rounds = ${max}). Stop and tell the user; with their OK, repeat with -F.`, `limite de rodadas: a sessão ${resume} já teve ${n} follow-up(s) (policy.max_rounds = ${max}). Pare e avise o usuário; com o OK dele, repita com -F.`));
+            console.error(m(`round limit: session ${resume} already had ${n} follow-up(s) (policy.max_rounds = ${max}). Stop and tell the user; with their OK, run \`orq rounds <ID> --diagnose\`, then repeat with -F.`, `limite de rodadas: a sessão ${resume} já teve ${n} follow-up(s) (policy.max_rounds = ${max}). Pare e avise o usuário; com o OK dele, rode \`orq rounds <ID> --diagnose\` e repita com -F.`));
             return 4;
         }
+        // -F past the limit also needs the watchdog's diagnosis of this round count (-F -F skips it: the user's own call).
+        // The issue folder is the prefix's folder, .orquestra/<ID>/ (where the .rounds-<session> counter lives).
+        if (n >= max && force === 1 && basename(dirname(dirname(O))) === ".orquestra") {
+            const g = gateFor(dirname(O)), id = basename(dirname(O));
+            if (g.verdict !== "ok") {
+                console.error(m(`no current diagnosis: ${g.verdict === "stale" ? `diagnosis-${g.rounds}.md is older than the latest fix/review` : `diagnosis-${g.rounds}.md does not exist`}. Run \`orq rounds ${id} --diagnose\` first, read it, and ask the user. -F -F skips this check.`, `sem diagnóstico atual: ${g.verdict === "stale" ? `diagnosis-${g.rounds}.md é mais antigo que o último fix/revisão` : `diagnosis-${g.rounds}.md não existe`}. Rode \`orq rounds ${id} --diagnose\` antes, leia e consulte o usuário. -F -F pula esta checagem.`));
+                return 4;
+            }
+        }
         mkdirSync(dirname(O), { recursive: true });
         writeFileSync(cf, String(n + 1));
     }
@@ -176,6 +192,7 @@ export async function agent(argv) {
     }
     catch { /* first run or ended */ }
     if (tui && resume && alive(pid) && screenOpen(open)) {
+        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 });
         typeInto(open, readFileSync(P, "utf8"));
@@ -184,7 +201,7 @@ export async function agent(argv) {
     }
     for (const s of [".done", ".out.md", ".pid"])
         rmSync(O + s, { force: true });
-    const throwaway = Boolean(def.throwaway && ro && !resume);
+    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");
     const wg = git(repo, "rev-parse", "--absolute-git-dir");
@@ -253,6 +270,7 @@ export async function agent(argv) {
     // 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`);
+    ackPrefix(O); // starting work on the issue again: its failure notices were seen
     const where = launch(host, { group: g || "agents", title: t, dir: repo, argv: [process.execPath, CLI, "agent", "--run", `${O}.job.json`], id: unit, keep: job.keep });
     writeFileSync(`${O}.pane`, `${where}\n`);
     console.log(`[orq agent] ${t} → ${where}${tui ? " (TUI)" : ""}`);
@@ -326,7 +344,7 @@ function turn(file, kind, rest) {
         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`);
         if (j.parent)
-            notify(j.parent, `[HERDR-AGENT DONE] ${j.title} status=${st} rc=0 answer: ${O}.out.md`, true);
+            notify(j.parent, `[HERDR-AGENT DONE] ${j.title} status=${st} rc=0 answer: ${O}.out.md`);
     }
     catch (e) {
         console.error(`orq agent --turn: ${e.message}`);
@@ -396,7 +414,7 @@ async function runJob(file) {
     const stateF = join(stateDir(), "agents", `${j.unit}.json`);
     const at = new Date().toISOString();
     const state = (extra = {}) => { try {
-        writeAtomic(stateF, JSON.stringify({ pid: process.pid, prefix: O, title: j.title, agent: j.agent, host: j.host, cap: j.cap, at, ...extra }));
+        writeAtomic(stateF, JSON.stringify({ pid: process.pid, prefix: O, title: j.title, agent: j.agent, model: argvModel(j.argv), host: j.host, cap: j.cap, at, ...extra }));
     }
     catch { /* best effort */ } };
     state();
@@ -449,7 +467,7 @@ async function runJob(file) {
             if (!existsSync(`${O}.done`)) {
                 writeAtomic(`${O}.done`, `status=fail rc=${code} 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`, true);
+                    notify(j.parent, `[HERDR-AGENT DONE] ${j.title} status=fail rc=${code} answer: ${O}.out.md`);
             }
             rmSync(`${O}.pid`, { force: true });
             return ok ? "ok" : "fail";

package/dist/commands/block.js

@@ -8,7 +8,9 @@ import { writeAtomic } from "../fsutil.js";
 import { loginId } from "../identity.js";
 import { m } from "../i18n.js";
 import { stateDir } from "../paths.js";
-export const USAGE = `orq block <agent|account> [--until YYYY-MM-DD[THH:MM] | --days N] [--reason "text"]   default: 7 days
+import { getPath, loadConfig } from "../config.js";
+import { collect } from "../quota.js";
+export const USAGE = `orq block <agent|account> [--until YYYY-MM-DD[THH:MM] | --days N | --quota] [--reason "text"]   default: 7 days; --quota: until the quota window resets
 orq block -r <agent|account>       unblock early
 orq block -l                       list active blocks (expired ones disappear by themselves)`;
 const file = () => join(stateDir(), "blocks.json");
@@ -45,7 +47,16 @@ export function parseLocal(s) {
         throw new Error(m(`invalid date: ${s}`, `data inválida: ${s}`));
     return d;
 }
-export function block(argv) {
+/** When a quota line's exhausted window resets, in epoch seconds: the week if it is used up, else the 5h window (the
+ *  reading can lag behind the limit: Codex's comes from its last session). undefined = no reset known. */
+export function quotaUntil(line) {
+    const reset = (k) => { const x = new RegExp(`\\b${k}=(\\d+)`).exec(line); return x ? Number(x[1]) : undefined; };
+    const week = /\bweek=(\d+)%/.exec(line);
+    if (week && Number(week[1]) >= 100 && reset("resetweek"))
+        return reset("resetweek");
+    return reset("reset5h") ?? reset("resetweek");
+}
+export async function block(argv) {
     const b = load();
     if (!argv.length || argv[0] === "-h" || argv[0] === "--help") {
         console.log(USAGE);
@@ -69,7 +80,7 @@ export function block(argv) {
         return 0;
     }
     const [name, ...rest] = argv;
-    let until = new Date(Date.now() + 7 * 86400_000), reason = "";
+    let until = new Date(Date.now() + 7 * 86400_000), reason = "", byQuota = false;
     while (rest.length) {
         const o = rest.shift();
         if (o === "--until")
@@ -78,6 +89,18 @@ export function block(argv) {
             until = new Date(Date.now() + Number(rest.shift()) * 86400_000);
         else if (o === "--reason")
             reason = rest.shift() ?? "";
+        else if (o === "--quota")
+            byQuota = true;
+    }
+    if (byQuota) {
+        const sources = (getPath(loadConfig().cfg, "quota") ?? {});
+        const line = (await collect(sources, [name])).find((l) => l.startsWith(`${name} `));
+        const r = line && quotaUntil(line);
+        if (!r) {
+            console.error(m(`${name}: no quota reset known; use --until or --days`, `${name}: sem horário de renovação da cota; use --until ou --days`));
+            return 1;
+        }
+        until = new Date(r * 1000);
     }
     if (Number.isNaN(until.getTime())) {
         console.error(USAGE);

package/dist/commands/board.js

@@ -16,12 +16,14 @@ import { collectCi, collectedAt, loadCache as loadCiCache } from "../ci.js";
 import { getPath, loadConfig } from "../config.js";
 import { writeAtomic } from "../fsutil.js";
 import { m, setLang } from "../i18n.js";
+import { argvModel } from "../agents.js";
 import { alive, status as lockStatus } from "../lock.js";
 import { expand, stateDir } from "../paths.js";
 import { processTableAsync, treeMem } from "../process.js";
 import { collect } from "../quota.js";
 import { collectRounds, mark, roundsSig } from "../rounds.js";
 import { collectRuns, rows } from "../stats.js";
+import { pendingNotices, readLog } from "../notice.js";
 import { load as loadBlocks } from "./block.js";
 import { herdrNamesAsync, nameOf } from "./claim.js";
 import { setValue } from "./set.js";
@@ -35,19 +37,20 @@ catch {
     return "";
 } };
 const models = new Map();
-/** The model a run was started with, from its job file (-m / --model in the argv). */
-function modelOf(prefix) {
-    if (!models.has(prefix)) {
+/** The model of a run recorded before its state file had one, from its job file; a rerun on the same prefix
+ *  overwrites that file, so another unit's job says nothing about this run. */
+function modelOf(prefix, unit) {
+    if (!models.has(unit)) {
         let v;
         try {
-            const a = (JSON.parse(read(`${prefix}.job.json`)).argv ?? []);
-            const i = a.findIndex((x) => x === "-m" || x === "--model");
-            v = i >= 0 ? a[i + 1] : a.find((x) => x.startsWith("--model="))?.slice(8);
+            const j = JSON.parse(read(`${prefix}.job.json`));
+            if (!j.unit || j.unit === unit)
+                v = argvModel(j.argv ?? []);
         }
         catch { /* no job file */ }
-        models.set(prefix, v?.split("/").pop());
+        models.set(unit, v);
     }
-    return models.get(prefix);
+    return models.get(unit);
 }
 /** What the agent did last, from the tail of its log (stream JSON of claude/opencode, else the last text line). */
 export function activity(log) {
@@ -110,7 +113,7 @@ function agents(table, now) {
             continue;
         if ((st === "ok" || st === "fail") && now - (end ?? at) > RECENT_MS)
             continue;
-        const a = { unit: f.slice(0, -5), title: String(s.title ?? ""), agent: String(s.agent ?? "?"), model: modelOf(prefix),
+        const a = { unit: f.slice(0, -5), title: String(s.title ?? ""), agent: String(s.agent ?? "?"), model: typeof s.model === "string" ? s.model : modelOf(prefix, f.slice(0, -5)),
             host: s.host, pid, issue: basename(dirname(prefix)), label: basename(prefix), state: st,
             secs: Math.max(0, Math.round(((end ?? now) - at) / 1000)), cap: typeof s.cap === "number" ? s.cap : undefined };
         if (s.rc !== undefined)
@@ -268,7 +271,7 @@ export async function snapshot(wss, table) {
     return {
         at: new Date(now).toISOString(), mem: { used: totalmem() - freemem(), total: totalmem() }, workspaces: wss,
         queue: { holders: q.holders.map(item), waiters: q.waiters.map(item) }, agents: agents(table, now),
-        conductors: await conductors(wss), quota: quota(now), ci: ci(wss, now), blocks: loadBlocks(), scoreboard: scoreboard(wss[0], now),
+        conductors: await conductors(wss), quota: quota(now), ci: ci(wss, now), blocks: loadBlocks(), scoreboard: scoreboard(wss[0], now), notices: pendingNotices(readLog(), now),
     };
 }
 // --- render -----------------------------------------------------------------------------------------------------
@@ -322,6 +325,15 @@ export function render(s, theme, cols, mode = colorMode()) {
     out.push(`${c.surf}${c.b}${c.acc} ORQ${c.b ? "\x1b[22m" : ""}${c.surf}${c.ink2}  ${ws}${" ".repeat(Math.max(1, W - left.length - right.length))}${c.mut}${right}`);
     const mp = Math.round(100 * s.mem.used / s.mem.total);
     out.push(` ${c.mut}MEM${c.r}  ${meter(mp, 24)} ${c.ink}${gb(s.mem.used)}${c.r} ${c.mut}/ ${gb(s.mem.total)}${c.r}`);
+    // Red line(s) first: a failure the conductor may not know about is what a person must see before anything else.
+    if (s.notices.length) {
+        const ago = (at) => dur(Math.max(0, Math.round((new Date(s.at).getTime() - at) / 1000)));
+        out.push(` ${c.err}${c.b}✗ ${m(`${s.notices.length} failure(s) the conductor may not know about`, `${s.notices.length} falha(s) que o conductor pode não saber`)}${c.r}`);
+        for (const n of s.notices.slice(0, 5)) {
+            const what = n.line.replace(/^\[[^\]]+\] /, "").replace(/ answer: .*/, "");
+            out.push(` ${c.err}  ${fit(n.issue ?? "-", 10)}${c.r} ${c.ink}${fit(what, Math.max(20, W - 44))}${c.r} ${c.err}${n.why === "undelivered" ? m("not delivered", "não entregue") : m("not acknowledged", "sem resposta")}${c.r} ${c.mut}${ago(n.at)}${m(" ago", " atrás")}${c.r}`);
+        }
+    }
     section("TRANSPORT", m("test queue", "fila de testes"));
     for (const h of s.queue.holders)
         out.push(` ${c.acc}▶ REC${c.r}  ${c.ink}${fit(h.label, 34)}${c.r} ${c.ok}${m("running", "rodando")}${c.r} ${c.ink}${dur(h.secs).padEnd(7)}${c.r} ${c.ink2}${gb(h.mem)}${c.r}`
@@ -332,7 +344,7 @@ export function render(s, theme, cols, mode = colorMode()) {
     section("TRACKS", m("agents", "agentes"));
     s.agents.forEach((a, i) => {
         const n = `${c.mut}${String(i + 1).padStart(2, "0")}${c.r}`, who = `${c.ink}${fit(a.issue, 9)}${c.r} ${c.ink2}${fit(a.label, 22)}${c.r} `
-            + `${c.ink}${fit(a.agent, 11)}${c.r}${c.mut}${fit(a.model ?? m("default", "padrão"), 17)}${c.r} ${c.ink}${dur(a.secs).padEnd(7)}${c.r}`;
+            + `${c.ink}${fit(a.agent, 11)}${c.r}${c.mut}${fit(a.model ?? m("default", "padrão"), 17)}${c.r} ${c.ink}${(a.state === "died" ? "?" : dur(a.secs)).padEnd(7)}${c.r}`; // died: when it stopped is unknown
         if (a.state === "running") {
             const pct = a.cap && a.mem ? Math.round(100 * a.mem / a.cap) : 0, used = 1 + 2 + 2 + 10 + 23 + 11 + 17 + 1 + 8 + 6 + 1 + 7 + 1;
             const warn = a.secs > 3 * 3600 ? ` ${c.err}⚠ ${m("for", "há")} ${dur(a.secs)}${c.r}` : "";

package/dist/commands/completion.js

@@ -18,9 +18,9 @@ const DESC = {
 export const WORDS = {
     setup: ["--preset", "--detect", "--answers", "--write", "--install", "--workspace"],
     config: ["get", "files", "-w"], lang: ["pt", "en", "auto", "toggle"], lock: ["wait", "release", "run", "status"],
-    pick: ["impl", "fix", "worker", "review", "opinion"], instructions: ["claude", "agents"], board: ["--once", "--json", "-w"],
+    pick: ["impl", "fix", "worker", "review", "opinion", "watchdog"], instructions: ["claude", "agents"], board: ["--once", "--json", "-w"],
     completion: ["bash", "zsh", "fish", "powershell"], stats: ["--days", "--json", "-w"], wait: ["--any", "--timeout", "--answer"],
-    ci: ["--json", "-w"], rounds: ["--json", "-w"],
+    ci: ["--json", "-w"], rounds: ["--json", "--diagnose", "-w"],
 };
 const q = (s) => `'${s.replace(/'/g, "''")}'`; // PowerShell single quotes
 const qf = (s) => `'${s.replace(/[\\']/g, "\\$&")}'`; // fish single quotes

package/dist/commands/pick.js

@@ -13,7 +13,7 @@ import { collect } from "../quota.js";
 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> [--level simple|medium|heavy] [--impl-vendor <v>|--impl-agent <a>]
+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]
 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.

package/dist/commands/rounds.js

@@ -1,9 +1,22 @@
 // orq rounds <ID> [-w <workspace>] [--json]   per-issue round metrics from .orquestra/<ID>/ (src/rounds.ts), no LLM
+// orq rounds <ID> --diagnose [-w <workspace>]  warn/stop only: a cheap read only "watchdog" agent (another vendor than the
+//   implementer when known) diagnoses why the rounds don't converge → .orquestra/<ID>/diagnosis-<rounds>.md (advisory)
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { getPath, loadConfig } from "../config.js";
+import { buildPrompt, evidence, latestDiagnosis, recommendation } from "../diagnose.js";
 import { m } from "../i18n.js";
 import { expand } from "../paths.js";
 import { collectRounds, mark } from "../rounds.js";
-export const USAGE = "orq rounds <ID> [-w <workspace>] [--json]   rounds vs max_rounds, time per round, repeated findings, alert level";
+import { alive } from "../lock.js";
+import { wait } from "./wait.js";
+export const USAGE = `orq rounds <ID> [-w <workspace>] [--json]   rounds vs max_rounds, time per round, repeated findings, alert level
+orq rounds <ID> --diagnose [-w <workspace>]   on warn/stop: an independent cheap agent diagnoses why rounds don't converge (advisory; needed for orq agent -R -F)`;
+export const WATCHDOG_TIMEOUT = 900; // seconds `orq rounds --diagnose` waits for the agent
+const CLI = fileURLToPath(new URL("../cli.js", import.meta.url));
 const dur = (s) => (s >= 3600 ? `${Math.floor(s / 3600)}h${String(Math.floor(s / 60) % 60).padStart(2, "0")}m` : s >= 60 ? `${Math.floor(s / 60)}m${String(s % 60).padStart(2, "0")}s` : `${s}s`);
 const why = (r) => ({
     over_max: m(`rounds ${r.n} > max_rounds ${r.max}`, `rodadas ${r.n} > max_rounds ${r.max}`),
@@ -12,8 +25,8 @@ const why = (r) => ({
     repeated: m(`${r.n} repeated finding(s)`, `${r.n} achado(s) repetido(s)`),
     slow: m(`round ${r.rounds?.join(", ")} much slower than the others`, `rodada ${r.rounds?.join(", ")} bem mais lenta que as outras`),
 })[r.code];
-export function rounds(argv) {
-    let ws, id, json = false;
+export async function rounds(argv) {
+    let ws, id, json = false, diagnose = false;
     for (let i = 0; i < argv.length; i++) {
         if (argv[i] === "-w") {
             if (!argv[i + 1]) {
@@ -24,6 +37,8 @@ export function rounds(argv) {
         }
         else if (argv[i] === "--json")
             json = true;
+        else if (argv[i] === "--diagnose")
+            diagnose = true;
         else if (!id && !argv[i].startsWith("-"))
             id = argv[i];
         else {
@@ -42,6 +57,8 @@ export function rounds(argv) {
         console.error(m(`no rounds recorded for ${id} in ${ws}/.orquestra`, `nenhuma rodada registrada para ${id} em ${ws}/.orquestra`));
         return 1;
     }
+    if (diagnose)
+        return diagnoseIssue(ws, id, x);
     if (json) {
         console.log(JSON.stringify(x, null, 2));
         return 0;
@@ -54,5 +71,62 @@ export function rounds(argv) {
         console.log(m("repeated findings:", "achados repetidos:"));
     for (const r of x.repeats)
         console.log(`  [${m("rounds", "rodadas")} ${r.rounds.join(",")}] ${r.title.slice(0, 100)}`);
+    const d = latestDiagnosis(join(ws, ".orquestra", id));
+    if (d)
+        console.log(`${m("diagnosis", "diagnóstico")} ${d.n}: ${d.line ?? m("(no RECOMMENDATION line)", "(sem linha RECOMMENDATION)")}`);
+    return 0;
+}
+const orq = (...a) => spawnSync(process.execPath, [CLI, ...a], { encoding: "utf8" });
+/** --diagnose: pick a watchdog, run it read only on the evidence, keep its answer as diagnosis-<rounds>.md. */
+async function diagnoseIssue(ws, id, x) {
+    if (x.level === "ok") {
+        console.log(m(`${id}: level is ok, no diagnosis needed`, `${id}: nível ok, não precisa de diagnóstico`));
+        return 0;
+    }
+    const dir = join(ws, ".orquestra", id), prefix = join(dir, `watchdog-${x.rounds}-${Date.now()}`), out = join(dir, `diagnosis-${x.rounds}.md`);
+    // The implementer, when known (impl-<repo>.pick saved by the playbook): the watchdog must be another vendor.
+    const implPick = readdirSync(dir).filter((n) => /^impl-.+\.pick$/.test(n)).map((n) => /(?:^|\s)-a (\S+)/.exec(readFileSync(join(dir, n), "utf8"))?.[1]).find(Boolean);
+    // A watchdog still running for this issue (a previous --diagnose that timed out or was interrupted): don't start another.
+    for (const n of readdirSync(dir).filter((f) => /^watchdog-.+\.pid$/.test(f))) {
+        const pid = Number(readFileSync(join(dir, n), "utf8"));
+        if (pid && alive(pid)) {
+            console.error(m(`a watchdog for ${id} is still running (${n}, pid ${pid}); wait for it or stop it first`, `um watchdog de ${id} ainda está rodando (${n}, pid ${pid}); espere ou encerre antes`));
+            return 1;
+        }
+    }
+    const ev = evidence(dir);
+    writeFileSync(`${prefix}.md`, buildPrompt(x, ev.fixes, ev.reviews));
+    const p = orq("pick", "watchdog", "--level", "simple", "-w", ws, ...(implPick ? ["--impl-agent", implPick] : []));
+    if (p.status !== 0) {
+        console.error(p.stderr.trim() || `orq pick watchdog: exit ${p.status}`);
+        return p.status ?? 1;
+    }
+    const picked = p.stdout.trim().split(/\s+/);
+    // The agent runs in a scratch folder (everything it needs is in the prompt): it can't touch the issue files, even write sandboxed.
+    const scratch = mkdtempSync(join(tmpdir(), "orq-watchdog-"));
+    try {
+        const a = orq("agent", ...picked, "-r", "-t", `${id} watchdog`, "-d", scratch, "-g", "watchdog", "-o", prefix, "--", `${prefix}.md`);
+        process.stderr.write(a.stderr);
+        process.stdout.write(a.stdout);
+        if (a.status !== 0)
+            return a.status ?? 1;
+        return await finish(await wait(["--timeout", String(WATCHDOG_TIMEOUT), prefix]), prefix, out);
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}
+async function finish(rc, prefix, out) {
+    if (rc === 124) {
+        console.error(m(`diagnosis not written: the watchdog agent did not finish in ${WATCHDOG_TIMEOUT}s`, `diagnóstico não gravado: o agente watchdog não terminou em ${WATCHDOG_TIMEOUT}s`));
+        return 124;
+    }
+    if (rc !== 0 || !existsSync(`${prefix}.out.md`)) {
+        console.error(m("the watchdog agent failed; no diagnosis written", "o agente watchdog falhou; diagnóstico não gravado"));
+        return 1;
+    }
+    copyFileSync(`${prefix}.out.md`, out);
+    console.log(m(`diagnosis saved to ${out}`, `diagnóstico gravado em ${out}`));
+    console.log(recommendation(readFileSync(out, "utf8")) ?? m("(no RECOMMENDATION line in the answer)", "(sem linha RECOMMENDATION na resposta)"));
     return 0;
 }

package/dist/commands/stats.js

@@ -5,7 +5,7 @@ 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";
 const k = (n) => (n === null ? "-" : n >= 1000 ? `${Math.round(n / 1000)}k` : String(n));
-const ORDER = ["impl", "fix", "review", "other"];
+const ORDER = ["impl", "fix", "review", "watchdog", "other"];
 export function stats(argv) {
     let ws, days = 30, json = false;
     for (let i = 0; i < argv.length; i++) {

package/dist/commands/verify.js

@@ -11,6 +11,7 @@ import { tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { getPath, loadConfig } from "../config.js";
 import { m } from "../i18n.js";
+import { ackPrefix } from "../notice.js";
 import { dropWorktree, failures, git, inJob, JS_EXT, launchJob, linkModules, runnerArgs, runnerOf, runTests, testCap, today, unsupported } from "../testrun.js";
 export const USAGE = "orq verify -w <workspace> -r <repo> -d <worktree> -b <base> -o <prefix> [-g group] [-x]   tests of the diff, new vs pre-existing failures";
 export async function verify(argv) {
@@ -36,6 +37,7 @@ export async function verify(argv) {
         }
     const out = resolve(o.o);
     mkdirSync(dirname(out), { recursive: true });
+    ackPrefix(out); // re-running the tests of an issue: its failure notices were seen
     rmSync(`${out}.done`, { force: true });
     rmSync(`${out}.txt`, { force: true });
     // Title "<ID> verify <repo>" (ID = the prefix's folder, .orquestra/<ID>/) so closing the issue finds the tab.

package/dist/commands/wait.js

@@ -6,6 +6,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { basename } from "node:path";
 import { m } from "../i18n.js";
 import { alive } from "../lock.js";
+import { ackPrefix } from "../notice.js";
 export const USAGE = "orq wait [--any] [--timeout <s>] [--answer] <prefix>...   block until child agents finish (exit 1 = one failed)";
 const read = (f) => { try {
     return readFileSync(f, "utf8");
@@ -61,6 +62,7 @@ export async function wait(argv) {
                 continue;
             pending.splice(pending.indexOf(p), 1);
             console.log(d.line);
+            ackPrefix(p); // the conductor has the result in hand: this issue's failure notice is acknowledged
             if (answer) {
                 const t = read(`${p}.out.md`);
                 if (t)

package/dist/config.js

@@ -27,7 +27,7 @@ export const DEFAULTS = {
         max_rounds: 2, // fix rounds before stopping and calling the user
         review: "other-vendor", // other-vendor | any
     },
-    ui: { lang: "auto", theme: "gunmetal" }, // lang: auto | en | pt · theme: gunmetal | chrome | lcd | terminal
+    ui: { lang: "auto", theme: "gunmetal", desktop_notify: true }, // lang: auto | en | pt · theme: gunmetal | chrome | lcd | terminal · desktop_notify: desktop popup for failures (Linux, notify-send)
     // Where quota comes from, per agent: "builtin" | "none" | false | { command = "..." } (see src/quota.ts).
     // "claude" covers every account in claude-accounts.
     quota: { claude: "builtin", codex: "builtin", opencode: "builtin", antigravity: "builtin", copilot: "builtin" },