@irythill/orq 0.3.0 → 0.5.0

package/dist/commands/rounds.js

@@ -0,0 +1,132 @@
+// orq rounds <ID> [-w <workspace>] [--json]   per-issue round metrics from .orquestra/<ID>/ (src/rounds.ts), no LLM
+// orq rounds <ID> --diagnose [-w <workspace>]  warn/stop only: a cheap read only "watchdog" agent (another vendor than the
+//   implementer when known) diagnoses why the rounds don't converge → .orquestra/<ID>/diagnosis-<rounds>.md (advisory)
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getPath, loadConfig } from "../config.js";
+import { buildPrompt, evidence, latestDiagnosis, recommendation } from "../diagnose.js";
+import { m } from "../i18n.js";
+import { expand } from "../paths.js";
+import { collectRounds, mark } from "../rounds.js";
+import { alive } from "../lock.js";
+import { wait } from "./wait.js";
+export const USAGE = `orq rounds <ID> [-w <workspace>] [--json]   rounds vs max_rounds, time per round, repeated findings, alert level
+orq rounds <ID> --diagnose [-w <workspace>]   on warn/stop: an independent cheap agent diagnoses why rounds don't converge (advisory; needed for orq agent -R -F)`;
+export const WATCHDOG_TIMEOUT = 900; // seconds `orq rounds --diagnose` waits for the agent
+const CLI = fileURLToPath(new URL("../cli.js", import.meta.url));
+const dur = (s) => (s >= 3600 ? `${Math.floor(s / 3600)}h${String(Math.floor(s / 60) % 60).padStart(2, "0")}m` : s >= 60 ? `${Math.floor(s / 60)}m${String(s % 60).padStart(2, "0")}s` : `${s}s`);
+const why = (r) => ({
+    over_max: m(`rounds ${r.n} > max_rounds ${r.max}`, `rodadas ${r.n} > max_rounds ${r.max}`),
+    at_max: m(`rounds ${r.n} = max_rounds ${r.max}`, `rodadas ${r.n} = max_rounds ${r.max}`),
+    same_finding: m(`same finding in ${r.n} reviews`, `mesmo achado em ${r.n} revisões`),
+    repeated: m(`${r.n} repeated finding(s)`, `${r.n} achado(s) repetido(s)`),
+    slow: m(`round ${r.rounds?.join(", ")} much slower than the others`, `rodada ${r.rounds?.join(", ")} bem mais lenta que as outras`),
+})[r.code];
+export async function rounds(argv) {
+    let ws, id, json = false, diagnose = false;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "-w") {
+            if (!argv[i + 1]) {
+                console.error(USAGE);
+                return 2;
+            }
+            ws = expand(argv[++i]);
+        }
+        else if (argv[i] === "--json")
+            json = true;
+        else if (argv[i] === "--diagnose")
+            diagnose = true;
+        else if (!id && !argv[i].startsWith("-"))
+            id = argv[i];
+        else {
+            console.error(USAGE);
+            return 2;
+        }
+    }
+    if (!id) {
+        console.error(USAGE);
+        return 2;
+    }
+    ws ??= getPath(loadConfig().cfg, "_workspace") ?? process.cwd();
+    const { cfg } = loadConfig(ws); // the workspace's own policy.max_rounds
+    const x = collectRounds(ws, id, Number(getPath(cfg, "policy.max_rounds") ?? 2));
+    if (!x) {
+        console.error(m(`no rounds recorded for ${id} in ${ws}/.orquestra`, `nenhuma rodada registrada para ${id} em ${ws}/.orquestra`));
+        return 1;
+    }
+    if (diagnose)
+        return diagnoseIssue(ws, id, x);
+    if (json) {
+        console.log(JSON.stringify(x, null, 2));
+        return 0;
+    }
+    console.log(`${id}  ${mark(x)}  ${m("alert", "alerta")}: ${x.level}${x.reasons.length ? ` (${x.reasons.map(why).join("; ")})` : ""}`);
+    console.log(m(`rounds ${x.rounds} of max ${x.max}; total time ${dur(x.secs)}; ${x.findings} finding(s) across reviews`, `rodadas ${x.rounds} de no máx. ${x.max}; tempo total ${dur(x.secs)}; ${x.findings} achado(s) nas revisões`));
+    for (const r of x.perRound)
+        console.log(`  ${r.round === 0 ? m("impl + review", "impl + revisão") : m(`fix ${r.round} + review`, `fix ${r.round} + revisão`)}: ${dur(r.secs)}`);
+    if (x.repeats.length)
+        console.log(m("repeated findings:", "achados repetidos:"));
+    for (const r of x.repeats)
+        console.log(`  [${m("rounds", "rodadas")} ${r.rounds.join(",")}] ${r.title.slice(0, 100)}`);
+    const d = latestDiagnosis(join(ws, ".orquestra", id));
+    if (d)
+        console.log(`${m("diagnosis", "diagnóstico")} ${d.n}: ${d.line ?? m("(no RECOMMENDATION line)", "(sem linha RECOMMENDATION)")}`);
+    return 0;
+}
+const orq = (...a) => spawnSync(process.execPath, [CLI, ...a], { encoding: "utf8" });
+/** --diagnose: pick a watchdog, run it read only on the evidence, keep its answer as diagnosis-<rounds>.md. */
+async function diagnoseIssue(ws, id, x) {
+    if (x.level === "ok") {
+        console.log(m(`${id}: level is ok, no diagnosis needed`, `${id}: nível ok, não precisa de diagnóstico`));
+        return 0;
+    }
+    const dir = join(ws, ".orquestra", id), prefix = join(dir, `watchdog-${x.rounds}-${Date.now()}`), out = join(dir, `diagnosis-${x.rounds}.md`);
+    // The implementer, when known (impl-<repo>.pick saved by the playbook): the watchdog must be another vendor.
+    const implPick = readdirSync(dir).filter((n) => /^impl-.+\.pick$/.test(n)).map((n) => /(?:^|\s)-a (\S+)/.exec(readFileSync(join(dir, n), "utf8"))?.[1]).find(Boolean);
+    // A watchdog still running for this issue (a previous --diagnose that timed out or was interrupted): don't start another.
+    for (const n of readdirSync(dir).filter((f) => /^watchdog-.+\.pid$/.test(f))) {
+        const pid = Number(readFileSync(join(dir, n), "utf8"));
+        if (pid && alive(pid)) {
+            console.error(m(`a watchdog for ${id} is still running (${n}, pid ${pid}); wait for it or stop it first`, `um watchdog de ${id} ainda está rodando (${n}, pid ${pid}); espere ou encerre antes`));
+            return 1;
+        }
+    }
+    const ev = evidence(dir);
+    writeFileSync(`${prefix}.md`, buildPrompt(x, ev.fixes, ev.reviews));
+    const p = orq("pick", "watchdog", "--level", "simple", "-w", ws, ...(implPick ? ["--impl-agent", implPick] : []));
+    if (p.status !== 0) {
+        console.error(p.stderr.trim() || `orq pick watchdog: exit ${p.status}`);
+        return p.status ?? 1;
+    }
+    const picked = p.stdout.trim().split(/\s+/);
+    // The agent runs in a scratch folder (everything it needs is in the prompt): it can't touch the issue files, even write sandboxed.
+    const scratch = mkdtempSync(join(tmpdir(), "orq-watchdog-"));
+    try {
+        const a = orq("agent", ...picked, "-r", "-t", `${id} watchdog`, "-d", scratch, "-g", "watchdog", "-o", prefix, "--", `${prefix}.md`);
+        process.stderr.write(a.stderr);
+        process.stdout.write(a.stdout);
+        if (a.status !== 0)
+            return a.status ?? 1;
+        return await finish(await wait(["--timeout", String(WATCHDOG_TIMEOUT), prefix]), prefix, out);
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}
+async function finish(rc, prefix, out) {
+    if (rc === 124) {
+        console.error(m(`diagnosis not written: the watchdog agent did not finish in ${WATCHDOG_TIMEOUT}s`, `diagnóstico não gravado: o agente watchdog não terminou em ${WATCHDOG_TIMEOUT}s`));
+        return 124;
+    }
+    if (rc !== 0 || !existsSync(`${prefix}.out.md`)) {
+        console.error(m("the watchdog agent failed; no diagnosis written", "o agente watchdog falhou; diagnóstico não gravado"));
+        return 1;
+    }
+    copyFileSync(`${prefix}.out.md`, out);
+    console.log(m(`diagnosis saved to ${out}`, `diagnóstico gravado em ${out}`));
+    console.log(recommendation(readFileSync(out, "utf8")) ?? m("(no RECOMMENDATION line in the answer)", "(sem linha RECOMMENDATION na resposta)"));
+    return 0;
+}

package/dist/commands/stats.js

@@ -5,7 +5,7 @@ import { expand } from "../paths.js";
 import { collectRuns, rows } from "../stats.js";
 export const USAGE = "orq stats [-w <workspace>] [--days N] [--json]   scoreboard: delivery, time and tokens per agent";
 const k = (n) => (n === null ? "-" : n >= 1000 ? `${Math.round(n / 1000)}k` : String(n));
-const ORDER = ["impl", "fix", "review", "other"];
+const ORDER = ["impl", "fix", "review", "watchdog", "other"];
 export function stats(argv) {
     let ws, days = 30, json = false;
     for (let i = 0; i < argv.length; i++) {

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,7 @@ 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";
 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");
@@ -61,6 +62,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

@@ -20,11 +20,14 @@ export const DEFAULTS = {
     },
     agents: {}, // only agents declared here are available; run templates: built in for 5 (src/agents.ts), or `run = ...`
     policy: {
-        quota_limit: 90, // quota % from which an agent/account is skipped
+        quota_limit: 90, // also caps the 5h pick limit; marks ! in `orq quota --line`
+        pacing_penalty: 0.3, // score penalty when usage at the current pace would pass the pick limit by the window's reset (0 = off)
+        quota_week: 95, // weekly % from which an agent/account is skipped
+        quota_5h: { simple: 90, medium: 85, heavy: 80 }, // same for the 5h window, per task level
         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 }, // 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/identity.js

@@ -0,0 +1,55 @@
+// Who is logged in behind an agent or account name — only to tell that the login CHANGED. `orq block` records it, and a
+// block made for one login is dropped once another is there (a new account has its own quota). Ids are short hashes of
+// something stable per login (never the secret itself); undefined = cannot tell, so the block stays until its date.
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { claudeAccounts } from "./accounts.js";
+import { agyToken, minimaxKey } from "./quota.js";
+const hash = (s) => createHash("sha256").update(s).digest("hex").slice(0, 16);
+const json = (f) => { try {
+    return JSON.parse(readFileSync(f, "utf8"));
+}
+catch {
+    return undefined;
+} };
+/** Claude Code keeps the logged-in account in .claude.json: inside the config dir, or in ~ for the default ~/.claude. */
+function claudeId(dir) {
+    const files = [join(dir, ".claude.json"), ...(resolve(dir) === join(homedir(), ".claude") ? [join(homedir(), ".claude.json")] : [])];
+    for (const f of files) {
+        const id = json(f)?.oauthAccount?.accountUuid;
+        if (id)
+            return String(id);
+    }
+    return undefined;
+}
+function copilotId() {
+    const r = spawnSync("gh", ["api", "/user", "-q", ".id"], { encoding: "utf8", timeout: 15_000 });
+    return r.status === 0 && r.stdout.trim() ? r.stdout.trim() : undefined;
+}
+/** The login id for a block name (an agent, or a Claude account), or undefined when it cannot be told. */
+export function loginId(name) {
+    const accs = claudeAccounts();
+    const acc = accs.find((a) => a.name === name);
+    if (acc)
+        return claudeId(acc.dir);
+    if (name === "claude") { // the whole vendor: any account changing counts
+        const ids = accs.map((a) => claudeId(a.dir));
+        return ids.every(Boolean) ? hash(ids.sort().join(",")) : undefined;
+    }
+    if (name === "codex") {
+        const t = json(join(process.env.CODEX_HOME ?? join(homedir(), ".codex"), "auth.json"))?.tokens;
+        return t?.account_id ?? undefined;
+    }
+    if (name === "antigravity" || name === "agy")
+        return agyToken()?.acct;
+    if (name === "copilot")
+        return copilotId();
+    if (name === "opencode" || name === "minimax") {
+        const k = minimaxKey();
+        return k ? hash(k) : undefined;
+    }
+    return undefined;
+}

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;
+}