mergestorm 0.3.9 → 0.3.15

package/dist/ui/usage.js

@@ -1,10 +1,12 @@
 import { ansi } from "./ansi.js";
+import { frameWidth } from "./box.js";
+import { padVisible, visibleWidth } from "./width.js";
 /**
  * Usage meter — long thin bar + percent only:
  *   `[████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 7% used`
  *
  * No used/limit clutter. Edge cases:
- * - `limit === 0` → dim "not included" (premium on non-Maelstrom)
+ * - `limit === 0` → dim "not included"
  * - `limit == null` → "unlimited" (dev-bypass)
  */
 export function usageBar(used, limit, opts = {}) {
@@ -28,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)
@@ -61,7 +63,74 @@ 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);
 }
+/** Bar cells so `  [bar] 100% used` stays inside the terminal. */
+export function usageBarWidth(columns) {
+    return Math.max(8, frameWidth(80, columns) - 13);
+}
+function clipLine(line, columns) {
+    if (visibleWidth(line) <= columns)
+        return line;
+    return padVisible(line, columns);
+}
+/**
+ * Static `/usage` panel: identity, a bar sized from `frameWidth()`, reset
+ * line, then the last five jobs. Every row is clipped to `columns`.
+ */
+export function formatUsagePanel(input) {
+    const columns = Math.max(20, input.columns);
+    const color = input.color ?? false;
+    const identity = `● ${input.keyPrefix} · ${input.plan}`;
+    const bar = usageBar(input.used, input.limit, {
+        width: usageBarWidth(columns),
+        color,
+    });
+    const lines = [
+        `  ${identity}`,
+        `  ${bar}`,
+        `  ${formatResetLabel(input.resetsAt)}`,
+        "",
+    ];
+    if (input.jobs.length === 0) {
+        lines.push(input.jobsError ? `  ${input.jobsError}` : "  No review jobs yet.");
+        return lines.map((line) => clipLine(line, columns));
+    }
+    const inner = Math.max(20, columns - 2);
+    const jobW = 8;
+    const verdictW = 15;
+    const creditsW = 7;
+    const whenW = 8;
+    const gaps = 8;
+    const threadW = Math.max(6, inner - jobW - verdictW - creditsW - whenW - gaps);
+    const header = ["JOB", "VERDICT", "THREAD", "CREDITS", "WHEN"];
+    const widths = [jobW, verdictW, threadW, creditsW, whenW];
+    const fmt = (cols) => "  " + cols.map((c, i) => padVisible(c, widths[i])).join("  ");
+    lines.push(fmt(header));
+    for (const job of input.jobs.slice(0, 5)) {
+        lines.push(fmt([job.job, job.verdict, job.thread, job.credits, job.when]));
+    }
+    return lines.map((line) => clipLine(line, columns));
+}

package/dist/ui/width.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Terminal cell arithmetic. Everything that frames, pads, or parks a cursor
+ * must count *cells*, not UTF-16 units: CJK is two cells, combining marks
+ * and ZWJ are zero, an astral emoji is one grapheme. Getting this wrong is
+ * why the right border of the prompt box drifted on non-Latin input.
+ */
+export declare function stripSgr(str: string): string;
+/** Cells for one code point on its own (no cluster context). */
+export declare function codePointWidth(cp: number): number;
+/**
+ * Cells one grapheme cluster occupies. A cluster is as wide as its widest
+ * base (a ZWJ family emoji is 2, not 6); VS16 promotes a text-style symbol
+ * to emoji presentation (2 cells); a cluster of nothing but marks is 0.
+ */
+export declare function graphemeWidth(cluster: string): number;
+/** Terminal cells a string occupies, ignoring SGR colour codes. */
+export declare function visibleWidth(str: string): number;
+/**
+ * Take the cells `[start, start + cells)` of `str`, keeping every SGR code
+ * (so colours survive) and substituting spaces for a wide glyph cut by
+ * either edge, so the result's geometry is exactly what the caller asked
+ * for even when a CJK character straddles the window.
+ */
+export declare function sliceVisible(str: string, start: number, cells: number): string;
+/** Pad or truncate to an exact cell width (ANSI-safe). */
+export declare function padVisible(line: string, width: number): string;

package/dist/ui/width.js

@@ -0,0 +1,262 @@
+/**
+ * Terminal cell arithmetic. Everything that frames, pads, or parks a cursor
+ * must count *cells*, not UTF-16 units: CJK is two cells, combining marks
+ * and ZWJ are zero, an astral emoji is one grapheme. Getting this wrong is
+ * why the right border of the prompt box drifted on non-Latin input.
+ */
+const SGR_PATTERN = /\u001b\[[0-9;]*m/g;
+const SGR_SPLIT = /(\u001b\[[0-9;]*m)/;
+export function stripSgr(str) {
+    return str.replace(SGR_PATTERN, "");
+}
+/**
+ * East Asian Wide / Fullwidth ranges (plus emoji presentation blocks).
+ * Deliberately excludes Ambiguous-width ranges such as box drawing
+ * (U+2500..257F) and block elements (U+2580..259F, the TORNADO_LOGO
+ * glyphs), which every terminal we target renders in one cell.
+ */
+const WIDE_RANGES = [
+    [0x1100, 0x115f], // Hangul Jamo
+    [0x231a, 0x231b],
+    [0x2329, 0x232a],
+    [0x23e9, 0x23ec],
+    [0x23f0, 0x23f0],
+    [0x23f3, 0x23f3],
+    [0x25fd, 0x25fe],
+    [0x2614, 0x2615],
+    [0x2648, 0x2653],
+    [0x267f, 0x267f],
+    [0x2693, 0x2693],
+    [0x26a1, 0x26a1],
+    [0x26aa, 0x26ab],
+    [0x26bd, 0x26be],
+    [0x26c4, 0x26c5],
+    [0x26ce, 0x26ce],
+    [0x26d4, 0x26d4],
+    [0x26ea, 0x26ea],
+    [0x26f2, 0x26f3],
+    [0x26f5, 0x26f5],
+    [0x26fa, 0x26fa],
+    [0x26fd, 0x26fd],
+    [0x2705, 0x2705],
+    [0x270a, 0x270b],
+    [0x2728, 0x2728],
+    [0x274c, 0x274c],
+    [0x274e, 0x274e],
+    [0x2753, 0x2755],
+    [0x2757, 0x2757],
+    [0x2795, 0x2797],
+    [0x27b0, 0x27b0],
+    [0x27bf, 0x27bf],
+    [0x2b1b, 0x2b1c],
+    [0x2b50, 0x2b50],
+    [0x2b55, 0x2b55],
+    [0x2e80, 0x303e], // CJK radicals, Kangxi, ideographic description, CJK symbols
+    [0x3041, 0x33ff], // Hiragana, Katakana, Bopomofo, Hangul compat, enclosed CJK
+    [0x3400, 0x4dbf], // CJK ext A
+    [0x4e00, 0x9fff], // CJK unified
+    [0xa000, 0xa4cf], // Yi
+    [0xa960, 0xa97f], // Hangul Jamo ext A
+    [0xac00, 0xd7a3], // Hangul syllables
+    [0xf900, 0xfaff], // CJK compat ideographs
+    [0xfe10, 0xfe19], // vertical forms
+    [0xfe30, 0xfe6f], // CJK compat forms, small forms
+    [0xff00, 0xff60], // fullwidth forms
+    [0xffe0, 0xffe6],
+    [0x16fe0, 0x16fe4],
+    [0x17000, 0x18aff], // Tangut, Khitan
+    [0x1b000, 0x1b2ff], // Kana supplement / ext
+    [0x1f004, 0x1f004],
+    [0x1f0cf, 0x1f0cf],
+    [0x1f18e, 0x1f18e],
+    [0x1f191, 0x1f19a],
+    [0x1f1e6, 0x1f1ff], // regional indicators (flags pair to one 2-cell cluster)
+    [0x1f200, 0x1f202],
+    [0x1f210, 0x1f23b],
+    [0x1f240, 0x1f248],
+    [0x1f250, 0x1f251],
+    [0x1f260, 0x1f265],
+    [0x1f300, 0x1f320],
+    [0x1f32d, 0x1f335],
+    [0x1f337, 0x1f37c],
+    [0x1f37e, 0x1f393],
+    [0x1f3a0, 0x1f3ca],
+    [0x1f3cf, 0x1f3d3],
+    [0x1f3e0, 0x1f3f0],
+    [0x1f3f4, 0x1f3f4],
+    [0x1f3f8, 0x1f43e],
+    [0x1f440, 0x1f440],
+    [0x1f442, 0x1f4fc],
+    [0x1f4ff, 0x1f53d],
+    [0x1f54b, 0x1f54e],
+    [0x1f550, 0x1f567],
+    [0x1f57a, 0x1f57a],
+    [0x1f595, 0x1f596],
+    [0x1f5a4, 0x1f5a4],
+    [0x1f5fb, 0x1f64f],
+    [0x1f680, 0x1f6c5],
+    [0x1f6cc, 0x1f6cc],
+    [0x1f6d0, 0x1f6d2],
+    [0x1f6d5, 0x1f6d7],
+    [0x1f6dc, 0x1f6df],
+    [0x1f6eb, 0x1f6ec],
+    [0x1f6f4, 0x1f6fc],
+    [0x1f7e0, 0x1f7eb],
+    [0x1f7f0, 0x1f7f0],
+    [0x1f90c, 0x1f93a],
+    [0x1f93c, 0x1f945],
+    [0x1f947, 0x1f9ff],
+    [0x1fa70, 0x1faff],
+    [0x20000, 0x2fffd], // CJK ext B..F
+    [0x30000, 0x3fffd], // CJK ext G..
+];
+const ZERO_WIDTH_RE = /^[\p{M}\p{Cc}\p{Cf}\u200b-\u200f\u2028-\u202e\u2060-\u2064\ufeff]$/u;
+function isWide(cp) {
+    // Binary search over the sorted range table.
+    let lo = 0;
+    let hi = WIDE_RANGES.length - 1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const [start, end] = WIDE_RANGES[mid];
+        if (cp < start)
+            hi = mid - 1;
+        else if (cp > end)
+            lo = mid + 1;
+        else
+            return true;
+    }
+    return false;
+}
+/** Cells for one code point on its own (no cluster context). */
+export function codePointWidth(cp) {
+    if (cp === 0xfe0f)
+        return 0; // VS16 handled at cluster level
+    const ch = String.fromCodePoint(cp);
+    if (ZERO_WIDTH_RE.test(ch))
+        return 0;
+    if (cp >= 0xfe00 && cp <= 0xfe0f)
+        return 0; // variation selectors
+    if (cp >= 0xe0100 && cp <= 0xe01ef)
+        return 0; // VS supplement
+    if (cp >= 0xe0020 && cp <= 0xe007f)
+        return 0; // emoji tag sequence
+    if (cp >= 0xd800 && cp <= 0xdfff)
+        return 1; // lone surrogate (broken slice)
+    return isWide(cp) ? 2 : 1;
+}
+let segmenter;
+/**
+ * Grapheme clusters of `text`, yielded lazily so an early exit (e.g.
+ * `sliceVisible` cutting a cell window) never segments the whole tail of a
+ * long buffer. Falls back to code-point iteration without Intl.Segmenter.
+ */
+function* graphemes(text) {
+    if (segmenter === undefined) {
+        try {
+            segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+        }
+        catch {
+            segmenter = null;
+        }
+    }
+    if (segmenter) {
+        for (const seg of segmenter.segment(text))
+            yield seg.segment;
+        return;
+    }
+    for (const ch of text)
+        yield ch;
+}
+/**
+ * Cells one grapheme cluster occupies. A cluster is as wide as its widest
+ * base (a ZWJ family emoji is 2, not 6); VS16 promotes a text-style symbol
+ * to emoji presentation (2 cells); a cluster of nothing but marks is 0.
+ */
+export function graphemeWidth(cluster) {
+    let width = 0;
+    let vs16 = false;
+    for (const ch of cluster) {
+        const cp = ch.codePointAt(0);
+        if (cp === 0xfe0f) {
+            vs16 = true;
+            continue;
+        }
+        width = Math.max(width, codePointWidth(cp));
+    }
+    if (vs16 && width === 1)
+        return 2;
+    return width;
+}
+/** Terminal cells a string occupies, ignoring SGR colour codes. */
+export function visibleWidth(str) {
+    const plain = stripSgr(str);
+    if (!plain)
+        return 0;
+    let total = 0;
+    for (const cluster of graphemes(plain))
+        total += graphemeWidth(cluster);
+    return total;
+}
+/**
+ * Take the cells `[start, start + cells)` of `str`, keeping every SGR code
+ * (so colours survive) and substituting spaces for a wide glyph cut by
+ * either edge, so the result's geometry is exactly what the caller asked
+ * for even when a CJK character straddles the window.
+ */
+export function sliceVisible(str, start, cells) {
+    if (cells <= 0)
+        return "";
+    const end = start + cells;
+    let out = "";
+    let offset = 0;
+    const parts = str.split(SGR_SPLIT);
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        if (!part)
+            continue;
+        if (i % 2 === 1) {
+            out += part;
+            continue;
+        }
+        // Offsets only grow, so once we're past the window no later content can
+        // land in it; stop segmenting the tail of a long buffer.
+        if (offset > end)
+            continue;
+        for (const cluster of graphemes(part)) {
+            if (offset > end)
+                break;
+            const w = graphemeWidth(cluster);
+            const from = offset;
+            const to = offset + w;
+            offset = to;
+            if (w === 0) {
+                // Marks attach to the previous glyph; keep them only when that glyph
+                // was emitted.
+                if (from > start && from <= end)
+                    out += cluster;
+                continue;
+            }
+            if (to <= start || from >= end)
+                continue;
+            if (from >= start && to <= end) {
+                out += cluster;
+            }
+            else {
+                out += " ".repeat(Math.min(to, end) - Math.max(from, start));
+            }
+        }
+    }
+    return out;
+}
+/** Pad or truncate to an exact cell width (ANSI-safe). */
+export function padVisible(line, width) {
+    const target = Math.max(0, width);
+    const w = visibleWidth(line);
+    if (w === target)
+        return line;
+    if (w < target)
+        return `${line}${" ".repeat(target - w)}`;
+    const cut = sliceVisible(line, 0, target);
+    const cutWidth = visibleWidth(cut);
+    return cutWidth < target ? `${cut}${" ".repeat(target - cutWidth)}` : cut;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mergestorm",
-  "version": "0.3.9",
+  "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",
@@ -18,6 +18,10 @@
     "mergestorm": "./dist/cli.js",
     "mg": "./dist/cli.js"
   },
+  "exports": {
+    ".": "./dist/cli.js",
+    "./client": "./dist/client/index.js"
+  },
   "homepage": "https://mergestorm.ai/docs#review-jobs-api",
   "repository": {
     "type": "git",
@@ -28,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.

package/skill/mergestorm-pr-loop/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: mergestorm-pr-loop
+description: Patch an already-open GitHub PR from Mergestorm Vortex findings until it comes back clean. Wait for the PR's Vortex pass, fix, push the PR head, wait for the pass at the pushed SHA. Not for local pre-PR reviews (use mergestorm-review for those).
+---
+
+# Mergestorm PR loop
+
+Vortex already reviews every push to an open PR on a monitored repo; nothing here starts a review. This skill reads the latest pass, patches the PR head branch, pushes, and waits for the follow-up pass.
+
+Two worlds, never mixed: reviewing a local branch before a PR exists is the `mergestorm-review` skill. This skill is only for a PR that is already open on GitHub.
+
+## Install (Claude Code / Cursor)
+
+```bash
+mg skill install --claude --cursor
+```
+
+## Preconditions (in order)
+
+1. There is an already-open GitHub PR on a Vortex-monitored repo. No PR, wrong skill.
+2. Auto-patch (Cyclone) must be off so you are the only patcher. Do not take anyone's word for it: the settings API is the source of truth, and step 1 of the loop verifies it before anything else runs.
+3. `whoami` works on the `mergestorm` MCP server (or `mg whoami --json` exits 0). Otherwise stop and ask for install/login.
+
+## Loop (in order)
+
+1. Call `settings_get` and read `auto_patch_enabled`.
+   - If `settings_get` errors or its result has no `auto_patch_enabled`: refuse the loop. Do not wait, patch, or push; tell the human that Cyclone auto-patch could not be verified.
+   - If it is `false`: continue. You are the only patcher.
+   - If it is `true` and the human asked you to turn Cyclone off: call `settings_set` with `auto_patch_enabled: false`, then call `settings_get` again and confirm it now reads `false`.
+   - If it is `true` otherwise: refuse the loop. Do not wait, patch, or push; tell the human Cyclone auto-patch is still on and where to turn it off.
+   - Never set `auto_patch_enabled` to `true`.
+2. Call `review_wait_pr` with the PR's owner, repo, and pr_number (`review_get_pr` works for a first look at the resting state).
+3. Confirm the envelope's `head_sha` is the commit you have checked out as the PR head (compare its leading 7+ hex characters with `git rev-parse HEAD`). If it is not, someone else pushed after this pass and its findings are not yours to patch: do not edit. Fetch and check out the PR head, then go to step 7 with `after_sha` set to that head.
+4. Read `findings.inline` and `findings.offDiff` (or `off_diff`) sorted by severity. Fix or explain each.
+5. Patch on the PR head branch only.
+6. Push that head branch with an ordinary push. If the push is rejected because the remote branch moved, another patcher already pushed for this pass. Do not rebase, do not force, do not retry the push: stop and tell the human that a second patcher is active on this PR.
+7. Call `review_wait_pr` again with `after_sha` set to the SHA you just pushed (7+ hex). An envelope whose `head_sha` is an older commit is a previous pass, not yours; keep waiting.
+8. Repeat from step 3 until a stop rule fires.
+
+## Stop rules
+
+Map these to `mergestorm.pr_review/v1` envelope fields; do not invent statuses.
+
+- `finding_count` is 0 (empty inline and offDiff): stop. Tell the human the PR is clear and that Auto land owns landing. Never merge it yourself.
+- status is `rate_limited`, or `patch_policy.mode` is `"hold"`: surface the findings to the human and stop. Do not patch.
+- status is `failed`: report to the human. Do not keep pushing to retrigger.
+- status is `in_progress` and the envelope has a `head_sha`: the pass is still running; call `review_wait_pr` again with the same `after_sha`.
+- status is `in_progress` and the envelope has no `head_sha`: the wait timed out before Vortex wrote a pass for your SHA. Call `review_wait_pr` once more with the same `after_sha`. If it comes back the same way a second time in a row, stop and tell the human that Vortex did not pick up the push. Do not push again to retrigger.
+- status is `skipped`, `stopped`, `trial_expired`, or `synced`: surface the status and reason to the human and stop. Do not patch or push.
+
+## Never
+
+- submit a local review job, or call the job-id tools `review_wait` / `review_get` here. Local jobs are `mergestorm-review`'s world: they cost credits and do not fire Vortex on the PR.
+- land, merge, enqueue, or touch stack authoring or the merge queue
+- turn `auto_patch_enabled` on, from this skill, for any reason
+- push any branch other than the PR head
+- force-push, or rebase and retry a push that was rejected because the remote moved
+- patch a pass whose `head_sha` is not the commit you have checked out
+- wrap the CLI in a shell escape hatch
+- claim a finding is fixed without a diff that touches its path
+
+## Fallback (no MCP)
+
+Verify auto-patch with the CLI instead of `settings_get`:
+
+```bash
+mg settings --json
+```
+
+Read `auto_patch_enabled` from stdout. If the command errors or the result has no `auto_patch_enabled`, refuse the loop and tell the human that Cyclone auto-patch could not be verified. If it is `true` and the human asked you to turn Cyclone off, run `mg settings --auto-patch off` and re-read; otherwise refuse the loop, same rule as step 1.
+
+```bash
+mg pr <owner/repo>#<n> --json --wait --after-sha <sha> --timeout <s>
+```
+
+Parse stdout as one `mergestorm.pr_review/v1` object. Same fields, same stop rules.