@irythill/orq 0.1.0 → 0.3.0

package/dist/commands/agent.js

@@ -4,6 +4,10 @@
 // Returns at once; `orq wait <prefix>` blocks until .done. A conductor in herdr (HERDR_PANE_ID) also gets ONE line
 // "[HERDR-AGENT DONE] <title> status=... answer: <prefix>.out.md" typed into its pane by herdr-notify.
 // The launcher writes <prefix>.job.json and starts `orq agent --run <job>` on the terminal host; that runner does the rest.
+// -T (or machine.tui / HERDR_AGENT_TUI=1): the agent's own screen (its `tui` template) in a herdr tab or tmux window,
+// same cap and files. The agent calls `orq agent --turn <job> <kind>` at every end of turn, which writes .out.md/.id/
+// .done and notifies; the screen stays open (holding memory) until you close it. -T -R with the screen still open types
+// the follow-up into it; with the screen closed it reopens the session (tui_resume).
 import { spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { appendFileSync, copyFileSync, createWriteStream, existsSync, mkdirSync, openSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
@@ -14,11 +18,12 @@ import { agentDef, ALIASES, expandString, expandTemplate, FORMATS } from "../age
 import { loadConfig } from "../config.js";
 import { writeAtomic } from "../fsutil.js";
 import { m } from "../i18n.js";
+import { alive } from "../lock.js";
 import { stateDir } from "../paths.js";
 import { killTree, parseSize, resolveMode, runCapped } from "../process.js";
-import { closeOwnTab, detectHost, launch, shq } from "../terminal.js";
+import { closeOwnTab, detectHost, launch, screenOpen, shq, typeInto } from "../terminal.js";
 import { dropWorktree, notify } from "../testrun.js";
-export const USAGE = "orq agent -a <agent> -t <title> -d <dir> -o <prefix> [-g group] [-m model] [-e effort] [-c account] [-i file]... [-b base] [-r] [-R session] -- <prompt.md>   run a child agent";
+export const USAGE = "orq agent -a <agent> -t <title> -d <dir> -o <prefix> [-g group] [-m model] [-e effort] [-c account] [-i file]... [-b base] [-r] [-R session] [-T] -- <prompt.md>   run a child agent";
 const CLI = fileURLToPath(new URL("../cli.js", import.meta.url));
 const PF = ".herdr-agent-prompt.md"; // prompt_in_dir file name (kept from herdr-agent)
 const git = (dir, ...a) => {
@@ -28,8 +33,10 @@ const git = (dir, ...a) => {
 export async function agent(argv) {
     if (argv[0] === "--run")
         return runJob(argv[1]);
+    if (argv[0] === "--turn")
+        return turn(argv[1], argv[2], argv.slice(3));
     let a = process.env.AGENT || "codex", g = "", t = "", d = "", o = "", model = "", effort = "", acc = "", resume = "", base = "";
-    let ro = false, prompt;
+    let ro = false, tui = false, prompt;
     const inc = [];
     for (let i = 0; i < argv.length; i++) {
         const x = argv[i], v = () => argv[++i] ?? "";
@@ -63,10 +70,8 @@ export async function agent(argv) {
             v();
         else if (x === "-r")
             ro = true;
-        else if (x === "-T") {
-            console.error(m("-T (the agent's own TUI) only exists in herdr: use herdr-agent -T", "-T (a TUI do próprio agente) só existe no herdr: use herdr-agent -T"));
-            return 2;
-        }
+        else if (x === "-T")
+            tui = true;
         else if (!x.startsWith("-") && prompt === undefined)
             prompt = x;
         else {
@@ -94,10 +99,27 @@ export async function agent(argv) {
         console.error(m(`-c only applies to agents with Claude accounts (claude)`, `-c só vale para agentes com contas Claude (claude)`));
         return 2;
     }
-    if (resume && !def.resume) {
+    const mach = (cfg.machine ?? {});
+    const host = detectHost(cfg);
+    // Screen by default (machine.tui, HERDR_AGENT_TUI=1) only where it can be: a terminal host and an agent with a screen.
+    if (!tui && (process.env.HERDR_AGENT_TUI === "1" || mach.tui === true) && host !== "plain" && def.tui && (!resume || def.tui_resume))
+        tui = true;
+    if (tui && !def.tui) {
+        console.error(m(`-T: ${a} has no screen mode (agents.${a}.tui)`, `-T: ${a} não tem modo tela (agents.${a}.tui)`));
+        return 2;
+    }
+    if (resume && !tui && !def.resume) {
         console.error(m(`${a} has no resume template (agents.${a}.resume)`, `${a} não tem template de resume (agents.${a}.resume)`));
         return 2;
     }
+    if (tui && resume && !def.tui_resume) {
+        console.error(m(`-T -R: ${a} has no tui_resume template`, `-T -R: ${a} não tem template tui_resume`));
+        return 2;
+    }
+    if (tui && host === "plain") {
+        console.error(m("-T shows the agent's own screen: it needs herdr or tmux (run inside one, or set ORQ_TERMINAL)", "-T mostra a tela do próprio agente: precisa do herdr ou do tmux (rode dentro de um, ou defina ORQ_TERMINAL)"));
+        return 2;
+    }
     const repo = resolve(d), O = resolve(o);
     let P = resolve(prompt);
     if (!existsSync(repo)) {
@@ -119,9 +141,6 @@ export async function agent(argv) {
         writeFileSync(`${O}.diff`, r.stdout);
         inc.push(`${O}.diff`);
     }
-    // Follow-ups (-R) reuse the prefix: remove the previous round's result so ".done exists" means "this one finished".
-    for (const s of [".done", ".out.md", ".pid"])
-        rmSync(O + s, { force: true });
     if (inc.length) {
         let text = readFileSync(P, "utf8");
         for (const f of inc)
@@ -129,6 +148,24 @@ export async function agent(argv) {
         writeFileSync(`${O}.prompt.md`, text);
         P = `${O}.prompt.md`;
     }
+    // Follow-ups (-R) reuse the prefix: remove the previous round's result so ".done exists" means "this one finished".
+    // -T -R with the screen still open: the follow-up is typed into it (its runner, and .pid, carry on). Open = the agent
+    // is still running there, not just the pane: after it exits the pane may hold a shell, which must never get the text.
+    let open = "", pid = 0;
+    try {
+        open = readFileSync(`${O}.pane`, "utf8").trim();
+        pid = Number(readFileSync(`${O}.pid`, "utf8"));
+    }
+    catch { /* first run or ended */ }
+    if (tui && resume && alive(pid) && screenOpen(open)) {
+        for (const s of [".done", ".out.md"])
+            rmSync(O + s, { force: true });
+        typeInto(open, readFileSync(P, "utf8"));
+        console.log(`[orq agent] ${t} → ${open} ${m("(follow-up typed into the open screen)", "(follow-up digitado na tela aberta)")}`);
+        return 0;
+    }
+    for (const s of [".done", ".out.md", ".pid"])
+        rmSync(O + s, { force: true });
     const throwaway = Boolean(def.throwaway && ro && !resume);
     const dir = throwaway ? `${repo}.review-${process.pid}` : repo;
     const gd = git(repo, "rev-parse", "--path-format=absolute", "--git-common-dir");
@@ -140,22 +177,36 @@ export async function agent(argv) {
     }
     catch { /* none */ }
     const session = resume || (def.session === "uuid" ? randomUUID() : "");
+    const tpl = tui ? (resume ? def.tui_resume : def.tui) : resume ? def.resume : def.run;
+    // End of turn (-T): the agent runs `orq agent --turn <job> <kind>`; Claude gets it as a Stop hook, Codex as notify,
+    // OpenCode through a plugin orq writes next to the job.
+    const hook = [process.execPath, CLI, "agent", "--turn", `${O}.job.json`, def.turn_hook ?? "text"];
+    // OpenCode v2 drops a partial MCP entry without a word: each one turned off needs its type and command too.
+    const off = { type: "local", command: ["true"], enabled: false };
+    const ocCfg = {
+        mcp: { plane: off, shadcn: off, "linear-server": off },
+        permission: { bash: "allow", question: "deny", webfetch: "deny",
+            external_directory: { "*": "deny", ...(gd ? { [`${gd}/*`]: "allow" } : {}), "/tmp/*": "allow", ...(nm ? { [`${nm}/*`]: "allow" } : {}) },
+            edit: ro ? "deny" : "allow" },
+    };
+    if (tui && def.turn_hook === "opencode") {
+        mkdirSync(`${O}.opencode`, { recursive: true }); // a v2 plugin is a folder with index.js
+        writeFileSync(join(`${O}.opencode`, "index.js"), opencodePlugin(O, hook));
+        ocCfg.plugin = [`${O}.opencode`];
+        if (model && model !== "auto")
+            ocCfg.model = model; // the screen has no -m
+    }
     const vars = {
-        prompt: P, prompt_text: def.run.includes("{prompt_text}") || def.resume?.includes("{prompt_text}") ? readFileSync(P, "utf8") : "",
+        prompt: P, prompt_text: tpl.includes("{prompt_text}") ? readFileSync(P, "utf8") : "",
         prompt_hint: `Read the file ${PF} (in the current folder, with your file-reading tool): it holds your complete instructions for this task. Follow them. ${PF} is not part of the code: don't review or edit it.`,
         out: `${O}.out.md`, dir, repo, title: t, model: model === "auto" ? "" : model, effort, session,
-        gitdir: gd ?? "", gitroots: roots, gitroots_json: JSON.stringify(roots), mode: [],
-        opencode_config: JSON.stringify({
-            mcp: { plane: { enabled: false }, shadcn: { enabled: false }, "linear-server": { enabled: false } },
-            permission: { bash: "allow", question: "deny", webfetch: "deny",
-                external_directory: { "*": "deny", ...(gd ? { [`${gd}/*`]: "allow" } : {}), "/tmp/*": "allow", ...(nm ? { [`${nm}/*`]: "allow" } : {}) },
-                edit: ro ? "deny" : "allow" },
-        }),
+        gitdir: gd ?? "", gitroots: roots, gitroots_json: JSON.stringify(roots), mode: [], opencode_config: JSON.stringify(ocCfg),
+        hook_cmd: hook.map(shq).join(" "), hook_json: JSON.stringify(hook),
+        hook_settings: JSON.stringify({ hooks: { Stop: [{ hooks: [{ type: "command", command: hook.map(shq).join(" ") }] }] } }),
     };
     vars.mode = expandTemplate((ro ? def.readonly : def.write) || "", vars);
-    const tpl = resume ? def.resume : def.run;
     const cmd = expandTemplate(tpl, vars);
-    if (!tpl.includes("{mode}") && !resume)
+    if (!tpl.includes("{mode}") && !resume && !tui)
         cmd.push(...vars.mode);
     const env = {};
     for (const [k, val] of Object.entries(def.env ?? {}))
@@ -168,9 +219,7 @@ export async function agent(argv) {
         }
         env.CLAUDE_CONFIG_DIR = ac.dir;
     }
-    const mach = (cfg.machine ?? {});
     const closeAfter = Number(process.env.HERDR_CLOSE_DELAY ?? mach.close_tab_after ?? 20);
-    const host = detectHost(cfg);
     const unit = `herdr-agent-${Math.floor(Date.now() / 1000)}-${process.pid}`; // herdr-board lists herdr-agent-* scopes
     const job = {
         agent: a, title: t, repo, dir, prefix: O, prompt: P, argv: cmd, env, unset: def.unset_env ?? [], stdin: Boolean(def.stdin),
@@ -179,7 +228,7 @@ export async function agent(argv) {
         host, unit, cap: parseSize(def.mem_max ?? mach.agent_mem_max ?? "off"),
         swap: parseSize(mach.agent_swap_max), mode: mach.mem_enforce ?? "auto",
         throwaway, promptInDir: Boolean(def.prompt_in_dir), closeAfter,
-        keep: process.env.HERDR_KEEP_TAB === "1" || process.env.ORQ_KEEP_TAB === "1" || closeAfter <= 0,
+        keep: process.env.HERDR_KEEP_TAB === "1" || process.env.ORQ_KEEP_TAB === "1" || closeAfter <= 0, tui,
     };
     writeAtomic(`${O}.job.json`, JSON.stringify(job, null, 1));
     // Readable copy of the command (also what orq stats and herdr-board read).
@@ -187,9 +236,102 @@ export async function agent(argv) {
         `cd ${shq(dir)}\n${Object.entries(env).map(([k, val]) => `${k}=${shq(val)} `).join("")}${cmd.map(shq).join(" ")}${job.stdin ? ` < ${shq(P)}` : ""}\n`);
     const where = launch(host, { group: g || "agents", title: t, dir: repo, argv: [process.execPath, CLI, "agent", "--run", `${O}.job.json`], id: unit, keep: job.keep });
     writeFileSync(`${O}.pane`, `${where}\n`);
-    console.log(`[orq agent] ${t} → ${where}`);
+    console.log(`[orq agent] ${t} → ${where}${tui ? " (TUI)" : ""}`);
     return 0;
 }
+/** OpenCode (v2) plugin for -T: when the main session's run ends, its last answer goes to `orq agent --turn`. */
+function opencodePlugin(O, hook) {
+    return `// orq agent -T end of turn (generated)
+import { writeFileSync } from "fs"; import { spawn } from "child_process";
+export default {
+  id: "orq-turn",
+  setup: async (ctx) => {
+    const sub = new Set(), text = new Map(); // child sessions (subagents); answer text per session
+    (async () => {
+      for await (const e of ctx.event.subscribe()) {
+        const d = e.data ?? {}, id = d.sessionID;
+        if (e.type === "session.created" && d.parentID) sub.add(id);
+        if (!id || sub.has(id)) continue;
+        if (e.type === "session.execution.started") text.set(id, { msg: "", parts: [] });
+        else if (e.type === "session.text.ended") {
+          const t = text.get(id) ?? { msg: "", parts: [] };
+          if (t.msg !== d.assistantMessageID) { t.msg = d.assistantMessageID; t.parts = []; } // only the last message
+          t.parts[d.ordinal ?? t.parts.length] = d.text ?? ""; text.set(id, t);
+        } else if (e.type.startsWith("session.execution.") && e.type !== "session.execution.started") {
+          const f = ${JSON.stringify(`${O}.turn.md`)};
+          writeFileSync(f, (text.get(id)?.parts ?? []).filter((x) => x !== undefined).join("\\n"));
+          spawn(${JSON.stringify(hook[0])}, [...${JSON.stringify(hook.slice(1))}, id, f], { detached: true, stdio: "ignore" }).unref();
+        }
+      }
+    })().catch(() => {});
+    return {};
+  },
+};
+`;
+}
+/** End of a turn on the agent's screen: answer, session and .done from the agent's own hook payload. Never fails the agent. */
+function turn(file, kind, rest) {
+    try {
+        const j = JSON.parse(readFileSync(file, "utf8")), O = j.prefix;
+        let answer = "", sid;
+        if (kind === "codex") {
+            const e = JSON.parse(rest[rest.length - 1] ?? "{}");
+            if (e.type !== "agent-turn-complete")
+                return 0;
+            answer = String(e["last-assistant-message"] ?? "");
+            sid = e["thread-id"];
+        }
+        else if (kind === "claude") {
+            const e = JSON.parse(readFileSync(0, "utf8"));
+            if (e.stop_hook_active)
+                return 0;
+            sid = e.session_id;
+            answer = String(e.last_assistant_message ?? "") || lastClaudeText(String(e.transcript_path ?? ""));
+        }
+        else if (kind === "opencode") {
+            sid = rest[0];
+            try {
+                answer = readFileSync(rest[1], "utf8");
+                rmSync(rest[1], { force: true });
+            }
+            catch { /* none */ }
+        }
+        else {
+            sid = rest[0];
+            answer = readFileSync(0, "utf8");
+        }
+        writeFileSync(`${O}.out.md`, answer);
+        if (sid)
+            writeFileSync(`${O}.id`, `${sid}\n`);
+        const st = /\S/.test(answer) ? "ok" : "fail";
+        writeAtomic(`${O}.done`, `status=${st} rc=0 at=${new Date().toISOString()} agent=${j.agent} mode=tui\n`);
+        if (j.parent)
+            notify(j.parent, `[HERDR-AGENT DONE] ${j.title} status=${st} rc=0 answer: ${O}.out.md`, true);
+    }
+    catch (e) {
+        console.error(`orq agent --turn: ${e.message}`);
+    }
+    return 0;
+}
+/** The last text Claude wrote, from its transcript (older Stop hooks have no last_assistant_message). */
+function lastClaudeText(transcript) {
+    let text = "";
+    try {
+        for (const l of readFileSync(transcript, "utf8").split(/\r?\n/)) {
+            try {
+                const e = JSON.parse(l);
+                if (e.type !== "assistant")
+                    continue;
+                const t = (e.message?.content ?? []).filter((c) => c.type === "text").map((c) => c.text).join("\n");
+                if (t)
+                    text = t;
+            }
+            catch { /* not JSON */ }
+        }
+    }
+    catch { /* no transcript */ }
+    return text;
+}
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /** Splits a stream into lines for `each`. */
 function lines(s, each) {
@@ -218,7 +360,6 @@ async function runJob(file) {
     catch { /* best effort */ } };
     state();
     const fmt = FORMATS[j.format] ?? FORMATS.text;
-    const log = createWriteStream(`${O}.log`);
     let rc = 0, stdout = "", logText = "";
     const pre = () => {
         if (j.throwaway) {
@@ -254,6 +395,51 @@ async function runJob(file) {
         if (j.throwaway)
             dropWorktree(j.repo, j.dir);
     };
+    if (j.tui) {
+        // The agent's own screen: the terminal is its; answers come from the end-of-turn hook (`--turn`).
+        let ended = false;
+        const end = (code) => {
+            if (ended)
+                return "fail";
+            ended = true;
+            post();
+            // Closed before any turn ended (or mid follow-up): a failure, so `orq wait` doesn't hang.
+            const ok = /\bstatus=ok\b/.test(existsSync(`${O}.done`) ? readFileSync(`${O}.done`, "utf8") : "");
+            if (!existsSync(`${O}.done`)) {
+                writeAtomic(`${O}.done`, `status=fail rc=${code} at=${new Date().toISOString()} agent=${j.agent} mode=tui\n`);
+                if (j.parent)
+                    notify(j.parent, `[HERDR-AGENT DONE] ${j.title} status=fail rc=${code} answer: ${O}.out.md`, true);
+            }
+            rmSync(`${O}.pid`, { force: true });
+            return ok ? "ok" : "fail";
+        };
+        if (!pre())
+            rc = 2;
+        else {
+            const env = { ...process.env, ...j.env };
+            for (const k of j.unset)
+                delete env[k];
+            // Ctrl+C belongs to the agent (it reaches us too, as part of the terminal's foreground group). The screen going
+            // away (tab or tmux server closed) still ends the agent and cleans up.
+            let child;
+            process.on("SIGINT", () => { });
+            const gone = () => { if (child)
+                killTree(child, false); end(129); process.exit(0); };
+            for (const sig of ["SIGHUP", "SIGTERM"])
+                process.on(sig, gone);
+            rc = await runCapped(j.argv[0], j.argv.slice(1), { cap: j.cap, swap: j.swap, mode: j.mode, unit: j.unit, cwd: j.dir, env, quote: true, tty: true,
+                onSpawn: (c) => { child = c.pid; } });
+        }
+        const st = end(rc);
+        state({ status: st, rc, end: new Date().toISOString() });
+        console.log(`\n[${j.agent} (TUI) ${m("exited", "encerrado")}] ${m("answer", "resposta")}: ${O}.out.md`);
+        if (!j.keep) {
+            await sleep(j.closeAfter * 1000);
+            closeOwnTab(j.host);
+        }
+        return 0;
+    }
+    const log = createWriteStream(`${O}.log`);
     if (!pre())
         rc = 2;
     else {

package/dist/commands/block.js

@@ -6,8 +6,8 @@ import { join } from "node:path";
 import { writeAtomic } from "../fsutil.js";
 import { m } from "../i18n.js";
 import { stateDir } from "../paths.js";
-export const USAGE = `orq block <agent|account> [--until YYYY-MM-DD[THH:MM] | --days N] [--reason "text"]   default: 7 days
-orq block -r <agent|account>       unblock early
+export const USAGE = `orq block <agent|account> [--until YYYY-MM-DD[THH:MM] | --days N] [--reason "text"]   default: 7 days
+orq block -r <agent|account>       unblock early
 orq block -l                       list active blocks (expired ones disappear by themselves)`;
 const file = () => join(stateDir(), "blocks.json");
 const now = () => Date.now() / 1000;

package/dist/commands/board.js

@@ -153,7 +153,7 @@ export function parseQuota(text) {
         return r ? [{ name: r[1], five: r[2], week: r[3], ...(r[4] ? { note: r[4] } : {}) }] : [];
     });
 }
-function quota(now) {
+export function quota(now) {
     let age;
     try {
         age = now - statSync(qfile()).mtimeMs;

package/dist/commands/claim.js

@@ -12,7 +12,7 @@ import { m } from "../i18n.js";
 import { acquire, release } from "../lock.js";
 export const USAGE = `orq claim [-w <workspace>] <ID> | -f <ID> | -r <ID> | -l   issue owner among conductors (exit 1 = someone else's)`;
 const field = (text, k) => new RegExp(`${k}=(\\S+)`).exec(text)?.[1] ?? "";
-function aliveOwner(text) {
+export function aliveOwner(text) {
     const id = field(text, "pane"), kind = field(text, "kind") || "herdr";
     if (kind === "herdr")
         return spawnSync("herdr", ["agent", "get", id], { stdio: "ignore" }).status === 0;

package/dist/commands/completion.js

@@ -11,7 +11,7 @@ const DESC = {
     quota: "quota per agent/account", pick: "pick agent, model and account for a role", stats: "scoreboard per agent",
     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",
+    instructions: "write the /issue playbook", claim: "issue owner among conductors", deps: "link node_modules into a worktree", gc: "remove merged issue worktrees",
     block: "block an agent or account", completion: "shell completion script",
 };
 /** Fixed words after a subcommand. */
@@ -27,52 +27,52 @@ export function script(shell, cmds) {
     const all = cmds.join(" ");
     const cases = (fmt) => Object.entries(WORDS).filter(([c]) => cmds.includes(c)).map(([c, w]) => fmt(c, w.join(" "))).join("\n");
     switch (shell) {
-        case "bash": return `# orq completion (bash): eval "$(orq completion bash)" in ~/.bashrc
-_orq() {
-  local cur=\${COMP_WORDS[COMP_CWORD]}
-  if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=($(compgen -W "${all}" -- "$cur")); return; fi
-  [ "$COMP_CWORD" -eq 2 ] || return
-  case \${COMP_WORDS[1]} in
-${cases((c, w) => `    ${c}) COMPREPLY=($(compgen -W "${w}" -- "$cur")) ;;`)}
-  esac
-}
-complete -o default -F _orq orq
+        case "bash": return `# orq completion (bash): eval "$(orq completion bash)" in ~/.bashrc
+_orq() {
+  local cur=\${COMP_WORDS[COMP_CWORD]}
+  if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=($(compgen -W "${all}" -- "$cur")); return; fi
+  [ "$COMP_CWORD" -eq 2 ] || return
+  case \${COMP_WORDS[1]} in
+${cases((c, w) => `    ${c}) COMPREPLY=($(compgen -W "${w}" -- "$cur")) ;;`)}
+  esac
+}
+complete -o default -F _orq orq
 `;
-        case "zsh": return `# orq completion (zsh): eval "$(orq completion zsh)" in ~/.zshrc, after compinit
-_orq() {
-  if (( CURRENT == 2 )); then compadd -- ${all}; return; fi
-  if (( CURRENT == 3 )); then
-    case $words[2] in
-${cases((c, w) => `      ${c}) compadd -- ${w}; return ;;`)}
-    esac
-  fi
-  _files
-}
-compdef _orq orq
+        case "zsh": return `# orq completion (zsh): eval "$(orq completion zsh)" in ~/.zshrc, after compinit
+_orq() {
+  if (( CURRENT == 2 )); then compadd -- ${all}; return; fi
+  if (( CURRENT == 3 )); then
+    case $words[2] in
+${cases((c, w) => `      ${c}) compadd -- ${w}; return ;;`)}
+    esac
+  fi
+  _files
+}
+compdef _orq orq
 `;
-        case "fish": return `# orq completion (fish): orq completion fish > ~/.config/fish/completions/orq.fish
-complete -c orq -f -n __fish_use_subcommand
-${cmds.map((c) => `complete -c orq -n __fish_use_subcommand -a ${c}${DESC[c] ? ` -d ${qf(DESC[c])}` : ""}`).join("\n")}
-${cases((c, w) => `complete -c orq -n "__fish_seen_subcommand_from ${c}" -a ${qf(w)}`)}
+        case "fish": return `# orq completion (fish): orq completion fish > ~/.config/fish/completions/orq.fish
+complete -c orq -f -n __fish_use_subcommand
+${cmds.map((c) => `complete -c orq -n __fish_use_subcommand -a ${c}${DESC[c] ? ` -d ${qf(DESC[c])}` : ""}`).join("\n")}
+${cases((c, w) => `complete -c orq -n "__fish_seen_subcommand_from ${c}" -a ${qf(w)}`)}
 `;
         case "powershell":
-        case "pwsh": return `# orq completion (PowerShell): add to $PROFILE:  orq completion powershell | Out-String | Invoke-Expression
-Register-ArgumentCompleter -Native -CommandName orq -ScriptBlock {
-  param($word, $ast, $cursor)
-  $w = @($ast.CommandElements | ForEach-Object { $_.ToString() })
-  $n = $w.Count; if ($word -ne '') { $n-- }
-  $words = @{
-${Object.entries(WORDS).filter(([c]) => cmds.includes(c)).map(([c, w]) => `    ${q(c)} = @(${w.map(q).join(", ")})`).join("\n")}
-  }
-  $desc = @{
-${cmds.map((c) => `    ${q(c)} = ${q(DESC[c] ?? c)}`).join("\n")}
-  }
-  if ($n -eq 1) { $list = @(${cmds.map(q).join(", ")}) } elseif ($n -eq 2 -and $words.ContainsKey($w[1])) { $list = $words[$w[1]] } else { return }
-  $list | Where-Object { $_ -like "$word*" } | ForEach-Object {
-    $tip = if ($n -eq 1) { $desc[$_] } else { $_ }
-    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $tip)
-  }
-}
+        case "pwsh": return `# orq completion (PowerShell): add to $PROFILE:  orq completion powershell | Out-String | Invoke-Expression
+Register-ArgumentCompleter -Native -CommandName orq -ScriptBlock {
+  param($word, $ast, $cursor)
+  $w = @($ast.CommandElements | ForEach-Object { $_.ToString() })
+  $n = $w.Count; if ($word -ne '') { $n-- }
+  $words = @{
+${Object.entries(WORDS).filter(([c]) => cmds.includes(c)).map(([c, w]) => `    ${q(c)} = @(${w.map(q).join(", ")})`).join("\n")}
+  }
+  $desc = @{
+${cmds.map((c) => `    ${q(c)} = ${q(DESC[c] ?? c)}`).join("\n")}
+  }
+  if ($n -eq 1) { $list = @(${cmds.map(q).join(", ")}) } elseif ($n -eq 2 -and $words.ContainsKey($w[1])) { $list = $words[$w[1]] } else { return }
+  $list | Where-Object { $_ -like "$word*" } | ForEach-Object {
+    $tip = if ($n -eq 1) { $desc[$_] } else { $_ }
+    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $tip)
+  }
+}
 `;
         default: return undefined;
     }

package/dist/commands/config.js

@@ -5,8 +5,8 @@
 import { getPath, loadConfig } from "../config.js";
 import { expand } from "../paths.js";
 import { m } from "../i18n.js";
-export const USAGE = `orq config [-w <workspace>]                 everything, as JSON
-orq config [-w <workspace>] get <a.b.c>     one value (plain text if scalar; JSON if object/list)
+export const USAGE = `orq config [-w <workspace>]                 everything, as JSON
+orq config [-w <workspace>] get <a.b.c>     one value (plain text if scalar; JSON if object/list)
 orq config [-w <workspace>] files           which files were read`;
 export function config(argv) {
     let ws;

package/dist/commands/gc.js

@@ -0,0 +1,164 @@
+// 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 { loadConfig } from "../config.js";
+import { m } from "../i18n.js";
+import { aliveOwner } from "./claim.js";
+export const USAGE = "orq gc [-w <workspace>] [--yes] [--days N] [--json]   remove merged issue worktrees";
+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); };
+// 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";
+    return bin.endsWith(".js") ? spawnSync(process.execPath, [bin, ...args], { cwd, encoding: "utf8" })
+        : spawnSync(bin, args, { cwd, encoding: "utf8" });
+};
+const output = (cwd, ...args) => { const r = git(cwd, ...args); return r.status === 0 ? r.stdout.trim() : undefined; };
+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++) {
+        if (argv[i] === "-w" && argv[i + 1])
+            ws = resolve(argv[++i]);
+        else if (argv[i] === "--yes")
+            yes = true;
+        else if (argv[i] === "--json")
+            json = true;
+        else if (argv[i] === "--days" && argv[i + 1] && /^\d+$/.test(argv[i + 1]))
+            days = Number(argv[++i]);
+        else {
+            console.error(USAGE);
+            return 2;
+        }
+    }
+    const { cfg } = loadConfig(ws), rows = [];
+    let ghUnavailable = false, fetchWarned = false;
+    const root = join(ws, ".worktrees");
+    const orq = join(ws, ".orquestra");
+    const issues = existsSync(orq) ? readdirSync(orq) : [];
+    for (const repoName of readdirSync(ws, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)) {
+        const repo = join(ws, repoName);
+        if (!existsSync(join(repo, ".git")))
+            continue;
+        const listings = output(repo, "worktree", "list", "--porcelain");
+        if (listings === undefined)
+            continue;
+        const worktrees = listings.split(/\n\n/).map((block) => Object.fromEntries(block.split("\n").map((line) => {
+            const i = line.indexOf(" ");
+            return [i < 0 ? line : line.slice(0, i), i < 0 ? "" : line.slice(i + 1)];
+        })));
+        const main = real(worktrees[0]?.worktree ?? repo);
+        const conf = cfg.repos?.[repoName];
+        const head = output(repo, "symbolic-ref", "refs/remotes/origin/HEAD")?.replace("refs/remotes/", "");
+        const prod = conf?.prod_ref || head || "origin/main";
+        const fetchRef = prod.replace(/^origin\//, "");
+        if (git(repo, "fetch", "origin", fetchRef).status !== 0 && !fetchWarned) {
+            console.error(m("WARNING: git fetch failed; using local refs", "AVISO: git fetch falhou; usando as refs locais"));
+            fetchWarned = true;
+        }
+        const prodTree = output(repo, "rev-parse", `${prod}^{tree}`);
+        for (const wt of worktrees) {
+            const path = real(wt.worktree ?? "");
+            if (!wt.worktree || path === main || !inside(real(root), path))
+                continue;
+            const branch = wt.branch?.replace(/^refs\/heads\//, "") ?? "";
+            if (!branch)
+                continue;
+            // The branch carries the ID in lowercase (plane-abc-123); .orquestra/ keeps it as written (ABC-123).
+            const id = /^.*?plane-(.+)$/.exec(branch)?.[1];
+            const issue = id && issues.find((d) => d.toLowerCase() === id.toLowerCase());
+            const status = output(path, "status", "--porcelain");
+            const unpushed = output(repo, "rev-list", branch, "--not", "--remotes");
+            let reason = "", verdict = "REMOVABLE";
+            if (status) {
+                verdict = "KEEP";
+                reason = m("uncommitted changes", "alterações não commitadas");
+            }
+            const ownerFile = issue && join(ws, ".orquestra", issue, "owner");
+            if (verdict !== "KEEP" && ownerFile && existsSync(ownerFile) && aliveOwner(readFileSync(ownerFile, "utf8"))) {
+                verdict = "KEEP";
+                reason = m("issue has a live owner", "issue tem um responsável ativo");
+            }
+            // A .pane/.id without a same-stem .done is treated as a running child.
+            const issueDir = issue && join(ws, ".orquestra", issue);
+            if (verdict !== "KEEP" && issueDir && existsSync(issueDir)) {
+                const files = readdirSync(issueDir), running = files.some((f) => /\.(pane|id)$/.test(f) && !existsSync(join(issueDir, `${f.replace(/\.(pane|id)$/, "")}.done`)));
+                if (running) {
+                    verdict = "KEEP";
+                    reason = m("child agent may still be running", "um agente filho pode estar em execução");
+                }
+            }
+            let merged = false;
+            if (verdict !== "KEEP") {
+                // Merged counts only if the PR's head is the local head: a commit made after the merge must not be lost.
+                const pr = gh(repo, ["pr", "list", "--head", branch, "--state", "merged", "--json", "number,headRefOid", "--limit", "1"]);
+                const local = output(repo, "rev-parse", branch);
+                if (pr.status === 0) {
+                    try {
+                        const p = JSON.parse(pr.stdout)[0];
+                        merged = !!p && (!p.headRefOid || p.headRefOid === local);
+                    }
+                    catch {
+                        ghUnavailable = true;
+                    }
+                }
+                else
+                    ghUnavailable = true;
+            }
+            const inBase = verdict !== "KEEP" && !!prodTree && output(repo, "merge-tree", "--write-tree", prod, branch) === prodTree;
+            if (verdict !== "KEEP" && unpushed && !merged && !inBase) {
+                verdict = "KEEP";
+                reason = m("commits not contained in remote refs", "commits fora das refs remotas");
+            }
+            else if (verdict !== "KEEP" && (merged || inBase)) {
+                verdict = "REMOVABLE";
+                reason = merged ? "PR merged" : m("content is in base", "conteúdo já está na base");
+            }
+            else if (verdict !== "KEEP") {
+                const closed = gh(repo, ["pr", "list", "--head", branch, "--state", "closed", "--json", "number", "--limit", "1"]);
+                const isClosed = closed?.status === 0 && (() => { try {
+                    return JSON.parse(closed.stdout).length > 0;
+                }
+                catch {
+                    return false;
+                } })();
+                const commit = output(repo, "log", "-1", "--format=%ct", branch), old = commit !== undefined && clock() - Number(commit) * 1000 > days * 86400_000;
+                verdict = "STALE";
+                reason = isClosed ? m("PR closed without merge", "PR fechada sem merge") : old ? m(`last commit is older than ${days} days`, `último commit tem mais de ${days} dias`) : m("not merged", "não integrado");
+            }
+            rows.push({ repo: repoName, worktree: basename(path), branch, verdict, reason, path });
+        }
+    }
+    if (ghUnavailable)
+        console.error(m("NOTE: gh unavailable or failed; PR signals were skipped", "NOTA: gh indisponível ou falhou; sinais de PR ignorados"));
+    let failed = false;
+    if (yes)
+        for (const row of rows.filter((r) => r.verdict === "REMOVABLE")) {
+            const removed = git(join(ws, row.repo), "worktree", "remove", row.path);
+            if (removed.status !== 0) {
+                failed = true;
+                row.reason += `; ${m("worktree removal failed", "falha ao remover worktree")}`;
+                continue;
+            }
+            if (git(join(ws, row.repo), "branch", "-D", row.branch).status !== 0) {
+                failed = true;
+                row.reason += `; ${m("branch deletion failed", "falha ao excluir branch")}`;
+            }
+            git(join(ws, row.repo), "worktree", "prune");
+        }
+    if (json)
+        console.log(JSON.stringify(rows));
+    else {
+        const table = [["REPO", "WORKTREE", "BRANCH", "VERDICT", "REASON"], ...rows.map((r) => [r.repo, r.worktree, r.branch, r.verdict, r.reason])];
+        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"));
+    }
+    return failed ? 1 : 0;
+}