@irythill/orq 0.0.0-stage → 0.2.0

package/dist/quota.js

@@ -0,0 +1,334 @@
+// Quota per agent/account, from the sources in the [quota] config section:
+//   "builtin"            claude: the account's usage (Anthropic OAuth usage endpoint, same login Claude Code uses)
+//                        codex:  the rate_limits Codex writes into its latest session file
+//                        antigravity: per-model quota from Cloud Code (fetchAvailableModels), with the login agy keeps
+//                                 in the OS keyring (src/keyring.ts: Secret Service, Keychain, Credential Manager)
+//                        opencode: the MiniMax Token Plan (/v1/token_plan/remains) with $MINIMAX_API_KEY or the key
+//                                 OpenCode keeps in its auth.json; $MINIMAX_API_HOST for the China region
+//                        copilot: premium requests left this month (`gh api /copilot_internal/user`; a monthly
+//                                 allowance, shown in the week slot)
+//   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]".
+//   -  = the plan has no such window (not limiting);  ? = no data (expired login, collector failed).
+import { spawnSync } from "node:child_process";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { join } from "node:path";
+import { claudeAccounts } from "./accounts.js";
+import { writeAtomic } from "./fsutil.js";
+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}]` : ""}`;
+const noData = (name, note) => ({ name, five: "?", week: "?", note });
+const KEEP_MS = 5 * 3600_000;
+const cacheFile = (name) => join(stateDir(), "quota", `${name}.json`);
+function remember(name, five, week) {
+    try {
+        writeAtomic(cacheFile(name), JSON.stringify({ five, week, at: Date.now() }));
+    }
+    catch { /* best effort */ }
+    return { name, five: five.pct, week: week.pct };
+}
+/** 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()) {
+    try {
+        const c = JSON.parse(readFileSync(cacheFile(name), "utf8"));
+        const still = (w) => {
+            if (w.resetsAt) {
+                const t = Date.parse(w.resetsAt);
+                if (!Number.isNaN(t))
+                    return t > now ? w.pct : 0;
+            }
+            return now - c.at < KEEP_MS ? w.pct : undefined;
+        };
+        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`) };
+        }
+    }
+    catch { /* no cache */ }
+    return noData(name, why);
+}
+function claudeToken(dir) {
+    try {
+        return JSON.parse(readFileSync(join(dir, ".credentials.json"), "utf8")).claudeAiOauth;
+    }
+    catch { /* not in a file: macOS keeps it in the Keychain */ }
+    if (process.platform !== "darwin")
+        return undefined;
+    try {
+        return JSON.parse(readSecret("Claude Code-credentials", userInfo().username) ?? "").claudeAiOauth;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function claudeQuota(name, dir) {
+    const t = claudeToken(dir);
+    if (!t?.accessToken)
+        return noData(name, m("not logged in", "sem login"));
+    // Never refresh the token here (that would rotate Claude Code's login): an expired one just means "open claude".
+    if (t.expiresAt && t.expiresAt < Date.now())
+        return noData(name, m("login expired: open claude once", "login expirado: abra o claude uma vez"));
+    try {
+        const r = await fetch("https://api.anthropic.com/api/oauth/usage", {
+            headers: { Authorization: `Bearer ${t.accessToken}`, "anthropic-beta": "oauth-2025-04-20" },
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (r.status === 401)
+            return noData(name, m("login expired: open claude once", "login expirado: abra o claude uma vez"));
+        if (!r.ok)
+            return fromCache(name, `HTTP ${r.status}`);
+        const j = await r.json();
+        const win = (w) => ({ pct: typeof w?.utilization === "number" ? w.utilization : "-",
+            ...(typeof w?.resets_at === "string" ? { resetsAt: w.resets_at } : {}) });
+        return remember(name, win(j.five_hour), win(j.seven_day));
+    }
+    catch (e) {
+        return fromCache(name, m("collector failed", "coletor falhou") + `: ${e.message}`);
+    }
+}
+// --- codex ----------------------------------------------------------------------------------------------------------
+function latestCodexSession() {
+    const root = join(process.env.CODEX_HOME ?? join(homedir(), ".codex"), "sessions");
+    let best;
+    const walk = (d, depth) => {
+        let entries;
+        try {
+            entries = readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const p = join(d, e.name);
+            if (e.isDirectory() && depth < 3)
+                walk(p, depth + 1);
+            else if (e.isFile() && e.name.endsWith(".jsonl")) {
+                const t = statSync(p).mtimeMs;
+                if (!best || t > best.t)
+                    best = { f: p, t };
+            }
+        }
+    };
+    walk(root, 0);
+    return best?.f;
+}
+/** The last rate_limits in a Codex session (.jsonl): a window up to 6 h = 5h; the longest one over that (10080 = week,
+ *  43200 on the free plan = 30 days) fills the week slot, with `span` (minutes) when it isn't a week; reset → 0. */
+export function codexFromSession(text, nowSec) {
+    let last;
+    for (const line of text.split("\n")) {
+        if (!line.includes('"rate_limits"'))
+            continue;
+        try {
+            const find = (o) => {
+                if (o && typeof o === "object") {
+                    const r = o.rate_limits;
+                    if (r && typeof r === "object")
+                        last = r;
+                    Object.values(o).forEach(find);
+                }
+            };
+            find(JSON.parse(line));
+        }
+        catch { /* partial line */ }
+    }
+    if (!last)
+        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 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 } : {}) };
+}
+export function codexQuota() {
+    const f = latestCodexSession();
+    if (!f)
+        return noData("codex", m("no Codex session yet", "nenhuma sessão do Codex ainda"));
+    const q = codexFromSession(readFileSync(f, "utf8"), Date.now() / 1000);
+    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 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; `) : "")
+            + 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. */
+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)
+            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;
+        }
+    }
+    return { five, week };
+}
+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");
+    if (!raw)
+        return undefined;
+    try {
+        const t = JSON.parse(raw).token;
+        return { access: t?.access_token, expiry: t?.expiry };
+    }
+    catch {
+        return undefined;
+    }
+}
+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).
+    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);
+    try {
+        const r = await fetch("https://cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels", {
+            method: "POST", body: "{}",
+            // The endpoint answers 403 without a client User-Agent.
+            headers: { Authorization: `Bearer ${t.access}`, "Content-Type": "application/json", "User-Agent": "antigravity" },
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (r.status === 401)
+            return fromCache(name, expired);
+        if (!r.ok)
+            return fromCache(name, `HTTP ${r.status}`);
+        const j = await r.json();
+        const { five, week } = antigravityFromModels(j.models ?? {});
+        return remember(name, five, week);
+    }
+    catch (e) {
+        return fromCache(name, m("collector failed", "coletor falhou") + `: ${e.message}`);
+    }
+}
+// --- copilot --------------------------------------------------------------------------------------------------------
+/** 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"));
+    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),
+        note: m("monthly premium requests", "requisições premium do mês") + reset };
+}
+export function copilotQuota() {
+    const r = spawnSync("gh", ["api", "/copilot_internal/user"], { encoding: "utf8", timeout: 15_000 });
+    if (r.error || r.status !== 0)
+        return noData("copilot", m("gh api failed (gh auth login?)", "gh api falhou (gh auth login?)"));
+    try {
+        return copilotFromUser(JSON.parse(r.stdout));
+    }
+    catch {
+        return noData("copilot", m("collector failed", "coletor falhou"));
+    }
+}
+/** Worst usage per window across the plan's models (remaining % → used %); resets from the windows' end times. */
+export function minimaxFromRemains(j) {
+    const ms = j?.model_remains ?? [];
+    if (!ms.length)
+        return undefined;
+    const worst = (pct, end) => {
+        let w = { pct: "-" };
+        for (const x of ms) {
+            if (typeof x[pct] !== "number")
+                continue;
+            const used = 100 - x[pct];
+            if (w.pct === "-" || used > w.pct)
+                w = { pct: used, ...(typeof x[end] === "number" ? { resetsAt: new Date(x[end]).toISOString() } : {}) };
+        }
+        return w;
+    };
+    return { five: worst("current_interval_remaining_percent", "end_time"),
+        week: worst("current_weekly_remaining_percent", "weekly_end_time") };
+}
+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");
+    try {
+        return JSON.parse(readFileSync(join(data, "opencode", "auth.json"), "utf8")).minimax?.key;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function minimaxQuota(name) {
+    const key = minimaxKey();
+    // OpenCode may run another provider: without a MiniMax key there is nothing to limit.
+    if (!key)
+        return { name, five: "-", week: "-", note: m("no MiniMax key", "sem chave da MiniMax") };
+    try {
+        const host = process.env.MINIMAX_API_HOST ?? "api.minimax.io";
+        const r = await fetch(`https://${host}/v1/token_plan/remains`, {
+            headers: { Authorization: `Bearer ${key}` }, signal: AbortSignal.timeout(15_000)
+        });
+        if (!r.ok)
+            return fromCache(name, `HTTP ${r.status}`);
+        const j = await r.json();
+        if (j.base_resp?.status_code)
+            return fromCache(name, `MiniMax ${j.base_resp.status_code}: ${j.base_resp.status_msg ?? ""}`.trim());
+        const q = minimaxFromRemains(j);
+        return q ? remember(name, q.five, q.week) : noData(name, m("no plan data", "sem dados do plano"));
+    }
+    catch (e) {
+        return fromCache(name, m("collector failed", "coletor falhou") + `: ${e.message}`);
+    }
+}
+// --- command ----------------------------------------------------------------------------------------------------------
+function commandQuota(name, cmd) {
+    const r = spawnSync(cmd, { shell: true, encoding: "utf8", timeout: 30_000 });
+    const lines = (r.stdout ?? "").split(/\r?\n/).filter((l) => /\S+ 5h=\S+ week=\S+/.test(l));
+    return lines.length ? lines : [format(noData(name, m("collector failed", "coletor falhou")))];
+}
+// --- all --------------------------------------------------------------------------------------------------------------
+/** One or more output lines per configured source, in config order. `want` filters by line name. */
+export async function collect(sources, want = []) {
+    const wanted = (n) => !want.length || want.includes(n);
+    const jobs = Object.entries(sources).map(async ([name, src]) => {
+        if (src === false)
+            return [];
+        if (src === "none")
+            return wanted(name) ? [format({ name, five: "-", week: "-", note: m("no quota collector", "sem coletor de cota") })] : [];
+        if (typeof src === "object" && src && "command" in src)
+            return commandQuota(name, src.command).filter((l) => wanted(l.split(" ")[0]));
+        if (name === "claude") {
+            const accs = claudeAccounts().filter((a) => wanted(a.name) || (want.includes("claude")));
+            return (await Promise.all(accs.map((a) => claudeQuota(a.name, a.dir)))).map(format);
+        }
+        if (name === "codex")
+            return wanted(name) ? [format(codexQuota())] : [];
+        if (name === "antigravity")
+            return wanted(name) ? [format(await antigravityQuota())] : [];
+        if (name === "copilot")
+            return wanted(name) ? [format(copilotQuota())] : [];
+        if (name === "opencode" || name === "minimax")
+            return wanted(name) ? [format(await minimaxQuota(name))] : [];
+        return wanted(name) ? [format(noData(name, m("no builtin collector: use \"none\" or a command", "sem coletor embutido: use \"none\" ou um comando")))] : [];
+    });
+    return (await Promise.all(jobs)).flat();
+}

package/dist/roles.js

@@ -0,0 +1,28 @@
+/** What the conductor asks for (orq pick <role>) → the [roles] section that answers it. */
+export const PICK_ROLES = ["impl", "fix", "worker", "review", "opinion"];
+const SECTION = {
+    impl: ["primary"], fix: ["primary"], worker: ["workers", "primary"], review: ["reviewer"], opinion: ["opinion"],
+};
+/** The role name used in the old agents.<name>.roles lists. */
+export const legacyRole = (r) => (r === "worker" ? "impl" : r);
+/** Vendors of the built-in agents, so a config may leave `vendor` out. */
+export const BUILTIN_VENDORS = {
+    claude: "anthropic", codex: "openai", antigravity: "google", copilot: "github",
+};
+export const vendorOf = (name, a) => a?.vendor ?? BUILTIN_VENDORS[name];
+export function resolveRole(cfg, role) {
+    const agents = (cfg.agents ?? {});
+    const roles = (cfg.roles ?? {});
+    const policyRule = String((cfg.policy ?? {}).review ?? "other-vendor");
+    const section = SECTION[role].find((s) => roles[s]);
+    const r = section ? roles[section] : undefined;
+    const rule = String(r?.rule ?? policyRule);
+    if (r && typeof r.agent === "string")
+        return { mode: "fixed", order: [r.agent, ...(r.fallback ?? [])], rule, section: section };
+    if (r && Array.isArray(r.pool))
+        return { mode: "auto", pool: r.pool, rule, section };
+    const legacy = legacyRole(role);
+    const pool = Object.entries(agents).filter(([, a]) => (a.roles ?? []).includes(legacy))
+        .map(([n]) => n);
+    return { mode: "auto", pool, rule, section };
+}

package/dist/stats.js

@@ -0,0 +1,159 @@
+// Agent scoreboard from the .orquestra/ history: what each agent delivered and what it cost (port of orq-stats).
+// Per run (<prefix>.run.sh + .log + .done + .out.md): agent, model, role (impl | fix | review | other), status,
+// 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.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+const ROLE = /^(impl|fix\d*|review\d*|[a-z]+-review\d*)-?/;
+const read = (f) => { try {
+    return readFileSync(f, "utf8");
+}
+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()];
+}
+function codexSession(sid) {
+    const root = join(process.env.CODEX_HOME ?? join(homedir(), ".codex"), "sessions");
+    const ls = (d) => { try {
+        return readdirSync(d);
+    }
+    catch {
+        return [];
+    } };
+    for (const y of ls(root))
+        for (const mo of ls(join(root, y)))
+            for (const d of ls(join(root, y, mo))) {
+                const f = ls(join(root, y, mo, d)).find((x) => x.startsWith("rollout-") && x.endsWith(`-${sid}.jsonl`));
+                if (f)
+                    return join(root, y, mo, d, f);
+            }
+}
+/** [new, total] — new excludes cache reads. */
+export function tokens(agent, log, sid = "") {
+    let neu = 0, tot = 0;
+    if (agent === "codex") {
+        const f = sid && codexSession(sid);
+        if (f) {
+            const last = read(f).split("\n").filter((l) => l.includes('"total_token_usage"')).pop();
+            const u = last && /"total_token_usage":(\{[^}]*\})/.exec(last);
+            if (u) {
+                const j = JSON.parse(u[1]);
+                return [j.total_tokens - (j.cached_input_tokens ?? 0), j.total_tokens];
+            }
+        }
+        const all = [...log.matchAll(/tokens used\s*\n\s*([\d,]+)/g)];
+        if (all.length)
+            tot = neu = Number(all[all.length - 1][1].replace(/,/g, ""));
+        return [neu, tot];
+    }
+    for (const line of log.split("\n")) {
+        if (!line.startsWith("{"))
+            continue;
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (agent === "claude" && e.type === "result") {
+            const u = e.usage ?? {};
+            const n = (u.input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0) + (u.output_tokens ?? 0);
+            [neu, tot] = [n, n + (u.cache_read_input_tokens ?? 0)];
+        }
+        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;
+        }
+        else if (agent === "antigravity" && e.event === "result") {
+            const u = e.result?.usage ?? {};
+            [neu, tot] = [u.total_tokens ?? 0, (u.total_tokens ?? 0) + (u.cache_read_tokens ?? 0)]; // agy's total excludes cache
+        }
+    }
+    return [neu, tot];
+}
+export function collectRuns(ws, days) {
+    const cutoff = Date.now() - days * 86400_000;
+    const base = join(ws, ".orquestra");
+    const runs = [];
+    const dirs = (() => { try {
+        return readdirSync(base);
+    }
+    catch {
+        return [];
+    } })();
+    for (const issue of dirs) {
+        let files;
+        try {
+            files = readdirSync(join(base, issue));
+        }
+        catch {
+            continue;
+        }
+        for (const f of files.filter((x) => x.endsWith(".run.sh"))) {
+            const pre = join(base, issue, f.slice(0, -".run.sh".length));
+            const runF = `${pre}.run.sh`, done = `${pre}.done`;
+            const rs = statSync(runF);
+            if (rs.mtimeMs < cutoff || !existsSync(done))
+                continue;
+            const txt = read(runF);
+            if (txt.includes("herdr-verify") || txt.includes("herdr-baseline"))
+                continue;
+            const log = read(`${pre}.log`);
+            const [agent, model] = agentModel(txt, log);
+            const name = basename(pre);
+            const rm = ROLE.exec(name);
+            const role = rm && rm[1].includes("review") ? "review"
+                : name.startsWith("fix") || txt.includes("-R ") || txt.includes(" resume ") || txt.includes("--resume") ? "fix"
+                    : 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: read(done).includes("status=ok") && out.trim() !== "",
+                secs: Math.max(0, Math.floor((statSync(done).mtimeMs - rs.mtimeMs) / 1000)), new: neu, tot,
+                repo: name.includes("-") ? name.slice(name.indexOf("-") + 1) : "" });
+        }
+    }
+    // Implementation delivery: the first review of the same repo in the issue.
+    for (const r of runs.filter((x) => x.role === "impl")) {
+        const rv = join(base, r.issue, `review-${r.repo}.out.md`);
+        if (!existsSync(rv))
+            continue;
+        // "non-blocking suggestion" shows up in approved reviews: the verdict is the word APPROVED (APROVADO in older runs).
+        const t = read(rv).slice(0, 4000).toUpperCase();
+        r.approved = (t.includes("APPROVED") || t.includes("APROVADO")) &&
+            !["NOT APPROVED", "REPROVADO", "NÃO APROVADO"].some((x) => t.includes(x));
+    }
+    return runs;
+}
+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;
+};
+export function rows(runs) {
+    const groups = new Map();
+    for (const r of runs) {
+        const k = JSON.stringify([r.role, r.agent, r.model]);
+        groups.set(k, [...(groups.get(k) ?? []), r]);
+    }
+    return [...groups.keys()].sort().map((k) => {
+        const rs = groups.get(k), [role, agent, model] = JSON.parse(k);
+        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,
+            new: withTok.length ? Math.floor(median(withTok.map((r) => r.new))) : null,
+            tot: withTok.length ? Math.floor(median(withTok.map((r) => r.tot))) : null };
+    });
+}
+export const scoreboard = (ws, days) => rows(collectRuns(ws, days));

package/dist/suggest.js

@@ -0,0 +1,121 @@
+// Guided setup: turns what a user knows (plans, trust, parallel tasks, RAM) into roles, weights and memory caps,
+// with a reason for each choice. The rules are the ones the case study found by hand (docs/case-study.md):
+//   shares quota with the conductor          → reserve
+//   small plan / monthly allowance           → opinion only
+//   pay-as-you-go                            → reviewer pool, not primary
+//   no free shell when headless (agy)        → reviewer only, diff attached
+//   trusted, else largest plan, not conductor → primary
+//   vendor ≠ primary's                       → reviewer (cross review)
+import { m } from "./i18n.js";
+import { BUILTIN_VENDORS } from "./roles.js";
+/** Agents that only read when headless (their CLI denies commands outside an allowlist). */
+const READ_ONLY = new Set(["antigravity"]);
+const RANK = { large: 3, free: 2, payg: 1, small: 0 };
+export function suggestRoles(a) {
+    const names = Object.keys(a.agents);
+    if (!names.length)
+        throw new Error(m("no agent to set up", "nenhum agente para configurar"));
+    const vendor = (n) => a.agents[n].vendor ?? BUILTIN_VENDORS[n] ?? n;
+    const reasons = [], notices = [];
+    const isConductor = (n) => n === a.conductor;
+    const canImpl = (n) => !READ_ONLY.has(n);
+    const single = a.preset === "single-agent" || names.length === 1;
+    // Primary: the trusted one, else the largest plan; avoid the conductor's quota, small plans and pay-as-you-go.
+    const implCands = names.filter(canImpl);
+    const byPlan = (xs) => [...xs].sort((x, y) => Number(Boolean(a.agents[y].trust)) - Number(Boolean(a.agents[x].trust))
+        || Number(isConductor(x)) - Number(isConductor(y))
+        || RANK[a.agents[y].plan] - RANK[a.agents[x].plan]);
+    const primary = byPlan(implCands.length ? implCands : names)[0];
+    const why = a.agents[primary].trust ? m("the one you trust most", "o que você mais confia")
+        : m("largest plan apart from the conductor's", "maior plano fora o do conductor");
+    reasons.push(`primary = ${primary}: ${why}`);
+    if (!canImpl(primary))
+        notices.push(m(`${primary} only reads when headless: it can't implement well`, `${primary} só lê no modo headless: não implementa bem`));
+    const workers = implCands.filter((n) => n !== primary && !["small", "payg"].includes(a.agents[n].plan));
+    const opinion = names.filter((n) => n !== primary && a.agents[n].plan === "small");
+    const otherVendor = names.filter((n) => vendor(n) !== vendor(primary) && !opinion.includes(n));
+    let reviewers = otherVendor.length ? otherVendor : names.filter((n) => !opinion.includes(n));
+    const rule = otherVendor.length && !single ? "other-vendor" : "any";
+    if (single)
+        reviewers = [primary];
+    if (single) {
+        notices.push(m("One agent does everything; reviews run in a fresh session. Cross-vendor review catches more — consider a second agent.", "Um agente faz tudo; a revisão roda numa sessão nova. Revisão entre fornecedores pega mais erros — considere um segundo agente."));
+    }
+    else if (!otherVendor.length) {
+        notices.push(m(`All agents are from ${vendor(primary)}: cross-vendor review is off (rule = "any"); review uses another session/model.`, `Todos os agentes são de ${vendor(primary)}: revisão entre fornecedores desligada (rule = "any"); a revisão usa outra sessão/modelo.`));
+    }
+    else {
+        reasons.push(`reviewer = ${reviewers.join(", ")}: ` + m(`vendor different from ${primary}'s (cross review)`, `fornecedor diferente do de ${primary} (revisão cruzada)`));
+    }
+    const agents = {};
+    for (const n of names) {
+        const ans = a.agents[n], roles = [];
+        if (n === primary || (!single && workers.includes(n)))
+            roles.push("impl", "fix");
+        if (reviewers.includes(n))
+            roles.push("review");
+        if (opinion.includes(n) && !single)
+            roles.push("opinion");
+        agents[n] = { vendor: vendor(n), roles, ...(ans.quota ? { quota: ans.quota } : {}) };
+        if (isConductor(n) && n !== primary && !single) {
+            agents[n].reserve = true;
+            reasons.push(`${n}: reserve — ` + m("shares quota with the conductor", "divide cota com o conductor"));
+        }
+        if (ans.plan === "small" && !single)
+            reasons.push(`${n}: opinion — ` + m("small plan or monthly allowance", "plano pequeno ou franquia mensal"));
+        if (ans.plan === "payg" && n !== primary)
+            reasons.push(`${n}: ` + m("pay-as-you-go → reviews (few tokens)", "pague-por-uso → revisa (poucos tokens)"));
+        if (READ_ONLY.has(n) && n !== primary)
+            reasons.push(`${n}: ` + m("reviews only (reads when headless, diff attached)", "só revisa (só lê no headless, diff anexado)"));
+    }
+    const roles = {
+        conductor: { agent: a.conductor },
+        primary: { agent: primary, ...(workers.length ? { fallback: workers } : {}) },
+        reviewer: { pick: "auto", pool: reviewers, rule },
+    };
+    if (workers.length)
+        roles.workers = { pick: "auto", pool: [primary, ...workers] };
+    if (opinion.length && !single)
+        roles.opinion = { pick: "auto", pool: opinion };
+    const quality = a.preset === "quality" || (a.preset !== "economy" && a.parallel <= 2);
+    const weights = quality ? { quality: 0.55, tokens: 0.3, speed: 0.15 } : { quality: 0.4, tokens: 0.45, speed: 0.15 };
+    reasons.push(quality ? m("weights favor quality (few tasks at once)", "pesos priorizam qualidade (poucas tarefas por vez)")
+        : m("weights favor tokens (several tasks at once)", "pesos priorizam tokens (várias tarefas por vez)"));
+    // Memory: ~60 % of RAM for agents; rarely more than two peak at once, so it is split by min(parallel, 2); 2–8 GB
+    // each. Tests get a bit more, up to 40 % of RAM.
+    const per = Math.max(2, Math.min(8, Math.floor((a.ramGB * 0.6) / Math.min(Math.max(1, a.parallel), 2))));
+    const test = Math.max(2, Math.min(per + 2, Math.floor(a.ramGB * 0.4)));
+    return { agents, roles, weights, machine: { agent_mem_max: `${per}G`, test_mem_max: `${test}G` }, reasons, notices };
+}
+const q = (s) => JSON.stringify(s);
+const list = (xs) => `[${xs.map(q).join(", ")}]`;
+/** The proposal as a commented config.toml (new installs; agent models are left to the CLI defaults). */
+export function toToml(p) {
+    const out = ["# Written by `orq setup`. Edit freely: everything here is a suggestion (docs/portability.md §4).", "",
+        "[machine]", `agent_mem_max = ${q(p.machine.agent_mem_max)}`, `test_mem_max  = ${q(p.machine.test_mem_max)}`, ""];
+    for (const [n, a] of Object.entries(p.agents)) {
+        out.push(`[agents.${n}]`, `vendor = ${q(a.vendor)}`, `roles  = ${list(a.roles)}`);
+        if (a.quota)
+            out.push(`quota  = ${list(a.quota)}`);
+        if (a.reserve)
+            out.push("reserve = true");
+        out.push("# models.<role>.<level> = \"model[@effort]\" — without models, the CLI's default model is used", "");
+    }
+    for (const [r, v] of Object.entries(p.roles)) {
+        out.push(`[roles.${r}]`);
+        if (v.agent)
+            out.push(`agent = ${q(v.agent)}`);
+        if (v.fallback)
+            out.push(`fallback = ${list(v.fallback)}`);
+        if (v.pick)
+            out.push(`pick = ${q(v.pick)}`);
+        if (v.pool)
+            out.push(`pool = ${list(v.pool)}`);
+        if (v.rule)
+            out.push(`rule = ${q(v.rule)}`);
+        out.push("");
+    }
+    out.push("[policy.weights]", `quality = ${p.weights.quality}`, `tokens  = ${p.weights.tokens}`, `speed   = ${p.weights.speed}`, "");
+    out.push("# Why:", ...p.reasons.map((r) => `#   ${r}`), ...p.notices.map((n) => `# ! ${n}`), "");
+    return out.join("\n");
+}