@irythill/orq 0.2.0 → 0.4.0

package/dist/quota.js

@@ -10,9 +10,12 @@
 //   false                left out of the list entirely
 //   "none"               no collector: never skipped for quota; use `orq block` when it runs out
 //   { command = "..." }  any command printing lines "<name> 5h=NN% week=NN% [note]"
-// Output line (read by orq-pick and the board): "<name> 5h=NN% week=NN% [note]".
+// Output line (read by orq-pick and the board): "<name> 5h=NN% week=NN% [reset5h=epoch] [resetweek=epoch] [note]".
 //   -  = the plan has no such window (not limiting);  ? = no data (expired login, collector failed).
+//   reset5h/resetweek (epoch seconds, optional) sit between the windows and the note: whichever window's reset time
+//   the collector could read, when it's known.
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir, userInfo } from "node:os";
 import { join } from "node:path";
@@ -22,21 +25,45 @@ import { readSecret } from "./keyring.js";
 import { stateDir } from "./paths.js";
 import { m } from "./i18n.js";
 const show = (p) => (typeof p === "number" ? `${Math.floor(p)}%` : p);
-export const format = (q) => `${q.name} 5h=${show(q.five)} week=${show(q.week)}${q.note ? ` [${q.note}]` : ""}`;
+// 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.
+export const format = (q) => `${q.name} 5h=${show(q.five)} week=${show(q.week)}`
+    + (q.reset5h !== undefined ? ` reset5h=${q.reset5h}` : "") + (q.resetWeek !== undefined ? ` resetweek=${q.resetWeek}` : "")
+    + (q.span5h !== undefined ? ` span5h=${q.span5h}` : "") + (q.spanWeek !== undefined ? ` spanweek=${q.spanWeek}` : "")
+    + (q.note ? ` [${q.note}]` : "");
 const noData = (name, note) => ({ name, five: "?", week: "?", note });
+const WD = [["Sun", "dom"], ["Mon", "seg"], ["Tue", "ter"], ["Wed", "qua"], ["Thu", "qui"], ["Fri", "sex"], ["Sat", "sáb"]];
+/** A reset epoch (seconds) as "14:30" when it falls today, else weekday + time. */
+export function humanReset(epochSec, now = Date.now()) {
+    const d = new Date(epochSec * 1000), n = new Date(now);
+    const hhmm = `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+    if (d.toDateString() === n.toDateString())
+        return hhmm;
+    const [en, pt] = WD[d.getDay()];
+    return `${m(en, pt)} ${hhmm}`;
+}
 const KEEP_MS = 5 * 3600_000;
 const cacheFile = (name) => join(stateDir(), "quota", `${name}.json`);
-function remember(name, five, week) {
+const resetOf = (w) => {
+    const t = w.resetsAt ? Date.parse(w.resetsAt) : NaN;
+    return Number.isNaN(t) ? undefined : Math.floor(t / 1000);
+};
+// `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) {
     try {
-        writeAtomic(cacheFile(name), JSON.stringify({ five, week, at: Date.now() }));
+        writeAtomic(cacheFile(name), JSON.stringify({ five, week, at: Date.now(), ...(acct ? { acct } : {}) }));
     }
     catch { /* best effort */ }
-    return { name, five: five.pct, week: week.pct };
+    const r5 = resetOf(five), rw = resetOf(week);
+    return { name, five: five.pct, week: week.pct, ...(r5 !== undefined ? { reset5h: r5 } : {}), ...(rw !== undefined ? { resetWeek: rw } : {}) };
 }
 /** The cached reading (its age in the note), window by window; nothing usable → the "no data" line. */
-export function fromCache(name, why, now = Date.now()) {
+export function fromCache(name, why, now = Date.now(), acct) {
     try {
         const c = JSON.parse(readFileSync(cacheFile(name), "utf8"));
+        if (acct !== undefined && c.acct !== acct)
+            return noData(name, why); // another login's reading
         const still = (w) => {
             if (w.resetsAt) {
                 const t = Date.parse(w.resetsAt);
@@ -48,7 +75,10 @@ export function fromCache(name, why, now = Date.now()) {
         const five = still(c.five), week = still(c.week);
         if (five !== undefined && week !== undefined) {
             const min = Math.round((now - c.at) / 60_000);
-            return { name, five, week, note: `${why}; ` + m(`last reading, ${min} min ago`, `última leitura, há ${min} min`) };
+            const r5 = resetOf(c.five), rw = resetOf(c.week);
+            return { name, five, week, ...(r5 !== undefined && r5 * 1000 > now ? { reset5h: r5 } : {}),
+                ...(rw !== undefined && rw * 1000 > now ? { resetWeek: rw } : {}),
+                note: `${why}; ` + m(`last reading, ${min} min ago`, `última leitura, há ${min} min`) };
         }
     }
     catch { /* no cache */ }
@@ -143,10 +173,14 @@ export function codexFromSession(text, nowSec) {
         return undefined;
     const ws = [last.primary, last.secondary].filter((w) => !!w);
     const pct = (w) => !w ? "-" : (w.resets_at ?? 0) < nowSec ? 0 : Math.floor(w.used_percent ?? 0);
+    const reset = (w) => w?.resets_at !== undefined && w.resets_at >= nowSec ? w.resets_at : undefined;
     const short = ws.find((x) => (x.window_minutes ?? 0) <= 360);
     const long = ws.filter((x) => (x.window_minutes ?? 0) > 360).sort((a, b) => b.window_minutes - a.window_minutes)[0];
     const span = long && long.window_minutes !== 10080 ? long.window_minutes : undefined;
-    return { five: pct(short), week: pct(long), ...(span ? { span } : {}) };
+    const r5 = reset(short), rw = reset(long);
+    const span5 = short && short.window_minutes && short.window_minutes !== 300 ? short.window_minutes : undefined;
+    return { five: pct(short), week: pct(long), ...(span ? { span } : {}), ...(span5 ? { span5 } : {}), ...(r5 !== undefined ? { reset5h: r5 } : {}),
+        ...(rw !== undefined ? { resetWeek: rw } : {}) };
 }
 export function codexQuota() {
     const f = latestCodexSession();
@@ -156,9 +190,9 @@ export function codexQuota() {
     if (!q)
         return noData("codex", m("no limit data", "sem dados de limite"));
     const age = Math.round((Date.now() - statSync(f).mtimeMs) / 60_000);
-    const { span, ...pcts } = q;
+    const { span, span5, ...pcts } = q;
     const d = span && Math.round(span / 1440);
-    return { name: "codex", ...pcts, note: (d ? m(`${d}-day window in the week slot; `, `janela de ${d} dias no lugar da semana; `) : "")
+    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. */
@@ -179,7 +213,7 @@ export function antigravityFromModels(models, now = Date.now()) {
     }
     return { five, week };
 }
-function agyToken() {
+export function agyToken() {
     // agy (go-keyring) keeps {"token": {access_token, expiry, ...}} under service "gemini", user "antigravity"
     // (on Windows go-keyring names the credential "gemini:antigravity").
     const raw = readSecret("gemini", "antigravity", "gemini:antigravity");
@@ -187,21 +221,34 @@ function agyToken() {
         return undefined;
     try {
         const t = JSON.parse(raw).token;
-        return { access: t?.access_token, expiry: t?.expiry };
+        // The refresh token is stable for a login and differs between accounts (the access token rotates hourly).
+        const id = t?.refresh_token ?? t?.id_token;
+        return { access: t?.access_token, expiry: t?.expiry, refresh: !!t?.refresh_token,
+            ...(id ? { acct: createHash("sha256").update(String(id)).digest("hex").slice(0, 16) } : {}) };
     }
     catch {
         return undefined;
     }
 }
+/** Why the stored agy token can't be used as is: idle (expired, agy renews it on its next run) or login expired (no refresh token). */
+export function agyNote(t, now = Date.now()) {
+    const at = t.expiry ? Date.parse(t.expiry) : NaN;
+    if (Number.isNaN(at) || at >= now)
+        return undefined;
+    return t.refresh ? m("token idle (agy refreshes on next run)", "token ocioso (o agy renova no próximo uso)")
+        : m("login expired: run `agy models`", "login expirado: rode `agy models`");
+}
 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"));
-    // Never refresh it here (that is agy's login): an expired one just means "run agy once" (`agy models` is enough).
+    // 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`");
-    if (t.expiry && Date.parse(t.expiry) < Date.now())
-        return fromCache(name, expired);
+    const note = agyNote(t);
+    if (note)
+        return fromCache(name, note, undefined, t.acct);
     try {
         const r = await fetch("https://cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels", {
             method: "POST", body: "{}",
@@ -210,30 +257,45 @@ export async function antigravityQuota() {
             signal: AbortSignal.timeout(15_000),
         });
         if (r.status === 401)
-            return fromCache(name, expired);
+            return fromCache(name, expired, undefined, t.acct);
         if (!r.ok)
-            return fromCache(name, `HTTP ${r.status}`);
+            return fromCache(name, `HTTP ${r.status}`, undefined, t.acct);
         const j = await r.json();
         const { five, week } = antigravityFromModels(j.models ?? {});
-        return remember(name, five, week);
+        return remember(name, five, week, t.acct);
     }
     catch (e) {
-        return fromCache(name, m("collector failed", "coletor falhou") + `: ${e.message}`);
+        return fromCache(name, m("collector failed", "coletor falhou") + `: ${e.message}`, undefined, t.acct);
     }
 }
 // --- copilot --------------------------------------------------------------------------------------------------------
+/** The same moment one calendar month earlier; a day the month lacks (31 Mar → Feb) clamps to its last day. */
+export function monthBefore(d) {
+    const out = new Date(d);
+    out.setDate(1);
+    out.setMonth(out.getMonth() - 1);
+    out.setDate(Math.min(d.getDate(), new Date(out.getFullYear(), out.getMonth() + 1, 0).getDate()));
+    return out;
+}
 /** Premium requests used this month, from the snapshot `gh api /copilot_internal/user` returns. No 5h window. */
 export function copilotFromUser(j) {
     const u = j;
     const p = u?.quota_snapshots?.premium_interactions;
     if (!p)
         return noData("copilot", m("no premium request data", "sem dados de requisições premium"));
+    // A bare date ("2026-11-01") would parse as UTC midnight: local midnight matches the date the note itself shows
+    // (same fix as parseLocal in commands/block.ts).
+    const at = u.quota_reset_date
+        ? Date.parse(/^\d{4}-\d{2}-\d{2}$/.test(u.quota_reset_date) ? `${u.quota_reset_date}T00:00` : u.quota_reset_date)
+        : NaN;
+    const prev = Number.isNaN(at) ? new Date(NaN) : monthBefore(new Date(at));
+    const resetWeek = Number.isNaN(at) ? {} : { resetWeek: Math.floor(at / 1000), spanWeek: Math.round((at - prev.getTime()) / 60_000) };
     if (p.unlimited)
         return { name: "copilot", five: "-", week: "-", note: m("unlimited", "ilimitado") };
     if (typeof p.percent_remaining !== "number")
         return noData("copilot", m("no premium request data", "sem dados de requisições premium"));
     const reset = u.quota_reset_date ? m(`, resets ${u.quota_reset_date}`, `, renova em ${u.quota_reset_date}`) : "";
-    return { name: "copilot", five: "-", week: Math.max(0, 100 - p.percent_remaining),
+    return { name: "copilot", five: "-", week: Math.max(0, 100 - p.percent_remaining), ...resetWeek,
         note: m("monthly premium requests", "requisições premium do mês") + reset };
 }
 export function copilotQuota() {
@@ -266,7 +328,7 @@ export function minimaxFromRemains(j) {
     return { five: worst("current_interval_remaining_percent", "end_time"),
         week: worst("current_weekly_remaining_percent", "weekly_end_time") };
 }
-function minimaxKey() {
+export function minimaxKey() {
     if (process.env.MINIMAX_API_KEY)
         return process.env.MINIMAX_API_KEY;
     const data = process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share");

package/dist/rounds.js

@@ -0,0 +1,167 @@
+// Watchdog layer 1: per-issue round metrics from the files already in .orquestra/<ID>/, no LLM and no extra recording.
+//   fix-<n>.md                    the blockers sent to the implementer in fix round n (its mtime = the round started)
+//   review-<repo>.out.md          the first review (round 0);  review-<repo>-<n>.out.md  the review after fix round n
+// Rounds = highest fix-<n> (or the .rounds-<session> counter `orq agent -R` keeps). Findings are the tagged list items
+// of each review ("- [blocker] src/a.ts:10 title", or a leading bold severity word in PT/EN: "1. **Bloqueante** — ...",
+// "- **Sugestão — `a.ts:7–8`:** ..."; "**Critério 1**" is not one). Files may be markdown links; a ".worktrees/<dir>/" prefix is
+// stripped so a file matches across rounds. A finding "repeats" when a later review has one on the same file
+// with similar words (token overlap, see similar()).
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+export const SIMILAR_FILE = 0.4; // token overlap needed when both findings name the same file
+export const SIMILAR_LOOSE = 0.6; // ... when a file is missing on either side
+export const SLOW_FACTOR = 2; // a round this many times slower than the median of the others is flagged
+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 HEAVY = new Set(["blocker", "major", "critical"]); // only these count towards repeats and the alert
+const read = (f) => { try {
+    return readFileSync(f, "utf8");
+}
+catch {
+    return "";
+} };
+const STOP = new Set(["the", "a", "an", "of", "in", "on", "to", "is", "are", "and", "or", "for", "with", "not", "no", "this", "that", "it",
+    "de", "do", "da", "o", "os", "as", "um", "uma", "em", "no", "na", "para", "com", "que", "se", "não"]);
+const words = (s) => new Set(s.toLowerCase().replace(/[^\p{L}\p{N}_]+/gu, " ").split(" ").filter((w) => w.length > 2 && !STOP.has(w)));
+const SEV = {
+    bloqueante: "blocker", bloqueador: "blocker", blocker: "blocker", critico: "critical", critical: "critical",
+    importante: "major", important: "major", major: "major", menor: "minor", minor: "minor",
+    sugestao: "suggestion", suggestion: "suggestion", nit: "nit",
+};
+const fold = (w) => w.normalize("NFD").replace(/\p{M}/gu, "").toLowerCase();
+const URL = /^[a-z][a-z0-9+.-]*:\/\//i;
+// GitHub-style ".../blob/<ref>/<path>" → "<path>" (no query, no #L4), so URL mentions match plain-path mentions.
+const blobPath = (u) => /^[a-z][a-z0-9+.-]*:\/\/[^/]+\/[^/]+\/[^/]+\/blob\/[^/]+\/([^#?\s)]+)/i.exec(u)?.[1];
+const LINK = /\[([^\]]*)\]\(([^)\s]*)\)/g;
+// Reviews run in a different worktree per round (".worktrees/<repo>-<id>.review-<pid>/"): drop it so the same file matches across rounds.
+const repoRel = (f) => f.replace(/\\/g, "/").replace(/^.*\.worktrees\/[^/]+\//, "");
+/** One review-list item → finding. Only items carrying a severity (a "[blocker]" tag or a leading bold "**Bloqueante**") count. */
+export function parseFindings(text, round) {
+    const out = [];
+    for (const line of text.split("\n")) {
+        const it = /^\s*(?:[-*+]|\d+[.)])\s+(.*)$/.exec(line);
+        if (!it)
+            continue;
+        const sevOf = (w) => { const k = fold(w ?? ""); return Object.hasOwn(SEV, k) ? SEV[k] : undefined; };
+        let m0 = /^\*\*\s*(\p{L}+)/u.exec(it[1]); // a leading bold severity wins over a [tag]
+        if (!sevOf(m0?.[1]))
+            m0 = /\[(blocker|major|minor|nit|suggestion|important|critical)\]/i.exec(it[1]);
+        const sev = sevOf(m0?.[1]);
+        if (!m0 || !sev)
+            continue;
+        const rest = it[1].replace(m0[0], " ");
+        const byTarget = rest.replace(LINK, (_, t, p) => ` ${URL.test(p) ? blobPath(p) ?? t : repoRel(p)} `)
+            .replace(/[a-z][a-z0-9+.-]*:\/\/\S+/gi, (u) => ` ${blobPath(u) ?? ""} `);
+        const m = /([\w@./\\-]+\.\w+)(?::\d+(?:[-\u2013]\d+)?)?/.exec(byTarget);
+        const file = m ? repoRel(m[1]) : "";
+        out.push({ round, severity: sev, file, title: rest.replace(LINK, "$1").replace(/[`*_]/g, "").replace(/\s+/g, " ").trim() });
+    }
+    return out;
+}
+/** Same finding? Same file (when both name one) and enough shared words; without a file, a stricter overlap. */
+export function similar(a, b) {
+    const wa = words(a.title), wb = words(b.title);
+    if (!wa.size || !wb.size)
+        return false;
+    let inter = 0;
+    for (const w of wa)
+        if (wb.has(w))
+            inter++;
+    const j = inter / (wa.size + wb.size - inter), both = a.file && b.file;
+    if (both && a.file !== b.file)
+        return false;
+    return j >= (both ? SIMILAR_FILE : SIMILAR_LOOSE);
+}
+/** Findings that reappear in more than one round. Each group is matched against its first member. */
+export function repeats(fs) {
+    const groups = [];
+    for (const f of [...fs].sort((a, b) => a.round - b.round)) {
+        const g = groups.find((x) => similar(x[0], f));
+        if (g)
+            g.push(f);
+        else
+            groups.push([f]);
+    }
+    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);
+}
+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) {
+    const per = all.filter((r) => r.round > 0);
+    if (per.length < 3)
+        return [];
+    return per.filter((r) => r.secs >= SLOW_MIN_SECS && r.secs > SLOW_FACTOR * median(per.filter((x) => x !== r).map((x) => x.secs))).map((r) => r.round);
+}
+/** 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 = [];
+    let level = "ok";
+    const raise = (l, why) => { reasons.push(why); if (l === "stop" || level === "ok")
+        level = l; };
+    if (f.rounds > f.max)
+        raise("stop", { code: "over_max", n: f.rounds, max: f.max });
+    else if (f.rounds >= f.max && f.max > 0)
+        raise("warn", { code: "at_max", n: f.rounds, max: f.max });
+    const worst = Math.max(0, ...reps.map((r) => r.rounds.length));
+    if (worst >= REPEAT_STOP)
+        raise("stop", { code: "same_finding", n: worst });
+    else if (reps.length)
+        raise("warn", { code: "repeated", n: reps.length });
+    const slow = slowRounds(f.perRound);
+    if (slow.length)
+        raise("warn", { code: "slow", n: slow.length, rounds: slow });
+    return { issue, rounds: f.rounds, max: f.max, secs: f.secs, perRound: f.perRound, findings: f.findings.length, repeats: reps, level, reasons };
+}
+/** 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);
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return undefined;
+    }
+    const mt = (n) => statSync(join(dir, n)).mtimeMs;
+    const fixes = new Map(), reviews = new Map();
+    let counter = 0;
+    for (const n of names) {
+        const fx = /^fix-(\d+)\.md$/.exec(n);
+        if (fx)
+            fixes.set(Number(fx[1]), mt(n));
+    }
+    for (const n of names) {
+        // A trailing -<n> is a round only when fix-<n>.md exists; otherwise it is part of the repo name (round 0).
+        const rv = /^review-(.+?)(?:-(\d+))?\.out\.md$/.exec(n), k = rv && rv[2] !== undefined && fixes.has(Number(rv[2])) ? Number(rv[2]) : 0;
+        if (rv)
+            reviews.set(k, [...(reviews.get(k) ?? []), n]);
+        else if (n.startsWith(".rounds-"))
+            counter = Math.max(counter, Number(read(join(dir, n))) || 0);
+    }
+    if (!reviews.size && !fixes.size)
+        return undefined;
+    const rounds = Math.max(counter, 0, ...fixes.keys());
+    const all = names.filter((n) => !n.startsWith(".")).map(mt), t0 = Math.min(...all), t1 = Math.max(...all);
+    // Round k runs from fix-k.md (round 0: the oldest file) to the next fix, the last one to the newest file.
+    const starts = [t0, ...Array.from({ length: rounds }, (_, i) => fixes.get(i + 1) ?? NaN)];
+    const perRound = starts.map((s, k) => {
+        const next = k < rounds ? starts[k + 1] : t1;
+        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) });
+}
+/** Cheap change signature of an issue folder (names + mtimes, no reads) for caching collectRounds between redraws. */
+export function roundsSig(ws, issue) {
+    const dir = join(ws, ".orquestra", issue);
+    try {
+        return readdirSync(dir).filter((n) => /^(fix-\d+\.md|review-.+\.out\.md|\.rounds-.+)$/.test(n)).map((n) => `${n}:${statSync(join(dir, n)).mtimeMs}`).join("|");
+    }
+    catch {
+        return "";
+    }
+}
+/** Board marker: "r2/2 ⚠", "r3/2 ✗"; just "r1/2" when ok. */
+export const mark = (x) => `r${x.rounds}/${x.max}${x.level === "warn" ? " ⚠" : x.level === "stop" ? " ✗" : ""}`;

package/dist/terminal.js

@@ -3,6 +3,7 @@
 //   tmux   a background window in the current tmux session
 //   plain  a detached background process; its screen output goes to <state dir>/agents/<run>.log
 // auto = herdr inside a herdr pane (HERDR_PANE_ID), else tmux inside tmux (TMUX), else plain.
+// The agent's own screen (-T) needs herdr or tmux; follow-ups are typed into it while it is open.
 import { spawn, spawnSync } from "node:child_process";
 import { closeSync, mkdirSync, openSync } from "node:fs";
 import { join } from "node:path";
@@ -69,6 +70,31 @@ export function launch(host, l) {
     closeSync(fd);
     return `pid:${c.pid}`;
 }
+/** Is the screen `launch` returned still open? (herdr pane or tmux pane; a background pid has no screen) */
+export function screenOpen(where) {
+    if (where.startsWith("tmux:"))
+        return spawnSync("tmux", ["display-message", "-p", "-t", where.slice(5), "#{pane_id}"], { stdio: "ignore" }).status === 0;
+    if (!where || where.startsWith("pid:"))
+        return false;
+    return spawnSync("herdr", ["pane", "get", where], { stdio: "ignore" }).status === 0;
+}
+/** Type `text` into an open screen and submit it (a follow-up to an agent's own TUI). */
+export function typeInto(where, text) {
+    if (where.startsWith("tmux:")) {
+        // A bracketed paste keeps a multi-line prompt as one message; then Enter sends it.
+        const t = where.slice(5), run = (a, input) => {
+            const r = spawnSync("tmux", a, { input, encoding: "utf8" });
+            if (r.status !== 0)
+                throw new Error(`tmux ${a[0]}: ${(r.stderr || "").trim()}`);
+        };
+        run(["load-buffer", "-b", "orq-prompt", "-"], text);
+        run(["paste-buffer", "-p", "-d", "-b", "orq-prompt", "-t", t]);
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 300); // let the TUI take the paste before Enter
+        run(["send-keys", "-t", t, "Enter"]);
+        return;
+    }
+    herdr(["agent", "prompt", where, text]);
+}
 /** After a run: close our own herdr tab (the result stays in the files). tmux windows close when the runner exits. */
 export function closeOwnTab(host) {
     const p = process.env.HERDR_PANE_ID;

package/dist/testrun.js

@@ -2,13 +2,14 @@
 // memory cap (src/process.ts) and read its JSON report into "<file relative to the repo> :: <full test name>" lines.
 // The runner's own bin (node_modules/<runner>/package.json "bin") runs with this node, so Windows needs no shell;
 // without it, npx as before. Also the background job both share (launch on a TerminalHost, queue, .pid/.done, notify).
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { createWriteStream, existsSync, lstatSync, readFileSync, realpathSync, rmdirSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { writeAtomic } from "./fsutil.js";
 import { m } from "./i18n.js";
 import { acquire, release } from "./lock.js";
+import { stateDir } from "./paths.js";
 import { killTree, parseSize, runCapped } from "./process.js";
 import { closeOwnTab, detectHost, launch } from "./terminal.js";
 export const JS_EXT = /\.(ts|tsx|js|jsx|mjs|cjs|mts|cts)$/;
@@ -196,8 +197,28 @@ export async function inJob(j, label, slots, body, done) {
     }
     return st === "ok" ? 0 : 1;
 }
-/** The conductor is a herdr pane: type the line into it (herdr-notify waits for it to leave a dialog). */
-export function notify(pane, line) {
-    const local = join(dirname(CLI), "..", "setup", "herdr-notify");
-    spawnSync(existsSync(local) ? local : "herdr-notify", [pane, line], { stdio: "inherit" });
+/** Where `orq handoff` records the pane that replaced a conductor's. */
+export const handoffFile = (pane) => join(stateDir(), "handoff", pane.replace(/\W/g, "_"));
+/** The conductor is a herdr pane: type the line into it (herdr-notify waits for it to leave a dialog). In the
+ * background when the caller must not wait for that (an agent's end-of-turn hook holds its screen meanwhile). */
+export function notify(pane, line, background = false) {
+    const seen = new Set();
+    while (!seen.has(pane) && existsSync(handoffFile(pane))) {
+        seen.add(pane);
+        let next;
+        try {
+            next = readFileSync(handoffFile(pane), "utf8").trim();
+        }
+        catch {
+            break;
+        } // gone between the two calls
+        if (!next || next === pane)
+            break;
+        pane = next; // follow repeated handoffs to the current conductor
+    }
+    const local = join(dirname(CLI), "..", "setup", "herdr-notify"), cmd = existsSync(local) ? local : "herdr-notify";
+    if (background)
+        spawn(cmd, [pane, line], { detached: true, stdio: "ignore" }).on("error", () => { }).unref();
+    else
+        spawnSync(cmd, [pane, line], { stdio: "inherit" });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@irythill/orq",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Orchestrate coding agents (Claude Code, Codex, OpenCode, Antigravity, Copilot) from one conductor.",
   "license": "MIT",
   "type": "module",

package/skills/issue/SKILL.md

@@ -15,7 +15,7 @@ start. Below, `$WS` = workspace.
 **Inside herdr** (`HERDR_ENV=1`): children open in herdr tabs and their notices reach your pane — the flow below.
 **Outside herdr** (any terminal, tmux, any OS): the same flow with these swaps —
 - `herdr-agent ...` → `orq agent ...` (same flags; it is the same program). Children run in tmux windows inside tmux,
-  else in the background (their screen goes to a log; the answer is still `<prefix>.out.md`). No `-T`.
+  else in the background (their screen goes to a log; the answer is still `<prefix>.out.md`). `-T` needs tmux.
 - `herdr-claim` → `orq claim` (set `ORQ_CONDUCTOR_ID` to a fixed name per conductor), `herdr-deps` → `orq deps`.
 - **Completion signal:** no line arrives in your pane. After dispatching, run `orq wait <prefix>` **as a background
   task** (Claude Code: Bash with `run_in_background`); its exit wakes you and its output is the line
@@ -30,7 +30,15 @@ Issue artifacts (prompts, notes) live in `$WS/.orquestra/<ID>/`.
 ## 1. Read the issue
 - **First, claim it:** `herdr-claim -w $WS <ID>`. Exit 1 = another conductor owns it: **stop** and tell the user
   (don't read it, don't dispatch anything). Taking it over (e.g. switching accounts) only with the user's OK:
-  `herdr-claim -w $WS -f <ID>`. Several conductors may share a workspace; `herdr-claim -w $WS -l` lists who has what.
+  `herdr-claim -w $WS -f <ID>`. Several conductors may share a workspace; `herdr-claim -w $WS -l` lists who has what,
+  with each conductor's name (its herdr workspace label, e.g. "emp: orq-cms-dsgn"; outside herdr, `ORQ_CONDUCTOR_ID`).
+- **The user names another conductor** ("take over orq-cms-dsgn's work"): never guess a pane id. Run
+  `orq claim -w $WS --from "<what they said>"` (any part of the name works). It lists that conductor's issues; exit 3 =
+  the name matches more than one conductor (show the list, ask which); exit 1 = none. With the user's OK,
+  `orq claim -w $WS --from "<name>" -f` takes them all. **Resuming** an issue someone else started: don't start over.
+  Read `$O/` first — `impl-<repo>.md`/`.out.md` (prompt, answer, `## Decisions`), `.pick` files, the last
+  `fix-<n>.md` and `review-<repo>.out.md`, `verify-<repo>.txt` — and the Plane comments, then go on from the step the
+  files show (a `.pane`/`.id` without `.done` = a child still running: `orq wait` for it instead of dispatching again).
 - `mcp__plane__workitem` `retrieve_by_identifier` with `workitem_identifier: "<ID>"`; then `workitem_comment list`.
 - Extract: goal, **acceptance criteria**, affected repos, links. No acceptance criteria → write a short proposal and
   **ask the user** before dispatching.
@@ -44,6 +52,14 @@ One task per repo. Level:
 - **medium** — business rule, API↔front integration, several files.
 - **heavy** — architecture, data migration, hard/concurrency bug, security.
 
+**Scope check, before dispatching.** Estimate the size. Split into sub-issues or sequential batches (each its own PR)
+when it touches several unrelated areas, changes roughly >400 lines, mixes refactor with behavior change, or has
+independent acceptance criteria.
+- Each batch is independently testable and reviewable; dispatch in order, one implementer per batch. Record the split in
+  Plane (sub-issues or a checklist comment) before starting.
+- Scope too big mid-run (reviews hitting `policy.max_rounds`, repeated findings, the implementer asking to change
+  scope): stop, split the remainder, don't force more rounds.
+
 ## 3. Pick agent and model: always `orq pick`, never by hand
 `orq pick` decides agent, model, effort and account (user config + delivery and token history + current quota +
 rotation). **Do not choose by preference, by a rule you read elsewhere, or by what worked last time**: run it before
@@ -51,8 +67,10 @@ EVERY dispatch (implementation, review, second opinion) and use its output verba
 ```bash
 orq pick impl --level simple|medium|heavy                          # → e.g. -a codex -m gpt-6-sol -e low
 orq pick review --level <level> --impl-agent <agent that implemented>   # → another vendor, e.g. -a opencode -m ...
-orq pick opinion                                                   # second opinion (e.g. Copilot), see step 5
+orq pick opinion --impl-agent <agent that implemented>             # second opinion (e.g. Copilot), see step 5
 ```
+More than one agent eligible for `review`/`opinion` (declared, not excluded or blocked, with a model for the role; quota is not considered) and neither `--impl-agent` nor `--impl-vendor` given → exit 2:
+always pass one of them (`--no-record`/`--explain` do not change this).
 The output goes straight into `herdr-agent` (`herdr-agent $(orq pick ...) -g ... -t ... -d ... -o ... -- prompt.md`).
 - Exit 3 = no candidate (quota exhausted, no agent with that role): **stop and ask the user**.
 - Implementer failed review twice (step 6) → pick again without it: `orq pick impl --level <level> --exclude-agent <agent>`.
@@ -64,10 +82,10 @@ The output goes straight into `herdr-agent` (`herdr-agent $(orq pick ...) -g ...
 `opencode run` / `agy -p` / `copilot -p`) in a herdr tab (workspace = group `-g`, tab = title) with live output.
 When it finishes it writes `<prefix>.done` and sends ONE line `[HERDR-AGENT DONE] <title> status=ok|fail ...` to your
 pane; no MCP, and a **4 GB memory cap per agent** (own cgroup: if it blows up, only it dies). NEVER `herdr agent start`
-for children (no memory cap, no answer file). **Screen mode (`-T`, or `HERDR_AGENT_TUI=1`):** the tab shows the
-agent's own TUI instead of the log; same cap, same files, same signal (end-of-turn hook). The screen stays open after
-the turn (it holds memory until the tab closes); `-R` with the tab open types the follow-up into it. Use it when the
-user wants to watch. The repo must already be trusted in Codex/Claude (otherwise the TUI stops at the "trust this
+for children (no memory cap, no answer file). **Screen mode (`-T`, or `HERDR_AGENT_TUI=1`; herdr or tmux):** the tab
+shows the agent's own TUI instead of the log; same cap, same files, same signal (end-of-turn hook). The screen stays
+open after the turn (it holds memory until the tab closes); `-R` with the tab open types the follow-up into it. Use it
+when the user wants to watch. The repo must already be trusted in Codex/Claude (otherwise the TUI stops at the "trust this
 folder?" dialog — tell the user, don't approve it for them).
 
 ## 4. Dispatch the implementer
@@ -108,7 +126,7 @@ tell me".
 orq pick impl --level <level> > $O/impl-<repo>.pick    # the fix rounds reuse it (step 6)
 herdr-agent $(cat $O/impl-<repo>.pick) -g <group> -t "<ID> impl <repo>" -d $WT -o $O/impl-<repo> -- $O/impl-<repo>.md
 ```
-- The Claude account (`-c`) already comes from `orq pick` (the least used one under the limit).
+- 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).
 - `herdr-agent` returns immediately (no need to background it); the child's pane is in `<prefix>.pane`
@@ -161,6 +179,13 @@ are in the attached verify)". If the reviewer ends with `status=fail` and no ver
 `--exclude-agent` applies **only to redoing that review** (save the new pick to `review-<repo>.pick`); the next
 round reuses whoever gave the verdict. An agent that failed twice in a row with no verdict →
 `orq block <agent> --days 1` and tell the user.
+**Review tools** (an agent whose `run` has no `{prompt}`/`{prompt_text}`/stdin, e.g. a CodeRabbit-like CLI with
+`ok_exit`/`filter` in the config): same command; it ignores the prompt and the attachments and reviews the branch
+against `{base}` itself. Read its answer like any other: `status=ok` with `rc≠0` is a verdict with findings, not a
+failure. Its high-severity items are the blockers, still under the step 6 rule (`file:line` + concrete failure).
+If the tool's answer opens with (or, when short, consists of) a statement that nothing was reviewed (e.g. Corvus's "Nada para revisar"), `agents.<name>.no_review` (a
+regex) makes `orq agent` end that run `status=fail`: `orq pick`'s fallback and the conductor treat it as not run,
+same as an empty answer.
 **Second opinion** (`orq pick opinion`, read only, same attachments): only on **heavy** issues or when reviewer and
 implementer disagree about a blocker. It never becomes a round by itself: you weigh both answers and decide.
 **Before dispatching:** `git -C $R fetch origin $BASE; git -C $WT merge-base --is-ancestor origin/$BASE HEAD` — if it
@@ -180,7 +205,7 @@ repo checklist.
 **Only `[blocker]` items open a round.** An item tagged blocker without `file:line` and a concrete failure, or that
 only restates a `## Decisions` choice, counts as a suggestion; when you downgrade one, say why in the Plane comment.
 No blockers left → APPROVED, even with suggestions.
-Blocking problems → write the list (blockers only) to `$O/fix-<n>.md` and continue the implementer's session (any agent):
+Blocking problems → write the list (blockers only) to `$O/fix-<n>.md` (always this name; reviews `$O/review-<repo>-<n>`, never `fix<n>-<repo>` or other variants — a later conductor counts rounds by these files) and continue the implementer's session (any agent):
 `herdr-agent $(orq pick fix --same $O/impl-<repo>.pick) -g <group> -t "<ID> fix<n> <repo>" -d $WT -o $O/impl-<repo> -R $(cat $O/impl-<repo>.id) -- $O/fix-<n>.md`.
 A fix is a continuation: same agent, model, account and session, effort one level up (`--same` reads the implementer's
 pick; never a new `orq pick`, never `-a` alone — without `-m` the session resumes on the CLI's default model, which
@@ -196,10 +221,18 @@ Then a new `herdr-verify` (4b) and the **round review** (step 5 with these chang
   (the full `-b $BASE` diff stays, as context).
 - 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. **Maximum: `orq config get policy.max_rounds` rounds**; 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. 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, `-F` only with their OK; 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.
 
+## Screenshots / visual validation
+Only when the issue asks for it. **One** attempt (a job with `--effort low`, a short prompt that says which screens and
+where to save the images), at most ~6 images, and read them only as files you need to judge — never re-read the same
+image. If it fails, tell the user instead of dispatching a second `shots` job. Playwright runs inside that child's
+worktree, never as an MCP in the conductor (images in the conductor's context are re-billed every turn).
+
 ## 7. Close
 **Commit/PR conventions belong to the repo, not to you.** The **implementer, in the worktree** (where the repo's
 rules live) commits and writes the PR. Find and cite in the prompt, by path, whatever the repo has:
@@ -212,6 +245,10 @@ rules live) commits and writes the PR. Find and cite in the prompt, by path, wha
   issue) and the answer in `$O/impl-<repo>.out.md`. Check the opened PR against the template.
 - Plane comment (`workitem_comment create`): summary, repo(s), branch, agents and models used (`orq pick` output),
   review result, checks that ran.
+- **Review bots on the PR** (a GitHub App reviewer): one more input, not a new review cycle. Only a finding with
+  high severity, `file:line` and a concrete failure, not already decided in the rounds, goes into a fix round (it
+  counts towards `policy.max_rounds`); the rest goes into the Plane comment or a follow-up issue. Don't re-request the
+  bot's review to "get it clean".
 - **CI after every push:** `gh pr checks <n>` (no `--watch`; if pending, end your turn and check on the next notice).
   Red → `gh run view <id> --log-failed | tail -40`: error from the diff → fix round; error already on the base → create
   a Plane issue (workspace standard) and tell the user. "Ready to merge" only with green checks or an explained failure

package/skills/orq-setup/SKILL.md

@@ -61,7 +61,7 @@ Offer `$ORQ/examples/irythill/config.toml` as an example, saying clearly **it is
 
 ## 4. Policy
 Explain simply, then suggest the example's values and ask if they want to change any:
-- `quota_limit` (90): an agent at or above this % of its 5h/weekly quota is left out.
+- `quota_week` (95) and `quota_5h` (simple 90, medium 85, heavy 80): an agent at or above these % is left out.
 - weights — already suggested by `orq setup` from the parallel tasks: `quality` (did it deliver?), `tokens` (spent
   little?), `speed` (finished fast?), `rotation` (penalty for being picked recently, spreads the work).
 - `max_rounds` (2) review rounds before handing back; `machine.agent_mem_max` / `test_mem_max` come from `orq setup`