@irythill/orq 0.4.0 → 0.6.0

package/dist/commands/verify.js

@@ -11,6 +11,7 @@ import { tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { getPath, loadConfig } from "../config.js";
 import { m } from "../i18n.js";
+import { ackPrefix } from "../notice.js";
 import { dropWorktree, failures, git, inJob, JS_EXT, launchJob, linkModules, runnerArgs, runnerOf, runTests, testCap, today, unsupported } from "../testrun.js";
 export const USAGE = "orq verify -w <workspace> -r <repo> -d <worktree> -b <base> -o <prefix> [-g group] [-x]   tests of the diff, new vs pre-existing failures";
 export async function verify(argv) {
@@ -36,6 +37,7 @@ export async function verify(argv) {
         }
     const out = resolve(o.o);
     mkdirSync(dirname(out), { recursive: true });
+    ackPrefix(out); // re-running the tests of an issue: its failure notices were seen
     rmSync(`${out}.done`, { force: true });
     rmSync(`${out}.txt`, { force: true });
     // Title "<ID> verify <repo>" (ID = the prefix's folder, .orquestra/<ID>/) so closing the issue finds the tab.

package/dist/commands/wait.js

@@ -6,6 +6,8 @@ import { existsSync, readFileSync } from "node:fs";
 import { basename } from "node:path";
 import { m } from "../i18n.js";
 import { alive } from "../lock.js";
+import { ackPrefix } from "../notice.js";
+import { doneStatus } from "../process.js";
 export const USAGE = "orq wait [--any] [--timeout <s>] [--answer] <prefix>...   block until child agents finish (exit 1 = one failed)";
 const read = (f) => { try {
     return readFileSync(f, "utf8");
@@ -28,7 +30,10 @@ export function doneLine(prefix) {
     }
     catch { /* verify/baseline: no job */ }
     const answer = [`${prefix}.out.md`, `${prefix}.txt`].find(existsSync) ?? prefix;
-    return { line: `[ORQ AGENT DONE] ${title} ${done} answer: ${answer}`, ok: /\bstatus=ok\b/.test(done) };
+    const status = doneStatus(done);
+    if (status === "killed")
+        done = done.replace(/\bstatus=\S+/, "status=killed"); // legacy "status=ok rc=137"
+    return { line: `[ORQ AGENT DONE] ${title} ${done} answer: ${answer}`, ok: status === "ok" };
 }
 export async function wait(argv) {
     let any = false, timeout = 0, answer = false;
@@ -61,6 +66,7 @@ export async function wait(argv) {
                 continue;
             pending.splice(pending.indexOf(p), 1);
             console.log(d.line);
+            ackPrefix(p); // the conductor has the result in hand: this issue's failure notice is acknowledged
             if (answer) {
                 const t = read(`${p}.out.md`);
                 if (t)

package/dist/config.js

@@ -15,6 +15,7 @@ export const DEFAULTS = {
         mem_enforce: "auto", // auto (kernel cap where possible, else watchdog) | kernel | watchdog | off
         test_slots: 1, // test suites in parallel on the machine
         close_tab_after: 20, // seconds until a finished child tab closes (0 = never)
+        tui_idle_close_min: 30, // minutes a finished -T agent waits for a follow-up before it is closed (0 = never)
         tui: false, // children in the agent's own screen (-T) by default
         terminal: "auto", // where children show their output: auto (herdr, else tmux, else plain) | herdr | tmux | plain
     },
@@ -27,7 +28,7 @@ export const DEFAULTS = {
         max_rounds: 2, // fix rounds before stopping and calling the user
         review: "other-vendor", // other-vendor | any
     },
-    ui: { lang: "auto", theme: "gunmetal" }, // lang: auto | en | pt · theme: gunmetal | chrome | lcd | terminal
+    ui: { lang: "auto", theme: "gunmetal", desktop_notify: true, board_hide_hours: 6 }, // board_hide_hours: finished/dead agents older than this leave `orq board` (still in --json) · lang: auto | en | pt · theme: gunmetal | chrome | lcd | terminal · desktop_notify: desktop popup for failures (Linux, notify-send)
     // Where quota comes from, per agent: "builtin" | "none" | false | { command = "..." } (see src/quota.ts).
     // "claude" covers every account in claude-accounts.
     quota: { claude: "builtin", codex: "builtin", opencode: "builtin", antigravity: "builtin", copilot: "builtin" },

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,310 @@
+// 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, rmSync, 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;
+/** Does herdr know this pane? true | false (herdr answered pane_not_found) | undefined (unreachable or unclear).
+ *  `pane get`, not `agent get`: a live pane whose agent exited has no agent but is still a place to type. */
+export function paneExists(pane, run = exec) {
+    const r = run("herdr", ["pane", "get", pane], 2_000);
+    if (r.status === 0)
+        return true;
+    if (r.status === null)
+        return undefined; // herdr is not installed / did not answer
+    return /"code"\s*:\s*"pane_not_found"/.test(`${r.stdout}\n${r.stderr}`) ? false : undefined;
+}
+/**
+ * Follow `orq handoff` redirects to the pane that now holds the conductor (stops at cycles and unreadable files).
+ * Walks the whole chain by files and returns the furthest pane that still exists, so a dead middle hop (A→B→C, B gone,
+ * C alive) does not strand the notice. The redirect out of that last live pane leads nowhere live: it is deleted (and
+ * logged). When herdr cannot be asked, a hop counts as live (the old behaviour: follow blindly).
+ */
+export function currentPane(pane, run = exec) {
+    const chain = [pane], 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;
+        chain.push(next);
+        pane = next;
+    }
+    let last = 0;
+    for (let i = 1; i < chain.length; i++)
+        if (paneExists(chain[i], run) !== false)
+            last = i;
+    // A redirect out of the last live pane exists only when the chain went on to dead panes.
+    if (last < chain.length - 1 && existsSync(handoffFile(chain[last]))) {
+        try {
+            rmSync(handoffFile(chain[last]), { force: true });
+            append({ id: `redirect-${Date.now().toString(36)}`, ev: "redirect", pane: chain[last], detail: `stale handoff to closed ${chain[last + 1]} removed` });
+        }
+        catch { /* best effort */ }
+    }
+    return chain[last];
+}
+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/process.js

@@ -77,6 +77,13 @@ export function treePids(root, table = processTable()) {
 export function treeMem(root, table = processTable()) {
     return treePids(root, table).reduce((t, p) => t + (table.get(p)?.[1] ?? 0), 0);
 }
+/** An exit code of 128+signal (137 = SIGKILL): the process was killed, it did not finish. */
+export const killedRc = (rc) => rc !== undefined && rc > 128 && rc <= 128 + 64;
+/** "status=ok rc=137" (written before `killed` existed) is a kill, not a success: the status a done line really means. */
+export function doneStatus(line) {
+    const st = /\bstatus=(\S+)/.exec(line)?.[1], rc = /\brc=(\d+)/.exec(line)?.[1];
+    return st === "ok" && killedRc(rc === undefined ? undefined : Number(rc)) ? "killed" : st;
+}
 export function killTree(pid, group = true) {
     if (process.platform === "win32")
         spawnSync("taskkill", ["/T", "/F", "/PID", String(pid)], { stdio: "ignore" });

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) => {