@irythill/orq 0.6.1 → 0.8.0

package/README.md

@@ -48,9 +48,9 @@ You ── "/issue DEMO-123" ──► conductor (Claude, in any terminal)
 | 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`; quota from its session files (the free plan's 30-day window included) |
+| Codex | `codex` | implement, review | sandbox without network: orq runs `git fetch` before a write run (`network = false`); 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 |
+| Antigravity | `agy` | review (implement with an allowlist) | headless denies commands outside its allowlist: it reviews by reading the attached diff; it can't commit, so orq commits its write runs (`commit = false`) |
 | GitHub Copilot | `copilot` | second opinion | small allowances on some plans: occasional use |
 
 You declare only the ones you have, and the roles each may take.
@@ -58,7 +58,7 @@ You declare only the ones you have, and the roles each may take.
 ## Install
 
 Linux, macOS or Windows (native, not only WSL), in any shell — bash, zsh, fish, PowerShell, cmd.
-**Requirements:** Node 20+ with `npm`, `git`, and at least one agent from the table above, logged in. Optional:
+**Requirements:** Node 22+ with `npm`, `git`, and at least one agent from the table above, logged in. Optional:
 [herdr](https://herdr.dev) or tmux, so each child gets its own tab or window (otherwise children run in the
 background and `orq board` shows them).
 
@@ -100,7 +100,7 @@ git clone https://github.com/irythill/orq ~/Code/orq && cd ~/Code/orq
 ./install.sh            # links in ~/.local/bin, herdr service, skills for Claude
 ```
 
-Needs `git`, `jq`, Node 20+ with `npm`, `python3` (3.11+ for TOML config; older → JSON config or
+Needs `git`, `jq`, Node 22+ with `npm`, `python3` (3.11+ for TOML config; older → JSON config or
 `pip install --user tomli`) and user `systemd` (WSL2: Ubuntu 22.04+ with systemd enabled). `install.sh` checks the
 requirements (table of what's found and missing), builds the `orq` CLI (`src/` → `dist/`), then **symlinks** (never
 copies) the scripts into `~/.local/bin`, `setup/herdr.service` into `~/.config/systemd/user/` (and enables it), and
@@ -120,10 +120,10 @@ Two layers, to keep **your way of working** apart from **the team's project**:
 | File | Whose | What it holds |
 |---|---|---|
 | `~/.config/orq/config.toml` | yours, stays on your machine | agents, accounts, models per role and level, pick weights, memory limits |
-| `<workspace>/.orq/workspace.toml` 🚧 | the team's, versioned | Plane (projects, issue standard), repos, base branch, verification, tests, dependencies |
+| `<workspace>/.orq/workspace.toml` | the team's, versioned | Plane (projects, issue standard), repos, base branch, verification, tests, dependencies |
 
-The more specific one wins, key by key. JSON works too (`config.json`). To see the merged result: `orq-config`
-(everything), `orq-config get policy.weights`, `orq-config files`.
+The more specific one wins, key by key. JSON works too (`config.json`). To see the merged result: `orq config`
+(everything), `orq config get policy.weights`, `orq config files`.
 
 ### Example: personal config
 Complete, commented example: [`examples/irythill/config.toml`](examples/irythill/config.toml). The essentials:
@@ -135,7 +135,7 @@ roles  = ["impl", "fix", "review"]
 quota  = ["codex"]                       # name in agent-quota's output
 [agents.codex.models.impl]
 simple = "gpt-6-sol@low"                 # model@effort, per issue level
-medium = "gpt-6-sol@medium"
+medium = ["gpt-6-sol@medium", "gpt-6-luna@medium"]  # several: each (agent, model) pair is scored on its own history
 heavy  = "gpt-6.1-sol@high"
 [agents.codex.models.review]
 simple  = "gpt-6-sol@low"                # reviews scale with the issue too
@@ -155,6 +155,9 @@ run     = "revtool --markdown -b {base}"  # {base} = orq agent -b; it reads the
 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
+# commit = false                         # can't git commit: orq commits a write run's changes
+# network = false                        # no network: orq fetches origin before a write run
+# base_commit = false                    # can't review `-b <sha>` (default for a tool): pick skips it on a round delta, agent falls back to the branch base
 # filter = "jq -r '...'"                 # optional: its output → [blocker]/[suggestion] lines
 
 [conductor]
@@ -177,18 +180,19 @@ speed    = 0.15
 rotation = 0.20                          # penalty for having been picked recently
 ```
 
-### 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 prefers one whose pace stays within the limit, then
+### How `orq pick` chooses
+1. **Filters:** only agents with that role whose CLI is on the PATH, under the quota limit, not blocked (`orq block`)
+   and, for reviews, from a vendor other than the implementer's (and, for a round's delta, able to review a commit:
+   `base_commit`). 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.
+   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.
 
 ```bash
-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 review --impl-agent codex --explain     # every candidate's score and who was left out, and why
+orq stats --days 30                              # scoreboard per agent and model: delivery, approval, time (to the first turn), tokens
+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
 ```
 
@@ -196,7 +200,7 @@ orq pick fix --same .orquestra/<ID>/impl-<repo>.pick   # a fix round: the implem
 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);
+- `orq lang pt` / `orq lang en` / `orq lang toggle` (`orq lang` alone shows the current one);
 - `l` inside `orq board`;
 - in herdr, a key for it: see [With herdr](#with-herdr).
 
@@ -213,7 +217,9 @@ Open the conductor in any terminal, in your workspace folder (the one `orq setup
 ```bash
 cd ~/Code/<workspace> && orq conductor [account] [model]   # any terminal: loads the conductor instructions, the workspace CLAUDE.md and the /issue skill
 ```
-With several conductors, give each a fixed name (`export ORQ_CONDUCTOR_ID=<name>`) so `orq claim` can tell them apart.
+With several conductors, give each a fixed name (`export ORQ_CONDUCTOR_ID=<name>`; in herdr, the workspace label is
+used) so `orq claim` can tell them apart: the Claude session is named `conductor-<workspace>:<name>`, and
+`orq claim -l` ends each line with that `session=`, so conductors can message each other.
 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.
@@ -299,6 +305,7 @@ Day to day, shortcuts and several issues at once: [docs/herdr.md](docs/herdr.md)
 - [docs/omarchy.md](docs/omarchy.md) — extras for Omarchy users
 - [docs/portability.md](docs/portability.md) — the roadmap: Linux, macOS and native Windows, any agent as conductor, user-defined roles, guided setup
 - [CHANGELOG.md](CHANGELOG.md) — what changed, release by release
+- [CONTRIBUTING.md](CONTRIBUTING.md) — branches, PR titles, how releases are cut
 - `examples/` — real configurations to copy
 
 ## License

package/README.pt-BR.md

@@ -50,9 +50,9 @@ You ── "/issue DEMO-123" ──► conductor (Claude, in any terminal)
 | 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`; cota lida dos arquivos de sessão (inclusive a janela de 30 dias do plano free) |
+| Codex | `codex` | implement, review | sandbox sem rede: o orq roda o `git fetch` antes de uma execução de escrita (`network = false`); 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 |
+| Antigravity | `agy` | review (implement com allowlist) | em modo headless nega comandos fora da allowlist: faz a review lendo o diff anexado; não consegue commitar, então o orq commita as execuções de escrita dele (`commit = false`) |
 | GitHub Copilot | `copilot` | segunda opinião | cota pequena em alguns planos: uso ocasional |
 
 Você declara só os que tem, e os papéis que cada um pode assumir.
@@ -60,7 +60,7 @@ Você declara só os que tem, e os papéis que cada um pode assumir.
 ## Instalação
 
 Linux, macOS ou Windows (nativo, não só WSL), em qualquer shell — bash, zsh, fish, PowerShell, cmd.
-**Requisitos:** Node 20+ com `npm`, `git`, e pelo menos um agente da tabela acima, logado. Opcional:
+**Requisitos:** Node 22+ com `npm`, `git`, e pelo menos um agente da tabela acima, logado. Opcional:
 [herdr](https://herdr.dev) ou tmux, para cada filho ter sua própria aba ou janela (sem eles, os filhos rodam em
 segundo plano e o `orq board` mostra todos).
 
@@ -103,7 +103,7 @@ git clone https://github.com/irythill/orq ~/Code/orq && cd ~/Code/orq
 ./install.sh            # links em ~/.local/bin, serviço do herdr, skills do Claude
 ```
 
-Precisa de `git`, `jq`, Node 20+ com `npm`, `python3` (3.11+ para config em TOML; mais antigo → config em JSON ou
+Precisa de `git`, `jq`, Node 22+ com `npm`, `python3` (3.11+ para config em TOML; mais antigo → config em JSON ou
 `pip install --user tomli`) e `systemd` de usuário (WSL2: Ubuntu 22.04+ com systemd habilitado). O `install.sh`
 confere os requisitos (tabela do que foi encontrado e do que falta), compila o CLI `orq` (`src/` → `dist/`) e depois
 cria **symlinks** (nunca copia) dos scripts em `~/.local/bin`, do `setup/herdr.service` em `~/.config/systemd/user/`
@@ -114,7 +114,7 @@ sobrescreve um arquivo de verdade (avisa e pula) e nunca escreve a sua config.
 | Flag | O que faz |
 |---|---|
 | `--dry-run` | mostra o que faria, sem mudar nada |
-| `--uninstall` | remove só os links que ele cria, e só os que apontam para este repo (config e histórico ficam) |
+| `--uninstall` | remove só os links que ele cria, e só os que apontam para este repo, e desativa os timers de usuário do orq no systemd (`systemctl --user disable --now`); config e histórico ficam |
 
 ## Configuração
 
@@ -123,10 +123,10 @@ Duas camadas, para separar **o seu jeito de trabalhar** do **projeto do time**:
 | Arquivo | De quem | O que guarda |
 |---|---|---|
 | `~/.config/orq/config.toml` | seu, fica na sua máquina | agentes, contas, modelos por papel e nível, pesos do pick, limites de memória |
-| `<workspace>/.orq/workspace.toml` 🚧 | do time, versionado | Plane (projetos, padrão de issue), repos, branch base, verificação, testes, dependências |
+| `<workspace>/.orq/workspace.toml` | do time, versionado | Plane (projetos, padrão de issue), repos, branch base, verificação, testes, dependências |
 
 O mais específico ganha, chave por chave. JSON também funciona (`config.json`). Para ver o resultado mesclado:
-`orq-config` (tudo), `orq-config get policy.weights`, `orq-config files`.
+`orq config` (tudo), `orq config get policy.weights`, `orq config files`.
 
 ### Exemplo: config pessoal
 Exemplo completo e comentado: [`examples/irythill/config.toml`](examples/irythill/config.toml). O essencial:
@@ -138,7 +138,7 @@ roles  = ["impl", "fix", "review"]
 quota  = ["codex"]                       # name in agent-quota's output
 [agents.codex.models.impl]
 simple = "gpt-6-sol@low"                 # model@effort, per issue level
-medium = "gpt-6-sol@medium"
+medium = ["gpt-6-sol@medium", "gpt-6-luna@medium"]  # several: each (agent, model) pair is scored on its own history
 heavy  = "gpt-6.1-sol@high"
 [agents.codex.models.review]
 simple  = "gpt-6-sol@low"                # reviews scale with the issue too
@@ -151,6 +151,18 @@ 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
+# commit = false                         # can't git commit: orq commits a write run's changes
+# network = false                        # no network: orq fetches origin before a write run
+# base_commit = false                    # can't review `-b <sha>` (default for a tool): pick skips it on a round delta, agent falls back to the branch base
+# filter = "jq -r '...'"                 # optional: its output → [blocker]/[suggestion] lines
+
 [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
@@ -160,7 +172,8 @@ reset_grace_min = 15                     # toda janela acima do gatilho renova d
 issue_pattern = "(?<![a-z0-9])(?<issue>[a-z][a-z0-9]*-\\d+)(?![a-z0-9])"   # Nome de branch/worktree → ID da issue, para `orq gc` e `orq ci` — padrão mostrado; regex, grupo nomeado `issue` (senão o grupo 1)
 
 [policy]
-quota_limit = 90                         # caps the 5h pick limit; also sets ! in `orq quota --line`
+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]
@@ -170,18 +183,19 @@ speed    = 0.15
 rotation = 0.20                          # penalty for having been picked recently
 ```
 
-### 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, prefere uma cujo ritmo fique dentro do limite e, como
+### Como o `orq pick` escolhe
+1. **Filtros:** só agentes com aquele papel cuja CLI está no PATH, abaixo do limite de quota, não bloqueados
+   (`orq block`) e, para reviews, de um vendor diferente do implementador (e, para o delta de uma rodada, capazes de
+   revisar um commit: `base_commit`). 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.
+   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.
 
 ```bash
-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 review --impl-agent codex --explain     # every candidate's score and who was left out, and why
+orq stats --days 30                              # scoreboard per agent and model: delivery, approval, time (to the first turn), tokens
+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
 ```
 
@@ -189,7 +203,7 @@ orq pick fix --same .orquestra/<ID>/impl-<repo>.pick   # a fix round: the implem
 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);
+- `orq lang pt` / `orq lang en` / `orq lang toggle` (`orq lang` sozinho mostra o atual);
 - a tecla `l` dentro do `orq board`;
 - no herdr, uma tecla para isso: veja [Com o herdr](#com-o-herdr).
 
@@ -205,7 +219,9 @@ Abra o conductor em qualquer terminal, na pasta do seu workspace (a que o `orq s
 ```bash
 cd ~/Code/<workspace> && orq conductor [conta] [modelo]   # qualquer terminal: carrega as instruções do conductor, o CLAUDE.md do workspace e a skill /issue
 ```
-Com vários conductors, dê a cada um um nome fixo (`export ORQ_CONDUCTOR_ID=<nome>`) para o `orq claim` distingui-los.
+Com vários conductors, dê a cada um um nome fixo (`export ORQ_CONDUCTOR_ID=<nome>`; no herdr, vale o label do
+workspace) para o `orq claim` distingui-los: a sessão do Claude se chama `conductor-<workspace>:<nome>`, e o
+`orq claim -l` termina cada linha com esse `session=`, para os conductors conseguirem se falar.
 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.
@@ -293,6 +309,7 @@ Dia a dia, atalhos e várias issues ao mesmo tempo: [docs/pt-BR/herdr.md](docs/p
 - [docs/pt-BR/omarchy.md](docs/pt-BR/omarchy.md) — extras para quem usa Omarchy
 - [docs/pt-BR/portability.md](docs/pt-BR/portability.md) — o roadmap: Linux, macOS e Windows nativo, qualquer agente como conductor, papéis definidos pelo usuário, setup guiado
 - [CHANGELOG.pt-BR.md](CHANGELOG.pt-BR.md) — o que mudou, versão a versão
+- [CONTRIBUTING.md](CONTRIBUTING.md) — branches, títulos de PR, como sai uma versão (em inglês)
 - `examples/` — configurações reais para copiar
 
 ## Licença

package/dist/agents.js

@@ -1,6 +1,59 @@
+// AgentDef — how to run each agent, as command templates in the config. The five built-in agents below are defaults
+// the user may override key by key in [agents.<name>]; any other CLI becomes usable by declaring `run` there.
+//
+//   [agents.acme]
+//   run      = "acme exec [--model {model}] --prompt-file {prompt} {mode}"   # new session
+//   resume   = "acme exec --resume {session} --prompt-file {prompt} {mode}"  # follow-up (-R)
+//   readonly = "--sandbox read-only"       # {mode} in read-only runs (-r); appended to `run` when it has no {mode}
+//   write    = "--sandbox workspace-write" # {mode} otherwise; false = the agent only runs read only
+//   stdin    = true                        # the prompt goes on stdin (else use {prompt} or {prompt_text})
+//   format   = "text"                      # text (answer = stdout) | claude | codex | opencode | antigravity
+//   session  = { from_log = "session: (\\S+)" }   # or "uuid": orq makes one and passes it as {session}
+//   answer   = "stdout"                    # stdout | file (the agent writes {out} itself)
+//   env      = { ACME_NO_MCP = "1" }
+//   tui      = "acme --on-turn-end {hook_cmd} {prompt_text}"   # -T: the agent's own screen (new session)
+//   tui_resume = "acme --resume {session} --on-turn-end {hook_cmd} {prompt_text}"   # -T -R with the screen closed
+//   ok_exit  = [0, 1]                     # exit codes that still count as a verdict (a review tool exits 1 on findings)
+//   filter   = "jq -r '.findings[] | ...'" # shell line: gets the answer on stdin, its stdout becomes the answer
+//   no_review = "Nothing to review"       # regex: a match on the answer's first line (or a short answer, 200 chars) = nothing reviewed → status=fail
+//   commit   = false                      # the agent can't run git commit: orq commits a write run's changes for it
+//   network  = false                      # the agent has no network: orq fetches origin before a write run (no fetch/pull/push for it)
+//   base_commit = false                   # can't review `-b <commit>` (diffs against origin/<base> itself): pick skips it, agent falls back to the branch base (default: follows usesPrompt: true if the agent takes the prompt, false for a tool that ignores it)
+//
+// Templates: words split on spaces ('...' or "..." keep spaces). {name} or {name:default}; a [group] is dropped when
+// any placeholder in it is empty, and repeated for a list placeholder ({gitroots}). Placeholders: prompt (file),
+// prompt_text, prompt_hint, out (answer file), dir (where the agent runs), repo (-d), base (-b), model, effort, session, gitdir,
+// gitroots, gitroots_json, opencode_config, title, mode; in tui templates also the end-of-turn hook as hook_cmd (a
+// shell line), hook_json (an argv array, Codex's notify) and hook_settings (Claude's --settings).
+// The hook (`orq agent --turn <job> <turn_hook>`) reads the turn in the agent's own shape: claude (Stop hook JSON on
+// stdin), codex (notify JSON as the last argument), opencode (<session id> <answer file>, from orq's plugin) or text
+// (the answer on stdin, the session id as an argument).
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
 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 ?? ""));
+/** Can the agent review the delta from a commit (`-b <sha>`)? A tool that ignores the prompt diffs against origin/<base> itself, so by default it can't. */
+export const baseCommit = (def) => def.base_commit ?? usesPrompt(def);
+/** Does `base` name a commit rather than a branch (no origin/<base>, but it resolves)? A fix round's round-<n>.sha does. */
+export function isCommitBase(repo, base) {
+    const has = (ref) => spawnSync("git", ["-C", repo, "rev-parse", "--verify", "-q", `${ref}^{commit}`]).status === 0;
+    return !has(`origin/${base}`) && has(base);
+}
+/** What orq does for a write run in a git repo that the agent itself can't: commit its changes, fetch origin. */
+export const stepIns = (def, ro, inGit) => ({ commit: !ro && inGit && def.commit === false, fetch: !ro && inGit && def.network === false });
+/** The note added to the prompt so the agent doesn't try what orq does for it. */
+export function stepInNote(s) {
+    const l = [];
+    if (s.fetch)
+        l.push("- You have no network access. orq already ran `git fetch origin`, so the origin/* refs are fresh: rebase or diff against them locally. Don't run git fetch, pull or push.");
+    if (s.commit)
+        l.push("- You can't run `git commit`. Leave your changes in the working tree; orq commits them after you finish. Start your final answer with a one-line commit message in the form `Commit: <message>`.");
+    return l.length ? `\n\n## Environment (from orq)\n${l.join("\n")}\n` : "";
+}
+/** The commit message an agent proposed (`Commit: ...` line in its answer), else the fallback. */
+export const commitMessage = (answer, fallback) => /^\W*commit:\s*`?([^`\n]+?)`?\s*$/im.exec(answer)?.[1]?.trim() || fallback;
 /** 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";
@@ -29,7 +82,7 @@ export const BUILTIN_AGENTS = {
             `--skip-git-repo-check {mode} ${NOMCP_CODEX} -o {out} -`,
         resume: `codex exec resume {session} -c model_reasoning_effort={effort:low} ` +
             `-c sandbox_workspace_write.writable_roots={gitroots_json} ${NOMCP_CODEX} -o {out} -`,
-        readonly: "", write: "[--add-dir {gitroots}]", stdin: true, format: "codex", answer: "file", throwaway: true,
+        readonly: "", write: "[--add-dir {gitroots}]", stdin: true, format: "codex", answer: "file", throwaway: true, network: false,
         // The screen: no approvals (nobody to approve), the same sandbox as exec; notify = end of turn.
         tui: `codex [-m {model}] -c model_reasoning_effort={effort:low} -s workspace-write -a never -C {dir} {mode} ` +
             `${NOMCP_CODEX} -c notify={hook_json} {prompt_text}`,
@@ -51,7 +104,7 @@ export const BUILTIN_AGENTS = {
         // 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,
+        format: "antigravity", throwaway: true, prompt_in_dir: true, commit: false,
     },
     copilot: {
         // Second opinion, always read only: git reads allowed, anything else denied by -p without asking.
@@ -68,6 +121,26 @@ export function agentDef(cfg, name) {
         throw new Error(m(`unknown agent: ${name} (built in: ${Object.keys(BUILTIN_AGENTS).join(", ")}; others need agents.${name}.run in the config)`, `agente desconhecido: ${name} (embutidos: ${Object.keys(BUILTIN_AGENTS).join(", ")}; outros precisam de agents.${name}.run no config)`));
     return def;
 }
+/** Is `bin` on PATH? (PATHEXT on Windows: claude.cmd, codex.exe…) A path (with a slash) must exist itself. */
+export function onPath(bin) {
+    if (/[\\/]/.test(bin))
+        return existsSync(bin);
+    const exts = process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
+    return (process.env.PATH ?? "").split(delimiter).some((d) => d && exts.some((e) => existsSync(join(d, bin + e))));
+}
+/** Why `name` can't start here (its CLI doesn't resolve on the PATH the child inherits), or undefined when it can. */
+export function missingBinary(cfg, name) {
+    let bin;
+    try {
+        bin = tokenize(agentDef(cfg, name).run)[0]?.text;
+    }
+    catch {
+        return undefined;
+    }
+    if (!bin || onPath(bin))
+        return undefined;
+    return m(`\`${bin}\` not found on PATH (installed for another Node version? reinstall it)`, `\`${bin}\` não está no PATH (instalado para outra versão do Node? reinstale)`);
+}
 /** Split a template into words, remembering which [group] each belongs to. */
 export function tokenize(t) {
     const out = [];