mergestorm 0.3.13 → 0.3.15

package/dist/ui/tabs.js

@@ -0,0 +1,480 @@
+import * as readline from "node:readline";
+import { stdin, stdout } from "node:process";
+import { ansi } from "./ansi.js";
+import { frameWidth, preferBoxedUi, roundedBox, terminalColumns, } from "./box.js";
+import { padVisible, visibleWidth } from "./width.js";
+import { formatUsagePanel } from "./usage.js";
+import { dropdownViewport } from "./prompt.js";
+export const TAB_ORDER = ["status", "usage", "jobs", "config"];
+const TAB_LABELS = {
+    status: "Status",
+    usage: "Usage",
+    jobs: "Jobs",
+    config: "Config",
+};
+export function initialTabsState(tab = "status") {
+    return {
+        tab,
+        scroll: { status: 0, usage: 0, detail: 0 },
+        jobsIndex: 0,
+        configIndex: 0,
+        detail: null,
+    };
+}
+function clampNum(value, lo, hi) {
+    return Math.min(Math.max(value, lo), Math.max(lo, hi));
+}
+/**
+ * One keypress against the browser state. Pure so tests can drive the whole
+ * key map without a TTY. Tabs clamp at the ends (no wrap-around, so "which
+ * tab am I on" never gets ambiguous); Esc backs out of a job detail before
+ * it closes the browser; `q` always closes.
+ */
+export function reduceTabsKey(state, key, ctx) {
+    if (key === "q")
+        return { kind: "close" };
+    if (key === "escape") {
+        if (state.detail) {
+            return {
+                kind: "state",
+                state: { ...state, detail: null, scroll: { ...state.scroll, detail: 0 } },
+            };
+        }
+        return { kind: "close" };
+    }
+    if (key === "left" || key === "right") {
+        const at = TAB_ORDER.indexOf(state.tab);
+        const next = key === "left" ? Math.max(0, at - 1) : Math.min(TAB_ORDER.length - 1, at + 1);
+        return {
+            kind: "state",
+            state: {
+                ...state,
+                tab: TAB_ORDER[next],
+                detail: null,
+                scroll: { ...state.scroll, detail: 0 },
+            },
+        };
+    }
+    if (key === "up" || key === "down") {
+        const delta = key === "up" ? -1 : 1;
+        if (state.detail) {
+            return {
+                kind: "state",
+                state: {
+                    ...state,
+                    scroll: {
+                        ...state.scroll,
+                        detail: clampNum(state.scroll.detail + delta, 0, ctx.maxScroll),
+                    },
+                },
+            };
+        }
+        if (state.tab === "jobs") {
+            return {
+                kind: "state",
+                state: {
+                    ...state,
+                    jobsIndex: clampNum(state.jobsIndex + delta, 0, Math.max(0, ctx.jobsCount - 1)),
+                },
+            };
+        }
+        if (state.tab === "config") {
+            const count = ctx.config?.length ?? 0;
+            return {
+                kind: "state",
+                state: {
+                    ...state,
+                    configIndex: clampNum(state.configIndex + delta, 0, Math.max(0, count - 1)),
+                },
+            };
+        }
+        return {
+            kind: "state",
+            state: {
+                ...state,
+                scroll: {
+                    ...state.scroll,
+                    [state.tab]: clampNum(state.scroll[state.tab] + delta, 0, ctx.maxScroll),
+                },
+            },
+        };
+    }
+    if (key === "return" && state.tab === "jobs" && !state.detail && ctx.jobsCount > 0) {
+        return { kind: "open-job", index: state.jobsIndex, state };
+    }
+    if (key === "space" && state.tab === "config" && !state.detail) {
+        const row = ctx.config?.[state.configIndex];
+        // Read-only rows (connected flags) ignore Space instead of erroring.
+        if (row?.writable) {
+            return { kind: "toggle-setting", key: row.key, value: !row.value, state };
+        }
+    }
+    return { kind: "state", state };
+}
+/** Body rows available inside the frame: total rows minus chrome + hint. */
+export function tabsBodyRows(rows) {
+    const r = typeof rows === "number" && Number.isFinite(rows) && rows >= 1 ? rows : 24;
+    return Math.max(3, r - 4);
+}
+export function tabsMaxScroll(layout) {
+    return Math.max(0, layout.contentRows - layout.bodyRows);
+}
+function tabsTitle(state, color) {
+    const parts = TAB_ORDER.map((tab) => {
+        let label = TAB_LABELS[tab];
+        if (tab === "jobs" && state.detail) {
+            label = `${label} › ${state.detail.jobId.slice(0, 8)}`;
+        }
+        if (!color)
+            return tab === state.tab ? `[${label}]` : ` ${label} `;
+        return tab === state.tab ? ansi.boldBrightGreen(label) : ansi.dim(label);
+    });
+    return parts.join(color ? ansi.dim(" · ") : " · ");
+}
+function jobsBody(state, data, bodyRows, width, color) {
+    if (data.jobs.length === 0) {
+        const text = data.jobsEmptyText ?? "No review jobs yet. Run `review` to submit one.";
+        return [`  ${color ? ansi.dim(text) : text}`];
+    }
+    const header = ["JOB", "STATUS", "VERDICT", "THREAD", "WHEN"];
+    const cells = data.jobs.map((j) => [
+        j.cells.job,
+        j.cells.status,
+        j.cells.verdict,
+        j.cells.thread,
+        j.cells.when,
+    ]);
+    const widths = header.map((h, i) => Math.max(h.length, ...cells.map((r) => r[i]?.length ?? 0)));
+    const fmt = (cols) => cols.map((c, i) => padVisible(c, widths[i])).join("  ");
+    const lines = [`    ${color ? ansi.dim(fmt(header)) : fmt(header)}`];
+    const viewportRows = Math.max(1, bodyRows - 1);
+    const view = dropdownViewport(data.jobs.length, state.jobsIndex, viewportRows);
+    const end = Math.min(data.jobs.length, view.start + viewportRows);
+    for (let i = view.start; i < end; i++) {
+        const selected = i === state.jobsIndex;
+        const marker = selected ? "›" : " ";
+        const row = `  ${color && selected ? ansi.brightGreen(marker) : marker} ${fmt(cells[i])}`;
+        const clipped = visibleWidth(row) > width ? padVisible(row, width) : row;
+        lines.push(color && selected ? ansi.invert(clipped) : clipped);
+    }
+    return lines;
+}
+/** On/off rows for the Config tab; scrolls by selection like the jobs list. */
+function configBody(state, data, bodyRows, width, color) {
+    if (!data.config || data.config.length === 0) {
+        const text = data.configEmptyText ?? "Settings unavailable (offline or older API).";
+        return [`  ${color ? ansi.dim(text) : text}`];
+    }
+    const rows = data.config;
+    const labelWidth = Math.max(...rows.map((r) => r.label.length));
+    const noteRows = data.configNote ? 1 : 0;
+    const viewportRows = Math.max(1, bodyRows - noteRows);
+    const view = dropdownViewport(rows.length, state.configIndex, viewportRows);
+    const end = Math.min(rows.length, view.start + viewportRows);
+    const lines = [];
+    for (let i = view.start; i < end; i++) {
+        const row = rows[i];
+        const selected = i === state.configIndex;
+        const marker = selected ? "›" : " ";
+        const value = row.writable
+            ? row.value
+                ? "on"
+                : "off"
+            : row.value
+                ? "connected"
+                : "not connected";
+        const paintedValue = !color
+            ? value
+            : row.writable
+                ? row.value
+                    ? ansi.brightGreen(value)
+                    : ansi.dim(value)
+                : ansi.dim(value);
+        const line = `  ${color && selected ? ansi.brightGreen(marker) : marker} ${padVisible(row.label, labelWidth + 2)}${paintedValue}`;
+        const clipped = visibleWidth(line) > width ? padVisible(line, width) : line;
+        lines.push(color && selected ? ansi.invert(clipped) : clipped);
+    }
+    if (data.configNote) {
+        const note = `  ${data.configNote}`;
+        lines.push(color ? ansi.dim(note) : note);
+    }
+    return lines;
+}
+/** Key hint on the left, optional reachability note on the right. */
+export function tabsHintLine(left, right, columns, color) {
+    const room = Math.max(1, columns - 1);
+    const L = ` ${color ? ansi.dim(left) : left}`;
+    if (!right) {
+        return visibleWidth(L) > room ? padVisible(L, room) : L;
+    }
+    const R = color ? ansi.dim(right) : right;
+    if (visibleWidth(L) + 1 + visibleWidth(R) > room) {
+        const keep = Math.max(0, room - visibleWidth(R) - 1);
+        const clippedL = padVisible(L, keep);
+        const gap = Math.max(1, room - visibleWidth(clippedL) - visibleWidth(R));
+        return `${clippedL}${" ".repeat(gap)}${R}`;
+    }
+    return `${L}${" ".repeat(Math.max(1, room - visibleWidth(L) - visibleWidth(R)))}${R}`;
+}
+/**
+ * The whole browser frame for one render: tab strip in the top border, the
+ * active tab's body clipped to `rows - 4`, and a dim key hint. Pure; the
+ * raw-mode loop and tests both consume it.
+ */
+export function layoutTabs(state, data, columns, rows) {
+    const color = data.color ?? false;
+    const boxed = preferBoxedUi(columns);
+    const cols = terminalColumns(80, columns);
+    const outer = frameWidth(80, columns);
+    const contentCells = boxed ? Math.max(20, outer - 4) : Math.max(20, cols - 1);
+    const bodyRows = tabsBodyRows(rows);
+    const clip = (line) => visibleWidth(line) > contentCells ? padVisible(line, contentCells) : line;
+    let content;
+    let contentRows;
+    let scroll = 0;
+    if (state.detail) {
+        content = state.detail.rows;
+        contentRows = content.length;
+        scroll = state.scroll.detail;
+    }
+    else if (state.tab === "status") {
+        content = data.statusLines;
+        contentRows = content.length;
+        scroll = state.scroll.status;
+    }
+    else if (state.tab === "usage") {
+        const usageEmpty = data.usageEmptyText ?? "Usage unavailable (offline or older API).";
+        content = data.usage
+            ? formatUsagePanel({ ...data.usage, columns: contentCells, color })
+            : [`  ${color ? ansi.dim(usageEmpty) : usageEmpty}`];
+        contentRows = content.length;
+        scroll = state.scroll.usage;
+    }
+    else if (state.tab === "config") {
+        content = configBody(state, data, bodyRows, contentCells, color);
+        // Config scrolls by selection inside configBody; no body scroll.
+        contentRows = content.length;
+        scroll = 0;
+    }
+    else {
+        content = jobsBody(state, data, bodyRows, contentCells, color);
+        // The jobs list scrolls by selection inside jobsBody; no body scroll.
+        contentRows = content.length;
+        scroll = 0;
+    }
+    const start = clampNum(scroll, 0, Math.max(0, contentRows - bodyRows));
+    const body = content.slice(start, start + bodyRows).map(clip);
+    // Constant frame height regardless of tab, so redraws replace every row.
+    while (body.length < bodyRows)
+        body.push("");
+    const hint = state.detail
+        ? "↑↓ scroll · esc back to jobs · q quit"
+        : state.tab === "jobs"
+            ? "←→ tabs · ↑↓ select · enter open · q close"
+            : state.tab === "config"
+                ? "←→ tabs · ↑↓ select · space toggle · q close"
+                : "←→ tabs · ↑↓ scroll · esc close";
+    const clippedHint = tabsHintLine(hint, data.footerNote, cols, color);
+    const title = tabsTitle(state, color);
+    if (!boxed) {
+        const plainTitle = visibleWidth(title) > cols - 1 ? padVisible(title, cols - 1) : title;
+        return {
+            lines: [plainTitle, ...body, clippedHint],
+            bodyRows,
+            contentRows,
+        };
+    }
+    return {
+        lines: [
+            ...roundedBox(body, { title, width: outer, padding: 1 }),
+            clippedHint,
+        ],
+        bodyRows,
+        contentRows,
+    };
+}
+const up = (n) => `\u001b[${n}A`;
+const clearDown = "\u001b[0J";
+/** Resize redraw clears from row 1: old rows may have wrapped (see prompt.ts). */
+const homeClear = `\u001b[H${clearDown}`;
+/**
+ * Raw-mode tabbed browser (Status / Usage / Jobs / Config) on the select.ts
+ * loop: Left/Right switch tabs, Up/Down scroll or select, Enter opens a job
+ * in place, Space toggles a Config setting, `q`/Esc close, resize re-renders.
+ * Non-TTY streams fall back to the static panels (callers normally gate on
+ * TTY already).
+ */
+export async function runTabsBrowser(opts) {
+    const input = opts.input ?? stdin;
+    const output = opts.output ?? stdout;
+    const data = opts.data;
+    if (!input.isTTY || !output.isTTY) {
+        const layout = layoutTabs(initialTabsState(opts.initial ?? "status"), data, output.columns, output.rows);
+        for (const line of layout.lines)
+            console.log(line);
+        return;
+    }
+    return new Promise((resolve) => {
+        let state = initialTabsState(opts.initial ?? "status");
+        let lastLayout = null;
+        let linesDrawn = 0;
+        let finished = false;
+        let detailSeq = 0;
+        let toggleSeq = 0;
+        const wasRaw = Boolean(input.isRaw);
+        readline.emitKeypressEvents(input);
+        input.setRawMode(true);
+        input.resume();
+        function render(prefix) {
+            if (prefix) {
+                output.write(prefix);
+            }
+            else if (linesDrawn > 0) {
+                output.write(`${up(linesDrawn)}\r${clearDown}`);
+            }
+            lastLayout = layoutTabs(state, data, output.columns, output.rows);
+            output.write(lastLayout.lines.join("\r\n") + "\r\n");
+            linesDrawn = lastLayout.lines.length;
+        }
+        function onResize() {
+            if (!finished)
+                render(homeClear);
+        }
+        function cleanup() {
+            input.removeListener("keypress", onKeypress);
+            output.removeListener("resize", onResize);
+            input.setRawMode(wasRaw);
+            input.pause();
+        }
+        function finish() {
+            if (finished)
+                return;
+            finished = true;
+            cleanup();
+            // Erase the frame so the shell prompt reclaims the space.
+            if (linesDrawn > 0)
+                output.write(`${up(linesDrawn)}\r${clearDown}`);
+            resolve();
+        }
+        function openJob(index) {
+            const job = data.jobs[index];
+            if (!job || !opts.loadJobDetail)
+                return;
+            const seq = ++detailSeq;
+            state = {
+                ...state,
+                detail: {
+                    jobId: job.id,
+                    rows: [`  Loading job ${job.id.slice(0, 8)}…`],
+                },
+                scroll: { ...state.scroll, detail: 0 },
+            };
+            render();
+            opts
+                .loadJobDetail(job.id)
+                .then((rows) => {
+                if (finished || seq !== detailSeq)
+                    return;
+                if (!state.detail || state.detail.jobId !== job.id)
+                    return;
+                state = { ...state, detail: { jobId: job.id, rows } };
+                render();
+            })
+                .catch((err) => {
+                if (finished || seq !== detailSeq)
+                    return;
+                if (!state.detail || state.detail.jobId !== job.id)
+                    return;
+                const message = err instanceof Error ? err.message : String(err);
+                state = {
+                    ...state,
+                    detail: { jobId: job.id, rows: [ansi.red(`  ${message}`)] },
+                };
+                render();
+            });
+        }
+        function applyToggle(key, value) {
+            if (!opts.toggleSetting)
+                return;
+            const seq = ++toggleSeq;
+            data.configNote = "saving…";
+            render();
+            opts
+                .toggleSetting(key, value)
+                .then((rows) => {
+                if (finished || seq !== toggleSeq)
+                    return;
+                data.config = rows;
+                delete data.configNote;
+                render();
+            })
+                .catch((err) => {
+                if (finished || seq !== toggleSeq)
+                    return;
+                // Keep the stored rows; only the note reports the rejection.
+                data.configNote = err instanceof Error ? err.message : String(err);
+                render();
+            });
+        }
+        function onKeypress(str, key) {
+            if (finished || !key)
+                return;
+            if (key.ctrl && key.name === "c") {
+                finish();
+                return;
+            }
+            let name = null;
+            if (key.name === "left" || key.name === "right" || key.name === "up" || key.name === "down") {
+                name = key.name;
+            }
+            else if (key.name === "return") {
+                name = "return";
+            }
+            else if (key.name === "space" || str === " ") {
+                name = "space";
+            }
+            else if (key.name === "escape") {
+                name = "escape";
+            }
+            else if (key.name === "q" || str === "q") {
+                name = "q";
+            }
+            if (!name)
+                return;
+            const step = reduceTabsKey(state, name, {
+                jobsCount: data.jobs.length,
+                maxScroll: lastLayout ? tabsMaxScroll(lastLayout) : 0,
+                config: data.config ?? [],
+            });
+            if (step.kind === "close") {
+                finish();
+                return;
+            }
+            if (step.kind === "open-job") {
+                openJob(step.index);
+                return;
+            }
+            if (step.kind === "toggle-setting") {
+                applyToggle(step.key, step.value);
+                return;
+            }
+            state = step.state;
+            try {
+                render();
+            }
+            catch {
+                finish();
+            }
+        }
+        input.on("keypress", onKeypress);
+        output.on("resize", onResize);
+        try {
+            // First paint homes so we do not write from the idle input row
+            // (mid-pane) and scroll the welcome chrome.
+            render(homeClear);
+        }
+        catch {
+            finish();
+        }
+    });
+}

package/dist/ui/usage.d.ts

@@ -20,6 +20,8 @@ export declare function nextUtcMonthStart(now?: Date): string;
  * Falls back to next UTC month start when `iso` is missing/invalid.
  */
 export declare function formatResetLabel(iso: string | null | undefined, now?: Date): string;
+/** How long until `iso` (the API `resets_at`). Empty when the date is unusable. */
+export declare function formatDaysLeft(iso: string | null | undefined, now?: Date): string;
 /** Alias kept for callers that still import `formatResetDate`. */
 export declare function formatResetDate(iso: string | null | undefined): string;
 /** Bar cells so `  [bar] 100% used` stays inside the terminal. */
@@ -38,6 +40,8 @@ export type UsagePanelInput = {
     limit: number | null;
     resetsAt: string | null | undefined;
     jobs: UsagePanelJob[];
+    /** When the jobs fetch failed, show this instead of "No review jobs yet." */
+    jobsError?: string;
     columns: number;
     color?: boolean;
 };

package/dist/ui/usage.js

@@ -30,7 +30,7 @@ export function usageBar(used, limit, opts = {}) {
     if (!color) {
         return `[${filledSeg}${emptySeg}]${suffix}`;
     }
-    let fillColor = ansi.green;
+    let fillColor = ansi.brightGreen;
     if (ratio >= 0.9)
         fillColor = ansi.red;
     else if (ratio >= 0.75)
@@ -63,6 +63,26 @@ export function formatResetLabel(iso, now = new Date()) {
     const mm = String(m).padStart(2, "0");
     return `Resets ${month} ${day}, ${h}:${mm}${ampm} (UTC)`;
 }
+/** How long until `iso` (the API `resets_at`). Empty when the date is unusable. */
+export function formatDaysLeft(iso, now = new Date()) {
+    if (!iso)
+        return "";
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return "";
+    const ms = d.getTime() - now.getTime();
+    if (ms <= 0)
+        return "reset due";
+    const days = Math.floor(ms / 86_400_000);
+    const hours = Math.floor((ms % 86_400_000) / 3_600_000);
+    if (days >= 2)
+        return `${days} days left`;
+    if (days === 1)
+        return "1 day left";
+    if (hours >= 1)
+        return `${hours}h left`;
+    return "resets soon";
+}
 /** Alias kept for callers that still import `formatResetDate`. */
 export function formatResetDate(iso) {
     return formatResetLabel(iso);
@@ -95,7 +115,7 @@ export function formatUsagePanel(input) {
         "",
     ];
     if (input.jobs.length === 0) {
-        lines.push("  No review jobs yet.");
+        lines.push(input.jobsError ? `  ${input.jobsError}` : "  No review jobs yet.");
         return lines.map((line) => clipLine(line, columns));
     }
     const inner = Math.max(20, columns - 2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mergestorm",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "description": "Mergestorm CLI (mg) — local reviews & stacked PRs. MIT; build from source: https://github.com/marginsystems/mergestorm-cli",
   "license": "MIT",
   "type": "module",
@@ -32,6 +32,7 @@
   },
   "files": [
     "dist",
+    "skill",
     "LICENSE",
     "README.md"
   ],

package/skill/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: mergestorm-review
+description: Review a local branch with Mergestorm Vortex specialists before opening a PR, then apply the findings yourself.
+---
+
+# Mergestorm review
+
+Use this skill to review a local git branch with Mergestorm, then apply the findings yourself.
+
+## When to use
+
+Before opening a PR; after a large refactor; when the user says review, audit, second opinion, or "is this safe to merge".
+
+Not for merging, landing, or pushing. For a PR that is already open on GitHub, use the `mergestorm-pr-loop` skill instead.
+
+## Install (Claude Code / Cursor)
+
+```bash
+mg skill install --claude
+mg skill install --cursor
+# or both: mg skill install --claude --cursor
+```
+
+That writes `.claude/skills/mergestorm-review/SKILL.md` and/or `.cursor/skills/mergestorm-review/SKILL.md` in the current repo.
+
+Hand-copy still works: Claude Code project skill `.claude/skills/mergestorm-review/SKILL.md` (or `~/.claude/skills/mergestorm-review/SKILL.md`). Cursor: the same file under `.cursor/skills/mergestorm-review/SKILL.md`; otherwise a rule at `.cursor/rules/mergestorm-review.mdc` with this description and `alwaysApply: false`.
+
+MCP server:
+
+```bash
+curl -fsSL https://mergestorm.ai/install.sh | bash -s -- --mcp
+# or: npm i -g mergestorm mergestorm-mcp
+claude mcp add mergestorm -- npx -y mergestorm-mcp
+```
+
+Cursor `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "mergestorm": {
+      "command": "npx",
+      "args": ["-y", "mergestorm-mcp"]
+    }
+  }
+}
+```
+
+## Preconditions
+
+1. Prefer the `mergestorm` MCP server. Call `whoami`. If MCP is missing, require `mg` on PATH with `mg whoami --json` exit 0. If neither is available, stop and print the install one-liner above.
+2. Call `credits` (or `mg credits --json`). If remaining standard credits are 0, say so and stop.
+
+## Hire policy
+
+Default: omit `router` (account setting).
+
+- `router: "off"` for tiny diffs or docs-only
+- `manual` with pins when the change is clearly one domain: `security` (auth/crypto/input), `frontend` (components), `data` (migrations), `api` (route contracts), `tests` (mostly tests), `performance` (hot paths), `architecture` (cross-module moves)
+- `max` only when the user asks for a full pass
+- Never request `governance` or `seam`. Neither exists for local reviews. Seam runs automatically during Mergestorm stack promotes and is controlled by the Agents settings toggle (default on).
+
+## Submit
+
+Call `review_submit` on the repo cwd (git collect when `diff` is omitted). Pass one or two sentences of intent in `context`. Pass an ADR or spec as `context_files` when one exists in the repo under review — never from outside it. Do not paste the diff into context.
+
+Optional: `thread`, `idempotency_key`, `wait`, `timeout_s`. Default wait is 300s; on timeout the tool returns `status: in_progress` and the job id — then call `review_wait`.
+
+Use `review_get` or `review_list` to resume a known job.
+
+Status handling:
+
+- status is `no_changes`: success. The branch matches the selected base, no review job was submitted, and no review credit was used. Stop unless the user expected a different base.
+- status is `rate_limited`: wait `retry_after_seconds`. Use `review_list`, `review_get`, or `review_wait` for an existing in-flight job before resubmitting. Do not immediately resubmit the same diff.
+
+## Apply findings
+
+Read `findings.inline` (and `off_diff` / `offDiff`) sorted by severity. Fix or explain each. Never silence a finding by deleting the test. Then submit again on the same branch so the thread chains, with `context` stating what was addressed.
+
+## Never
+
+- land, merge, push, or open a PR
+- call stack authoring or land commands
+- wrap the CLI in a shell escape hatch
+- claim a finding is fixed without a diff that touches its path
+- resubmit an identical failing diff (that burns a credit)
+- treat `no_changes` or `rate_limited` as a failed review that needs an immediate resubmit
+- pass `--context-file` or `--context` contents from outside the repo under review
+
+## Fallback (no MCP)
+
+```bash
+mg review --json --context "…"
+# optional: --router … --specialists … --context-file … --thread … --wait / --no-wait --timeout
+# context files must live inside the repo under review
+```
+
+Parse stdout as one JSON object (`mergestorm.review_job/v1`). Exit 0 includes `no_changes`. Exit 5 means detach and poll with `mg status <id> --json --wait`. Exit 7 means `rate_limited`: wait `retry_after_seconds` before trying again.