@irythill/orq 0.4.0 → 0.6.0

package/README.md

@@ -2,11 +2,12 @@
 
 <p align="center"><img src="docs/img/orq-logo.svg" alt="orq — an orc in a tailcoat raising a conductor's baton" width="304"></p>
 
-# orq — orchestrating coding agents with herdr
+# orq — orchestrating coding agents
 
 You describe the work in a Plane issue. A **conductor** (Claude, ideally Opus) reads it, picks the right agent for
-each step, dispatches the **implementer**, the **tests** and a **cross-vendor review** in [herdr](https://herdr.dev)
-tabs, and hands the issue back *In Review* with a summary in Plane. Merge, PR and deploy stay with you.
+each step, dispatches the **implementer**, the **tests** and a **cross-vendor review** (each in its own tab or window
+in [herdr](https://herdr.dev) or tmux, or in the background), and hands the issue back *In Review* with a summary in
+Plane. Merge, PR and deploy stay with you.
 
 What orq does **not** decide for you: which agents you have, how much each may spend and how you like to work. All of
 that lives in your config.
@@ -19,17 +20,18 @@ that lives in your config.
 ## How it works
 
 ```
-You ── "/issue DEMO-123" ──► conductor (Claude in herdr)
-                                │  orq-pick impl ──► which agent/model implements (config + history + quota)
-                                ├─► implementer   herdr-agent  own tab · worktree from origin/<base> · memory cap
-                                ├─► tests         herdr-verify  only the diff's tests · queue of one suite at a time
-                                │  orq-pick review ─► a reviewer from ANOTHER vendor
-                                ├─► reviewer      herdr-agent -r  read only · diff + criteria + test results attached
+You ── "/issue DEMO-123" ──► conductor (Claude, in any terminal)
+                                │  orq pick impl ──► which agent/model implements (config + history + quota)
+                                ├─► implementer   orq agent  own tab/window or background · worktree from origin/<base> · memory cap
+                                ├─► tests         orq verify  only the diff's tests · queue of one suite at a time
+                                │  orq pick review ─► a reviewer from ANOTHER vendor
+                                ├─► reviewer      orq agent -r  read only · diff + criteria + test results attached
                                 └─► Plane         comment, state, labels
-                                ◄── "[HERDR-AGENT DONE] ..." in the conductor's pane (the only completion signal)
+                                ◄── "[HERDR-AGENT DONE] ..." typed into the conductor's herdr pane, or `orq wait` printing "[ORQ AGENT DONE] ..."
 ```
 
-- **Every step in a herdr tab.** You watch it live and the tab closes when it's done. Results stay in
+- **Every step in its own tab or window.** In herdr or tmux you watch it live and the tab closes when it's done;
+  without them the step runs in the background (`orq board` shows it). Results stay in
   `.orquestra/<ID>/` (`.out.md`, `.log`, `.done`).
 - **Fixed order every round:** implementer ok → tests with no new failure → review. Only a `[blocker]` with
   `file:line` and a concrete failure becomes a fix round; the rest goes into the Plane comment (configurable maximum).
@@ -37,7 +39,7 @@ You ── "/issue DEMO-123" ──► conductor (Claude in herdr)
   one level up), fixes only the listed blockers with a test each, and the next review, by the same reviewer, checks
   those blockers and the fix's own diff instead of starting over. The implementer ends with a `## Decisions` section, so
   a deliberate choice doesn't come back as a blocker.
-- **Nobody picks an agent by gut feeling.** `orq-pick` decides from data: what each agent delivered in the history,
+- **Nobody picks an agent by gut feeling.** `orq pick` decides from data: what each agent delivered in the history,
   how many tokens it spent, how long it took, the current quota, and a rotation so no agent gets all the work.
 - **The machine stays up.** Each agent runs under its own memory cap; tests wait in a queue.
 
@@ -146,13 +148,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]
@@ -188,13 +190,12 @@ orq pick fix --same .orquestra/<ID>/impl-<repo>.pick   # a fix round: the implem
 ```
 
 ### Language and theme
-orq speaks English and Portuguese: CLI messages, `herdr-board`, notices and `install.sh`. It follows
+orq speaks English and Portuguese: CLI messages, `orq board`, notices and `install.sh`. It follows
 `[ui] lang` in your config (`"auto"` = system locale, `"en"`, `"pt"`), or the `ORQ_LANG` environment variable.
 Switch it any time:
 - `orq-lang pt` / `orq-lang en` / `orq-lang toggle` (`orq-lang` alone shows the current one);
 - `l` inside `orq board`;
-- a herdr key: `install.sh` links the `orq` herdr plugin; bind its `orq.lang-toggle` action (snippet in
-  `herdr-plugin/herdr-plugin.toml`) — e.g. `prefix+shift+l` — and `orq.board` to open the board as an overlay.
+- in herdr, a key for it: see [With herdr](#with-herdr).
 
 `orq board` has its own look, from the [SYNTH.DECK](https://github.com/irythill/synth-deck-portfolio)
 portfolio: `[ui] theme = "gunmetal"` (default, dark graphite), `"chrome"` (light silver), `"lcd"` (phosphor green) or
@@ -205,26 +206,49 @@ Whatever is already running keeps its language. Conductors always talk to you in
 
 ## Daily use
 
+Open the conductor in any terminal, in your workspace folder (the one `orq setup` prepared):
 ```bash
-herdr                                    # opens the window (the server runs as a service)
-cd ~/Code/<workspace> && herdr-conductor # inside a herdr pane: opens the conductor (account and model optional)
+cd ~/Code/<workspace> && orq conductor [account] [model]   # any terminal: loads the conductor instructions, the workspace CLAUDE.md and the /issue skill
 ```
-In the conductor: **`/issue DEMO-123`**. It answers in one line and moves on by itself at every `[HERDR-AGENT DONE]`.
+With several conductors, give each a fixed name (`export ORQ_CONDUCTOR_ID=<name>`) so `orq claim` can tell them apart.
+Variants:
+- **herdr:** run `herdr` (the server runs as a service), then the same `orq conductor` in a pane (`herdr-conductor` still works).
+- **tmux:** run `orq conductor` in a pane; children open as tmux windows.
+- **Neither:** children run in the background and the conductor waits with `orq wait`.
+
+In the conductor: **`/issue DEMO-123`**. It answers in one line and moves on by itself at every completion signal
+(`[HERDR-AGENT DONE]` in a herdr pane, otherwise the `[ORQ AGENT DONE]` line printed by `orq wait`).
 You only come back when it asks for a decision or says it's done.
 
 To see everything at once, keep **`orq board`** open in a tab or window (any terminal, any OS; `herdr-board` calls it):
 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.
-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
-CI column it does not just read the cache); a run turning red or green also pops a herdr notification, and a
-failure pings the owning conductor once per commit. After merges, `orq gc` lists and removes the issue worktrees
-left behind.
-
-Several issues at once: one conductor per issue (ideally on different accounts). `herdr-claim` keeps two conductors
-off the same issue. Details, shortcuts and scenarios: [docs/herdr.md](docs/herdr.md).
+CI/CD per claimed issue, blocks and the 7-day scoreboard. `--once` prints it once, `--json` for scripts.
+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 `✗` title on the conductor's pane (herdr) 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).
+`orq quota --line` prints quota in one line for any status 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 CI column it does not just read the cache); a failure pings the owning conductor once per commit. After
+merges, `orq gc` lists and removes the issue worktrees left behind.
+
+Several issues at once: one conductor per issue (ideally on different accounts). `orq claim` (`herdr-claim`) keeps two
+conductors off the same issue.
+
+## With herdr
+
+herdr is optional, but it gives orq the most polish: children in their own tabs, notices typed into the conductor's
+pane, and a few extras:
+- `orq conductor` (or `herdr-conductor`) in a herdr pane also names the pane "conductor".
+- `ui.toast.delivery = "system"` in herdr's config makes each finished step pop up a native OS notification; failures
+  also get a herdr notification with sound, and a CI run turning red or green pops one too.
+- `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)).
+- A key for the language: `install.sh` links the `orq` herdr plugin; bind its `orq.lang-toggle` action (snippet in
+  `herdr-plugin/herdr-plugin.toml`) — e.g. `prefix+shift+l` — and `orq.board` to open the board as an overlay.
+
+Day to day, shortcuts and several issues at once: [docs/herdr.md](docs/herdr.md).
 
 ## Skills
 
@@ -240,18 +264,19 @@ off the same issue. Details, shortcuts and scenarios: [docs/herdr.md](docs/herdr
 
 | Command | What it does |
 |---|---|
-| `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 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; a finished screen closes after `[machine] tui_idle_close_min` minutes without a follow-up, default 30, `0` = never) |
 | `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 |
-| `herdr-conductor` | Opens the conductor in the current pane |
-| `herdr-claim` | Owner of each issue among conductors |
-| `herdr-deps` | Links the worktree's dependencies to the main repo's (no reinstall) |
+| `orq conductor [account] [model] [-r <id>]` (`herdr-conductor`) | Opens the conductor (Claude) in the current terminal with its instructions, account and model; `-r` resumes a session |
+| `orq claim` (`herdr-claim`) | Owner of each issue among conductors |
+| `orq deps` (`herdr-deps`) | Links the worktree's dependencies to the main repo's (no reinstall) |
 | `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

@@ -2,11 +2,12 @@
 
 <p align="center"><img src="docs/img/orq-logo.svg" alt="orq — um orc de fraque erguendo a batuta de maestro" width="304"></p>
 
-# orq — orquestrando agentes de código com o herdr
+# orq — orquestrando agentes de código
 
 Você descreve o trabalho numa issue do Plane. Um **conductor** (Claude, de preferência Opus) lê a issue, escolhe o
-agente certo para cada etapa, despacha o **implementador**, os **testes** e uma **review cross-vendor** em abas do
-[herdr](https://herdr.dev), e devolve a issue *In Review* com um resumo no Plane. Merge, PR e deploy continuam com você.
+agente certo para cada etapa, despacha o **implementador**, os **testes** e uma **review cross-vendor** (cada um
+em sua própria aba ou janela no [herdr](https://herdr.dev) ou no tmux, ou em segundo plano), e devolve a issue
+*In Review* com um resumo no Plane. Merge, PR e deploy continuam com você.
 
 O que o orq **não** decide por você: quais agentes você tem, quanto cada um pode gastar e como você gosta de
 trabalhar. Tudo isso fica na sua config.
@@ -19,17 +20,18 @@ trabalhar. Tudo isso fica na sua config.
 ## Como funciona
 
 ```
-You ── "/issue DEMO-123" ──► conductor (Claude in herdr)
-                                │  orq-pick impl ──► which agent/model implements (config + history + quota)
-                                ├─► implementer   herdr-agent  own tab · worktree from origin/<base> · memory cap
-                                ├─► tests         herdr-verify  only the diff's tests · queue of one suite at a time
-                                │  orq-pick review ─► a reviewer from ANOTHER vendor
-                                ├─► reviewer      herdr-agent -r  read only · diff + criteria + test results attached
+You ── "/issue DEMO-123" ──► conductor (Claude, in any terminal)
+                                │  orq pick impl ──► which agent/model implements (config + history + quota)
+                                ├─► implementer   orq agent  own tab/window or background · worktree from origin/<base> · memory cap
+                                ├─► tests         orq verify  only the diff's tests · queue of one suite at a time
+                                │  orq pick review ─► a reviewer from ANOTHER vendor
+                                ├─► reviewer      orq agent -r  read only · diff + criteria + test results attached
                                 └─► Plane         comment, state, labels
-                                ◄── "[HERDR-AGENT DONE] ..." in the conductor's pane (the only completion signal)
+                                ◄── "[HERDR-AGENT DONE] ..." typed into the conductor's herdr pane, or `orq wait` printing "[ORQ AGENT DONE] ..."
 ```
 
-- **Cada etapa numa aba do herdr.** Você acompanha ao vivo e a aba fecha quando termina. Os resultados ficam em
+- **Cada etapa na sua própria aba ou janela.** No herdr ou no tmux você acompanha ao vivo e a aba fecha quando
+  termina; sem eles a etapa roda em segundo plano (o `orq board` mostra). Os resultados ficam em
   `.orquestra/<ID>/` (`.out.md`, `.log`, `.done`).
 - **Ordem fixa em toda rodada:** implementador ok → testes sem falha nova → review. Só um `[blocker]` com
   `arquivo:linha` e uma falha concreta vira rodada de correção; o resto vai para o comentário no Plane (com máximo
@@ -181,13 +183,12 @@ orq pick fix --same .orquestra/<ID>/impl-<repo>.pick   # a fix round: the implem
 ```
 
 ### Idioma e tema
-O orq fala inglês e português: mensagens da CLI, `herdr-board`, avisos e `install.sh`. Ele segue `[ui] lang` na sua
+O orq fala inglês e português: mensagens da CLI, `orq board`, avisos e `install.sh`. Ele segue `[ui] lang` na sua
 config (`"auto"` = idioma do sistema, `"en"`, `"pt"`) ou a variável de ambiente `ORQ_LANG`. Para trocar a qualquer
 momento:
 - `orq-lang pt` / `orq-lang en` / `orq-lang toggle` (`orq-lang` sozinho mostra o atual);
 - a tecla `l` dentro do `orq board`;
-- uma tecla no herdr: o `install.sh` liga o plugin `orq` do herdr; associe a ação `orq.lang-toggle` (trecho pronto em
-  `herdr-plugin/herdr-plugin.toml`) — por exemplo, `prefix+shift+l` — e a `orq.board` para abrir o painel por cima.
+- no herdr, uma tecla para isso: veja [Com o herdr](#com-o-herdr).
 
 O `orq board` tem visual próprio, inspirado no portfólio [SYNTH.DECK](https://github.com/irythill/synth-deck-portfolio):
 `[ui] theme = "gunmetal"` (padrão, grafite escuro), `"chrome"` (prata claro), `"lcd"` (verde fósforo) ou `"terminal"`
@@ -197,27 +198,51 @@ O que já está rodando continua no idioma em que começou. Os conductors sempre
 
 ## Uso diário
 
+Abra o conductor em qualquer terminal, na pasta do seu workspace (a que o `orq setup` preparou):
 ```bash
-herdr                                    # abre a janela (o servidor roda como serviço)
-cd ~/Code/<workspace> && herdr-conductor # dentro de um pane do herdr: abre o conductor (conta e modelo opcionais)
+cd ~/Code/<workspace> && orq conductor [conta] [modelo]   # qualquer terminal: carrega as instruções do conductor, o CLAUDE.md do workspace e a skill /issue
 ```
-No conductor: **`/issue DEMO-123`**. Ele responde numa linha e segue sozinho a cada `[HERDR-AGENT DONE]`. Você só volta
+Com vários conductors, dê a cada um um nome fixo (`export ORQ_CONDUCTOR_ID=<nome>`) para o `orq claim` distingui-los.
+Variantes:
+- **herdr:** rode `herdr` (o servidor roda como serviço) e, num pane, o mesmo `orq conductor` (o `herdr-conductor` continua funcionando).
+- **tmux:** rode `orq conductor` num pane; os filhos abrem como janelas do tmux.
+- **Nenhum dos dois:** os filhos rodam em segundo plano e o conductor espera com `orq wait`.
+
+No conductor: **`/issue DEMO-123`**. Ele responde numa linha e segue sozinho a cada sinal de conclusão
+(`[HERDR-AGENT DONE]` num pane do herdr; fora dele, a linha `[ORQ AGENT DONE]` impressa pelo `orq wait`). Você só volta
 quando ele pede uma decisão ou avisa que terminou.
 
 Para ver tudo de uma vez, deixe o **`orq board`** aberto numa aba ou janela (qualquer terminal, qualquer SO; o
 `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
-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
-cache); quando um deles vira verde ou vermelho sai uma notificação do herdr, e uma falha também avisa o conductor
-dono num aviso só por commit. Depois dos merges, o `orq gc` lista e remove as worktrees de issues que ficaram para
-trás.
-
-Várias issues ao mesmo tempo: um conductor por issue (de preferência em contas diferentes). O `herdr-claim` impede que
-dois conductors peguem a mesma issue. Detalhes, atalhos e cenários: [docs/pt-BR/herdr.md](docs/pt-BR/herdr.md).
+vez, `--json` para scripts.
+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 um título `✗` no pane do
+conductor (herdr) 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).
+O `orq quota --line` imprime a cota numa linha para qualquer barra de status. 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 cache); uma falha também avisa o conductor dono num
+aviso só por commit. Depois dos merges, o `orq gc` lista e remove as worktrees de issues que ficaram para trás.
+
+Várias issues ao mesmo tempo: um conductor por issue (de preferência em contas diferentes). O `orq claim`
+(`herdr-claim`) impede que dois conductors peguem a mesma issue.
+
+## Com o herdr
+
+O herdr é opcional, mas é com ele que o orq fica mais redondo: filhos em abas próprias, avisos digitados no pane do
+conductor e alguns extras:
+- `orq conductor` (ou `herdr-conductor`) num pane do herdr também dá o nome "conductor" ao pane.
+- `ui.toast.delivery = "system"` na config do herdr faz cada etapa concluída gerar uma notificação nativa do sistema;
+  falhas também geram uma notificação do herdr com som, e um CI que fica verde ou vermelho também gera uma.
+- 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)).
+- Uma tecla para o idioma: o `install.sh` liga o plugin `orq` do herdr; associe a ação `orq.lang-toggle` (trecho pronto
+  em `herdr-plugin/herdr-plugin.toml`) — por exemplo, `prefix+shift+l` — e a `orq.board` para abrir o painel por cima.
+
+Dia a dia, atalhos e várias issues ao mesmo tempo: [docs/pt-BR/herdr.md](docs/pt-BR/herdr.md).
 
 ## Skills
 
@@ -233,18 +258,19 @@ dois conductors peguem a mesma issue. Detalhes, atalhos e cenários: [docs/pt-BR
 
 | Comando | O que faz |
 |---|---|
-| `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 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; a tela que terminou fecha após `[machine] tui_idle_close_min` minutos sem follow-up, padrão 30, `0` = nunca) |
 | `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 |
-| `herdr-conductor` | Abre o conductor no pane atual |
-| `herdr-claim` | Dono de cada issue entre os conductors |
-| `herdr-deps` | Liga as dependências do worktree às do repo principal (sem reinstalar) |
+| `orq conductor [conta] [modelo] [-r <id>]` (`herdr-conductor`) | Abre o conductor (Claude) no terminal atual com as instruções, conta e modelo; `-r` retoma uma sessão |
+| `orq claim` (`herdr-claim`) | Dono de cada issue entre os conductors |
+| `orq deps` (`herdr-deps`) | Liga as dependências do worktree às do repo principal (sem reinstalar) |
 | `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}";
@@ -43,8 +47,8 @@ export const BUILTIN_AGENTS = {
         turn_hook: "opencode",
     },
     antigravity: {
-        // --sandbox + accept-edits (no skip-permissions); headless denies commands outside agy's allowlist, so in practice
-        // it reviews. The prompt goes in a file in its folder (excluded from git) and -p only says "read it".
+        // --sandbox + accept-edits (no skip-permissions); headless denies commands outside agy's allowlist (see agy-impl.json);
+        // a run that only had commands denied still counts when the worktree changed (see the antigravity format). The prompt goes in a file in its folder (excluded from git) and -p only says "read it".
         run: `${AGY} {mode} -p {prompt_hint}`, resume: `${AGY} --conversation {session} {mode} -p {prompt_hint}`,
         readonly: "--mode plan", write: "--mode accept-edits --add-dir {gitdir}",
         format: "antigravity", throwaway: true, prompt_in_dir: true,
@@ -202,13 +206,63 @@ export const FORMATS = {
             return s.step_type === "tool" && s.state === "DONE" ? "\n· tool\n" : undefined;
         },
         finish(log) {
-            const res = jsonLines(log).filter((j) => j.event === "result").map((j) => j.result ?? {});
+            const evs = jsonLines(log);
+            const res = evs.filter((j) => j.event === "result").map((j) => j.result ?? {});
             let answer = lastOf(res.map((r) => String(r.response ?? ""))) ?? "";
-            // An agy error (e.g. a denied command) is a failure, even with an answer.
             const errs = log.split(/\r?\n/).filter((l) => l.startsWith("jetski: "));
+            // Denied commands: ERROR steps with the command line, plus denied_actions on the result.
+            const denied = [];
+            let text = "", textId, lastCmd = "", sawResult = false; // lastCmd: last CommandLine streamed before the result
+            const hinted = res.some((r) => Array.isArray(r.denied_actions) && r.denied_actions.length) || errs.some((l) => /permission/.test(l));
+            for (const e of evs) {
+                if (e.event === "result")
+                    sawResult = true;
+                const s = e.event === "step_update" ? e.step_update : undefined;
+                if (!s)
+                    continue;
+                const seen = (s.tool_info ?? e.tool_info)?.parameters?.CommandLine;
+                if (!sawResult && typeof seen === "string" && seen.trim())
+                    lastCmd = seen.trim();
+                if (s.step_type === "agent_response") {
+                    const id = s.step_id ?? s.step_index ?? s.id;
+                    if (id !== textId) {
+                        textId = id;
+                        if (s.text_delta)
+                            text = "";
+                    }
+                    text += String(s.text_delta ?? "");
+                }
+                if (s.state === "ERROR") {
+                    const ti = s.tool_info ?? e.tool_info, cmd = ti?.parameters?.CommandLine, msg = String(s.error?.message ?? "");
+                    if (/permission check failed|not allowed|denied/i.test(msg) || (cmd && !msg && hinted)) {
+                        const d = `${cmd ? `\`${cmd}\`` : "(command)"}${msg ? ` — ${msg}` : ""}`;
+                        if (!denied.includes(d))
+                            denied.push(d);
+                    }
+                }
+            }
+            const acts = res.flatMap((r) => (Array.isArray(r.denied_actions) ? r.denied_actions : []));
+            const wasDenied = denied.length > 0 || acts.length > 0 || errs.some((l) => /permission/.test(l));
+            // denied_actions only says "RunCommand": the command is the last one the stream showed before the result.
+            if (!denied.length && lastCmd && acts.length && acts.every((a) => a.display_name === "RunCommand"))
+                denied.push(`denied: ${lastCmd}`);
+            if (wasDenied && !answer.trim())
+                answer = text.trim();
+            if (wasDenied) {
+                answer += `${answer ? "\n\n" : ""}## Denied commands\n` +
+                    "agy denied commands outside its allowlist (headless, nobody to approve). Retry with a different command, or add a glob rule such as command(/usr/bin/*) to agy's allowlist (~/.config/orq/agy-impl.json, see examples/agy-impl.json) -- usually that is the fix.\n" +
+                    (denied.length ? denied.map((d) => `- ${d}`).join("\n") : acts.map((a) => `- ${a.action ?? "command"} (${a.display_name ?? "?"})`).join("\n")) + "\n";
+            }
             if (errs.length)
                 answer += (answer ? "\n" : "") + errs.join("\n") + "\n";
-            return { session: lastOf(res.map((r) => r.conversation_id).filter(Boolean)), answer, rc: errs.length ? 3 : undefined };
+            return { session: lastOf(res.map((r) => r.conversation_id).filter(Boolean)), answer, rc: errs.length || wasDenied ? 3 : undefined,
+                denied: wasDenied ? (denied.length ? denied : ["(command)"]) : undefined };
         },
     },
 };
+/** 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

@@ -11,6 +11,7 @@ import { block, USAGE as BLOCK } from "./commands/block.js";
 import { claim, USAGE as CLAIM } from "./commands/claim.js";
 import { ci, USAGE as CI } from "./commands/ci.js";
 import { completion, USAGE as COMPLETION } from "./commands/completion.js";
+import { conductor, USAGE as CONDUCTOR } from "./commands/conductor.js";
 import { config, USAGE as CONFIG } from "./commands/config.js";
 import { deps, USAGE as DEPS } from "./commands/deps.js";
 import { gc, USAGE as GC } from "./commands/gc.js";
@@ -18,6 +19,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 +29,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, conductor, 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 +50,8 @@ ${HANDOFF}
 ${VERIFY}
 ${BASELINE}
 ${INSTRUCTIONS}
+${NOTICE}
+${CONDUCTOR}
 ${CLAIM}
 ${DEPS}
 ${GC}