@irythill/orq 0.0.0-stage → 0.2.0

package/dist/commands/deps.js

@@ -0,0 +1,82 @@
+// orq deps — the worktree's node_modules is a LINK to the main repo's (never install in a worktree: ~1 GB and tens of
+// thousands of files per copy). If the main repo's deps are behind origin/<base> and it is clean and on <base>:
+// fast-forward + ONE install there. One install per repo at a time (orq lock); the second waits, then only links.
+// Windows: a directory junction (no admin rights needed); elsewhere a symlink.
+//   orq deps -r <main repo> -b <base> -w <worktree>     exit 0 = linked · 3 = main repo dirty or not on <base>: ASK THE USER
+import { spawnSync } from "node:child_process";
+import { appendFileSync, existsSync, lstatSync, readFileSync, rmSync, symlinkSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { m } from "../i18n.js";
+import { acquire, release } from "../lock.js";
+export const USAGE = "orq deps -r <main repo> -b <base> -w <worktree>   link node_modules into a worktree (exit 3 = ask the user)";
+const git = (cwd, ...a) => spawnSync("git", ["-C", cwd, ...a], { encoding: "utf8" });
+export function installer(repo) {
+    const has = (f) => existsSync(join(repo, f));
+    if (has("bun.lock") || has("bun.lockb"))
+        return ["bun", "install"];
+    if (has("pnpm-lock.yaml"))
+        return ["pnpm", "install"];
+    if (has("yarn.lock"))
+        return ["yarn", "install"];
+    return ["npm", "install"];
+}
+export function link(target, at) {
+    try {
+        if (lstatSync(at))
+            rmSync(at, { recursive: true, force: true });
+    }
+    catch { /* not there */ }
+    symlinkSync(target, at, process.platform === "win32" ? "junction" : "dir");
+}
+export async function deps(argv) {
+    let R = "", B = "", WT = "";
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "-r")
+            R = resolve(argv[++i]);
+        else if (argv[i] === "-b")
+            B = argv[++i];
+        else if (argv[i] === "-w")
+            WT = resolve(argv[++i]);
+        else {
+            console.error(USAGE);
+            return 2;
+        }
+    }
+    if (!R || !B || !WT) {
+        console.error(USAGE);
+        return 2;
+    }
+    const gd = git(R, "rev-parse", "--path-format=absolute", "--git-common-dir").stdout.trim();
+    const ex = join(gd, "info", "exclude");
+    if (!(existsSync(ex) ? readFileSync(ex, "utf8") : "").split(/\r?\n/).includes("node_modules"))
+        appendFileSync(ex, "node_modules\n");
+    const name = `deps-${basename(R)}`;
+    await acquire(name, process.pid, `deps ${basename(R)}`, 1, () => console.log(m(`another conductor is installing dependencies in ${basename(R)}; waiting...`, `outro conductor está instalando dependências em ${basename(R)}; aguardando...`)));
+    try {
+        git(R, "fetch", "-q", "origin", B);
+        const locks = ["package.json", "bun.lock", "bun.lockb", "package-lock.json", "yarn.lock", "pnpm-lock.yaml"]
+            .filter((f) => existsSync(join(R, f)));
+        const stale = git(R, "diff", "--quiet", "HEAD", `origin/${B}`, "--", ...locks).status !== 0;
+        if (stale || !existsSync(join(R, "node_modules"))) {
+            const br = git(R, "branch", "--show-current").stdout.trim();
+            if (br !== B || git(R, "status", "--porcelain", "--untracked-files=no").stdout.trim()) {
+                console.log(m(`deps are stale, but ${basename(R)} is on '${br}' or has changes: not touching it. Ask the user.`, `deps defasadas, mas ${basename(R)} está em '${br}' ou com alterações: não mexo. Pergunte ao usuário.`));
+                return 3;
+            }
+            git(R, "merge", "-q", "--ff-only", `origin/${B}`);
+            const cmd = installer(R);
+            console.log(`${m("installing dependencies in", "instalando dependências em")} ${basename(R)} (${cmd.join(" ")})...`);
+            const r = spawnSync(cmd[0], cmd.slice(1), { cwd: R, stdio: "ignore", shell: process.platform === "win32" });
+            if (r.status !== 0) {
+                console.error(`${cmd.join(" ")}: exit ${r.status}`);
+                return 1;
+            }
+        }
+        link(join(R, "node_modules"), join(WT, "node_modules"));
+        console.log(`ok: ${join(WT, "node_modules")} -> ${join(R, "node_modules")}`);
+        return 0;
+    }
+    finally {
+        release(name, process.pid);
+    }
+}

package/dist/commands/gc.js

@@ -0,0 +1,164 @@
+// orq gc — find issue worktrees whose branch is already safe to remove.
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { basename, isAbsolute, join, relative, resolve } from "node:path";
+import { loadConfig } from "../config.js";
+import { m } from "../i18n.js";
+import { aliveOwner } from "./claim.js";
+export const USAGE = "orq gc [-w <workspace>] [--yes] [--days N] [--json]   remove merged issue worktrees";
+const git = (cwd, ...args) => spawnSync("git", ["-C", cwd, ...args], { encoding: "utf8" });
+// Paths as git prints them can differ from ours (macOS /var → /private/var, Windows C:/ vs C:\): compare real paths.
+const real = (p) => { try {
+    return realpathSync.native(p);
+}
+catch {
+    return resolve(p);
+} };
+const inside = (dir, p) => { const r = relative(dir, p); return !!r && !r.startsWith("..") && !isAbsolute(r); };
+// ORQ_GH may be a .js file (tests: a fake gh that also runs on Windows).
+const gh = (cwd, args) => {
+    const bin = process.env.ORQ_GH || "gh";
+    return bin.endsWith(".js") ? spawnSync(process.execPath, [bin, ...args], { cwd, encoding: "utf8" })
+        : spawnSync(bin, args, { cwd, encoding: "utf8" });
+};
+const output = (cwd, ...args) => { const r = git(cwd, ...args); return r.status === 0 ? r.stdout.trim() : undefined; };
+export async function gc(argv, clock = Date.now) {
+    let ws = process.cwd(), yes = false, json = false, days = 14;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "-w" && argv[i + 1])
+            ws = resolve(argv[++i]);
+        else if (argv[i] === "--yes")
+            yes = true;
+        else if (argv[i] === "--json")
+            json = true;
+        else if (argv[i] === "--days" && argv[i + 1] && /^\d+$/.test(argv[i + 1]))
+            days = Number(argv[++i]);
+        else {
+            console.error(USAGE);
+            return 2;
+        }
+    }
+    const { cfg } = loadConfig(ws), rows = [];
+    let ghUnavailable = false, fetchWarned = false;
+    const root = join(ws, ".worktrees");
+    const orq = join(ws, ".orquestra");
+    const issues = existsSync(orq) ? readdirSync(orq) : [];
+    for (const repoName of readdirSync(ws, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)) {
+        const repo = join(ws, repoName);
+        if (!existsSync(join(repo, ".git")))
+            continue;
+        const listings = output(repo, "worktree", "list", "--porcelain");
+        if (listings === undefined)
+            continue;
+        const worktrees = listings.split(/\n\n/).map((block) => Object.fromEntries(block.split("\n").map((line) => {
+            const i = line.indexOf(" ");
+            return [i < 0 ? line : line.slice(0, i), i < 0 ? "" : line.slice(i + 1)];
+        })));
+        const main = real(worktrees[0]?.worktree ?? repo);
+        const conf = cfg.repos?.[repoName];
+        const head = output(repo, "symbolic-ref", "refs/remotes/origin/HEAD")?.replace("refs/remotes/", "");
+        const prod = conf?.prod_ref || head || "origin/main";
+        const fetchRef = prod.replace(/^origin\//, "");
+        if (git(repo, "fetch", "origin", fetchRef).status !== 0 && !fetchWarned) {
+            console.error(m("WARNING: git fetch failed; using local refs", "AVISO: git fetch falhou; usando as refs locais"));
+            fetchWarned = true;
+        }
+        const prodTree = output(repo, "rev-parse", `${prod}^{tree}`);
+        for (const wt of worktrees) {
+            const path = real(wt.worktree ?? "");
+            if (!wt.worktree || path === main || !inside(real(root), path))
+                continue;
+            const branch = wt.branch?.replace(/^refs\/heads\//, "") ?? "";
+            if (!branch)
+                continue;
+            // The branch carries the ID in lowercase (plane-abc-123); .orquestra/ keeps it as written (ABC-123).
+            const id = /^.*?plane-(.+)$/.exec(branch)?.[1];
+            const issue = id && issues.find((d) => d.toLowerCase() === id.toLowerCase());
+            const status = output(path, "status", "--porcelain");
+            const unpushed = output(repo, "rev-list", branch, "--not", "--remotes");
+            let reason = "", verdict = "REMOVABLE";
+            if (status) {
+                verdict = "KEEP";
+                reason = m("uncommitted changes", "alterações não commitadas");
+            }
+            const ownerFile = issue && join(ws, ".orquestra", issue, "owner");
+            if (verdict !== "KEEP" && ownerFile && existsSync(ownerFile) && aliveOwner(readFileSync(ownerFile, "utf8"))) {
+                verdict = "KEEP";
+                reason = m("issue has a live owner", "issue tem um responsável ativo");
+            }
+            // A .pane/.id without a same-stem .done is treated as a running child.
+            const issueDir = issue && join(ws, ".orquestra", issue);
+            if (verdict !== "KEEP" && issueDir && existsSync(issueDir)) {
+                const files = readdirSync(issueDir), running = files.some((f) => /\.(pane|id)$/.test(f) && !existsSync(join(issueDir, `${f.replace(/\.(pane|id)$/, "")}.done`)));
+                if (running) {
+                    verdict = "KEEP";
+                    reason = m("child agent may still be running", "um agente filho pode estar em execução");
+                }
+            }
+            let merged = false;
+            if (verdict !== "KEEP") {
+                // Merged counts only if the PR's head is the local head: a commit made after the merge must not be lost.
+                const pr = gh(repo, ["pr", "list", "--head", branch, "--state", "merged", "--json", "number,headRefOid", "--limit", "1"]);
+                const local = output(repo, "rev-parse", branch);
+                if (pr.status === 0) {
+                    try {
+                        const p = JSON.parse(pr.stdout)[0];
+                        merged = !!p && (!p.headRefOid || p.headRefOid === local);
+                    }
+                    catch {
+                        ghUnavailable = true;
+                    }
+                }
+                else
+                    ghUnavailable = true;
+            }
+            const inBase = verdict !== "KEEP" && !!prodTree && output(repo, "merge-tree", "--write-tree", prod, branch) === prodTree;
+            if (verdict !== "KEEP" && unpushed && !merged && !inBase) {
+                verdict = "KEEP";
+                reason = m("commits not contained in remote refs", "commits fora das refs remotas");
+            }
+            else if (verdict !== "KEEP" && (merged || inBase)) {
+                verdict = "REMOVABLE";
+                reason = merged ? "PR merged" : m("content is in base", "conteúdo já está na base");
+            }
+            else if (verdict !== "KEEP") {
+                const closed = gh(repo, ["pr", "list", "--head", branch, "--state", "closed", "--json", "number", "--limit", "1"]);
+                const isClosed = closed?.status === 0 && (() => { try {
+                    return JSON.parse(closed.stdout).length > 0;
+                }
+                catch {
+                    return false;
+                } })();
+                const commit = output(repo, "log", "-1", "--format=%ct", branch), old = commit !== undefined && clock() - Number(commit) * 1000 > days * 86400_000;
+                verdict = "STALE";
+                reason = isClosed ? m("PR closed without merge", "PR fechada sem merge") : old ? m(`last commit is older than ${days} days`, `último commit tem mais de ${days} dias`) : m("not merged", "não integrado");
+            }
+            rows.push({ repo: repoName, worktree: basename(path), branch, verdict, reason, path });
+        }
+    }
+    if (ghUnavailable)
+        console.error(m("NOTE: gh unavailable or failed; PR signals were skipped", "NOTA: gh indisponível ou falhou; sinais de PR ignorados"));
+    let failed = false;
+    if (yes)
+        for (const row of rows.filter((r) => r.verdict === "REMOVABLE")) {
+            const removed = git(join(ws, row.repo), "worktree", "remove", row.path);
+            if (removed.status !== 0) {
+                failed = true;
+                row.reason += `; ${m("worktree removal failed", "falha ao remover worktree")}`;
+                continue;
+            }
+            if (git(join(ws, row.repo), "branch", "-D", row.branch).status !== 0) {
+                failed = true;
+                row.reason += `; ${m("branch deletion failed", "falha ao excluir branch")}`;
+            }
+            git(join(ws, row.repo), "worktree", "prune");
+        }
+    if (json)
+        console.log(JSON.stringify(rows));
+    else {
+        const table = [["REPO", "WORKTREE", "BRANCH", "VERDICT", "REASON"], ...rows.map((r) => [r.repo, r.worktree, r.branch, r.verdict, r.reason])];
+        const w = table[0].map((_, i) => Math.max(...table.map((t) => t[i].length)));
+        console.log(table.map((t) => t.map((c, i) => i < t.length - 1 ? c.padEnd(w[i]) : c).join("  ")).join("\n"));
+    }
+    return failed ? 1 : 0;
+}

package/dist/commands/instructions.js

@@ -0,0 +1,66 @@
+// orq instructions — the /issue playbook (skills/issue/SKILL.md, one source) in the conductor's own format:
+//   claude   <workspace>/.claude/skills/issue/SKILL.md   (Claude Code loads it as the /issue skill)
+//   agents   <workspace>/AGENTS.md                        (Codex, OpenCode and others that read AGENTS.md)
+// AGENTS.md may hold the user's own text: orq only replaces its block between the orq:issue markers.
+//   orq instructions claude|agents [-w <workspace>] [--print]
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { writeAtomic } from "../fsutil.js";
+import { m } from "../i18n.js";
+export const USAGE = "orq instructions claude|agents [-w <workspace>] [--print]   write the /issue playbook for the conductor";
+const SRC = fileURLToPath(new URL("../../skills/issue/SKILL.md", import.meta.url));
+const BEGIN = "<!-- orq:issue begin (generated by `orq instructions agents`; edits inside are overwritten) -->";
+const END = "<!-- orq:issue end -->";
+/** The playbook for harnesses without skills: no frontmatter, a trigger line, and how to wait without background tasks. */
+export function agentsBlock(skill) {
+    const body = skill.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, "").trim();
+    return `${BEGIN}
+When the user says "/issue <ID>", "take issue X" or "run ABC-123", follow this playbook.
+If your harness cannot run a command in the background, wait for children with \`orq wait\` in the foreground
+(\`orq wait --any <prefix>...\`): it is the one allowed blocking wait.
+
+${body}
+${END}
+`;
+}
+/** Put the block into an existing AGENTS.md text: replace ours, or append it. */
+export function mergeBlock(cur, block) {
+    const a = cur.indexOf(BEGIN), b = cur.indexOf(END);
+    if (a >= 0 && b > a)
+        return cur.slice(0, a) + block.trimEnd() + cur.slice(b + END.length);
+    return cur ? `${cur.trimEnd()}\n\n${block}` : block;
+}
+export async function instructions(argv) {
+    let ws = process.cwd(), print = false, fmt;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "-w")
+            ws = resolve(argv[++i]);
+        else if (argv[i] === "--print")
+            print = true;
+        else if (argv[i] === "claude" || argv[i] === "agents")
+            fmt = argv[i];
+        else {
+            console.error(USAGE);
+            return 2;
+        }
+    }
+    if (!fmt) {
+        console.error(USAGE);
+        return 2;
+    }
+    if (!existsSync(SRC)) {
+        console.error(m(`playbook not found: ${SRC}`, `playbook não encontrado: ${SRC}`));
+        return 2;
+    }
+    const skill = readFileSync(SRC, "utf8");
+    const file = fmt === "claude" ? join(ws, ".claude", "skills", "issue", "SKILL.md") : join(ws, "AGENTS.md");
+    const text = fmt === "claude" ? skill : mergeBlock(existsSync(file) ? readFileSync(file, "utf8") : "", agentsBlock(skill));
+    if (print) {
+        process.stdout.write(text);
+        return 0;
+    }
+    writeAtomic(file, text);
+    console.log(m(`wrote ${file}`, `escrito ${file}`));
+    return 0;
+}

package/dist/commands/lang.js

@@ -0,0 +1,35 @@
+// orq lang                 show the current language
+// orq lang pt|en|auto      set it (auto = system locale)
+// orq lang toggle          switch between en and pt
+// --notify                 also show a herdr pop-up (used by the herdr key binding)
+// Applies to whatever starts afterwards (board, notices, orq pick...); running agents keep their language.
+import { spawnSync } from "node:child_process";
+import { getPath, loadConfig } from "../config.js";
+import { detectLang } from "../i18n.js";
+import { setValue } from "./set.js";
+export const USAGE = "orq lang [pt|en|auto|toggle] [--notify]";
+const cfgLang = () => getPath(loadConfig().cfg, "ui.lang");
+export function lang(argv) {
+    let notify = false, arg = "";
+    for (const a of argv) {
+        if (a === "--notify")
+            notify = true;
+        else if (["pt", "en", "auto", "toggle"].includes(a))
+            arg = a;
+        else {
+            console.error(`usage: ${USAGE}`);
+            return 2;
+        }
+    }
+    const cur = detectLang(cfgLang(), false); // effective language, ignoring $ORQ_LANG
+    if (!arg) {
+        console.log(`${cur} (ui.lang = ${cfgLang() ?? "auto"})`);
+        return 0;
+    }
+    setValue("ui", "lang", arg === "toggle" ? (cur === "pt" ? "en" : "pt") : arg);
+    const msg = detectLang(cfgLang(), false) === "pt" ? "Idioma do orq: Português" : "orq language: English";
+    console.log(msg);
+    if (notify)
+        spawnSync("herdr", ["notification", "show", msg], { stdio: "ignore" });
+    return 0;
+}

package/dist/commands/lock.js

@@ -0,0 +1,69 @@
+// orq lock — the portable test queue (src/lock.ts). Scripts hold a slot for their own pid:
+//   orq lock wait verify --pid $$ --label "verify ABC-1 api"   blocks until it holds a slot (slots: machine.test_slots)
+//   orq lock release verify --pid $$                         (also freed by itself when that process dies)
+//   orq lock run verify [--label t] -- <cmd> [args]          runs a command holding a slot
+//   orq lock status [verify] [--json]                        holders and waiters, in order
+import { spawnSync } from "node:child_process";
+import { getPath, loadConfig } from "../config.js";
+import { m } from "../i18n.js";
+import { acquire, release, status } from "../lock.js";
+export const USAGE = `orq lock wait|release <name> [--pid P] [--label text]   test queue (slots = machine.test_slots)
+orq lock run <name> [--label text] -- <cmd>...  ·  orq lock status [<name>] [--json]`;
+const slots = () => Number(getPath(loadConfig().cfg, "machine.test_slots") ?? 1);
+const since = (at) => `${Math.round((Date.now() - at) / 1000)}s`;
+export async function lock(argv) {
+    const [sub, name = "verify", ...rest] = argv;
+    let pid = process.ppid, label = "", json = false;
+    const dd = rest.indexOf("--");
+    const opts = dd >= 0 ? rest.slice(0, dd) : rest, cmd = dd >= 0 ? rest.slice(dd + 1) : [];
+    for (let i = 0; i < opts.length; i++) {
+        if (opts[i] === "--pid")
+            pid = Number(opts[++i]);
+        else if (opts[i] === "--label")
+            label = opts[++i];
+        else if (opts[i] === "--json")
+            json = true;
+        else {
+            console.error(USAGE);
+            return 2;
+        }
+    }
+    const waitMsg = () => console.log(m("another verification is running; waiting for my turn...", "outra verificação em andamento; aguardando a vez..."));
+    switch (sub) {
+        case "wait":
+            await acquire(name, pid, label, slots(), waitMsg);
+            return 0;
+        case "release":
+            release(name, pid);
+            return 0;
+        case "run": {
+            if (!cmd.length) {
+                console.error(USAGE);
+                return 2;
+            }
+            await acquire(name, process.pid, label || cmd.join(" "), slots(), waitMsg);
+            try {
+                return spawnSync(cmd[0], cmd.slice(1), { stdio: "inherit", shell: process.platform === "win32" }).status ?? 1;
+            }
+            finally {
+                release(name, process.pid);
+            }
+        }
+        case "status": {
+            const s = status(name);
+            if (json) {
+                console.log(JSON.stringify(s));
+                return 0;
+            }
+            for (const e of s.holders)
+                console.log(`▶ ${e.pid} ${e.label} (${since(e.at)})`);
+            s.waiters.forEach((e, i) => console.log(`${i + 1}. ${e.pid} ${e.label} (${m("waiting", "aguardando")} ${since(e.at)})`));
+            if (!s.holders.length && !s.waiters.length)
+                console.log(m("queue empty", "fila vazia"));
+            return 0;
+        }
+        default:
+            console.error(USAGE);
+            return 2;
+    }
+}

package/dist/commands/pick.js

@@ -0,0 +1,111 @@
+// orq pick — agent, model, effort and account for a role, from [roles] (fixed or auto), the history, quota and blocks.
+// Prints the runner arguments (e.g. `-a codex -m gpt-6-sol -e low -c work`); each pick is recorded in
+// <state dir>/picks.jsonl (that feeds rotation). Exit 3 = no candidate: ask the user.
+// `orq pick fix --same <file>`: the implementer's saved pick, effort one level up (no choice, nothing recorded).
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadConfig } from "../config.js";
+import { m } from "../i18n.js";
+import { asArgs, escalate, parseQuota, pick as choose } from "../pick.js";
+import { expand, stateDir } from "../paths.js";
+import { collect } from "../quota.js";
+import { PICK_ROLES, vendorOf } from "../roles.js";
+import { collectRuns, rows } from "../stats.js";
+import { load as loadBlocks } from "./block.js";
+export const USAGE = `orq pick <impl|fix|worker|review|opinion> [--level simple|medium|heavy] [--impl-vendor <v>|--impl-agent <a>]
+         [--exclude-agent <a>]... [-w <workspace>] [--explain] [--no-record]
+orq pick fix --same <impl pick file>   same agent/model/account as the implementer, effort one level up`;
+// The board refreshes this file; fresher than 10 min → no new quota requests.
+const QCACHE = join(process.env.XDG_RUNTIME_DIR ?? tmpdir(), "herdr-board.quota");
+async function quotaText(cfg) {
+    if (existsSync(QCACHE) && Date.now() - statSync(QCACHE).mtimeMs < 600_000)
+        return readFileSync(QCACHE, "utf8");
+    return (await collect((cfg.quota ?? {}))).join("\n");
+}
+export async function pick(argv) {
+    const role = argv[0];
+    if (!PICK_ROLES.includes(role)) {
+        console.error(USAGE);
+        return 2;
+    }
+    if (role === "fix" && argv[1] === "--same") {
+        const f = argv[2];
+        if (!f || argv.length > 3) {
+            console.error(USAGE);
+            return 2;
+        }
+        if (!existsSync(f)) {
+            console.error(`orq pick: ${m("no such file: ", "arquivo não existe: ")}${f}`);
+            return 2;
+        }
+        const prev = readFileSync(f, "utf8").trim();
+        if (!/(^|\s)-a \S/.test(prev)) {
+            console.error(`orq pick: ${m("not a pick: ", "não é um pick: ")}${f}`);
+            return 2;
+        }
+        console.log(escalate(prev));
+        return 0;
+    }
+    let level = "medium", implVendor, implAgent, ws;
+    let explain = false, record = true;
+    const exclude = new Set();
+    for (let i = 1; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--level")
+            level = argv[++i];
+        else if (a === "--impl-vendor")
+            implVendor = argv[++i];
+        else if (a === "--impl-agent")
+            implAgent = argv[++i];
+        else if (a === "--exclude-agent")
+            exclude.add(argv[++i]);
+        else if (a === "-w")
+            ws = expand(argv[++i]);
+        else if (a === "--explain")
+            explain = true;
+        else if (a === "--no-record")
+            record = false;
+        else {
+            console.error(USAGE);
+            return 2;
+        }
+    }
+    const { cfg } = loadConfig(ws);
+    const agents = (cfg.agents ?? {});
+    if (implAgent && !implVendor)
+        implVendor = vendorOf(implAgent, agents[implAgent]);
+    const w = (cfg.policy ?? {});
+    const stats = rows(collectRuns((ws ?? cfg._workspace ?? process.cwd()), Number(w.history_days ?? 30)));
+    const picksF = join(stateDir(), "picks.jsonl");
+    const window = Number(((w.weights ?? {}).window) ?? 6);
+    const recent = (existsSync(picksF) ? readFileSync(picksF, "utf8").split("\n").filter(Boolean).slice(-200) : [])
+        .map((l) => { try {
+        return JSON.parse(l);
+    }
+    catch {
+        return {};
+    } })
+        .filter((p) => p.role === role).slice(-window);
+    const res = choose({ cfg, role, level, implVendor, exclude, stats, quota: parseQuota(await quotaText(cfg)),
+        blocks: new Set(Object.keys(loadBlocks())), recent });
+    if (!res.best) {
+        console.error(`orq pick: ${m("no candidate for ", "nenhum candidato para ")}${role}`
+            + (res.notes.length ? `; ${res.notes.join("; ")}` : ""));
+        return 3;
+    }
+    if (explain) {
+        for (const c of res.cands)
+            console.error(`${c === res.best ? "→" : " "} ${res.mode === "fixed" ? "  fixed" : (c.score >= 0 ? "+" : "") + c.score.toFixed(3)}  `
+                + `${c.agent.padEnd(12)} ${c.model.padEnd(24)} ${c.why}`);
+        for (const n of res.notes)
+            console.error(`  ${m("out", "fora")}: ${n}`);
+    }
+    if (record) {
+        mkdirSync(stateDir(), { recursive: true });
+        appendFileSync(picksF, JSON.stringify({ t: Math.floor(Date.now() / 1000), role, level, agent: res.best.agent,
+            model: res.best.model }) + "\n");
+    }
+    console.log(asArgs(res.best));
+    return 0;
+}

package/dist/commands/quota.js

@@ -0,0 +1,40 @@
+// orq quota [name...]   quota of each source in [quota] (default: all) — lines "<name> 5h=NN% week=NN% [note]"
+// orq quota --line      one line for a status bar (herdr's tab_bar_right command entry): the board's cache, never
+//                       the network — a stale cache starts the board's background collection, like the board does.
+import { getPath, loadConfig } from "../config.js";
+import { m } from "../i18n.js";
+import { collect } from "../quota.js";
+import { quota as cached } from "./board.js";
+import { load as loadBlocks } from "./block.js";
+export const USAGE = `orq quota [name...]                   quota per agent/account ([quota] in the config)
+orq quota --line                      one line for a status bar, from the board's cache (e.g. herdr tab_bar_right)`;
+const pct = (p) => (/^\d+%$/.test(p) ? Number(p.slice(0, -1)) : undefined);
+/** "work 64 · home 93! · codex 81 · minimax ?": the tighter of the two windows per source; ! at or over the pick
+ *  limit, ⊘ blocked (orq block), ? no data; sources with no window at all ("-" and "-") are left out. */
+export function quotaLine(lines, limit, blocked, age) {
+    const parts = lines.filter((q) => q.five !== "-" || q.week !== "-").map((q) => {
+        if (blocked.has(q.name))
+            return `${q.name} ⊘`;
+        const ns = [pct(q.five), pct(q.week)].filter((n) => n !== undefined);
+        if (!ns.length)
+            return `${q.name} ?`;
+        const top = Math.max(...ns);
+        return `${q.name} ${top}${top >= limit ? "!" : ""}`;
+    });
+    if (!parts.length)
+        return age === undefined ? m("quota: collecting...", "cota: coletando...") : "";
+    const old = age !== undefined && age > 15 * 60_000 ? ` (${Math.round(age / 60_000)} min)` : "";
+    return parts.join(" · ") + old;
+}
+export async function quota(argv) {
+    const { cfg } = loadConfig();
+    if (argv[0] === "--line") {
+        const q = cached(Date.now());
+        console.log(quotaLine(q.lines, Number(getPath(cfg, "policy.quota_limit") ?? 90), new Set(Object.keys(loadBlocks())), q.age));
+        return 0;
+    }
+    const sources = (getPath(cfg, "quota") ?? {});
+    for (const l of await collect(sources, argv))
+        console.log(l);
+    return 0;
+}

package/dist/commands/run.js

@@ -0,0 +1,46 @@
+// orq run — run a command under a memory cap on any OS (src/process.ts).
+//   orq run [--agent <name> | --test] [--mem 4G|off] [--swap 1G] [--mode auto|kernel|watchdog|off] [--unit name] -- <cmd>...
+// Cap: --mem, else agents.<name>.mem_max (with --agent), else machine.test_mem_max (--test) or machine.agent_mem_max.
+// Mode: --mode, else machine.mem_enforce. Exit code = the command's; 137 = killed for memory.
+import { loadConfig } from "../config.js";
+import { parseSize, resolveMode, runCapped } from "../process.js";
+export const USAGE = "orq run [--agent <a> | --test] [--mem 4G|off] [--mode auto|kernel|watchdog|off] -- <cmd>...   memory-capped run";
+export async function run(argv) {
+    const dd = argv.indexOf("--");
+    if (dd < 0 || dd === argv.length - 1) {
+        console.error(USAGE);
+        return 2;
+    }
+    const opts = argv.slice(0, dd), cmd = argv.slice(dd + 1);
+    let agent, test = false, mem, swap;
+    let mode, unit, explain = false;
+    for (let i = 0; i < opts.length; i++) {
+        const a = opts[i];
+        if (a === "--agent")
+            agent = opts[++i];
+        else if (a === "--test")
+            test = true;
+        else if (a === "--mem")
+            mem = opts[++i];
+        else if (a === "--swap")
+            swap = opts[++i];
+        else if (a === "--mode")
+            mode = opts[++i];
+        else if (a === "--unit")
+            unit = opts[++i];
+        else if (a === "--explain")
+            explain = true;
+        else {
+            console.error(USAGE);
+            return 2;
+        }
+    }
+    const { cfg } = loadConfig();
+    const mach = (cfg.machine ?? {});
+    const agentCap = agent ? (cfg.agents ?? {})[agent]?.mem_max : undefined;
+    const cap = parseSize(mem ?? agentCap ?? String((test ? mach.test_mem_max : mach.agent_mem_max) ?? "off"));
+    const m = mode ?? mach.mem_enforce ?? "auto";
+    if (explain)
+        console.error(`orq run: cap=${cap ?? "off"} mode=${resolveMode(m, cap)}`);
+    return runCapped(cmd[0], cmd.slice(1), { cap, mode: m, unit, swap: parseSize(swap ?? mach.agent_swap_max) });
+}

package/dist/commands/set.js

@@ -0,0 +1,27 @@
+// orq set <section> <key> <value> — writes one string value into your orq config, atomically.
+// TOML: replaces `key = ...` inside [section], adds the key or the section if missing; everything else is kept.
+import { existsSync, readFileSync } from "node:fs";
+import { writeAtomic } from "../fsutil.js";
+import { userConfigFile } from "../paths.js";
+import { setTomlString } from "../toml-set.js";
+export const USAGE = "orq set <section> <key> <value>       e.g.  orq set ui theme lcd";
+export function setValue(section, key, value) {
+    const f = userConfigFile();
+    const text = existsSync(f) ? readFileSync(f, "utf8") : "";
+    if (f.endsWith(".json")) {
+        const j = text.trim() ? JSON.parse(text) : {};
+        j[section] = { ...(j[section] ?? {}), [key]: value };
+        writeAtomic(f, JSON.stringify(j, null, 2) + "\n");
+    }
+    else {
+        writeAtomic(f, setTomlString(text, section, key, value));
+    }
+}
+export function set(argv) {
+    if (argv.length !== 3) {
+        console.error(USAGE);
+        return 2;
+    }
+    setValue(argv[0], argv[1], argv[2]);
+    return 0;
+}