@irythill/orq 0.6.0 → 0.7.0

package/dist/quota.js

@@ -24,6 +24,7 @@ import { writeAtomic } from "./fsutil.js";
 import { readSecret } from "./keyring.js";
 import { stateDir } from "./paths.js";
 import { m } from "./i18n.js";
+import { modelKey } from "./pick.js";
 const show = (p) => (typeof p === "number" ? `${Math.floor(p)}%` : p);
 // reset5h/resetweek (epoch seconds) sit between the windows and the note: parseQuota/parseWindows only look at the
 // first three words, so old cached lines (no reset fields) and lines with them both parse the same way.
@@ -50,9 +51,9 @@ const resetOf = (w) => {
 };
 // `acct` identifies the login behind a reading (antigravity: one login per machine, swapped by the user): a cache
 // written under another login must never stand in for this one.
-function remember(name, five, week, acct) {
+function remember(name, five, week, acct, buckets) {
     try {
-        writeAtomic(cacheFile(name), JSON.stringify({ five, week, at: Date.now(), ...(acct ? { acct } : {}) }));
+        writeAtomic(cacheFile(name), JSON.stringify({ five, week, at: Date.now(), ...(acct ? { acct } : {}), ...(buckets ? { buckets } : {}) }));
     }
     catch { /* best effort */ }
     const r5 = resetOf(five), rw = resetOf(week);
@@ -195,23 +196,83 @@ export function codexQuota() {
     return { name: "codex", ...pcts, ...(span5 ? { span5h: span5 } : {}), ...(span ? { spanWeek: span } : {}), note: (d ? m(`${d}-day window in the week slot; `, `janela de ${d} dias no lugar da semana; `) : "")
             + m(`from the last session, ${age} min ago`, `da última sessão, há ${age} min`) };
 }
-/** Worst usage per window across models: a reset within 6 h belongs to the 5h window, a later one to the week. */
+/** Per-model buckets, and the agent's own pair: its least used bucket (the agent still has quota while any
+ *  model does; `orq pick` checks the model it is about to choose against that model's own bucket). */
 export function antigravityFromModels(models, now = Date.now()) {
     const five = { pct: "-" }, week = { pct: "-" };
-    for (const { quotaInfo: q } of Object.values(models ?? {})) {
-        if (typeof q?.remainingFraction !== "number" || !q.resetTime)
+    const buckets = {};
+    for (const [id, { quotaInfo: q } = {}] of Object.entries(models ?? {})) {
+        if (!q?.resetTime)
             continue;
         const at = Date.parse(q.resetTime);
         if (Number.isNaN(at))
             continue;
-        const w = at - now <= 6 * 3600_000 ? five : week;
-        const used = Math.round((1 - q.remainingFraction) * 100);
-        if (w.pct === "-" || used > w.pct) {
-            w.pct = used;
-            w.resetsAt = q.resetTime;
+        const left = typeof q.remainingFraction === "number" ? q.remainingFraction : 0;
+        const used = Math.min(100, Math.max(0, Math.round((1 - left) * 100)));
+        const isWeek = at - now > 6 * 3600_000;
+        buckets[id] = { used, resetsAt: q.resetTime, week: isWeek };
+    }
+    // The agent's pair is its least used bucket overall, in that bucket's window (the other stays "-"): a weekly cap on
+    // one model must not read as the whole agent being out.
+    const best = Object.values(buckets).sort((x, y) => x.used - y.used || Number(x.week) - Number(y.week))[0];
+    if (best)
+        Object.assign(best.week ? week : five, { pct: best.used, resetsAt: best.resetsAt });
+    return { five, week, buckets };
+}
+/** One quota line per model, named "<agent>/<model>", with its bucket in the 5h or the week slot and "-" in the other. */
+export function modelLines(name, buckets, now = Date.now(), note) {
+    const out = [];
+    for (const [id, b] of Object.entries(buckets)) {
+        const at = Date.parse(b.resetsAt);
+        if (Number.isNaN(at) || at <= now)
+            continue; // reset since the reading: no figure to stand on
+        const reset = Math.floor(at / 1000);
+        out.push({ name: `${name}/${id}`, five: b.week ? "-" : b.used, week: b.week ? b.used : "-",
+            ...(b.week ? { resetWeek: reset } : { reset5h: reset }), ...(note ? { note } : {}) });
+    }
+    return out;
+}
+/** Learned exhausted buckets (from a run that hit the limit) outlive API readings until their reset, unless the API
+ *  returns that model with something left. The API's own bucket for the model stands in when it also says exhausted. */
+export function mergeLearned(api, learned, now = Date.now()) {
+    const out = { ...api };
+    for (const [id, b] of Object.entries(learned)) {
+        if (!b.learned || Date.parse(b.resetsAt) <= now)
+            continue;
+        const key = modelKey(id, Object.keys(api));
+        if (key && api[key].used < 100)
+            continue; // the API says it has quota again
+        out[id] = b;
+    }
+    return out;
+}
+/** Record that a run found `model` out of quota for `secs` more seconds (best effort; keeps the cached reading). */
+export function learnExhausted(name, model, secs, acct, now = Date.now()) {
+    const at = now + secs * 1000;
+    const b = { used: 100, resetsAt: new Date(at).toISOString(), week: at - now > 6 * 3600_000, learned: true };
+    try {
+        let c = { five: { pct: "-" }, week: { pct: "-" }, at: now };
+        try {
+            c = JSON.parse(readFileSync(cacheFile(name), "utf8"));
         }
+        catch { /* none yet */ }
+        if (acct !== undefined && c.acct !== undefined && c.acct !== acct)
+            c = { five: { pct: "-" }, week: { pct: "-" }, at: now };
+        const buckets = { ...(c.buckets ?? {}), [model]: b };
+        writeAtomic(cacheFile(name), JSON.stringify({ ...c, ...(acct ? { acct } : {}), buckets }));
+    }
+    catch { /* best effort */ }
+    return b;
+}
+/** The per-model buckets of the last good reading, when it was this login's. */
+function cachedBuckets(name, acct) {
+    try {
+        const c = JSON.parse(readFileSync(cacheFile(name), "utf8"));
+        return acct !== undefined && c.acct !== acct ? {} : c.buckets ?? {};
+    }
+    catch {
+        return {};
     }
-    return { five, week };
 }
 export function agyToken() {
     // agy (go-keyring) keeps {"token": {access_token, expiry, ...}} under service "gemini", user "antigravity"
@@ -242,13 +303,17 @@ export async function antigravityQuota() {
     const name = "antigravity";
     const t = agyToken();
     if (!t?.access)
-        return noData(name, m("no agy login in the keyring", "sem login do agy no chaveiro"));
+        return [noData(name, m("no agy login in the keyring", "sem login do agy no chaveiro"))];
     // Never refresh it here (that is agy's login). The access token lives 1h and agy renews it only when it runs, so a
     // passed expiry with a refresh token is just idle (a note, not an expired login); without one, "run agy once".
     const expired = m("login expired: run `agy models`", "login expirado: rode `agy models`");
+    const stale = (why) => {
+        const line = fromCache(name, why, undefined, t.acct);
+        return [line, ...modelLines(name, cachedBuckets(name, t.acct), Date.now(), line.note)];
+    };
     const note = agyNote(t);
     if (note)
-        return fromCache(name, note, undefined, t.acct);
+        return stale(note);
     try {
         const r = await fetch("https://cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels", {
             method: "POST", body: "{}",
@@ -257,15 +322,16 @@ export async function antigravityQuota() {
             signal: AbortSignal.timeout(15_000),
         });
         if (r.status === 401)
-            return fromCache(name, expired, undefined, t.acct);
+            return stale(expired);
         if (!r.ok)
-            return fromCache(name, `HTTP ${r.status}`, undefined, t.acct);
+            return stale(`HTTP ${r.status}`);
         const j = await r.json();
-        const { five, week } = antigravityFromModels(j.models ?? {});
-        return remember(name, five, week, t.acct);
+        const { five, week, buckets: api } = antigravityFromModels(j.models ?? {});
+        const buckets = mergeLearned(api, cachedBuckets(name, t.acct));
+        return [remember(name, five, week, t.acct, buckets), ...modelLines(name, buckets)];
     }
     catch (e) {
-        return fromCache(name, m("collector failed", "coletor falhou") + `: ${e.message}`, undefined, t.acct);
+        return stale(m("collector failed", "coletor falhou") + `: ${e.message}`);
     }
 }
 // --- copilot --------------------------------------------------------------------------------------------------------
@@ -385,7 +451,7 @@ export async function collect(sources, want = []) {
         if (name === "codex")
             return wanted(name) ? [format(codexQuota())] : [];
         if (name === "antigravity")
-            return wanted(name) ? [format(await antigravityQuota())] : [];
+            return wanted(name) ? (await antigravityQuota()).map(format) : [];
         if (name === "copilot")
             return wanted(name) ? [format(copilotQuota())] : [];
         if (name === "opencode" || name === "minimax")

package/dist/rounds.js

@@ -14,6 +14,7 @@ export const SLOW_FACTOR = 2; // a round this many times slower than the median
 export const SLOW_MIN_SECS = 600; // ... but only if it also took at least this long
 export const REPEAT_WARN = 2; // a finding seen in this many reviews: warn
 export const REPEAT_STOP = 3; // ... in this many: stop (it came back after two fix rounds)
+export const FRESH_WARN = 2; // fix rounds whose review brings heavy findings never seen before: the branch is too big, split it
 export const HEAVY = new Set(["blocker", "major", "critical"]); // only these count towards repeats and the alert
 const read = (f) => { try {
     return readFileSync(f, "utf8");
@@ -40,7 +41,8 @@ const repoRel = (f) => f.replace(/\\/g, "/").replace(/^.*\.worktrees\/[^/]+\//,
 export function parseFindings(text, round) {
     const out = [];
     for (const line of text.split("\n")) {
-        const it = /^\s*(?:[-*+]|\d+[.)])\s+(.*)$/.exec(line);
+        // A list item, or a bare line that starts with a severity tag ("[blocker] src/a.ts:10 ...", as some reviewers write).
+        const it = /^\s*(?:[-*+]|\d+[.)])\s+(.*)$/.exec(line) ?? /^\s*(\[(?:blocker|major|minor|nit|suggestion|important|critical)\].*)$/i.exec(line);
         if (!it)
             continue;
         const sevOf = (w) => { const k = fold(w ?? ""); return Object.hasOwn(SEV, k) ? SEV[k] : undefined; };
@@ -60,6 +62,13 @@ export function parseFindings(text, round) {
     return out;
 }
 /** Same finding? Same file (when both name one) and enough shared words; without a file, a stricter overlap. */
+// An explicit "nothing to fix" verdict, PT or EN, on a line of its own or as a heading/label.
+const APPROVED = /^\s*(?:[#>*_`-]+\s*)*(?:verdict|veredito|status|resultado)?\s*[:—-]?\s*\**\s*(approved|approve|lgtm|aprovad[oa]|no (?:blocking )?(?:findings|issues|blockers)|nenhum (?:achado|problema|blocker|bloqueante)|sem (?:achados|bloqueantes|blockers))\b/im;
+/** Does a review answer carry a verdict: at least one finding with a severity, or an explicit approval?
+ *  "I'll start by exploring the repo..." (a reviewer that stopped before reviewing) has neither. */
+export function hasVerdict(text) {
+    return parseFindings(text, 0).length > 0 || APPROVED.test(text);
+}
 export function similar(a, b) {
     const wa = words(a.title), wb = words(b.title);
     if (!wa.size || !wb.size)
@@ -86,6 +95,14 @@ export function repeats(fs) {
     return groups.map((g) => ({ file: g[0].file, title: g[0].title, rounds: [...new Set(g.map((x) => x.round))] }))
         .filter((r) => r.rounds.length >= REPEAT_WARN);
 }
+/** Fix rounds (k ≥ 1) whose review raised a heavy finding not similar to any earlier one: a reviewer re-reading a big branch. */
+export function freshRounds(fs) {
+    const out = new Set();
+    for (const f of fs)
+        if (f.round > 0 && !fs.some((e) => e.round < f.round && similar(e, f)))
+            out.add(f.round);
+    return [...out].sort((a, b) => a - b);
+}
 const median = (xs) => { const s = [...xs].sort((a, b) => a - b), h = s.length >> 1; return s.length % 2 ? s[h] : (s[h - 1] + s[h]) / 2; };
 /** Fix rounds far above the median of the other fix rounds (round 0 is the implementation: never compared; needs 3 fix rounds). */
 export function slowRounds(all) {
@@ -96,7 +113,7 @@ export function slowRounds(all) {
 }
 /** The pure part: facts from the files → numbers, alert level and why. */
 export function metrics(issue, f) {
-    const reps = repeats(f.findings.filter((x) => HEAVY.has(x.severity))), reasons = [];
+    const heavy = f.findings.filter((x) => HEAVY.has(x.severity)), reps = repeats(heavy), reasons = [];
     let level = "ok";
     const raise = (l, why) => { reasons.push(why); if (l === "stop" || level === "ok")
         level = l; };
@@ -109,6 +126,9 @@ export function metrics(issue, f) {
         raise("stop", { code: "same_finding", n: worst });
     else if (reps.length)
         raise("warn", { code: "repeated", n: reps.length });
+    const fresh = freshRounds(heavy);
+    if (fresh.length >= FRESH_WARN)
+        raise("warn", { code: "fresh", n: fresh.length, rounds: fresh });
     const slow = slowRounds(f.perRound);
     if (slow.length)
         raise("warn", { code: "slow", n: slow.length, rounds: slow });
@@ -121,11 +141,25 @@ export function countRounds(dir, names) {
         const fx = /^fix-(\d+)\.md$/.exec(f);
         if (fx)
             n = Math.max(n, Number(fx[1]));
-        else if (f.startsWith(".rounds-"))
+        else if (f.startsWith(".rounds-") && !f.endsWith(".log"))
             n = Math.max(n, Number(read(join(dir, f))) || 0);
     }
     return n;
 }
+/** Follow-ups per reason (review|verify|unblock) from the .rounds-<session>.log files `orq agent -R` appends to. */
+export function roundReasons(dir, names) {
+    const out = {};
+    for (const f of names) {
+        if (!/^\.rounds-.+\.log$/.test(f))
+            continue;
+        for (const line of read(join(dir, f)).split("\n")) {
+            const r = line.split(" ")[1];
+            if (r)
+                out[r] = (out[r] ?? 0) + 1;
+        }
+    }
+    return out;
+}
 /** The impure part: read .orquestra/<issue>/. undefined when the issue has no fix or review files at all. */
 export function collectRounds(ws, issue, max) {
     const dir = join(ws, ".orquestra", issue);
@@ -160,7 +194,9 @@ export function collectRounds(ws, issue, max) {
         return { round: k, secs: Number.isNaN(s) || Number.isNaN(next) ? 0 : Math.max(0, Math.round((next - s) / 1000)) };
     });
     const findings = [...reviews].flatMap(([k, fs]) => fs.flatMap((n) => parseFindings(read(join(dir, n)), k)));
-    return metrics(issue, { rounds, max, perRound, findings, secs: Math.round((t1 - t0) / 1000) });
+    const x = metrics(issue, { rounds, max, perRound, findings, secs: Math.round((t1 - t0) / 1000) });
+    const fu = roundReasons(dir, names);
+    return Object.keys(fu).length ? { ...x, followups: fu } : x;
 }
 /** Cheap change signature of an issue folder (names + mtimes, no reads) for caching collectRounds between redraws. */
 export function roundsSig(ws, issue) {

package/dist/stats.js

@@ -3,9 +3,13 @@
 // duration, tokens. "New" tokens = excluding cache reads (what actually weighs on quota); Codex without a session
 // file only reports the total. Implementation delivery = the first review of the same repo in the issue said APPROVED.
 // Limitation: follow-ups (-R) reuse the implementation prefix, so the "impl" row shows the last round of that prefix.
+// Agent and model come from the job (<prefix>.job.json argv), then the pick (<prefix>.pick), then the log; a tool
+// without models (a review CLI) has model "-". Time runs to the first turn on a screen run (<prefix>.turns): later
+// turns wait on a person. Killed runs and older screen runs without .turns are counted but left out of the time median.
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
+import { argvModel, tokenize } from "./agents.js";
 import { doneStatus } from "./process.js";
 const ROLE = /^(impl|fix\d*|review\d*|[a-z]+-review\d*|watchdog\d*)-?/;
 const read = (f) => { try {
@@ -14,14 +18,40 @@ const read = (f) => { try {
 catch {
     return "";
 } };
-export function agentModel(run, log) {
-    const a = /\b(codex exec|codex resume|codex|claude -p|claude|opencode run|opencode|agy)\b/.exec(run);
-    const first = a ? a[1].split(" ")[0] : "?";
-    const agent = first === "agy" ? "antigravity" : first;
-    let model = /(?:\s-m|--model)\s+'?([^\s']+)/.exec(run)?.[1];
-    if (agent === "codex" && !model)
-        model = /^model: (\S+)/m.exec(log)?.[1] ?? "default";
-    return [agent, (model ?? "default").split("/").pop()];
+const BINS = /^(codex|claude|opencode|agy|copilot)$/;
+/** The model a log says was used: Claude's init event, Codex's banner, opencode's step events. */
+function logModel(log) {
+    return /"type"\s*:\s*"system"[^\n]*?"model"\s*:\s*"([^"]+)"/.exec(log)?.[1] ?? /^model: (\S+)/m.exec(log)?.[1]
+        ?? /"modelID"\s*:\s*"([^"]+)"/.exec(log)?.[1];
+}
+/** The argv of a generated .run.sh: its command, shell-tokenized (quotes span lines), without leading VAR=value words. */
+function runArgv(run) {
+    const body = run.split("\n").filter((l) => !l.startsWith("#") && !l.startsWith("cd ")).join("\n");
+    const words = tokenize(body.replace(/\s<\s\S+\s*$/, "")).map((w) => w.text);
+    while (words.length && /^\w+=/.test(words[0]))
+        words.shift();
+    return words;
+}
+/** [agent, model] of a run. `job` is <prefix>.job.json (argv + agent), `pick` the `-a … -m …` line it was dispatched with
+ *  (used only when it names the same agent). */
+export function agentModel(run, log, job, pick = "") {
+    let argv = job?.argv ?? runArgv(run);
+    const base = (w) => w.split(/[\\/]/).pop();
+    // Older runs wrap the agent (systemd-run …, git worktree … && codex): start at the first agent CLI found.
+    const at = job ? 0 : argv.findIndex((w) => BINS.test(base(w)));
+    if (at > 0)
+        argv = argv.slice(at);
+    const bin = base(argv[0] ?? "");
+    let agent = job?.agent || bin || "?";
+    if (agent === "agy")
+        agent = "antigravity";
+    const picked = / -a (\S+)/.exec(` ${pick}`)?.[1] === agent ? / -m (\S+)/.exec(pick)?.[1] : undefined;
+    // opencode's screen takes the model in its config env, not -m.
+    const envModel = /"model":"([^"]+)"/.exec(job?.env?.OPENCODE_CONFIG_CONTENT ?? "")?.[1];
+    const model = argvModel(argv) ?? envModel ?? picked ?? logModel(log);
+    if (model)
+        return [agent, model.split("/").pop()];
+    return [agent, /^(codex|claude|opencode|agy)$/.test(bin) ? "default" : "-"];
 }
 function codexSession(sid) {
     const root = join(process.env.CODEX_HOME ?? join(homedir(), ".codex"), "sessions");
@@ -74,8 +104,10 @@ export function tokens(agent, log, sid = "") {
         }
         else if (agent === "opencode" && e.type === "step_finish") {
             const t = e.part?.tokens ?? {};
-            neu += (t.total ?? 0) - (t.cache?.read ?? 0);
-            tot += t.total ?? 0;
+            // Newer opencode has no total: input + output + reasoning + cache.
+            const all = t.total ?? (t.input ?? 0) + (t.output ?? 0) + (t.reasoning ?? 0) + (t.cache?.read ?? 0) + (t.cache?.write ?? 0);
+            neu += all - (t.cache?.read ?? 0);
+            tot += all;
         }
         else if (agent === "antigravity" && e.event === "result") {
             const u = e.result?.usage ?? {};
@@ -112,7 +144,16 @@ export function collectRuns(ws, days) {
             if (txt.includes("herdr-verify") || txt.includes("herdr-baseline"))
                 continue;
             const log = read(`${pre}.log`);
-            const [agent, model] = agentModel(txt, log);
+            let job;
+            try {
+                job = JSON.parse(read(`${pre}.job.json`));
+            }
+            catch { /* older run */ }
+            const [agent, model] = agentModel(txt, log, job, read(`${pre}.pick`));
+            const dt = read(done), turns = read(`${pre}.turns`).split("\n").filter(Boolean);
+            const first = turns.length ? Date.parse(turns[0]) : NaN;
+            const end = Number.isFinite(first) ? first : statSync(done).mtimeMs;
+            const timed = Number.isFinite(first) || (!/\bmode=tui\b/.test(dt) && doneStatus(dt) !== "killed");
             const name = basename(pre);
             const rm = ROLE.exec(name);
             const role = rm && rm[1].includes("review") ? "review"
@@ -121,8 +162,8 @@ export function collectRuns(ws, days) {
                         : name.startsWith("impl") ? "impl" : "other";
             const out = read(`${pre}.out.md`);
             const [neu, tot] = tokens(agent, log, read(`${pre}.id`).trim());
-            runs.push({ issue, name, agent, model, role, ok: doneStatus(read(done)) === "ok" && out.trim() !== "",
-                secs: Math.max(0, Math.floor((statSync(done).mtimeMs - rs.mtimeMs) / 1000)), new: neu, tot,
+            runs.push({ issue, name, agent, model, role, ok: doneStatus(dt) === "ok" && out.trim() !== "",
+                secs: Math.max(0, Math.floor((end - rs.mtimeMs) / 1000)), timed, new: neu, tot,
                 repo: name.includes("-") ? name.slice(name.indexOf("-") + 1) : "" });
         }
     }
@@ -153,7 +194,7 @@ export function rows(runs) {
         const withTok = rs.filter((r) => r.tot), appr = rs.filter((r) => r.approved !== undefined).map((r) => r.approved);
         return { role, agent, model, n: rs.length, ok: Math.round(100 * rs.filter((r) => r.ok).length / rs.length),
             approved: appr.length ? Math.round(100 * appr.filter(Boolean).length / appr.length) : null, n_appr: appr.length,
-            min: Math.round(median(rs.map((r) => r.secs)) / 6) / 10,
+            min: rs.some((r) => r.timed) ? Math.round(median(rs.filter((r) => r.timed).map((r) => r.secs)) / 6) / 10 : null,
             new: withTok.length ? Math.floor(median(withTok.map((r) => r.new))) : null,
             tot: withTok.length ? Math.floor(median(withTok.map((r) => r.tot))) : null };
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@irythill/orq",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Orchestrate coding agents (Claude Code, Codex, OpenCode, Antigravity, Copilot) from one conductor.",
   "license": "MIT",
   "type": "module",
@@ -11,10 +11,11 @@
     "dist",
     "!dist/**/*.test.js",
     "skills",
-    "templates/workspace.CLAUDE.md"
+    "templates/workspace.CLAUDE.md",
+    "templates/conductor.instructions.md"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "repository": {
     "type": "git",
@@ -38,11 +39,11 @@
     "prepack": "tsc"
   },
   "dependencies": {
-    "@napi-rs/keyring": "^2.1.1",
+    "@napi-rs/keyring": "^2.1.2",
     "smol-toml": "^1.9.1"
   },
   "devDependencies": {
-    "@types/node": "^24.0.0",
+    "@types/node": "^22.20.5",
     "typescript": "^7.0.2"
   }
 }

package/skills/issue/SKILL.md

@@ -99,7 +99,8 @@ Always include:
   choice doesn't come back as a blocker.
 - **No tests in the child** (memory rule): "don't run jest/vitest; I run the related tests afterwards".
 - **Fresh branch:** "before your final answer: `git fetch origin <BASE> && git rebase origin/<BASE>`; on conflict stop
-  and report; after the rebase repeat lint/tsc". Codex has no network: for it, you fetch and check in step 5.
+  and report; after the rebase repeat lint/tsc". An agent without network (Codex) can't fetch: `orq agent` fetches before
+  the run and adds a note to its prompt, so it only rebases locally.
 
 **Base = the repo's base branch from the workspace `CLAUDE.md`, always from the updated remote (`origin/<BASE>`).**
 Worktree with `git worktree add` (not `herdr worktree create`: that opens a separate herdr workspace per worktree, and
@@ -128,7 +129,7 @@ orq agent $(cat $O/impl-<repo>.pick) -g <group> -t "<ID> impl <repo>" -d $WT -o
 ```
 - The Claude account (`-c`) already comes from `orq pick` (one under the limit whose pace stays within it, then the least used).
 - Full final answer in `$O/impl-<repo>.out.md`; log in `.log`; the agent's session id in `.id`.
-- Codex's sandbox has no network: `git fetch` is yours, beforehand (above). Push/PR: yours (step 7).
+- An agent without network (`network = false`, e.g. Codex): `orq agent` runs `git fetch origin` before a write run, so it can rebase locally. Push/PR: yours (step 7).
 - `orq agent` returns immediately (no need to background it); the child's pane is in `<prefix>.pane`
   (to peek: `<prefix>.log`; in herdr, `herdr pane read $(cat <prefix>.pane) --source recent`).
 - **No baseline in the issue flow:** don't run `orq baseline` before dispatching (the base moves with every merge and
@@ -157,7 +158,10 @@ Child with `status=ok` → run the tests related to the diff, in their own tab,
 `orq verify -w $WS -r <repo> -d $WT -b <BASE> -o $O/verify-<repo> -g <group>` → `$O/verify-<repo>.txt` with
 **new failures** and pre-existing ones: if any test fails, it runs the same test files on an updated
 `origin/<BASE>` (whatever fails there is pre-existing). You get the done line (`[HERDR-AGENT DONE]` / `[ORQ AGENT DONE]`) `verify ... new=N`.
-`new>0` → fix round with the list (step 6), no review. `new=0` → review.
+`new>0` → follow-up with the failing tests, no review: write `$O/verify-fix-<n>.md` (not `fix-<n>.md`) and add
+`--reason verify` to the `-R` call of step 6. `new=0` → review. A follow-up that only unblocks the child (files it
+couldn't fetch without network, a missing tool) uses `--reason unblock`. Only review rounds (the default `--reason
+review`) count towards `policy.max_rounds`.
 **Pre-existing failures get fixed too.** Any failure — tests listed as "already failing on origin/<BASE>", or a CI job
 (lint, biome, typecheck, shard, regression) failing on the PR or on the base — goes into a fix round on the issue's
 branch (separate `fix:`/`test:` commit naming the issue). Never close, move to In Review or call a PR done while
@@ -223,12 +227,19 @@ Then a new `orq verify` (4b) and the **round review** (step 5 with these changes
 - Same reviewer as the round before: `$(cat $O/review-<repo>.pick)`. Only if it is over quota, blocked or fails with
   no verdict → a new `orq pick review` (saved to the same file).
 - Extra attachments: `git -C $WT diff $(cat $O/round-<n>.sha)..HEAD > $O/fix-<n>.diff` → `-i $O/fix-<n>.md -i $O/fix-<n>.diff`
-  (the full `-b $BASE` diff stays, as context).
+  (the full `-b $BASE` diff stays, as context). **A review tool** gets `-b $(cat $O/round-<n>.sha)` instead of `-b $BASE`:
+  `{base}` becomes that commit, so it reviews only the round's delta, not the whole branch again. Pick the round reviewer with
+  `orq pick review --base $(cat $O/round-<n>.sha) ...`: a tool with `base_commit = false` is skipped. Dispatched anyway, `orq agent`
+  falls back to the branch base (`--base-branch $BASE`) and its answer says the review covers the whole branch.
 - The prompt asks a closed question: "for each item in fix-<n>.md: RESOLVED or NOT RESOLVED (why); then the fix diff:
   any regression it introduced, as `[blocker]`/`[suggestion]`. Outside the fix diff, report only a blocker you missed
-  before that would break production, and say why it wasn't in the first review". Anything else is a suggestion. A review tool can't answer that: it reviews the whole
-branch again, so you do the matching — a finding is a blocker this round only if it is inside `fix-<n>.diff` or is a
-NOT RESOLVED item of `fix-<n>.md`; one you already decided on (fixed, rejected or downgraded) stays decided. **Maximum: `orq config get policy.max_rounds` rounds** — `orq agent -R` refuses the next one (exit 4) and counts per session, so a renamed prefix doesn't reset it; on exit 4 stop and tell the user. With their OK run `orq rounds <ID> --diagnose` (a cheap independent agent, advisory: read its `RECOMMENDATION` — continue / split / change-implementer / ask-user — and tell the user), then `-F` (refused without a diagnosis newer than the last fix/review; `-F -F` skips that, only if the user says so); over it → `orq pick impl
+  before that would break production, and say why it wasn't in the first review". Anything else is a suggestion. If a review
+still names something outside `fix-<n>.diff`, you do the matching — a finding is a blocker this round only if it is inside
+`fix-<n>.diff` or is a NOT RESOLVED item of `fix-<n>.md`; one you already decided on (fixed, rejected or downgraded) stays decided.
+**A finding outside the fix diff never opens a round by itself**, however serious: it goes to a "deferred" list in the
+Plane comment (a follow-up issue). If it is a security or personal-data leak, stop and ask the user (fix in this branch
+or follow-up) instead of dispatching. `orq rounds <ID>` warns `fresh` when two fix rounds brought new heavy findings:
+the branch is too big — split, don't keep reviewing it whole. **Maximum: `orq config get policy.max_rounds` rounds** — `orq agent -R` refuses the next one (exit 4) and counts per session, so a renamed prefix doesn't reset it; on exit 4 stop and tell the user. With their OK run `orq rounds <ID> --diagnose` (a cheap independent agent, advisory: read its `RECOMMENDATION` — continue / split / change-implementer / ask-user — and tell the user), then `-F` (refused without a diagnosis newer than the last fix/review; `-F -F` skips that, only if the user says so); over it → `orq pick impl
 --exclude-agent <it> > $O/impl-<repo>.pick` only with the user's OK, or stop and report. Non-blocking suggestions go into the comment; they
 don't become a round.
 

package/templates/conductor.instructions.md

@@ -0,0 +1,31 @@
+# Conductor "{{NAME}}" — {{NAME}} ecosystem
+
+You orchestrate agents in the `{{WORKSPACE}}` ecosystem, in herdr (`HERDR_ENV=1`) or in any other terminal.
+Don't write code yourself. Opened by `orq conductor`. Talk to the user in the user's language.
+1. Read `{{WORKSPACE}}/CLAUDE.md` (repos, groups, base branch, Plane, issue standard, MCP limitations).
+2. For every Plane issue, follow the `/issue <ID>` skill.
+3. Never push, open a PR, merge or deploy unless the user asks. When unsure about scope or cost, ask.
+4. **Children only through `orq agent`** (implementer, fix, review), with the agent chosen by `orq pick`; tests through
+   `orq verify` (it checks the base by itself; no `orq baseline` in the flow), as the skill says. NEVER
+   `herdr agent start` for children (no memory cap, no answer file); to watch the agent's own screen, `orq agent -T` (herdr or tmux).
+5. **Completion = one single signal:** in herdr, the line `[HERDR-AGENT DONE] <title> status=ok|fail ... answer: <file>`
+   arriving in your pane; elsewhere, `orq wait <prefix>` (as a background task) printing
+   `[ORQ AGENT DONE] <title> status=ok|fail ... answer: <file>` (plus the `<prefix>.done` file either way). When it
+   arrives: read the answer file and act. Nothing else means done.
+6. **"Is it still running?"** is answered by the file only: `<prefix>.done` exists → finished; it doesn't → running;
+   check `<prefix>.log` (last write time) or, in herdr, peek at the pane: `herdr pane read $(cat <prefix>.pane) --source recent`.
+   NEVER `pgrep`/`ps` (they match their own command line).
+7. **Never block waiting** (`herdr agent wait`, `pane wait-output`, `sleep`): dispatch, report in one line and end
+   your turn (outside herdr: `orq wait` in the background, never in the foreground unless your harness has no background tasks).
+8. Worktrees always from `origin/<repo base>`, created with `git worktree add` (never `herdr worktree create`).
+9. Between batches of unrelated issues, suggest `/clear` to the user: state lives in Plane and in `.orquestra/`.
+
+## How you are used
+- **Dispatcher, not consultant.** Your job: issue → dispatch → report → PR/cleanup. Long questions about architecture,
+  infrastructure (DNS, email, deploy, webhooks) or business decisions: answer in at most 3 lines and suggest "take it
+  to a design session; come back with the decision recorded in the issue".
+- **The issue is the source.** A decision made in chat → record it in Plane (description or comment) before
+  dispatching; the child's prompt comes from the issue, not from the conversation.
+- **Context:** past ~150k tokens or after closing a batch of related issues → suggest `/clear` (state in Plane and in
+  `.orquestra/`).
+- 1–3 line answers. Final issue report: 3–5 lines + the PR link.