@irythill/orq 0.4.0 → 0.6.0

package/dist/commands/board.js

@@ -16,18 +16,20 @@ import { collectCi, collectedAt, loadCache as loadCiCache } from "../ci.js";
 import { getPath, loadConfig } from "../config.js";
 import { writeAtomic } from "../fsutil.js";
 import { m, setLang } from "../i18n.js";
+import { argvModel } from "../agents.js";
 import { alive, status as lockStatus } from "../lock.js";
 import { expand, stateDir } from "../paths.js";
-import { processTableAsync, treeMem } from "../process.js";
+import { killedRc, processTableAsync, treeMem, treePids } from "../process.js";
 import { collect } from "../quota.js";
 import { collectRounds, mark, roundsSig } from "../rounds.js";
 import { collectRuns, rows } from "../stats.js";
+import { pendingNotices, readLog } from "../notice.js";
 import { load as loadBlocks } from "./block.js";
 import { herdrNamesAsync, nameOf } from "./claim.js";
 import { setValue } from "./set.js";
 export const USAGE = "orq board [-w <workspace>]... [--once] [--json] [--interval S]   live board: queue, agents, conductors, quota";
 const CLI = fileURLToPath(new URL("../cli.js", import.meta.url));
-const QTTL = 300_000, RECENT_MS = 30 * 60_000, ORPHAN_MS = 24 * 3600_000;
+const QTTL = 300_000, HIDE_H = 6; // finished/dead rows older than ui.board_hide_hours (default 6) are folded into a count
 const read = (f) => { try {
     return readFileSync(f, "utf8");
 }
@@ -35,19 +37,20 @@ catch {
     return "";
 } };
 const models = new Map();
-/** The model a run was started with, from its job file (-m / --model in the argv). */
-function modelOf(prefix) {
-    if (!models.has(prefix)) {
+/** The model of a run recorded before its state file had one, from its job file; a rerun on the same prefix
+ *  overwrites that file, so another unit's job says nothing about this run. */
+function modelOf(prefix, unit) {
+    if (!models.has(unit)) {
         let v;
         try {
-            const a = (JSON.parse(read(`${prefix}.job.json`)).argv ?? []);
-            const i = a.findIndex((x) => x === "-m" || x === "--model");
-            v = i >= 0 ? a[i + 1] : a.find((x) => x.startsWith("--model="))?.slice(8);
+            const j = JSON.parse(read(`${prefix}.job.json`));
+            if (!j.unit || j.unit === unit)
+                v = argvModel(j.argv ?? []);
         }
         catch { /* no job file */ }
-        models.set(prefix, v?.split("/").pop());
+        models.set(unit, v);
     }
-    return models.get(prefix);
+    return models.get(unit);
 }
 /** What the agent did last, from the tail of its log (stream JSON of claude/opencode, else the last text line). */
 export function activity(log) {
@@ -88,9 +91,47 @@ function tail(file, bytes = 16_384) {
             closeSync(fd);
     }
 }
+// --- idle detection -----------------------------------------------------------------------------------------------
+// An interactive (-T) agent that finished keeps its screen, and its pid, open: "running" for hours. Its tree's CPU time
+// (/proc/<pid>/stat, utime+stime) barely moves while it only waits. Samples persist in <state>/board/cpu.json so a
+// one-shot board and a restarted one see the same history: per unit, the CPU reading when it last did real work.
+const IDLE_MIN = 30, ACTIVE_TICKS = 200; // 2 s of CPU (at 100 ticks/s) since the baseline counts as work
+/** utime+stime, in clock ticks, summed over `pids` (Linux; undefined elsewhere or when nothing is readable). */
+export function cpuTicks(pids) {
+    if (process.platform !== "linux")
+        return undefined;
+    let sum;
+    for (const p of pids) {
+        // comm (field 2) may hold spaces and parens: fields resume after the last ")"; state is field 3, utime/stime 14/15.
+        const raw = read(`/proc/${p}/stat`), f = raw.slice(raw.lastIndexOf(")") + 2).split(" ");
+        const t = Number(f[11]) + Number(f[12]);
+        if (!Number.isNaN(t))
+            sum = (sum ?? 0) + t;
+    }
+    return sum;
+}
+/** Seconds `unit` has been idle (no real CPU work since its baseline), or 0 while it is not; updates `base` in place. */
+export function idleFor(base, unit, ticks, now, idleMin = IDLE_MIN) {
+    const b = base[unit];
+    if (!b || ticks < b.ticks || ticks - b.ticks >= ACTIVE_TICKS) {
+        base[unit] = { ticks, at: now };
+        return 0;
+    } // new, restarted tree, or worked
+    return now - b.at >= idleMin * 60_000 ? Math.round((now - b.at) / 1000) : 0;
+}
+const cpuFile = () => join(qdir(), "cpu.json");
+function idleMinutes() {
+    const v = Number(getPath(loadConfig().cfg, "ui.board_idle_min") ?? IDLE_MIN);
+    return v > 0 ? v : IDLE_MIN;
+}
 function agents(table, now) {
-    const d = join(stateDir(), "agents"), out = [];
-    let files = [];
+    const d = join(stateDir(), "agents"), out = [], running = new Set(), cpu = (() => { try {
+        return JSON.parse(read(cpuFile()));
+    }
+    catch {
+        return {};
+    } })();
+    let idleMin, files = [];
     try {
         files = readdirSync(d).filter((f) => f.endsWith(".json"));
     }
@@ -105,24 +146,43 @@ function agents(table, now) {
         }
         const pid = Number(s.pid), at = Date.parse(String(s.at)), end = s.end ? Date.parse(String(s.end)) : undefined;
         const prefix = String(s.prefix ?? "");
-        const st = s.status === "ok" || s.status === "fail" ? s.status : alive(pid) ? "running" : "died";
-        if (st === "died" && now - at > ORPHAN_MS)
-            continue;
-        if ((st === "ok" || st === "fail") && now - (end ?? at) > RECENT_MS)
-            continue;
-        const a = { unit: f.slice(0, -5), title: String(s.title ?? ""), agent: String(s.agent ?? "?"), model: modelOf(prefix),
+        const st = s.status === "ok" && killedRc(Number(s.rc)) ? "killed" : s.status === "ok" || s.status === "fail" || s.status === "killed" ? s.status : alive(pid) ? "running" : "died";
+        const a = { unit: f.slice(0, -5), title: String(s.title ?? ""), agent: String(s.agent ?? "?"), model: typeof s.model === "string" ? s.model : modelOf(prefix, f.slice(0, -5)),
             host: s.host, pid, issue: basename(dirname(prefix)), label: basename(prefix), state: st,
-            secs: Math.max(0, Math.round(((end ?? now) - at) / 1000)), cap: typeof s.cap === "number" ? s.cap : undefined };
+            secs: Math.max(0, Math.round(((end ?? now) - at) / 1000)), age: Math.max(0, Math.round((now - (end ?? at)) / 1000)), cap: typeof s.cap === "number" ? s.cap : undefined };
         if (s.rc !== undefined)
             a.rc = Number(s.rc);
         if (st === "running") {
-            if (table)
+            if (table) {
                 a.mem = treeMem(pid, table);
+                const t = cpuTicks(treePids(pid, table));
+                if (t !== undefined) {
+                    running.add(a.unit);
+                    const i = idleFor(cpu, a.unit, t, now, idleMin ??= idleMinutes());
+                    if (i) {
+                        a.state = "idle";
+                        a.idleSecs = i;
+                    }
+                }
+            }
             a.activity = activity(tail(`${prefix}.log`))?.replace(/\s+/g, " ").replace(homedir(), "~").slice(0, 60);
         }
         out.push(a);
     }
-    const rank = { running: 0, died: 1, fail: 2, ok: 3 };
+    if (table) { // keep baselines of units still running; the rest are done or gone
+        for (const u of Object.keys(cpu))
+            if (!running.has(u))
+                delete cpu[u];
+        const text = JSON.stringify(cpu);
+        if (text !== read(cpuFile())) {
+            try {
+                mkdirSync(qdir(), { recursive: true });
+                writeAtomic(cpuFile(), text);
+            }
+            catch { /* best effort */ }
+        }
+    }
+    const rank = { running: 0, idle: 1, died: 1, killed: 2, fail: 2, ok: 3 };
     return out.sort((x, y) => rank[x.state] - rank[y.state] || y.secs - x.secs);
 }
 const field = (t, k) => new RegExp(`${k}=(\\S+)`).exec(t)?.[1] ?? "";
@@ -268,7 +328,7 @@ export async function snapshot(wss, table) {
     return {
         at: new Date(now).toISOString(), mem: { used: totalmem() - freemem(), total: totalmem() }, workspaces: wss,
         queue: { holders: q.holders.map(item), waiters: q.waiters.map(item) }, agents: agents(table, now),
-        conductors: await conductors(wss), quota: quota(now), ci: ci(wss, now), blocks: loadBlocks(), scoreboard: scoreboard(wss[0], now),
+        conductors: await conductors(wss), quota: quota(now), ci: ci(wss, now), blocks: loadBlocks(), scoreboard: scoreboard(wss[0], now), notices: pendingNotices(readLog(), now),
     };
 }
 // --- render -----------------------------------------------------------------------------------------------------
@@ -307,7 +367,12 @@ const when = (sec) => {
 };
 const gb = (b) => (b ? `${(b / 2 ** 30).toFixed(1)} GB` : "-");
 const fit = (s, n) => (s.length > n ? s.slice(0, Math.max(0, n - 1)) + "…" : s.padEnd(n));
-export function render(s, theme, cols, mode = colorMode()) {
+/** Hours after which finished/dead agents leave the board (they stay in --json). */
+export function hideHours() {
+    const v = Number(getPath(loadConfig().cfg, "ui.board_hide_hours") ?? HIDE_H);
+    return v > 0 ? v : HIDE_H;
+}
+export function render(s, theme, cols, mode = colorMode(), hideH = HIDE_H) {
     const c = inks(theme, mode), W = Math.max(60, cols), out = [];
     const meter = (pct, n) => {
         const f = Math.min(n, Math.round(Math.max(0, pct) * n / 100)), k = pct >= 90 ? c.err : pct >= 70 ? c.wrn : c.ok;
@@ -322,6 +387,15 @@ export function render(s, theme, cols, mode = colorMode()) {
     out.push(`${c.surf}${c.b}${c.acc} ORQ${c.b ? "\x1b[22m" : ""}${c.surf}${c.ink2}  ${ws}${" ".repeat(Math.max(1, W - left.length - right.length))}${c.mut}${right}`);
     const mp = Math.round(100 * s.mem.used / s.mem.total);
     out.push(` ${c.mut}MEM${c.r}  ${meter(mp, 24)} ${c.ink}${gb(s.mem.used)}${c.r} ${c.mut}/ ${gb(s.mem.total)}${c.r}`);
+    // Red line(s) first: a failure the conductor may not know about is what a person must see before anything else.
+    if (s.notices.length) {
+        const ago = (at) => dur(Math.max(0, Math.round((new Date(s.at).getTime() - at) / 1000)));
+        out.push(` ${c.err}${c.b}✗ ${m(`${s.notices.length} failure(s) the conductor may not know about`, `${s.notices.length} falha(s) que o conductor pode não saber`)}${c.r}`);
+        for (const n of s.notices.slice(0, 5)) {
+            const what = n.line.replace(/^\[[^\]]+\] /, "").replace(/ answer: .*/, "");
+            out.push(` ${c.err}  ${fit(n.issue ?? "-", 10)}${c.r} ${c.ink}${fit(what, Math.max(20, W - 44))}${c.r} ${c.err}${n.why === "undelivered" ? m("not delivered", "não entregue") : m("not acknowledged", "sem resposta")}${c.r} ${c.mut}${ago(n.at)}${m(" ago", " atrás")}${c.r}`);
+        }
+    }
     section("TRANSPORT", m("test queue", "fila de testes"));
     for (const h of s.queue.holders)
         out.push(` ${c.acc}▶ REC${c.r}  ${c.ink}${fit(h.label, 34)}${c.r} ${c.ok}${m("running", "rodando")}${c.r} ${c.ink}${dur(h.secs).padEnd(7)}${c.r} ${c.ink2}${gb(h.mem)}${c.r}`
@@ -330,21 +404,29 @@ export function render(s, theme, cols, mode = colorMode()) {
     if (!s.queue.holders.length && !s.queue.waiters.length)
         out.push(` ${c.mut}${m("empty", "vazia")}${c.r}`);
     section("TRACKS", m("agents", "agentes"));
-    s.agents.forEach((a, i) => {
+    // A finished or dead agent stops being news after a while; running ones always show. age = since its end (a
+    // died row's end is unknown: since its start).
+    const old = (a) => a.state !== "running" && a.state !== "idle" && a.age > hideH * 3600;
+    const shownAgents = s.agents.filter((a) => !old(a)), hidden = s.agents.length - shownAgents.length;
+    shownAgents.forEach((a, i) => {
         const n = `${c.mut}${String(i + 1).padStart(2, "0")}${c.r}`, who = `${c.ink}${fit(a.issue, 9)}${c.r} ${c.ink2}${fit(a.label, 22)}${c.r} `
-            + `${c.ink}${fit(a.agent, 11)}${c.r}${c.mut}${fit(a.model ?? m("default", "padrão"), 17)}${c.r} ${c.ink}${dur(a.secs).padEnd(7)}${c.r}`;
-        if (a.state === "running") {
+            + `${c.ink}${fit(a.agent, 11)}${c.r}${c.mut}${fit(a.model ?? m("default", "padrão"), 17)}${c.r} ${c.ink}${(a.state === "died" ? "?" : dur(a.secs)).padEnd(7)}${c.r}`; // died: when it stopped is unknown
+        if (a.state === "running" || a.state === "idle") {
             const pct = a.cap && a.mem ? Math.round(100 * a.mem / a.cap) : 0, used = 1 + 2 + 2 + 10 + 23 + 11 + 17 + 1 + 8 + 6 + 1 + 7 + 1;
-            const warn = a.secs > 3 * 3600 ? ` ${c.err}⚠ ${m("for", "há")} ${dur(a.secs)}${c.r}` : "";
-            out.push(` ${c.acc}●${c.r} ${n}  ${who} ${meter(pct, 4)} ${c.ink2}${gb(a.mem).padEnd(6)}${c.r} ${c.mut}${fit(a.activity ?? "", Math.max(0, W - used - 2)).trimEnd()}${c.r}${warn}`);
+            const idle = a.state === "idle", mark = idle ? `${c.wrn}◌` : `${c.acc}●`;
+            const warn = !idle && a.secs > 3 * 3600 ? ` ${c.err}⚠ ${m("for", "há")} ${dur(a.secs)}${c.r}` : "";
+            const what = idle ? `${c.wrn}${m("idle", "ocioso")} ${dur(a.idleSecs ?? 0)}` : fit(a.activity ?? "", Math.max(0, W - used - 2)).trimEnd();
+            out.push(` ${mark}${c.r} ${n}  ${who} ${meter(pct, 4)} ${c.ink2}${gb(a.mem).padEnd(6)}${c.r} ${c.mut}${what}${c.r}${warn}`);
         }
         else if (a.state === "died")
             out.push(` ${c.err}●${c.r} ${n}  ${who} ${c.err}${m("runner gone without finishing", "runner sumiu sem terminar")}${c.r}`);
         else
             out.push(` ${a.state === "ok" ? c.ok : c.err}${a.state === "ok" ? "✓" : "✗"}${c.r} ${n}  ${c.mut}${a.issue.padEnd(9).slice(0, 9)} ${fit(a.label, 22)} ${fit(a.agent, 11)}${fit(a.model ?? "", 17)} ${dur(a.secs).padEnd(7)} ${a.state} rc=${a.rc ?? "?"}${c.r}`);
     });
-    if (!s.agents.length)
+    if (!shownAgents.length)
         out.push(` ${c.mut}${m("none", "nenhum")}${c.r}`);
+    if (hidden)
+        out.push(` ${c.mut}${m(`+${hidden} older finished hidden`, `+${hidden} antigos finalizados ocultos`)}${c.r}`);
     section("MASTER", m("conductors", "conductors"));
     for (const k of s.conductors)
         out.push(` ${c.ok}●${c.r} ${c.mut}${fit(k.name || k.id, 22)}${c.r} ${c.ink2}${fit(k.account || "-", 14)}${c.r} ${c.ink}${k.issues.map((i) => (k.rounds?.[i] ? `${i} ${mark(k.rounds[i])}` : i)).join("  ")}${c.r}`);
@@ -429,7 +511,7 @@ export async function board(argv) {
     }
     const tty = Boolean(process.stdout.isTTY);
     if (once || !tty) {
-        const lines = render(await snapshot(wss, await processTableAsync()), theme, process.stdout.columns ?? 100);
+        const lines = render(await snapshot(wss, await processTableAsync()), theme, process.stdout.columns ?? 100, colorMode(), hideHours());
         const c = inks(theme);
         process.stdout.write(lines.map((l) => c.base + l + (c.base ? "\x1b[K" : "")).join("\n") + (c.base ? "\x1b[0m" : "") + "\n");
         return 0;
@@ -445,7 +527,7 @@ export async function board(argv) {
         }
         drawing = true;
         try {
-            const c = inks(theme), lines = render(await snapshot(wss, table), theme, out.columns ?? 100);
+            const c = inks(theme), lines = render(await snapshot(wss, table), theme, out.columns ?? 100, colorMode(), hideHours());
             out.write(`${c.base}\x1b[H` + lines.map((l) => c.base + l + "\x1b[K").join("\n") + `${c.base}\x1b[J`);
         }
         finally {

package/dist/commands/claim.js

@@ -12,6 +12,7 @@ import { basename, join, resolve } from "node:path";
 import { writeAtomic } from "../fsutil.js";
 import { m } from "../i18n.js";
 import { acquire, release } from "../lock.js";
+import { handoffFile } from "../notice.js";
 export const USAGE = `orq claim [-w <workspace>] <ID> | -f <ID> | -r <ID> | -l | --register   issue owner among conductors (exit 1 = someone else's)
 orq claim [-w <workspace>] --from <name> [-f]   a conductor's issues by its name (part of it is enough); -f takes them all`;
 const field = (text, k) => new RegExp(`${k}=(\\S+)`).exec(text)?.[1] ?? "";
@@ -139,6 +140,7 @@ export async function claim(argv) {
     if (mode === "register") {
         if (kind !== "herdr")
             return 0;
+        rmSync(handoffFile(me), { force: true }); // this pane is a live conductor again: drop a stale `orq handoff` redirect out of it
         const dir = join(O, ".conductors");
         mkdirSync(dir, { recursive: true });
         writeAtomic(join(dir, me.replace(/[^A-Za-z0-9_-]/g, "_")), `pane=${me} kind=herdr account=${account} at=${new Date().toISOString()} name=${myName || me}\n`);

package/dist/commands/completion.js

@@ -11,16 +11,16 @@ const DESC = {
     quota: "quota per agent/account", pick: "pick agent, model and account for a role", stats: "scoreboard per agent", rounds: "rounds, time and repeated findings of an issue",
     board: "live board", lock: "test queue", run: "run a command under a memory cap", agent: "run a child agent",
     wait: "wait for child agents", verify: "tests of a diff", baseline: "tests already failing on the base",
-    instructions: "write the /issue playbook", claim: "issue owner among conductors", deps: "link node_modules into a worktree", gc: "remove merged issue worktrees", ci: "CI/CD status per claimed issue", handoff: "move a conductor low on quota to another account",
+    instructions: "write the /issue playbook", conductor: "open the conductor (Claude) in this terminal", claim: "issue owner among conductors", deps: "link node_modules into a worktree", gc: "remove merged issue worktrees", ci: "CI/CD status per claimed issue", handoff: "move a conductor low on quota to another account",
     block: "block an agent or account", completion: "shell completion script",
 };
 /** Fixed words after a subcommand. */
 export const WORDS = {
     setup: ["--preset", "--detect", "--answers", "--write", "--install", "--workspace"],
     config: ["get", "files", "-w"], lang: ["pt", "en", "auto", "toggle"], lock: ["wait", "release", "run", "status"],
-    pick: ["impl", "fix", "worker", "review", "opinion"], instructions: ["claude", "agents"], board: ["--once", "--json", "-w"],
+    pick: ["impl", "fix", "worker", "review", "opinion", "watchdog"], instructions: ["claude", "agents"], board: ["--once", "--json", "-w"],
     completion: ["bash", "zsh", "fish", "powershell"], stats: ["--days", "--json", "-w"], wait: ["--any", "--timeout", "--answer"],
-    ci: ["--json", "-w"], rounds: ["--json", "-w"],
+    ci: ["--json", "-w"], rounds: ["--json", "--diagnose", "-w"],
 };
 const q = (s) => `'${s.replace(/'/g, "''")}'`; // PowerShell single quotes
 const qf = (s) => `'${s.replace(/[\\']/g, "\\$&")}'`; // fish single quotes

package/dist/commands/conductor.js

@@ -0,0 +1,104 @@
+// orq conductor — opens the conductor (Claude Code) in the current terminal, with the workspace's conductor
+// instructions, the chosen account and model (port of setup/herdr-conductor, for any terminal and OS).
+//   orq conductor [account|-] [model] [-r <session>]
+// Workspace: the current folder if it has .orquestra-conductor.md, else $CONDUCTOR_WS. $CONDUCTOR_FILE overrides the
+// instructions file. The session is named conductor-<workspace folder>.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { claudeAccounts } from "../accounts.js";
+import { m } from "../i18n.js";
+import { runCapped } from "../process.js";
+import { claim } from "./claim.js";
+export const USAGE = `orq conductor [account|-] [model] [-r <session>]   open the conductor (Claude) here: instructions, account, model
+  model: sonnet | opus | haiku | a full id; "-" as account = default account; -r resumes that conversation`;
+export const MODELS = {
+    sonnet: "claude-sonnet-5",
+    opus: "claude-opus-5-5",
+    haiku: "claude-haiku-4-5-20251001",
+};
+export const modelId = (alias) => MODELS[alias] ?? alias;
+/** [account|-] [model] [-r|--resume <id>]; further positionals are ignored (as herdr-conductor did). */
+export function parseArgs(argv) {
+    const out = { account: "", model: "", resume: "", help: false };
+    const pos = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "-r" || a === "--resume") {
+            const v = argv[++i];
+            if (!v) {
+                out.error = m("give the session id", "informe o id da sessão");
+                return out;
+            }
+            out.resume = v;
+        }
+        else if (a === "-h" || a === "--help")
+            out.help = true;
+        else
+            pos.push(a);
+    }
+    [out.account = "", out.model = ""] = pos;
+    return out;
+}
+/** The workspace folder: cwd when it holds .orquestra-conductor.md, else $CONDUCTOR_WS (resolved); undefined if neither. */
+export function findWorkspace(cwd, env, exists = existsSync) {
+    if (exists(join(cwd, ".orquestra-conductor.md")))
+        return cwd;
+    return env.CONDUCTOR_WS ? resolve(cwd, env.CONDUCTOR_WS) : undefined;
+}
+export const instructionsFile = (ws, env) => env.CONDUCTOR_FILE ? resolve(env.CONDUCTOR_FILE) : join(ws, ".orquestra-conductor.md");
+/** The claude command line (without the executable). The instructions go by file, so no shell ever sees their text. */
+export function claudeArgs(ws, a, file) {
+    return [...(a.resume ? ["--resume", a.resume] : []), "-n", `conductor-${basename(ws)}`,
+        ...(a.model ? ["--model", modelId(a.model)] : []), "--append-system-prompt-file", file];
+}
+export async function conductor(argv) {
+    const a = parseArgs(argv);
+    if (a.help) {
+        console.log(USAGE);
+        return 0;
+    }
+    if (a.error) {
+        console.error(a.error);
+        return 2;
+    }
+    const ws = findWorkspace(process.cwd(), process.env);
+    if (!ws) {
+        console.error(m("no .orquestra-conductor.md here: cd into a workspace (orq setup --workspace <dir>) or set CONDUCTOR_WS", "não há .orquestra-conductor.md aqui: entre num workspace (orq setup --workspace <pasta>) ou defina CONDUCTOR_WS"));
+        return 2;
+    }
+    const file = instructionsFile(ws, process.env);
+    if (!existsSync(file)) {
+        console.error(`${m("conductor instructions not found", "instruções do conductor não encontradas")}: ${file}`);
+        return 2;
+    }
+    const env = { ...process.env };
+    if (a.account && a.account !== "-") {
+        const accounts = claudeAccounts(), found = accounts.find((x) => x.name === a.account);
+        if (!found) {
+            console.error(m(`account '${a.account}' does not exist. Accounts:`, `a conta '${a.account}' não existe. Contas:`));
+            for (const x of accounts)
+                console.error(`${x.name} ${x.dir}`);
+            return 1;
+        }
+        env.CLAUDE_CONFIG_DIR = found.dir;
+    }
+    if (process.env.HERDR_ENV === "1" && process.env.HERDR_PANE_ID)
+        spawnSync("herdr", ["pane", "rename", process.env.HERDR_PANE_ID, "conductor"], { stdio: "ignore", timeout: 5_000 });
+    process.chdir(ws);
+    // Registration (.orquestra/.conductors) is a herdr thing (keyed by pane id; `claim --register` does nothing elsewhere),
+    // so only inside herdr. claim reads the account from this process's env (best effort, silent).
+    const saved = process.env.CLAUDE_CONFIG_DIR;
+    if (env.CLAUDE_CONFIG_DIR)
+        process.env.CLAUDE_CONFIG_DIR = env.CLAUDE_CONFIG_DIR;
+    if (process.env.HERDR_PANE_ID)
+        try {
+            await claim(["-w", ws, "--register"]);
+        }
+        catch { /* best effort */ }
+    if (saved === undefined)
+        delete process.env.CLAUDE_CONFIG_DIR;
+    else
+        process.env.CLAUDE_CONFIG_DIR = saved;
+    return runCapped("claude", claudeArgs(ws, a, file), { mode: "off", env, cwd: ws, quote: true, tty: true });
+}

package/dist/commands/gc.js

@@ -1,20 +1,27 @@
 // orq gc — find issue worktrees whose branch is already safe to remove.
 import { spawnSync } from "node:child_process";
-import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
-import { basename, isAbsolute, join, relative, resolve } from "node:path";
+import { existsSync, readdirSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { loadConfig } from "../config.js";
 import { m } from "../i18n.js";
+import { alive } from "../lock.js";
+import { stateDir } from "../paths.js";
 import { aliveOwner } from "./claim.js";
-export const USAGE = "orq gc [-w <workspace>] [--yes] [--days N] [--json]   remove merged issue worktrees";
+export const USAGE = "orq gc [-w <workspace>] [--yes] [--days N] [--json]   remove merged issue worktrees and stale agent state";
 const git = (cwd, ...args) => spawnSync("git", ["-C", cwd, ...args], { encoding: "utf8" });
 // Paths as git prints them can differ from ours (macOS /var → /private/var, Windows C:/ vs C:\): compare real paths.
-const real = (p) => { try {
-    return realpathSync.native(p);
-}
-catch {
-    return resolve(p);
-} };
-const inside = (dir, p) => { const r = relative(dir, p); return !!r && !r.startsWith("..") && !isAbsolute(r); };
+// A path that does not exist (yet) is resolved through its deepest existing ancestor, so both sides get the same prefix.
+const real = (p) => {
+    const abs = resolve(p);
+    try {
+        return realpathSync.native(abs);
+    }
+    catch { /* missing: resolve the parent */ }
+    const up = dirname(abs);
+    return up === abs ? abs : join(real(up), basename(abs));
+};
+const fold = (p) => (process.platform === "win32" ? p.toLowerCase() : p); // NTFS is case-insensitive
+const inside = (dir, p) => { const r = relative(fold(dir), fold(p)); return !!r && !r.startsWith("..") && !isAbsolute(r); };
 // ORQ_GH may be a .js file (tests: a fake gh that also runs on Windows).
 const gh = (cwd, args) => {
     const bin = process.env.ORQ_GH || "gh";
@@ -22,6 +29,30 @@ const gh = (cwd, args) => {
         : spawnSync(bin, args, { cwd, encoding: "utf8" });
 };
 const output = (cwd, ...args) => { const r = git(cwd, ...args); return r.status === 0 ? r.stdout.trim() : undefined; };
+/** Per-agent state files (<state>/agents/<unit>.json) of runs under `ws` that are finished or dead and older than `days`. */
+function staleAgentStates(ws, days, now) {
+    const dir = join(stateDir(), "agents"), out = [];
+    let files = [];
+    try {
+        files = readdirSync(dir).filter((f) => f.endsWith(".json"));
+    }
+    catch { /* no runs yet */ }
+    for (const f of files) {
+        try {
+            const s = JSON.parse(readFileSync(join(dir, f), "utf8"));
+            if (!inside(real(ws), real(String(s.prefix ?? ""))))
+                continue;
+            const finished = s.status === "ok" || s.status === "fail" || s.status === "killed";
+            if (!finished && alive(Number(s.pid)))
+                continue;
+            const since = Date.parse(String(s.end ?? s.at));
+            if (now - since > days * 86400_000)
+                out.push(join(dir, f));
+        }
+        catch { /* unreadable state: leave it */ }
+    }
+    return out;
+}
 export async function gc(argv, clock = Date.now) {
     let ws = process.cwd(), yes = false, json = false, days = 14;
     for (let i = 0; i < argv.length; i++) {
@@ -153,6 +184,10 @@ export async function gc(argv, clock = Date.now) {
             }
             git(join(ws, row.repo), "worktree", "prune");
         }
+    const stale = staleAgentStates(ws, days, clock());
+    if (yes)
+        for (const f of stale)
+            rmSync(f, { force: true });
     if (json)
         console.log(JSON.stringify(rows));
     else {
@@ -160,5 +195,8 @@ export async function gc(argv, clock = Date.now) {
         const w = table[0].map((_, i) => Math.max(...table.map((t) => t[i].length)));
         console.log(table.map((t) => t.map((c, i) => i < t.length - 1 ? c.padEnd(w[i]) : c).join("  ")).join("\n"));
     }
+    if (stale.length && !json)
+        console.log(yes ? m(`pruned ${stale.length} stale agent state file(s)`, `${stale.length} arquivo(s) de estado de agente antigo(s) removido(s)`)
+            : m(`${stale.length} stale agent state file(s) (finished/dead, older than ${days} days): --yes removes them`, `${stale.length} arquivo(s) de estado de agente antigo(s) (terminados/mortos, mais de ${days} dias): --yes remove`));
     return failed ? 1 : 0;
 }

package/dist/commands/handoff.js

@@ -163,6 +163,7 @@ async function move(ws, c, to, dir, model, mark) {
         for (const id of c.issues)
             writeAtomic(join(ws, ".orquestra", id, "owner"), `pane=${pane} kind=herdr account=${basename(dir)} at=${new Date().toISOString()} name=${label}\n`);
         writeAtomic(handoffFile(c.pane), pane);
+        rmSync(handoffFile(pane), { force: true }); // the new pane is live: a leftover redirect out of it would make a cycle
         const regs = join(ws, ".orquestra", ".conductors");
         mkdirSync(regs, { recursive: true });
         writeAtomic(join(regs, pane.replace(/[^A-Za-z0-9_-]/g, "_")), `pane=${pane} kind=herdr account=${basename(dir)} at=${new Date().toISOString()} name=${label}\n`);

package/dist/commands/pick.js

@@ -13,7 +13,7 @@ import { collect } from "../quota.js";
 import { PICK_ROLES, resolveRole, vendorOf } from "../roles.js";
 import { collectRuns, rows } from "../stats.js";
 import { load as loadBlocks } from "./block.js";
-export const USAGE = `orq pick <impl|fix|worker|review|opinion> [--level simple|medium|heavy] [--impl-vendor <v>|--impl-agent <a>]
+export const USAGE = `orq pick <impl|fix|worker|review|opinion|watchdog> [--level simple|medium|heavy] [--impl-vendor <v>|--impl-agent <a>]
          [--exclude-agent <a>]... [-w <workspace>] [--explain] [--no-record]
 orq pick fix --same <impl pick file>   same agent/model/account as the implementer, effort one level up`;
 // The board refreshes this file; fresher than 10 min → no new quota requests.

package/dist/commands/rounds.js

@@ -1,9 +1,22 @@
 // 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";
-export const USAGE = "orq rounds <ID> [-w <workspace>] [--json]   rounds vs max_rounds, time per round, repeated findings, alert level";
+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}`),
@@ -12,8 +25,8 @@ const why = (r) => ({
     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 function rounds(argv) {
-    let ws, id, json = false;
+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]) {
@@ -24,6 +37,8 @@ export function rounds(argv) {
         }
         else if (argv[i] === "--json")
             json = true;
+        else if (argv[i] === "--diagnose")
+            diagnose = true;
         else if (!id && !argv[i].startsWith("-"))
             id = argv[i];
         else {
@@ -42,6 +57,8 @@ export function rounds(argv) {
         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;
@@ -54,5 +71,62 @@ export function rounds(argv) {
         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++) {