@irythill/orq 0.4.0 → 0.5.0

package/dist/diagnose.js

@@ -0,0 +1,105 @@
+// Watchdog layer 2: `orq rounds <ID> --diagnose` asks a cheap, independent agent WHY the rounds don't converge.
+// Advisory only (read only agent, no edits). Its answer is kept in .orquestra/<ID>/diagnosis-<rounds>.md; `orq agent -R -F`
+// past policy.max_rounds needs that file for the current round count, newer than the latest fix/review file.
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { countRounds } from "./rounds.js";
+export const DIAG_CAP = 24000; // characters of fix/review text put in the prompt
+export const RECOMMENDATIONS = ["continue", "split", "change-implementer", "ask-user"];
+/** Keep the start and the end of a long text (the verdict is usually at one of them). */
+export function trim(s, max) {
+    if (s.length <= max)
+        return s;
+    const head = Math.ceil(max * 0.6), tail = max - head;
+    return `${s.slice(0, head)}\n[... ${s.length - max} characters trimmed ...]\n${s.slice(s.length - tail)}`;
+}
+const reason = (r) => ({
+    over_max: `rounds ${r.n} is over max_rounds ${r.max}`,
+    at_max: `rounds ${r.n} reached max_rounds ${r.max}`,
+    same_finding: `the same heavy finding came back in ${r.n} reviews`,
+    repeated: `${r.n} heavy finding(s) repeated across reviews`,
+    slow: `round ${r.rounds?.join(", ")} was much slower than the others`,
+})[r.code];
+const mins = (s) => `${Math.round(s / 60)} min`;
+/** The pure part: metrics + fix files + review outputs → the watchdog prompt. Each document is trimmed to its share of `cap`. */
+export function buildPrompt(x, fixes, reviews, cap = DIAG_CAP) {
+    const docs = [...fixes, ...reviews], each = docs.length ? Math.max(1500, Math.floor(cap / docs.length)) : 0;
+    const block = (d) => `--- ${d.name} ---\n${trim(d.text.trim(), each)}\n--- end of ${d.name} ---`;
+    return [
+        `You are an independent watchdog for issue ${x.issue}. An implementer agent and a reviewer agent have been going back and forth`,
+        `and the review/fix loop is not converging (alert: ${x.level}). Diagnose WHY. You are advisory only: do not edit, create or run anything;`,
+        `answer from the material below.`,
+        ``,
+        `## Metrics`,
+        `- fix rounds: ${x.rounds} (policy.max_rounds = ${x.max}); total time ${mins(x.secs)}; ${x.findings} finding(s) across reviews`,
+        ...x.perRound.map((r) => `- ${r.round === 0 ? "implementation + first review" : `fix ${r.round} + review`}: ${mins(r.secs)}`),
+        ...(x.reasons.length ? [`- why the alert: ${x.reasons.map(reason).join("; ")}`] : []),
+        ...(x.repeats.length ? [`- heavy findings that repeat:`, ...x.repeats.map((r) => `  - rounds ${r.rounds.join(",")}: ${r.file ? `${r.file} ` : ""}${r.title.slice(0, 160)}`)] : []),
+        ``,
+        `## What to decide`,
+        `Look for the real cause, for example: reviewer and implementer disagree about the requirement or the style; the scope is too big for one`,
+        `branch; a flaky or environment-dependent test; an ambiguous spec or acceptance criterion; fixes that fix the symptom of each review and`,
+        `introduce the next one; a reviewer that keeps raising new things instead of checking the previous ones.`,
+        ``,
+        `## Answer format`,
+        `A short diagnosis (at most 15 lines): the cause, with the evidence (which round, which file or finding). Then, as the LAST line, exactly:`,
+        `RECOMMENDATION: <${RECOMMENDATIONS.join(" | ")}> - one sentence why`,
+        `where continue = one more round is likely to converge, split = split the issue into smaller ones, change-implementer = another`,
+        `implementer should take over, ask-user = a decision or information only the user has is blocking.`,
+        ``,
+        `## Material`,
+        docs.length ? docs.map(block).join("\n\n") : "(no fix or review files)",
+        ``,
+    ].join("\n");
+}
+/** The "RECOMMENDATION: ..." line of a diagnosis (the last one), without markdown emphasis; undefined when there is none. */
+export function recommendation(text) {
+    const ls = text.split("\n").map((l) => l.replace(/[*_`]/g, "").trim()).filter((l) => /^RECOMMENDATION\s*:/i.test(l));
+    return ls.length ? ls[ls.length - 1] : undefined;
+}
+const num = (re, n) => { const r = re.exec(n); return r ? Number(r[1]) : undefined; };
+/** The pure gate for `orq agent -R -F` past max_rounds. ok = diagnosis-<rounds>.md exists and is not older than the latest
+ *  fix-<n>.md / review-*.out.md; missing = no such file; stale = it is older than one of them (the loop went on after it). */
+export function diagnosisGate(rounds, files) {
+    const d = files.find((f) => num(/^diagnosis-(\d+)\.md$/, f.name) === rounds);
+    if (!d)
+        return "missing";
+    const latest = Math.max(0, ...files.filter((f) => /^(fix-\d+\.md|review-.+\.out\.md)$/.test(f.name)).map((f) => f.mtimeMs));
+    return d.mtimeMs >= latest ? "ok" : "stale";
+}
+const times = (dir) => {
+    try {
+        return readdirSync(dir).map((name) => ({ name, mtimeMs: statSync(join(dir, name)).mtimeMs }));
+    }
+    catch {
+        return [];
+    }
+};
+const read = (f) => { try {
+    return readFileSync(f, "utf8");
+}
+catch {
+    return "";
+} };
+/** The impure part of the gate: the folder .orquestra/<ID>/ → verdict and the round count it was judged for. */
+export function gateFor(dir) {
+    const files = times(dir), rounds = countRounds(dir, files.map((f) => f.name)); // the same count `orq rounds` shows
+    return { verdict: diagnosisGate(rounds, files), rounds };
+}
+/** fix-<n>.md and review-*.out.md of an issue folder, in round order, as documents for buildPrompt. */
+export function evidence(dir) {
+    const names = times(dir).map((f) => f.name);
+    const fixes = names.filter((n) => /^fix-\d+\.md$/.test(n)).sort((a, b) => num(/(\d+)/, a) - num(/(\d+)/, b));
+    const rv = (n) => num(/-(\d+)\.out\.md$/, n) ?? 0;
+    const reviews = names.filter((n) => /^review-.+\.out\.md$/.test(n)).sort((a, b) => rv(a) - rv(b) || a.localeCompare(b));
+    const doc = (n) => ({ name: n, text: read(join(dir, n)) });
+    return { fixes: fixes.map(doc), reviews: reviews.map(doc) };
+}
+/** Highest diagnosis-<n>.md of an issue folder → its recommendation line (for `orq rounds`). */
+export function latestDiagnosis(dir) {
+    const ns = times(dir).map((f) => num(/^diagnosis-(\d+)\.md$/, f.name)).filter((n) => n !== undefined);
+    if (!ns.length)
+        return undefined;
+    const n = Math.max(...ns);
+    return { n, line: recommendation(read(join(dir, `diagnosis-${n}.md`))) };
+}

package/dist/notice.js

@@ -0,0 +1,282 @@
+// Notices to the conductor: a finished child (orq agent / verify / baseline) or a red CI tells the conductor's herdr
+// pane. Delivery is its own detached process (`orq notice <pane> <line>`), so it outlives whoever sent it (a job tab
+// that closes, an end-of-turn hook), and everything it does is written to <state>/notices.jsonl, one JSON per line:
+//   notice     the line, the pane, the issue, loud or not        try        one attempt: agent state + result
+//   delivered  herdr accepted the prompt                         failed     gave up (retries exhausted)
+//   ack        the conductor acted on the issue afterwards (orq wait printed its result, or orq verify / orq agent ran)
+// Besides the typed line (which a busy or confused conductor can miss) a FAILURE is also signalled where a person
+// looks: a herdr notification with sound, a "✗" title on the conductor's pane (display only, expires by itself) and,
+// if ui.desktop_notify allows, a desktop notification. Successes stay quiet: a plain herdr notification, nothing else.
+// `orq board` reads the same log to show failures that were not delivered or not yet acknowledged.
+import { spawn, spawnSync } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getPath, loadConfig } from "./config.js";
+import { m } from "./i18n.js";
+import { stateDir } from "./paths.js";
+export const logFile = () => join(stateDir(), "notices.jsonl");
+/** Where `orq handoff` records the pane that replaced a conductor's. */
+export const handoffFile = (pane) => join(stateDir(), "handoff", pane.replace(/\W/g, "_"));
+/** Wait before retry n (1-based): 5s, 15s, 45s, 2min, 5min — six attempts, about eight minutes in all. */
+export const BACKOFF_S = [5, 15, 45, 120, 300];
+export const WINDOW_MS = 60 * 60_000; // the board looks at failures this recent
+// A notice with no outcome is "in flight" while its delivery process is alive. It writes an event per attempt, and the
+// longest silence between two is the longest backoff plus one attempt's timeouts (get 10s + wait 70s + prompt 20s):
+// past that (plus a margin) with nothing new in the log, the process died and the notice counts as undelivered.
+export const GRACE_MS = (BACKOFF_S[BACKOFF_S.length - 1] + 100 + 30) * 1000;
+const TITLE_TTL_MS = 30 * 60_000; // the "✗" pane title clears itself
+/** After `tries` attempts (1-based) that ended in `r`: done, wait and try again, or give up. */
+export function nextStep(tries, r) {
+    if (r === "sent")
+        return { kind: "done" };
+    return tries <= BACKOFF_S.length ? { kind: "retry", afterMs: BACKOFF_S[tries - 1] * 1000 } : { kind: "giveup" };
+}
+/** A failure is loud (sound, pane title, desktop): "status=" other than ok in a done line, or a red CI line. */
+export function isLoud(line) {
+    const st = /\bstatus=(\S+)/.exec(line)?.[1];
+    if (st !== undefined)
+        return st !== "ok";
+    return /^\[ORQ CI\].* failed\b/.test(line);
+}
+/** The issue a notice is about: from the answer path (.orquestra/<ID>/...), else the first ID-looking word. */
+export function issueOf(text) {
+    return /\.orquestra[\\/]([^\\/\s]+)[\\/]/.exec(text)?.[1] ?? /\b([A-Z][A-Z0-9]*-\d+)\b/.exec(text)?.[1];
+}
+/** Popup title and body from a notice line: "✗ <title>" / "✓ <title>", details in the body. */
+export function popup(line) {
+    const loud = isLoud(line);
+    const t = line.replace(/^\[(HERDR-AGENT DONE|ORQ AGENT DONE|ORQ CI)\] /, "");
+    const i = t.indexOf(" status=");
+    const title = i < 0 ? t : t.slice(0, i), body = i < 0 ? "" : t.slice(i + 1).replace(/ answer: .*/, "");
+    return { title: `${loud ? "✗" : /\bstatus=/.test(line) ? "✓" : "•"} ${title}`, body };
+}
+/** ui.desktop_notify: true | false | "auto"; default on, but only on Linux with notify-send. */
+export function desktopEnabled(setting, platform, hasBin) {
+    if (setting === false || setting === "false" || setting === "off")
+        return false;
+    return platform === "linux" && hasBin;
+}
+export function append(e, file = logFile()) {
+    try {
+        mkdirSync(dirname(file), { recursive: true });
+        appendFileSync(file, JSON.stringify({ at: Date.now(), ...e }) + "\n");
+        // Rotate instead of rewriting: a rename is atomic, so a concurrent detached writer's append lands in the old or the
+        // new file, never lost. readLog() reads both.
+        if (statSync(file).size > 512 * 1024)
+            renameSync(file, `${file}.1`);
+    }
+    catch { /* the log never takes the caller down */ }
+}
+export function readLog(file = logFile()) {
+    const one = (f) => {
+        try {
+            return readFileSync(f, "utf8").split("\n").filter(Boolean).flatMap((l) => { try {
+                return [JSON.parse(l)];
+            }
+            catch {
+                return [];
+            } });
+        }
+        catch {
+            return [];
+        }
+    };
+    return [...one(`${file}.1`), ...one(file)];
+}
+/**
+ * The failures the board puts in red: loud notices from the last `windowMs` that were not delivered (retries exhausted,
+ * or no outcome after `graceMs` — the delivering process died) or were delivered but not acknowledged. Acknowledged =
+ * an `ack` for the same issue at or after the notice. One entry per issue (the newest). Newest first.
+ */
+export function pendingNotices(events, now, windowMs = WINDOW_MS, graceMs = GRACE_MS) {
+    const by = new Map();
+    for (const e of events)
+        by.set(e.id, [...(by.get(e.id) ?? []), e]);
+    const out = new Map();
+    for (const [id, evs] of by) {
+        const n = evs.find((e) => e.ev === "notice");
+        if (!n || !n.loud || now - n.at > windowMs)
+            continue;
+        if (n.issue && events.some((e) => e.ev === "ack" && e.issue === n.issue && e.at >= n.at))
+            continue;
+        const delivered = evs.some((e) => e.ev === "delivered"), failed = evs.some((e) => e.ev === "failed");
+        if (!delivered && !failed && now - Math.max(...evs.map((e) => e.at)) < graceMs)
+            continue; // still being delivered
+        const p = { id, ...(n.issue ? { issue: n.issue } : {}), line: n.line ?? "", at: n.at, why: delivered ? "unacknowledged" : "undelivered" };
+        // A delivered notice with no issue has nothing to acknowledge against: nothing to show.
+        if (p.why === "unacknowledged" && !n.issue)
+            continue;
+        const key = n.issue ?? id, old = out.get(key);
+        if (!old || old.at < p.at)
+            out.set(key, p);
+    }
+    return [...out.values()].sort((a, b) => b.at - a.at);
+}
+const herdrOk = (r) => r.status === 0;
+/** `herdr agent get` → the agent's state (idle | working | blocked | done | unknown), undefined when there is no such agent. */
+export function agentState(r) {
+    if (!herdrOk(r))
+        return undefined;
+    try {
+        return JSON.parse(r.stdout).result?.agent?.agent_status ?? "unknown";
+    }
+    catch {
+        return undefined;
+    }
+}
+/** One try: look at the agent, wait out a dialog, submit the prompt. */
+export function attempt(pane, line, d) {
+    const got = d.run("herdr", ["agent", "get", pane], 10_000), state = agentState(got);
+    if (state === undefined)
+        return { r: "no-agent", detail: (got.stderr || got.stdout).trim().slice(0, 200) || `exit ${got.status}` };
+    // Blocked = a dialog is open: typing now is rejected. Give it a minute to be answered; busy (working) is sent at
+    // once — the agent's own input queue holds the line until its turn ends.
+    if (state === "blocked")
+        d.run("herdr", ["agent", "wait", pane, "--until", "idle", "--until", "done", "--until", "working", "--timeout", "60000"], 70_000);
+    const p = d.run("herdr", ["agent", "prompt", pane, line], 20_000);
+    if (herdrOk(p))
+        return { r: "sent", state, detail: state === "working" ? "agent was working: queued in its input" : "ok" };
+    const err = (p.stderr || p.stdout).trim().slice(0, 200) || `exit ${p.status}`;
+    return { r: /agent_blocked/.test(err) ? "blocked" : "error", state, detail: err };
+}
+/** The visual signals, independent of the conductor reading text. Never throws. */
+export function signal(pane, line, d) {
+    const loud = isLoud(line), { title, body } = popup(line);
+    try {
+        d.run("herdr", ["notification", "show", title, ...(body ? ["--body", body] : []), "--sound", loud ? "request" : "none"], 10_000);
+        if (!loud)
+            return;
+        if (pane)
+            d.run("herdr", ["pane", "report-metadata", "--source", "orq", "--title", title, "--ttl-ms", String(TITLE_TTL_MS), pane], 10_000);
+        if (d.desktop)
+            d.run("notify-send", ["-u", "critical", "-a", "orq", title, body], 10_000);
+    }
+    catch { /* best effort */ }
+}
+/** Deliver one notice: signals first, then the typed line with retries. True when herdr accepted it. */
+export async function deliver(id, pane, line, d) {
+    signal(pane, line, d);
+    if (!pane)
+        return true; // no conductor pane: the signals are all there is
+    for (let n = 1;; n++) {
+        const a = attempt(pane, line, d);
+        d.log({ ev: "try", n, pane, detail: `${a.r}${a.state ? ` (agent ${a.state})` : ""}: ${a.detail}` });
+        const s = nextStep(n, a.r);
+        if (s.kind === "done") {
+            d.log({ ev: "delivered", n, pane });
+            return true;
+        }
+        if (s.kind === "giveup") {
+            d.log({ ev: "failed", n, pane, detail: a.detail });
+            if (isLoud(line) && d.desktop)
+                d.run("notify-send", ["-u", "critical", "-a", "orq", m("✗ notice NOT delivered to the conductor", "✗ aviso NÃO entregue ao conductor"), popup(line).title], 10_000);
+            return false;
+        }
+        await d.sleep(s.afterMs);
+    }
+}
+const exec = (cmd, args, timeoutMs = 15_000) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8", timeout: timeoutMs });
+    return { status: r.error ? null : r.status, stdout: r.stdout ?? "", stderr: r.stderr || (r.error ? String(r.error.message) : "") };
+};
+const hasBin = (b) => spawnSync(process.platform === "win32" ? "where" : "which", [b], { stdio: "ignore" }).status === 0;
+/** Follow `orq handoff` redirects to the pane that now holds the conductor (stops at cycles and unreadable files). */
+export function currentPane(pane) {
+    const seen = new Set();
+    while (!seen.has(pane) && existsSync(handoffFile(pane))) {
+        seen.add(pane);
+        let next;
+        try {
+            next = readFileSync(handoffFile(pane), "utf8").trim();
+        }
+        catch {
+            break;
+        }
+        if (!next || next === pane)
+            break;
+        pane = next;
+    }
+    return pane;
+}
+function realDeps(id, pane, issue) {
+    let setting;
+    try {
+        setting = getPath(loadConfig().cfg, "ui.desktop_notify");
+    }
+    catch { /* broken config: defaults */ }
+    return {
+        run: exec, sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        log: (e) => append({ id, pane, ...(issue ? { issue } : {}), ...e }),
+        desktop: desktopEnabled(setting, process.platform, hasBin("notify-send")),
+    };
+}
+const CLI = fileURLToPath(new URL("./cli.js", import.meta.url));
+/**
+ * Tell the conductor's herdr pane. Returns at once: logs the notice, then starts `orq notice --send` detached so the
+ * delivery (signals, retries, waiting out a dialog) survives the caller and nothing waits on it.
+ */
+export function notify(pane, line, start = startDetached) {
+    const id = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+    pane = currentPane(pane);
+    append({ id, ev: "notice", pane, loud: isLoud(line), line, ...(issueOf(line) ? { issue: issueOf(line) } : {}) });
+    try {
+        start(["notice", "--send", id, pane, line]);
+    }
+    catch {
+        append({ id, ev: "failed", pane, detail: "could not start the delivery process" });
+    }
+}
+function startDetached(argv) {
+    spawn(process.execPath, [CLI, ...argv], { detached: true, stdio: "ignore" })
+        .on("error", () => append({ id: argv[2], ev: "failed", pane: argv[3], detail: "could not start the delivery process" })).unref();
+}
+/** The delivery process: `orq notice --send <id> <pane> <line>`. */
+export async function send(id, pane, line) {
+    return deliver(id, pane, line, realDeps(id, pane, issueOf(line)));
+}
+/** Acknowledge an issue's failures: the conductor acted on it. Clears the "✗" pane titles it set. Never throws. */
+export function ack(issue, run = exec, file = logFile()) {
+    if (!issue)
+        return;
+    try {
+        const open = pendingNotices(readLog(file), Date.now(), WINDOW_MS, 0).filter((p) => p.issue === issue);
+        if (!open.length)
+            return;
+        append({ id: `ack-${Date.now().toString(36)}`, ev: "ack", issue }, file);
+        // Per pane: the title shows the newest failure still open there; cleared only when none remain.
+        const evs = readLog(file), paneOf = (id) => evs.find((e) => e.id === id && e.ev === "notice")?.pane;
+        const left = pendingNotices(evs, Date.now(), WINDOW_MS, 0);
+        for (const pane of new Set(open.map((p) => paneOf(p.id)).filter((x) => !!x))) {
+            const next = left.find((p) => paneOf(p.id) === pane);
+            run("herdr", ["pane", "report-metadata", "--source", "orq", ...(next ? ["--title", popup(next.line).title, "--ttl-ms", String(TITLE_TTL_MS)] : ["--clear-title"]), pane], 5_000);
+        }
+    }
+    catch { /* best effort */ }
+}
+/** ack() for a run prefix (<ws>/.orquestra/<ID>/<name>). */
+export const ackPrefix = (prefix) => ack(issueOf(prefix.replace(/\\/g, "/")));
+export const USAGE = "orq notice [--list] [-n N]   the delivery log of notices to conductors (what was sent, retried, failed)";
+export async function noticeCmd(argv) {
+    if (argv[0] === "--send")
+        return (await send(argv[1], argv[2], argv.slice(3).join(" "))) ? 0 : 1;
+    let n = 20;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "-n")
+            n = Number(argv[++i]);
+        else if (argv[i] !== "--list") {
+            console.error(USAGE);
+            return 2;
+        }
+    }
+    const evs = readLog();
+    if (!evs.length) {
+        console.log(m(`no notices yet (${logFile()})`, `nenhum aviso ainda (${logFile()})`));
+        return 0;
+    }
+    for (const e of evs.slice(-Math.max(1, n || 20))) {
+        const t = new Date(e.at).toTimeString().slice(0, 8);
+        console.log(`${t} ${e.id} ${e.ev}${e.loud ? " LOUD" : ""}${e.pane ? ` pane=${e.pane}` : ""}${e.issue ? ` issue=${e.issue}` : ""}${e.n ? ` try=${e.n}` : ""} ${e.line ?? e.detail ?? ""}`.trimEnd());
+    }
+    return 0;
+}

package/dist/pick.js

@@ -1,3 +1,18 @@
+// Picks agent, model, effort and account for a role (port of orq-pick, plus fixed roles).
+//   fixed role: the first agent of [agent, ...fallback] that passes the filters wins — no scoring, never swapped
+//               for an agent the user didn't list.
+//   auto role:  every pool agent that passes is scored:
+//     quality * delivery + tokens * economy + speed * quickness − rotation * (picks in the last `window`)
+//     − reserve (agents with reserve = true) + explore (fewer than `min_samples` runs)
+// Filters: --exclude-agent, orq block, nobody reviews their own code (unless no other agent can), cross-vendor rule, a model for the role/level,
+// quota under the limits: policy.quota_week (95) on the weekly window, and on the 5h one policy.quota_5h per level
+// (simple 90, medium 85, heavy 80): a heavy task needs more room left to finish.
+// An agent's `headroom` (points) lowers both limits for it: that share of its accounts stays for the conductors.
+// An account whose quota reading says the login expired is skipped, with the fix command in the note.
+// Pacing: an account whose usage, at the pace so far in a window (used ÷ elapsed share), projects past
+// that window's pick limit (the filter's) at its reset is passed over for another account under the limit when the agent has several,
+// and otherwise loses policy.pacing_penalty (default 0.3, 0 = off) of score — soft, never a drop.
+import { agentDef, usesPrompt } from "./agents.js";
 import { m } from "./i18n.js";
 import { humanReset } from "./quota.js";
 import { legacyRole, resolveRole, vendorOf } from "./roles.js";
@@ -62,7 +77,7 @@ export function modelFor(a, role, level) {
         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 ms = models[lr] ?? (lr === "fix" ? models.impl : lr === "watchdog" ? models.opinion ?? models.review : undefined) ?? {};
     const spec = ms[level] ?? ms.default ?? ms.medium ?? ms.simple;
     if (!spec)
         return undefined;
@@ -71,6 +86,15 @@ export function modelFor(a, role, level) {
 }
 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 ?? {}) });
+/** The merged definition (built-in + config) takes a prompt; an agent that can't be resolved doesn't. */
+function takesPrompt(cfg, name) {
+    try {
+        return usesPrompt(agentDef(cfg, name));
+    }
+    catch {
+        return false;
+    }
+}
 export function pick(inp) {
     const { cfg, role, level } = inp;
     const agents = (cfg.agents ?? {});
@@ -101,15 +125,19 @@ export function pick(inp) {
             out(name, m("blocked (orq block -l)", "bloqueado (orq block -l)"));
             continue;
         }
-        if ((role === "review" || role === "opinion") && name === inp.implAgent && someoneElse) {
+        if ((role === "review" || role === "opinion" || role === "watchdog") && name === inp.implAgent && someoneElse) {
             out(name, m("it implemented this code", "foi quem implementou"));
             continue;
         }
-        if ((role === "review" || role === "opinion") && res.rule === "other-vendor" && inp.implVendor && otherVendor
+        if ((role === "review" || role === "opinion" || role === "watchdog") && res.rule === "other-vendor" && inp.implVendor && otherVendor
             && vendorOf(name, a) === inp.implVendor) {
             out(name, m("same vendor as the implementer", "mesmo fornecedor do implementador"));
             continue;
         }
+        if (role === "watchdog" && !takesPrompt(cfg, name)) {
+            out(name, m("ignores prompts (a review tool)", "ignora prompts (ferramenta de revisão)"));
+            continue;
+        }
         const mf = modelFor(a, role, level);
         if (!mf) {
             out(name, m(`no model for ${role}/${level}`, `sem modelo para ${role}/${level}`));
@@ -175,7 +203,8 @@ export function pick(inp) {
         const chosen = ranked[0];
         const acct = qn.length > 1 ? chosen?.n : 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"));
+        const stOf = (sr) => inp.stats.find((r) => r.role === sr && r.agent === name && r.model === (mf[0].split("/").pop() || "default"));
+        const st = stOf(statRole) ?? (role === "watchdog" ? stOf("review") : undefined); // no watchdog runs yet: its review record
         pass.push({ agent: name, model: mf[0], effort: mf[1], acct, a, st, pace: chosen?.pace, hot: Boolean(chosen?.hot) });
         if (res.mode === "fixed")
             break; // the first that passes wins

package/dist/roles.js

@@ -1,7 +1,7 @@
 /** What the conductor asks for (orq pick <role>) → the [roles] section that answers it. */
-export const PICK_ROLES = ["impl", "fix", "worker", "review", "opinion"];
+export const PICK_ROLES = ["impl", "fix", "worker", "review", "opinion", "watchdog"];
 const SECTION = {
-    impl: ["primary"], fix: ["primary"], worker: ["workers", "primary"], review: ["reviewer"], opinion: ["opinion"],
+    impl: ["primary"], fix: ["primary"], worker: ["workers", "primary"], review: ["reviewer"], opinion: ["opinion"], watchdog: ["watchdog"],
 };
 /** The role name used in the old agents.<name>.roles lists. */
 export const legacyRole = (r) => (r === "worker" ? "impl" : r);
@@ -10,7 +10,16 @@ export const BUILTIN_VENDORS = {
     claude: "anthropic", codex: "openai", antigravity: "google", copilot: "github",
 };
 export const vendorOf = (name, a) => a?.vendor ?? BUILTIN_VENDORS[name];
+const count = (r) => (r.mode === "fixed" ? r.order : r.pool).length;
+/** The watchdog (orq rounds --diagnose) uses its own role when something declares it, else the opinion pool, else the review one. */
 export function resolveRole(cfg, role) {
+    const own = direct(cfg, role);
+    if (role !== "watchdog" || count(own))
+        return own;
+    const op = direct(cfg, "opinion");
+    return count(op) ? op : direct(cfg, "review");
+}
+function direct(cfg, role) {
     const agents = (cfg.agents ?? {});
     const roles = (cfg.roles ?? {});
     const policyRule = String((cfg.policy ?? {}).review ?? "other-vendor");

package/dist/rounds.js

@@ -114,6 +114,18 @@ export function metrics(issue, f) {
         raise("warn", { code: "slow", n: slow.length, rounds: slow });
     return { issue, rounds: f.rounds, max: f.max, secs: f.secs, perRound: f.perRound, findings: f.findings.length, repeats: reps, level, reasons };
 }
+/** Rounds of an issue folder: the highest .rounds-<session> counter or fix-<n>.md. Shared by `orq rounds` and the -F gate. */
+export function countRounds(dir, names) {
+    let n = 0;
+    for (const f of names) {
+        const fx = /^fix-(\d+)\.md$/.exec(f);
+        if (fx)
+            n = Math.max(n, Number(fx[1]));
+        else if (f.startsWith(".rounds-"))
+            n = Math.max(n, Number(read(join(dir, f))) || 0);
+    }
+    return n;
+}
 /** The impure part: read .orquestra/<issue>/. undefined when the issue has no fix or review files at all. */
 export function collectRounds(ws, issue, max) {
     const dir = join(ws, ".orquestra", issue);
@@ -126,7 +138,6 @@ export function collectRounds(ws, issue, max) {
     }
     const mt = (n) => statSync(join(dir, n)).mtimeMs;
     const fixes = new Map(), reviews = new Map();
-    let counter = 0;
     for (const n of names) {
         const fx = /^fix-(\d+)\.md$/.exec(n);
         if (fx)
@@ -137,13 +148,11 @@ export function collectRounds(ws, issue, max) {
         const rv = /^review-(.+?)(?:-(\d+))?\.out\.md$/.exec(n), k = rv && rv[2] !== undefined && fixes.has(Number(rv[2])) ? Number(rv[2]) : 0;
         if (rv)
             reviews.set(k, [...(reviews.get(k) ?? []), n]);
-        else if (n.startsWith(".rounds-"))
-            counter = Math.max(counter, Number(read(join(dir, n))) || 0);
     }
     if (!reviews.size && !fixes.size)
         return undefined;
-    const rounds = Math.max(counter, 0, ...fixes.keys());
-    const all = names.filter((n) => !n.startsWith(".")).map(mt), t0 = Math.min(...all), t1 = Math.max(...all);
+    const rounds = countRounds(dir, names);
+    const all = names.filter((n) => !n.startsWith(".") && !/^(diagnosis|watchdog)-/.test(n)).map(mt), t0 = Math.min(...all), t1 = Math.max(...all);
     // Round k runs from fix-k.md (round 0: the oldest file) to the next fix, the last one to the newest file.
     const starts = [t0, ...Array.from({ length: rounds }, (_, i) => fixes.get(i + 1) ?? NaN)];
     const perRound = starts.map((s, k) => {

package/dist/stats.js

@@ -6,7 +6,7 @@
 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 ROLE = /^(impl|fix\d*|review\d*|[a-z]+-review\d*|watchdog\d*)-?/;
 const read = (f) => { try {
     return readFileSync(f, "utf8");
 }
@@ -115,8 +115,9 @@ export function collectRuns(ws, days) {
             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";
+                : rm && rm[1].startsWith("watchdog") ? "watchdog"
+                    : 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() !== "",

package/dist/testrun.js

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

package/package.json

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