@irythill/orq 0.0.0-stage → 0.2.0

package/dist/install.js

@@ -0,0 +1,137 @@
+// What a fresh `npm i -g @irythill/orq` still needs, done by `orq setup` on any OS (install.sh is a Linux extra):
+//   skills      orq's skills (skills/*/SKILL.md, shipped in the package) linked into ~/.claude/skills and each Claude
+//               account's skills folder — a junction on Windows (no admin rights), a copy if linking fails. A real
+//               folder, or a link to another live copy (a clone of the repo), is never touched.
+//   workspace   <folder>/.orquestra, .worktrees, CLAUDE.md from the template (only if missing) and the /issue playbook
+//               in the conductor's format (orq instructions)
+//   environment what orq found: git, terminal host, memory cap, keyring, the shell's completion line
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { claudeAccounts } from "./accounts.js";
+import { writeAtomic } from "./fsutil.js";
+import { m } from "./i18n.js";
+import { backend } from "./keyring.js";
+import { hasKernelCap } from "./process.js";
+import { detectHost } from "./terminal.js";
+export const PKG = fileURLToPath(new URL("..", import.meta.url));
+const SKILLS = join(PKG, "skills");
+const real = (p) => { try {
+    return realpathSync(p);
+}
+catch {
+    return undefined;
+} };
+/** Skill folders of every Claude account (~/.claude always, like install.sh). */
+export function skillRoots() {
+    return [...new Set([join(homedir(), ".claude"), ...claudeAccounts().map((a) => a.dir)].map((d) => join(d, "skills")))];
+}
+/** Link each of orq's skills into each root; one line per skill and root. */
+export function installSkills(roots = skillRoots()) {
+    const out = [];
+    const skills = readdirSync(SKILLS).filter((s) => existsSync(join(SKILLS, s, "SKILL.md")));
+    for (const root of roots)
+        for (const s of skills) {
+            const src = join(SKILLS, s), dst = join(root, s);
+            let st;
+            try {
+                st = lstatSync(dst);
+            }
+            catch { /* missing */ }
+            if (st && !st.isSymbolicLink()) {
+                // A copy made by an earlier `orq setup` (no links on this system) is refreshed; anything else is the user's.
+                if (existsSync(join(dst, ".orq-copy"))) {
+                    rmSync(dst, { recursive: true, force: true });
+                    st = undefined;
+                }
+                else {
+                    out.push(`  ${m("skip", "pulei")}    ${dst} ${m("(a real folder, not a link: move it away to install)", "(uma pasta de verdade, não um link: tire-a do caminho para instalar)")}`);
+                    continue;
+                }
+            }
+            if (st) {
+                const to = real(dst);
+                if (to === real(src)) {
+                    out.push(`  ok      ${dst}`);
+                    continue;
+                }
+                if (to && existsSync(join(to, "SKILL.md"))) {
+                    out.push(`  ${m("keep", "mantive")}  ${dst} → ${readlinkSync(dst)}`);
+                    continue;
+                }
+                rmSync(dst, { force: true }); // dangling (e.g. an old node version's global folder)
+            }
+            mkdirSync(root, { recursive: true });
+            try {
+                symlinkSync(src, dst, process.platform === "win32" ? "junction" : "dir");
+                out.push(`  link    ${dst} → ${src}`);
+            }
+            catch {
+                cpSync(src, dst, { recursive: true });
+                writeAtomic(join(dst, ".orq-copy"), m("copied by orq setup; refreshed on every run\n", "copiado pelo orq setup; atualizado a cada execução\n"));
+                out.push(`  ${m("copy", "cópia")}    ${dst}`);
+            }
+        }
+    return out;
+}
+/** Prepare a conductor's workspace folder; `fmt` = claude (SKILL.md) | agents (AGENTS.md). */
+export function prepareWorkspace(dir, fmt, name = basename(resolve(dir))) {
+    const ws = resolve(dir), out = [];
+    for (const d of [".orquestra", ".worktrees"])
+        mkdirSync(join(ws, d), { recursive: true });
+    const map = join(ws, "CLAUDE.md");
+    if (!existsSync(map)) {
+        const t = readFileSync(join(PKG, "templates", "workspace.CLAUDE.md"), "utf8");
+        writeAtomic(map, t.split("{{WORKSPACE}}").join(ws).split("{{NAME}}").join(name));
+        out.push(m(`  created ${map} — fill in repos, group, base branch, Plane and issue standard`, `  criado ${map} — preencha repos, grupo, branch base, Plane e padrão de issue`));
+    }
+    else
+        out.push(m(`  ok      ${map} (kept)`, `  ok      ${map} (mantido)`));
+    const r = spawnSync(process.execPath, [join(PKG, "dist", "cli.js"), "instructions", fmt, "-w", ws], { encoding: "utf8" });
+    out.push(`  ${(r.stdout || r.stderr).trim()}`);
+    return out;
+}
+const SHELLS = ["bash", "zsh", "fish", "powershell"];
+/** The user's shell, from $SHELL (PowerShell on Windows without one). */
+export function userShell() {
+    const s = basename(process.env.SHELL ?? "").replace(/\.exe$/i, "");
+    if (s === "pwsh")
+        return "powershell";
+    if (SHELLS.includes(s))
+        return s;
+    return process.platform === "win32" ? "powershell" : undefined;
+}
+/** The line that turns completion on, per shell. */
+export const completionLine = (s) => ({
+    bash: `echo 'eval "$(orq completion bash)"' >> ~/.bashrc`,
+    zsh: `echo 'eval "$(orq completion zsh)"' >> ~/.zshrc   # ${m("after compinit", "depois do compinit")}`,
+    fish: "orq completion fish > ~/.config/fish/completions/orq.fish",
+    powershell: "Add-Content $PROFILE 'orq completion powershell | Out-String | Invoke-Expression'",
+}[s]);
+/** What orq found on this machine, one line each (required things first). */
+export function environment(cfg) {
+    const has = (c, a = ["--version"]) => spawnSync(c, a, { stdio: "ignore", timeout: 10_000 }).status === 0;
+    const row = (k, v) => `  ${k.padEnd(10)} ${v}`;
+    let host;
+    try {
+        host = detectHost(cfg);
+    }
+    catch (e) {
+        host = e.message;
+    }
+    const mode = String((cfg.machine ?? {}).mem_enforce ?? "auto");
+    const kb = backend(), sh = userShell();
+    return [
+        row("node", process.version),
+        row("git", has("git") ? "ok" : m("MISSING — required (worktrees, diffs, tests): install git", "FALTANDO — obrigatório (worktrees, diffs, testes): instale o git")),
+        row("terminal", `${host} ${m("(children: herdr tab, tmux window or background; machine.terminal)", "(filhos: aba do herdr, janela do tmux ou segundo plano; machine.terminal)")}`),
+        row(m("memory", "memória"), mode === "off" ? "off" : mode === "watchdog" || !hasKernelCap()
+            ? m("watchdog (samples the process tree; machine.mem_enforce)", "vigia (amostra a árvore de processos; machine.mem_enforce)")
+            : m("kernel (systemd scope)", "kernel (scope do systemd)")),
+        row("keyring", kb === "native" ? "ok" : kb === "cli" ? m("OS command (native module did not load)", "comando do SO (o módulo nativo não carregou)")
+            : m("none — Antigravity/macOS Claude quota shows ?", "nenhum — a cota do Antigravity/Claude no macOS mostra ?")),
+        row("shell", sh ? `${sh} — ${m("completion", "autocompletar")}: ${completionLine(sh)}` : m("unknown — orq completion bash|zsh|fish|powershell", "desconhecido — orq completion bash|zsh|fish|powershell")),
+    ];
+}

package/dist/keyring.js

@@ -0,0 +1,51 @@
+// Keyring — read a secret another tool keeps in the OS keyring (Secret Service on Linux, Keychain on macOS, Credential
+// Manager on Windows) through @napi-rs/keyring. orq only reads; it never writes or refreshes someone else's login.
+// The native module may not load (a platform without a prebuilt binary, a broken install): then the OS's own CLI where
+// there is one (Linux secret-tool, macOS security), else nothing. $ORQ_KEYRING = native | cli | off forces a backend.
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+let native;
+function load() {
+    if (native === undefined) {
+        try {
+            native = createRequire(import.meta.url)("@napi-rs/keyring");
+        }
+        catch {
+            native = null;
+        }
+    }
+    return native;
+}
+const cli = () => process.platform === "linux" ? "secret-tool" : process.platform === "darwin" ? "security" : undefined;
+/** Which backend reads secrets here. */
+export function backend() {
+    const want = process.env.ORQ_KEYRING;
+    if (want === "off")
+        return "none";
+    if (want !== "cli" && load())
+        return "native";
+    return cli() && spawnSync(cli(), ["--help"], { stdio: "ignore", timeout: 5000 }).error === undefined ? "cli" : "none";
+}
+/**
+ * The secret stored for (service, account), or undefined. `target` is the Windows credential name when the tool that
+ * wrote it doesn't use the keyring-rs default ("<account>.<service>"), e.g. go-keyring's "<service>:<account>".
+ */
+export function readSecret(service, account, target) {
+    const b = backend();
+    if (b === "native") {
+        try {
+            const e = target && process.platform === "win32" ? load().Entry.withTarget(target, service, account) : new (load().Entry)(service, account);
+            return e.getPassword() ?? undefined;
+        }
+        catch {
+            return undefined;
+        } // no keyring service (headless Linux without D-Bus), locked, denied
+    }
+    if (b === "cli") {
+        const args = process.platform === "linux" ? ["lookup", "service", service, "username", account]
+            : ["find-generic-password", "-s", service, "-a", account, "-w"];
+        const r = spawnSync(cli(), args, { encoding: "utf8", timeout: 10_000, stdio: ["ignore", "pipe", "ignore"] });
+        return r.status === 0 && r.stdout.trim() ? r.stdout.trim() : undefined;
+    }
+    return undefined;
+}

package/dist/lock.js

@@ -0,0 +1,81 @@
+// Portable FIFO lock with N slots (the test queue), made of plain files — no flock, no /proc/locks.
+//   <state dir>/locks/<name>/<ms>-<pid>.json   one entry per process that asked: {pid, label, at, held}
+// Holders are the entries with held = true whose process is alive. A waiter takes a slot when fewer than `slots` are
+// held and it is the oldest live non-held entry, after its file has existed for SETTLE_MS (so an older entry still
+// being written is seen first). Dead processes' entries are swept by whoever looks, so a crash never leaves the queue
+// stuck. Works the same on Linux, macOS and Windows (process.kill(pid, 0) checks liveness everywhere).
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { writeAtomic } from "./fsutil.js";
+import { stateDir } from "./paths.js";
+const SETTLE_MS = 250;
+const dir = (name) => join(stateDir(), "locks", name);
+export function alive(pid) {
+    if (!(pid > 0))
+        return false; // kill(0, …) would signal our own process group and "succeed"
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM";
+    }
+}
+/** Live entries in queue order (dead ones are removed). */
+export function entries(name) {
+    let files;
+    try {
+        files = readdirSync(dir(name)).filter((f) => f.endsWith(".json"));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files) {
+        const file = join(dir(name), f);
+        try {
+            const e = { ...JSON.parse(readFileSync(file, "utf8")), file };
+            if (alive(e.pid))
+                out.push(e);
+            else
+                rmSync(file, { force: true });
+        }
+        catch { /* being written or removed: skip this round */ }
+    }
+    return out.sort((a, b) => a.at - b.at || a.pid - b.pid);
+}
+export const status = (name) => {
+    const all = entries(name);
+    return { holders: all.filter((e) => e.held), waiters: all.filter((e) => !e.held) };
+};
+/** Queue `pid` and resolve once it holds a slot. `onWait` is called once if it has to wait. */
+export async function acquire(name, pid, label, slots = 1, onWait, pollMs = 500) {
+    mkdirSync(dir(name), { recursive: true });
+    const mine = entries(name).find((e) => e.pid === pid);
+    if (mine?.held)
+        return; // re-entrant for the same process
+    const at = mine?.at ?? Date.now();
+    const file = mine?.file ?? join(dir(name), `${at}-${pid}.json`);
+    writeAtomic(file, JSON.stringify({ pid, label, at, held: false }));
+    let told = false;
+    for (;;) {
+        const all = entries(name), held = all.filter((e) => e.held).length;
+        const first = all.find((e) => !e.held);
+        const settled = Date.now() - statSync(file).mtimeMs >= SETTLE_MS || Date.now() - at >= SETTLE_MS;
+        if (held < Math.max(1, slots) && first?.pid === pid && settled) {
+            writeAtomic(file, JSON.stringify({ pid, label, at, held: true }));
+            return;
+        }
+        if (!told && (held >= slots || first?.pid !== pid)) {
+            onWait?.(all.findIndex((e) => e.pid === pid) - held + 1);
+            told = true;
+        }
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+}
+export function release(name, pid) {
+    const e = entries(name).find((x) => x.pid === pid);
+    if (e)
+        rmSync(e.file, { force: true });
+    return Boolean(e);
+}

package/dist/paths.js

@@ -0,0 +1,34 @@
+// Where orq keeps its files, per OS. Linux/macOS keep the XDG paths the bash/Python scripts always used, so an
+// existing ~/.config/orq and ~/.local/state/orq keep working; Windows uses %APPDATA% / %LOCALAPPDATA%.
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const env = process.env;
+const win = process.platform === "win32";
+export function configDir() {
+    if (env.XDG_CONFIG_HOME)
+        return join(env.XDG_CONFIG_HOME, "orq");
+    if (win)
+        return join(env.APPDATA ?? join(homedir(), "AppData", "Roaming"), "orq");
+    return join(homedir(), ".config", "orq");
+}
+export function stateDir() {
+    if (env.XDG_STATE_HOME)
+        return join(env.XDG_STATE_HOME, "orq");
+    if (win)
+        return join(env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "orq", "state");
+    return join(homedir(), ".local", "state", "orq");
+}
+/** The personal config file to write: $ORQ_CONFIG, else config.json if only that exists, else config.toml. */
+export function userConfigFile() {
+    if (env.ORQ_CONFIG)
+        return env.ORQ_CONFIG;
+    const toml = join(configDir(), "config.toml"), json = join(configDir(), "config.json");
+    return existsSync(json) && !existsSync(toml) ? json : toml;
+}
+/** Expand a leading ~ and $VAR / ${VAR} (unknown variables are left as they are, like Python's expandvars). */
+export function expand(s) {
+    if (s === "~" || s.startsWith("~/") || s.startsWith("~\\"))
+        s = homedir() + s.slice(1);
+    return s.replace(/\$(\w+)|\$\{(\w+)\}/g, (all, a, b) => env[a ?? b] ?? all);
+}

package/dist/pick.js

@@ -0,0 +1,126 @@
+import { m } from "./i18n.js";
+import { legacyRole, resolveRole, vendorOf } from "./roles.js";
+/** "<name> 5h=NN% week=NN% [note]" lines → QuotaMap (same reading as the old orq-pick). */
+export function parseQuota(text) {
+    const out = {};
+    for (const line of text.split(/\r?\n/)) {
+        const p = line.split(/\s+/);
+        if (p.length < 3)
+            continue;
+        const vals = p.slice(1, 3).map((x) => x.replace(/.*=/, ""));
+        if (vals.some((v) => v.startsWith("?"))) {
+            out[p[0]] = null;
+            continue;
+        }
+        const nums = vals.map((v) => v.replace(/%$/, "")).filter((v) => /^\d+$/.test(v)).map(Number);
+        out[p[0]] = nums.length ? Math.max(...nums) : -1;
+    }
+    return out;
+}
+export function modelFor(a, role, level) {
+    if (a.models === undefined)
+        return ["", undefined]; // no models configured: the CLI's default
+    const models = a.models;
+    const lr = legacyRole(role);
+    const ms = models[lr] ?? (lr === "fix" ? models.impl : undefined) ?? {};
+    const spec = ms[level] ?? ms.default ?? ms.medium ?? ms.simple;
+    if (!spec)
+        return undefined;
+    const [model, effort] = spec.split("@");
+    return [model, effort || undefined];
+}
+const WEIGHTS = { quality: 0.4, tokens: 0.45, speed: 0.15, rotation: 0.2, reserve: 0.3, explore: 0.1, min_samples: 8, window: 6 };
+export const weights = (cfg) => ({ ...WEIGHTS, ...((cfg.policy ?? {}).weights ?? {}) });
+export function pick(inp) {
+    const { cfg, role, level } = inp;
+    const agents = (cfg.agents ?? {});
+    const pol = (cfg.policy ?? {});
+    const limit = Number(pol.quota_limit ?? 90);
+    const w = weights(cfg);
+    const res = resolveRole(cfg, role);
+    const names = res.mode === "fixed" ? res.order : res.pool;
+    const notes = [];
+    const out = (n, why) => { notes.push(`${n}: ${why}`); };
+    const pass = [];
+    for (const name of names) {
+        const a = agents[name];
+        if (!a) {
+            out(name, m("not declared in [agents]", "não declarado em [agents]"));
+            continue;
+        }
+        if (inp.exclude.has(name)) {
+            out(name, m("excluded (--exclude-agent)", "excluído (--exclude-agent)"));
+            continue;
+        }
+        if (inp.blocks.has(name)) {
+            out(name, m("blocked (orq block -l)", "bloqueado (orq block -l)"));
+            continue;
+        }
+        if ((role === "review" || role === "opinion") && res.rule === "other-vendor" && inp.implVendor
+            && vendorOf(name, a) === inp.implVendor) {
+            out(name, m("same vendor as the implementer", "mesmo fornecedor do implementador"));
+            continue;
+        }
+        const mf = modelFor(a, role, level);
+        if (!mf) {
+            out(name, m(`no model for ${role}/${level}`, `sem modelo para ${role}/${level}`));
+            continue;
+        }
+        // Quota: an agent with several accounts (claude) uses the least used one under the limit.
+        const qn = a.quota ?? [];
+        const accs = qn.filter((n) => !inp.blocks.has(n)).map((n) => [n, n in inp.quota ? inp.quota[n] : -1]);
+        if (qn.length && !accs.length) {
+            out(name, m("all accounts blocked", "todas as contas bloqueadas"));
+            continue;
+        }
+        const usable = accs.filter(([, v]) => v !== null && v < limit);
+        if (accs.length && !usable.length) {
+            out(name, `${m("quota", "cota")} >= ${limit}% ${m("or no data", "ou sem dados")} (${accs.map(([n, v]) => `${n}=${v}`).join(", ")})`);
+            continue;
+        }
+        const acct = accs.length > 1 ? [...usable].sort((x, y) => x[1] - y[1])[0][0] : undefined;
+        const statRole = role === "fix" || role === "worker" ? "impl" : role;
+        const st = inp.stats.find((r) => r.role === statRole && r.agent === name && r.model === (mf[0].split("/").pop() || "default"));
+        pass.push({ agent: name, model: mf[0], effort: mf[1], acct, a, st });
+        if (res.mode === "fixed")
+            break; // the first that passes wins
+    }
+    if (res.mode === "fixed") {
+        const c = pass[0];
+        const best = c && { agent: c.agent, model: c.model, effort: c.effort, acct: c.acct, score: 0,
+            why: m(`fixed by [roles.${res.section}]`, `fixo em [roles.${res.section}]`) };
+        return { mode: "fixed", best, cands: best ? [best] : [], notes };
+    }
+    const few = (st) => (st?.n ?? 0) < w.min_samples;
+    const toks = pass.filter((c) => c.st?.new && !few(c.st)).map((c) => c.st.new);
+    const mins = pass.filter((c) => c.st?.min && !few(c.st)).map((c) => c.st.min);
+    const cands = pass.map((c) => {
+        const prior = Number(c.a.prior ?? 0.6), n = c.st?.n ?? 0, reserve = Boolean(c.a.reserve);
+        const deliv = role === "impl" && c.st?.approved != null && c.st.n_appr >= 3 ? c.st.approved / 100
+            : c.st ? c.st.ok / 100 : undefined;
+        const d = few(c.st) || deliv === undefined ? prior : deliv;
+        const t = few(c.st) || !c.st?.new || !toks.length ? prior : Math.min(...toks) / c.st.new;
+        const s = few(c.st) || !c.st?.min || !mins.length ? prior : Math.min(...mins) / Math.max(c.st.min, 0.1);
+        const used = inp.recent.filter((p) => p.agent === c.agent).length;
+        const score = w.quality * d + w.tokens * t + w.speed * s - w.rotation * used
+            - (reserve ? w.reserve : 0) + (few(c.st) ? w.explore : 0);
+        const why = `${m("delivery", "entrega")}=${d.toFixed(2)} ${m("economy", "economia")}=${t.toFixed(2)} `
+            + `${m("speed", "rapidez")}=${s.toFixed(2)} ${m("rotation", "rodízio")}=-${used} `
+            + (reserve ? m("reserve ", "reserva ") : "") + (few(c.st) ? `${m("few samples", "poucos dados")}(n=${n})` : `n=${n}`);
+        return { agent: c.agent, model: c.model, effort: c.effort, acct: c.acct, score, why };
+    }).sort((x, y) => y.score - x.score);
+    return { mode: "auto", best: cands[0], cands, notes };
+}
+const EFFORTS = ["low", "medium", "high"];
+/** A fix continues the implementer's session: the same runner arguments (agent, model, account) with the effort one
+ *  level up, capped at high. Keeping the model keeps the session's prompt cache; an unknown or absent effort stays. */
+export function escalate(args) {
+    const p = args.trim().split(/\s+/);
+    const i = p.indexOf("-e");
+    const at = i >= 0 ? EFFORTS.indexOf(p[i + 1]) : -1;
+    if (at >= 0)
+        p[i + 1] = EFFORTS[Math.min(at + 1, EFFORTS.length - 1)];
+    return p.join(" ");
+}
+/** The arguments for the agent runner, e.g. "-a codex -m gpt-6-sol -e low -c work". */
+export const asArgs = (c) => `-a ${c.agent}` + (c.model ? ` -m ${c.model}` : "") + (c.effort ? ` -e ${c.effort}` : "") + (c.acct ? ` -c ${c.acct}` : "");

package/dist/process.js

@@ -0,0 +1,147 @@
+// ProcessHost — run a command under a memory cap, on any OS.
+//   kernel    Linux with a systemd user session: `systemd-run --user --scope -p MemoryMax=` (the kernel kills only
+//             that command, as orq always did)
+//   watchdog  everywhere else (macOS, Windows, Linux without systemd): orq samples the command's process tree every
+//             few seconds and kills the whole tree above the cap
+//   off       no cap
+// mode "auto" = kernel when available, else watchdog. (Windows Job Objects need a native addon: later, if the
+// watchdog proves too coarse.)
+import { execFile, spawn, spawnSync } from "node:child_process";
+import { m } from "./i18n.js";
+/** "4G", "512M", "1.5G", "off" → bytes (undefined = no cap). */
+export function parseSize(s) {
+    if (s === undefined || s === "" || s === "off" || s === false)
+        return undefined;
+    if (typeof s === "number")
+        return s;
+    const r = /^(\d+(?:\.\d+)?)\s*([KMGT]?)i?B?$/i.exec(s.trim());
+    if (!r)
+        throw new Error(m(`invalid size: ${s} (e.g. 4G, 512M, off)`, `tamanho inválido: ${s} (ex.: 4G, 512M, off)`));
+    return Math.round(Number(r[1]) * 1024 ** "BKMGT".indexOf((r[2] || "B").toUpperCase()));
+}
+let kernelOk;
+export function hasKernelCap() {
+    if (process.platform !== "linux")
+        return false;
+    kernelOk ??= spawnSync("systemd-run", ["--user", "--scope", "-q", "--", "true"], { stdio: "ignore", timeout: 10_000 }).status === 0;
+    return kernelOk;
+}
+// systemd-run expands ${...} in its arguments (the prompt!) unless told not to; the flag exists in systemd >= 254.
+let noExpand;
+const noExp = () => noExpand ??= /--expand-environment/.test(spawnSync("systemd-run", ["--help"], { encoding: "utf8" }).stdout ?? "")
+    ? ["--expand-environment=no"] : [];
+export function resolveMode(mode, cap) {
+    if (cap === undefined || mode === "off")
+        return "off";
+    if (mode === "kernel" || (mode === "auto" && hasKernelCap()))
+        return "kernel";
+    return "watchdog";
+}
+const LIST = process.platform === "win32"
+    ? ["powershell", ["-NoProfile", "-NonInteractive", "-Command",
+            "Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,WorkingSetSize | ForEach-Object { \"$($_.ProcessId) $($_.ParentProcessId) $($_.WorkingSetSize)\" }"]]
+    : ["ps", ["-A", "-o", "pid=,ppid=,rss="]];
+/** pid → [ppid, bytes] for every process (ps on Linux/macOS, CIM on Windows). */
+export function processTable() {
+    return parseTable(spawnSync(LIST[0], LIST[1], { encoding: "utf8", timeout: 15_000 }).stdout ?? "");
+}
+/** Same, without blocking: PowerShell takes seconds on Windows and the watchdog must keep running meanwhile. */
+export function processTableAsync() {
+    return new Promise((res) => execFile(LIST[0], LIST[1], { encoding: "utf8", timeout: 15_000, windowsHide: true }, (_e, out) => res(parseTable(out ?? ""))));
+}
+function parseTable(text) {
+    const t = new Map();
+    for (const line of text.split(/\r?\n/)) {
+        const [pid, ppid, mem] = line.trim().split(/\s+/).map(Number);
+        if (pid)
+            t.set(pid, [ppid, process.platform === "win32" ? mem : mem * 1024]);
+    }
+    return t;
+}
+/** Total memory of `root` and all its descendants. */
+export function treeMem(root, table = processTable()) {
+    const kids = new Map();
+    for (const [pid, [ppid]] of table)
+        kids.set(ppid, [...(kids.get(ppid) ?? []), pid]);
+    let total = 0;
+    const seen = new Set(), todo = [root];
+    while (todo.length) {
+        const p = todo.pop();
+        if (seen.has(p))
+            continue;
+        seen.add(p);
+        total += table.get(p)?.[1] ?? 0;
+        todo.push(...(kids.get(p) ?? []));
+    }
+    return total;
+}
+export function killTree(pid) {
+    if (process.platform === "win32")
+        spawnSync("taskkill", ["/T", "/F", "/PID", String(pid)], { stdio: "ignore" });
+    else
+        try {
+            process.kill(-pid, "SIGKILL");
+        }
+        catch {
+            try {
+                process.kill(pid, "SIGKILL");
+            }
+            catch { /* gone */ }
+        }
+}
+/** cmd.exe quoting for one argument (only used when Windows needs a shell). */
+export const winQuote = (a) => /[\s"&|<>^%()]/.test(a) || a === "" ? `"${a.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, "$1$1")}"` : a;
+const gb = (b) => `${(b / 2 ** 30).toFixed(1)} GB`;
+/** Run `cmd args` with stdio inherited, under the cap; resolves to the exit code (137 = killed for memory). */
+export function runCapped(cmd, args, o = {}) {
+    const mode = resolveMode(o.mode ?? "auto", o.cap);
+    if (mode === "kernel") {
+        const sd = ["--user", "--scope", "-q", ...noExp(), ...(o.unit ? [`--unit=${o.unit}`] : []), "-p", `MemoryMax=${o.cap}`,
+            ...(o.swap !== undefined ? ["-p", `MemorySwapMax=${o.swap}`] : []), "--", cmd, ...args];
+        const c = spawn("systemd-run", sd, { stdio: o.stdio ?? "inherit", cwd: o.cwd, env: o.env });
+        o.onSpawn?.(c);
+        return wait(c);
+    }
+    const win = process.platform === "win32";
+    // Own process group on Linux/macOS, so the whole tree can be killed at once.
+    // Windows: a shell only for .cmd/.bat shims (npx, claude…); an .exe runs directly (paths with spaces stay intact).
+    const shell = win && !/\.exe$/i.test(cmd), q = shell && o.quote;
+    const child = spawn(q ? winQuote(cmd) : cmd, q ? args.map(winQuote) : args, { stdio: o.stdio ?? "inherit", cwd: o.cwd, env: o.env, detached: !win, shell, windowsHide: true });
+    o.onSpawn?.(child);
+    if (mode === "off" || !child.pid)
+        return wait(child);
+    const fwd = (sig) => () => { try {
+        process.kill(-child.pid, sig);
+    }
+    catch {
+        child.kill(sig);
+    } };
+    const onInt = fwd("SIGINT"), onTerm = fwd("SIGTERM");
+    if (!win) {
+        process.on("SIGINT", onInt);
+        process.on("SIGTERM", onTerm);
+    }
+    let killed = false, sampling = false;
+    const timer = setInterval(async () => {
+        if (sampling || killed)
+            return; // a slow sample (Windows) never overlaps the next
+        sampling = true;
+        const used = treeMem(child.pid, await processTableAsync());
+        sampling = false;
+        if (used > o.cap && !killed) {
+            killed = true;
+            console.error(m(`orq: memory ${gb(used)} over the cap (${gb(o.cap)}): killing the process tree`, `orq: memória ${gb(used)} acima do limite (${gb(o.cap)}): encerrando a árvore de processos`));
+            killTree(child.pid);
+        }
+    }, o.intervalMs ?? 1000);
+    return wait(child).then((code) => {
+        clearInterval(timer);
+        process.off("SIGINT", onInt);
+        process.off("SIGTERM", onTerm);
+        return killed ? 137 : code;
+    });
+}
+const wait = (c) => new Promise((res) => {
+    c.on("error", (e) => { console.error(`orq: ${e.message}`); res(127); });
+    c.on("exit", (code, sig) => res(code ?? (sig ? 128 + 9 : 1)));
+});