@irythill/orq 0.3.0 → 0.5.0

package/README.md

@@ -31,8 +31,12 @@ You ── "/issue DEMO-123" ──► conductor (Claude in herdr)
 
 - **Every step in a herdr tab.** You watch it live and the tab closes when it's done. Results stay in
   `.orquestra/<ID>/` (`.out.md`, `.log`, `.done`).
-- **Fixed order every round:** implementer ok → tests with no new failure → review. A blocking problem becomes a fix
-  round in the implementer's own session (configurable maximum).
+- **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).
+- **Fix rounds converge.** A fix continues the implementer's session on the same model (`orq pick fix --same`, effort
+  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,
   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.
@@ -42,8 +46,8 @@ You ── "/issue DEMO-123" ──► conductor (Claude in herdr)
 | Agent | CLI | Possible roles | Notes |
 |---|---|---|---|
 | Claude Code | `claude` | conductor, implement, review | several accounts (`claude-accounts`); Opus as conductor |
-| Codex | `codex` | implement, review | sandbox without network: the conductor runs `git fetch` |
-| OpenCode | `opencode` | implement, review | any provider (e.g. MiniMax) |
+| Codex | `codex` | implement, review | sandbox without network: the conductor runs `git fetch`; quota from its session files (the free plan's 30-day window included) |
+| OpenCode | `opencode` | implement, review | any provider (e.g. MiniMax); on MiniMax, quota from the Token Plan API with your key |
 | Antigravity | `agy` | review | headless denies commands outside its allowlist: it reviews by reading the attached diff |
 | GitHub Copilot | `copilot` | second opinion | small allowances on some plans: occasional use |
 
@@ -105,7 +109,7 @@ your config.
 | Flag | What it does |
 |---|---|
 | `--dry-run` | print what it would do, change nothing |
-| `--uninstall` | remove only the links it creates, and only those pointing into this repo (config and history stay) |
+| `--uninstall` | remove only the links it creates, and only those pointing into this repo, and disable the orq systemd user timers (`systemctl --user disable --now`); config and history stay |
 
 ## Configuration
 
@@ -128,8 +132,13 @@ vendor = "openai"
 roles  = ["impl", "fix", "review"]
 quota  = ["codex"]                       # name in agent-quota's output
 [agents.codex.models.impl]
-simple = "gpt-6-sol@low"                 # model@effort
-heavy  = "gpt-6.1-sol@medium"
+simple = "gpt-6-sol@low"                 # model@effort, per issue level
+medium = "gpt-6-sol@medium"
+heavy  = "gpt-6.1-sol@high"
+[agents.codex.models.review]
+simple  = "gpt-6-sol@low"                # reviews scale with the issue too
+default = "gpt-6-sol@medium"
+heavy   = "gpt-6-sol@high"
 
 [agents.opencode]
 vendor = "minimax"
@@ -137,8 +146,25 @@ roles  = ["review"]                      # here it only reviews; for someone els
 [agents.opencode.models.review]
 default = "minimax/MiniMax-M3"
 
+[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     = "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 = "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]
+handoff_at = 85                          # % of the window → orq handoff moves the conductor to another account
+max_per_account = 2                      # an account already holding this many conductors is never a handoff target
+reset_grace_min = 15                     # every window over the trigger resetting within this many minutes skips the move
+
 [policy]
-quota_limit = 90                         # ≥ 90% used → agent out
+quota_week = 95                          # ≥ 95% of the week → agent out
+quota_5h = { simple = 90, medium = 85, heavy = 80 }  # same for the 5h window, by task level
+pacing_penalty = 0.3                     # score penalty when usage at the current pace would pass the pick limit (5h by level, week: quota_week) by the reset (0 = off)
+# [agents.claude] headroom = 25          # points kept for conductors: children leave the account at limit − 25
 [policy.weights]
 quality  = 0.40                          # did it deliver? (impl: approved on the first review)
 tokens   = 0.45                          # did it spend little?
@@ -148,7 +174,8 @@ rotation = 0.20                          # penalty for having been picked recent
 
 ### How `orq-pick` chooses
 1. **Filters:** only agents with that role, under the quota limit, not blocked (`orq-block`) and, for reviews, from a
-   vendor other than the implementer's. With several accounts, it takes the least used one.
+   vendor other than the implementer's. With several accounts, it prefers one whose pace stays within the limit, then
+   the least used.
 2. **Scores:** `quality × delivery + tokens × economy + speed × quickness − rotation × recent picks`. The numbers come
    from the history (`orq-stats`); an agent with few runs uses the config's `prior` and gets an exploration bonus.
 3. **`reserve = true` agents** (e.g. Claude, which shares quota with the conductor) only come in when nothing else fits.
@@ -157,6 +184,7 @@ rotation = 0.20                          # penalty for having been picked recent
 orq-pick review --impl-agent codex --explain     # every candidate's score and who was left out, and why
 orq-stats --days 30                              # scoreboard: delivery, approval, time and tokens per agent and model
 orq-block antigravity --days 3                   # out of the picks (e.g. weekly quota gone, no collector for it)
+orq pick fix --same .orquestra/<ID>/impl-<repo>.pick   # a fix round: the implementer's agent/model/account, effort +1
 ```
 
 ### Language and theme
@@ -186,8 +214,20 @@ 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,
-blocks and the 7-day scoreboard. `--once` prints it once, `--json` for scripts. With
+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
+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).
@@ -208,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 |
@@ -215,7 +256,10 @@ off the same issue. Details, shortcuts and scenarios: [docs/herdr.md](docs/herdr
 | `herdr-claim` | Owner of each issue among conductors |
 | `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]` | Lists issue worktrees that are safe to remove; `--yes` removes them |
+| `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] [--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) |
 | `orq <config\|set\|lang\|block\|quota>` | The cross-platform CLI (TypeScript); the `orq-*` and `agent-quota` names below call it |

package/README.pt-BR.md

@@ -31,8 +31,13 @@ You ── "/issue DEMO-123" ──► conductor (Claude in herdr)
 
 - **Cada etapa numa aba do herdr.** Você acompanha ao vivo e a aba fecha quando termina. Os resultados ficam em
   `.orquestra/<ID>/` (`.out.md`, `.log`, `.done`).
-- **Ordem fixa em toda rodada:** implementador ok → testes sem falha nova → review. Um problema bloqueante vira uma
-  rodada de correção na própria sessão do implementador (com máximo configurável).
+- **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
+  configurável).
+- **As rodadas convergem.** O fix continua a sessão do implementador no mesmo modelo (`orq pick fix --same`, esforço
+  um nível acima), corrige só os blockers listados, com um teste para cada, e o review seguinte, do mesmo reviewer,
+  confere esses blockers e o diff do próprio fix em vez de recomeçar. O implementador termina com uma seção
+  `## Decisions`, para que uma escolha proposital não volte como blocker.
 - **Ninguém escolhe agente no feeling.** O `orq-pick` decide com base em dados: o que cada agente entregou no
   histórico, quantos tokens gastou, quanto tempo levou, a quota atual e um rodízio para nenhum agente ficar com todo o
   trabalho.
@@ -43,8 +48,8 @@ You ── "/issue DEMO-123" ──► conductor (Claude in herdr)
 | Agente | CLI | Papéis possíveis | Observações |
 |---|---|---|---|
 | Claude Code | `claude` | conductor, implement, review | várias contas (`claude-accounts`); Opus como conductor |
-| Codex | `codex` | implement, review | sandbox sem rede: o conductor roda o `git fetch` |
-| OpenCode | `opencode` | implement, review | qualquer provider (ex.: MiniMax) |
+| Codex | `codex` | implement, review | sandbox sem rede: o conductor roda o `git fetch`; cota lida dos arquivos de sessão (inclusive a janela de 30 dias do plano free) |
+| OpenCode | `opencode` | implement, review | qualquer provider (ex.: MiniMax); na MiniMax, cota pela API do Token Plan com a sua chave |
 | Antigravity | `agy` | review | em modo headless nega comandos fora da allowlist: faz a review lendo o diff anexado |
 | GitHub Copilot | `copilot` | segunda opinião | cota pequena em alguns planos: uso ocasional |
 
@@ -130,8 +135,13 @@ vendor = "openai"
 roles  = ["impl", "fix", "review"]
 quota  = ["codex"]                       # name in agent-quota's output
 [agents.codex.models.impl]
-simple = "gpt-6-sol@low"                 # model@effort
-heavy  = "gpt-6.1-sol@medium"
+simple = "gpt-6-sol@low"                 # model@effort, per issue level
+medium = "gpt-6-sol@medium"
+heavy  = "gpt-6.1-sol@high"
+[agents.codex.models.review]
+simple  = "gpt-6-sol@low"                # reviews scale with the issue too
+default = "gpt-6-sol@medium"
+heavy   = "gpt-6-sol@high"
 
 [agents.opencode]
 vendor = "minimax"
@@ -139,8 +149,15 @@ roles  = ["review"]                      # here it only reviews; for someone els
 [agents.opencode.models.review]
 default = "minimax/MiniMax-M3"
 
+[conductor]
+handoff_at = 85                          # % da janela → o orq handoff move o conductor para outra conta
+max_per_account = 2                      # conta que já tem esse tanto de conductors nunca é alvo do handoff
+reset_grace_min = 15                     # toda janela acima do gatilho renova dentro desses minutos → pula a mudança
+
 [policy]
-quota_limit = 90                         # ≥ 90% used → agent out
+quota_limit = 90                         # caps the 5h pick limit; also sets ! in `orq quota --line`
+pacing_penalty = 0.3                     # score penalty when usage at the current pace would pass the pick limit (5h by level, week: quota_week) by the reset (0 = off)
+# [agents.claude] headroom = 25          # points kept for conductors: children leave the account at limit − 25
 [policy.weights]
 quality  = 0.40                          # did it deliver? (impl: approved on the first review)
 tokens   = 0.45                          # did it spend little?
@@ -150,7 +167,8 @@ rotation = 0.20                          # penalty for having been picked recent
 
 ### Como o `orq-pick` escolhe
 1. **Filtros:** só agentes com aquele papel, abaixo do limite de quota, não bloqueados (`orq-block`) e, para reviews,
-   de um vendor diferente do implementador. Com várias contas, pega a menos usada.
+   de um vendor diferente do implementador. Com várias contas, prefere uma cujo ritmo fique dentro do limite e, como
+   desempate, a menos usada.
 2. **Pontuação:** `quality × delivery + tokens × economy + speed × quickness − rotation × recent picks`. Os números vêm
    do histórico (`orq-stats`); um agente com poucas execuções usa o `prior` da config e ganha um bônus de exploração.
 3. **Agentes com `reserve = true`** (ex.: Claude, que divide quota com o conductor) só entram quando nada mais serve.
@@ -159,6 +177,7 @@ rotation = 0.20                          # penalty for having been picked recent
 orq-pick review --impl-agent codex --explain     # every candidate's score and who was left out, and why
 orq-stats --days 30                              # scoreboard: delivery, approval, time and tokens per agent and model
 orq-block antigravity --days 3                   # out of the picks (e.g. weekly quota gone, no collector for it)
+orq pick fix --same .orquestra/<ID>/impl-<repo>.pick   # a fix round: the implementer's agent/model/account, effort +1
 ```
 
 ### Idioma e tema
@@ -187,8 +206,21 @@ 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, 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.
+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. 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
+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).
@@ -209,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 |
@@ -216,7 +249,10 @@ dois conductors peguem a mesma issue. Detalhes, atalhos e cenários: [docs/pt-BR
 | `herdr-claim` | Dono de cada issue entre os conductors |
 | `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]` | Lista worktrees de issues seguras para remover; `--yes` as remove |
+| `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] [--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) |
 | `orq <config\|set\|lang\|block\|quota>` | O CLI multiplataforma (TypeScript); os nomes `orq-*` e `agent-quota` abaixo chamam ele |

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

@@ -0,0 +1,241 @@
+// CI/CD signal per claimed issue, for `orq ci` and the board's CI column: for each issue with a live owner
+// (.orquestra/<ID>/owner, as orq claim keeps it), the branch its worktree carries (as orq gc matches it:
+// <repo>-plane-<id-lower> under .worktrees) and that branch's PR checks via `gh pr view`, aggregated into
+// queued | running | passed | failed | none. Cached in the state dir (board/ci.json), like quota — orq board
+// never blocks on `gh`; a stale cache starts a background collection the same way quota does. `orq ci` itself is
+// the exception: it is the user explicitly asking for CI status right now, so it runs collectCi() in the
+// foreground (network and all) and prints the result — only `orq board` reads the cache.
+// On a transition to passed or failed: a herdr desktop notification; on failed, one line to the owning
+// conductor via testrun.ts's notify(), tracked by `${state}:${head SHA}` in the cache so a repeat collection of
+// the same commit never repeats it, but a new commit that is still red does.
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { aliveOwner } from "./commands/claim.js";
+import { writeAtomic } from "./fsutil.js";
+import { m } from "./i18n.js";
+import { alive } from "./lock.js";
+import { stateDir } from "./paths.js";
+import { notify } from "./testrun.js";
+const git = (cwd, ...args) => spawnSync("git", ["-C", cwd, ...args], { encoding: "utf8" });
+const output = (cwd, ...args) => { const r = git(cwd, ...args); return r.status === 0 ? r.stdout.trim() : undefined; };
+// ORQ_GH may be a .js file (tests: a fake gh that also runs on Windows), as orq gc already does it.
+const gh = (cwd, args) => {
+    const bin = process.env.ORQ_GH || "gh";
+    return bin.endsWith(".js") ? spawnSync(process.execPath, [bin, ...args], { cwd, encoding: "utf8", timeout: 15_000 })
+        : spawnSync(bin, args, { cwd, encoding: "utf8", timeout: 15_000 });
+};
+export const cacheFile = () => join(stateDir(), "board", "ci.json");
+export function loadCache() {
+    try {
+        return JSON.parse(readFileSync(cacheFile(), "utf8"));
+    }
+    catch {
+        return [];
+    }
+}
+export function saveCache(entries) { writeAtomic(cacheFile(), JSON.stringify(entries, null, 1)); }
+// A per-workspace "collected at" marker, separate from ci.json: collectCi() writes no cache entry for a workspace
+// with no claimed issue that has a matching worktree, so ci.json alone can't tell "never collected" apart from
+// "collected, found nothing" — the board would otherwise relaunch the collector every redraw forever in the
+// latter case. Keyed by a hash of the workspace path since it doubles as a file name.
+const wsKey = (ws) => createHash("sha1").update(ws).digest("hex").slice(0, 16);
+const collectedFile = (ws) => join(stateDir(), "board", "ci", `${wsKey(ws)}.at`);
+export function markCollected(ws, at) { writeAtomic(collectedFile(ws), String(at)); }
+/** When `ws` was last collected (collectCi ran for it, even if it found nothing), else undefined if never. */
+export function collectedAt(ws) {
+    try {
+        const n = Number(readFileSync(collectedFile(ws), "utf8"));
+        return Number.isFinite(n) ? n : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Claimed issues of a workspace with a live owner (as `orq claim -l` lists them), issue id → owner pane + kind
+ *  ("herdr" for a pane herdr-notify can reach, else a plain terminal conductor — see handoff.ts's same check). */
+export function claimedIssues(ws) {
+    const O = join(ws, ".orquestra"), out = [];
+    for (const d of existsSync(O) ? readdirSync(O).filter((x) => !x.startsWith(".")) : []) {
+        const f = join(O, d, "owner");
+        if (!existsSync(f))
+            continue;
+        const t = readFileSync(f, "utf8").trim();
+        if (aliveOwner(t))
+            out.push({ id: d, owner: /pane=(\S+)/.exec(t)?.[1] ?? "", kind: /kind=(\S+)/.exec(t)?.[1] ?? "herdr" });
+    }
+    return out;
+}
+/** Every worktree branch in the workspace's repos, one `git worktree list` per repo — called once per workspace
+ *  per collection (collectCi memoizes it across issues) rather than once per claimed issue. */
+export function listWorktrees(ws) {
+    if (!existsSync(join(ws, ".worktrees")))
+        return [];
+    const out = [];
+    for (const repoName of readdirSync(ws, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)) {
+        const repo = join(ws, repoName);
+        if (!existsSync(join(repo, ".git")))
+            continue;
+        const listings = output(repo, "worktree", "list", "--porcelain");
+        if (!listings)
+            continue;
+        for (const block of listings.split(/\n\n/)) {
+            const rec = Object.fromEntries(block.split("\n").map((line) => {
+                const i = line.indexOf(" ");
+                return [i < 0 ? line : line.slice(0, i), i < 0 ? "" : line.slice(i + 1)];
+            }));
+            const branch = rec.branch?.replace(/^refs\/heads\//, "") ?? "";
+            if (branch)
+                out.push({ repo: repoName, branch });
+        }
+    }
+    return out;
+}
+/** The repo + branch an issue's worktree carries, the same match `orq gc` uses: a worktree branch ending in
+ *  "plane-<id, lowercase>" under <ws>/.worktrees. An issue can have one per repo (several repos in play).
+ *  `all` lets a caller looping over several issues pass its own listWorktrees(ws) once instead of one per issue. */
+export function issueBranches(ws, issue, all = listWorktrees(ws)) {
+    const suffix = `plane-${issue.toLowerCase()}`;
+    return all.filter((b) => b.branch.toLowerCase().endsWith(suffix));
+}
+// GitHub's statusCheckRollup mixes CheckRun (status/conclusion, the GitHub Actions / Checks API shape) with the
+// legacy commit-status shape (StatusContext: just `state`, no status/conclusion at all) for repos whose CI still
+// posts plain commit statuses (Jenkins, CircleCI, old GitLab integrations). Left unmapped, every StatusContext
+// item reads as still-running forever: conclusion is undefined (never "failed"), status is undefined (never
+// "queued"), and `status !== "COMPLETED"` is always true.
+const STATUS_STATE = {
+    SUCCESS: { status: "COMPLETED", conclusion: "SUCCESS" }, FAILURE: { status: "COMPLETED", conclusion: "FAILURE" },
+    ERROR: { status: "COMPLETED", conclusion: "ERROR" }, PENDING: { status: "PENDING" },
+};
+const normalize = (c) => c.__typename === "StatusContext" ? (STATUS_STATE[c.state ?? ""] ?? { status: c.status, conclusion: c.conclusion }) : c;
+/** The worst signal across a PR's checks: any failure beats a pending one, which beats still running, which beats
+ *  all green; no checks at all (none configured, or not registered yet) reads as "none", not a false "passed". */
+export function aggregateChecks(rollup) {
+    if (!rollup.length)
+        return "none";
+    const checks = rollup.map(normalize);
+    if (checks.some((c) => ["FAILURE", "TIMED_OUT", "ACTION_REQUIRED", "STARTUP_FAILURE", "CANCELLED", "ERROR"].includes(c.conclusion ?? "")))
+        return "failed";
+    if (checks.some((c) => c.status === "QUEUED" || c.status === "PENDING" || c.status === "WAITING" || c.status === "REQUESTED"))
+        return "queued";
+    if (checks.some((c) => c.status !== "COMPLETED"))
+        return "running";
+    return "passed";
+}
+/** `gh pr view --json number,headRefOid,statusCheckRollup`'s stdout → the PR's number, head SHA and CI state;
+ *  no PR (empty/garbage JSON, or no "number") reads as "none". Pure: no network, so it needs no fake gh to test. */
+export function parsePrStatus(json) {
+    try {
+        const j = JSON.parse(json);
+        if (!j.number)
+            return { state: "none" };
+        return { pr: j.number, sha: j.headRefOid, state: aggregateChecks(j.statusCheckRollup ?? []) };
+    }
+    catch {
+        return { state: "none" };
+    }
+}
+/** The branch's PR and CI state; no `gh`, no PR, or a `gh` failure all read as "none" — never an error. */
+function prStatus(repo, branch) {
+    const r = gh(repo, ["pr", "view", branch, "--json", "number,headRefOid,statusCheckRollup"]);
+    return r.status === 0 ? parsePrStatus(r.stdout) : { state: "none" };
+}
+// `orq ci -w ws2` (foreground) and the board's detached `orq board --collect-ci` for ws1 can run at the same
+// time; both do a read-modify-write of the single shared ci.json, so without a lock the last one to save erases
+// the other's entries for its own workspace (and can drop a `notified` mark, causing a repeat notification).
+// A short-lived exclusive lock file around just the read-merge-write (never around the `gh`/network calls above
+// it) keeps that atomic; a stale lock (holder process died mid-write) is detected via lock.ts's `alive()` and
+// cleared instead of being waited on forever.
+function withCacheLock(fn) {
+    const dir = join(stateDir(), "board"), lf = join(dir, "ci.lock");
+    mkdirSync(dir, { recursive: true });
+    for (;;) {
+        try {
+            writeFileSync(lf, String(process.pid), { flag: "wx" });
+            break;
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+            try {
+                if (!alive(Number(readFileSync(lf, "utf8").trim() || "0"))) {
+                    rmSync(lf, { force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            } // lock file vanished mid-check: retry the exclusive create
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        rmSync(lf, { force: true });
+    }
+}
+function notifyDesktop(issue, repo, state) {
+    const title = state === "passed" ? m("CI passed", "CI passou") : m("CI failed", "CI falhou");
+    spawnSync("herdr", ["notification", "show", title, "--body", `${issue} ${repo}`], { stdio: "ignore" });
+}
+/**
+ * This workspace's current CI entries, merged into the cache (other workspaces' entries untouched). On a genuine
+ * transition (a known previous sighting, now a different head commit) to passed or failed: a herdr desktop
+ * notification, and on failed one line to the owning conductor — gated by `${state}:${sha}` in `notified`, so a
+ * repeat collection of the same head commit never notifies twice, but a new commit that is still red does (the
+ * mark carries the sha, so it is never redundant with the `prev` gate that skips a first sighting).
+ * The `prev` read, the notify decision and the `notified` mark all happen inside `withCacheLock`, alongside the
+ * save — otherwise a concurrent collector of the same workspace (`orq ci` in the foreground racing the board's
+ * detached collector) reads the same stale `prev`, both decide to notify and whichever saves last overwrites the
+ * other's freshly written `notified` mark, causing a third notification on the next collection.
+ * The notifications themselves fire after the lock is released: they must never hold up another collector's
+ * read-modify-write while they run.
+ * A non-herdr owner (a plain terminal conductor, same check as handoff.ts) has no pane herdr-notify can reach, so
+ * the line goes through `hooks.notice` (console.log by default) instead — never silently dropped, and never a
+ * crash from `herdr agent get` failing. The owner notify is always detached (background=true): collectCi() must
+ * never block on a conductor stuck in a dialog.
+ * `hooks` lets tests swap the notifiers for ones with no side effects, lets `orq ci --json` keep its stdout to
+ * just the JSON, and lets the board's detached collector (stdio: "ignore") persist `notice` to a file instead of
+ * the default console.log, which would otherwise vanish.
+ */
+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)), 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 = [];
+    const mine = withCacheLock(() => {
+        const cache = loadCache(), mine = [];
+        for (const { id, owner, kind, repo, branch, pr, sha, state } of found) {
+            const prev = cache.find((e) => e.ws === ws && e.issue === id && e.repo === repo && e.branch === branch);
+            let notified = prev?.notified;
+            const mark = sha ? `${state}:${sha}` : undefined;
+            if (prev && (state === "passed" || state === "failed") && mark && notified !== mark) {
+                toNotify.push({ owner, kind, id, repo, state, sha: sha });
+                notified = mark;
+            }
+            if (!prev && mark)
+                notified = mark; // first sighting: known, not news
+            mine.push({ ws, issue: id, repo, branch, ...(pr !== undefined ? { pr } : {}), ...(sha ? { sha } : {}), state, ...(notified ? { notified } : {}), at: now });
+        }
+        saveCache([...cache.filter((e) => e.ws !== ws), ...mine]);
+        return mine;
+    });
+    for (const { owner, kind, id, repo, state, sha } of toNotify) {
+        // 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")
+                toOwner(owner, line);
+            else
+                notice(line);
+        }
+    }
+    markCollected(ws, now);
+    return mine;
+}

package/dist/cli.js

@@ -9,22 +9,26 @@ import { board, USAGE as BOARD } from "./commands/board.js";
 import { baseline, USAGE as BASELINE } from "./commands/baseline.js";
 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 { 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";
+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";
 import { run, USAGE as RUN } from "./commands/run.js";
 import { set, USAGE as SET } from "./commands/set.js";
 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, setup, lock, claim, deps, gc, 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]
 
@@ -35,17 +39,21 @@ ${LANG}
 ${QUOTA}
 ${PICK}
 ${STATS}
+${ROUNDS}
 ${BOARD}
 ${LOCK}
 ${RUN}
 ${AGENT}
 ${WAIT}
+${HANDOFF}
 ${VERIFY}
 ${BASELINE}
 ${INSTRUCTIONS}
+${NOTICE}
 ${CLAIM}
 ${DEPS}
 ${GC}
+${CI}
 ${COMPLETION}
 ${BLOCK.split("\n")[0]}
   (orq block --help ${m("for more", "para mais")})`;