mergestorm 0.3.16 → 0.3.18

package/README.md

@@ -45,12 +45,12 @@ On a TTY, bare `mergestorm` (or `mergestorm shell`) opens a branded REPL: a comp
 
 ```
 ╭──────────────────────────────────────────────────────────────────────────────╮
-│ ▟██▛  mergestorm v0.3.16                                                     │
+│ ▟██▛  mergestorm v0.3.18                                                     │
 │  ▜▙   ● msk_live_…  · maelstrom                                              │
 │       [████████░░░░░░░░░░░░░░░░░░░░░░] 25% used · Resets Sep 5, 10:53am (UTC)│
 │                                                                              │
 │       review a diff · usage for tabs · /help for all commands                │
-│       New in v0.3.16: verify findings, small diff, public dismiss on skip    │
+│       New in v0.3.18: pr --wait fences a stale same-head pass                │
 ╰──────────────────────────────────────────────────────────────────────────────╯
 mergestorm
 ╭──────────────────────────────────────────────────────────────────────────────╮

package/dist/api.d.ts

@@ -46,6 +46,10 @@ export type MeResponse = {
             limit: number | null;
             remaining: number | null;
         };
+        /** Non-expiring credits spent after the monthly standard pool. */
+        bonus?: {
+            remaining: number;
+        };
     };
 };
 export type JobListItem = {
@@ -122,13 +126,33 @@ export type PrVortexReview = {
     verdict: string | null;
     summary?: string | null;
     head_sha: string | null;
+    /** Attempt number on this head (#2027). Absent only from servers older than the pass column. */
+    pass?: number;
     review_count: number;
     skip_reason: string | null;
     reviewed_at: string | null;
     finding_count: number;
     findings: PrReviewFindings | null;
     patch_policy: unknown | null;
+    /**
+     * MS-01: True when the returned row is a resting completion but a newer
+     * attempt is in flight (active lease). The CLI must continue polling.
+     */
+    newer_pass_pending?: boolean;
+};
+/**
+ * Pass selection on the DB-only PR review read (#2027). `pass` names one row;
+ * `afterPass` asks for a later pass (`pass > afterPass`) on the SHA filter.
+ */
+export type PrReviewPassSelector = {
+    pass?: number;
+    afterPass?: number;
 };
+export declare function isPositiveInteger(value: unknown): value is number;
+/** Append pass selection and SHA filter to a PR review query. */
+export declare function applyPrReviewQuery(query: URLSearchParams, opts: PrReviewPassSelector & {
+    afterSha?: string;
+}): void;
 /**
  * Bearer-writable settings keys, mirroring the `/api/v1/settings` allowlist.
  * The connected flags are read-only there and deliberately absent here.
@@ -172,7 +196,8 @@ export declare function getReview(jobId: string, cfg?: Config, opts?: {
 export declare function getPrVortexReview(owner: string, repo: string, prNumber: number, cfg?: Config, opts?: {
     signal?: AbortSignal;
     timeoutMs?: number;
-}): Promise<PrVortexReview>;
+    afterSha?: string;
+} & PrReviewPassSelector): Promise<PrVortexReview>;
 /** List stacks (Bearer GET /api/v1/stacks). */
 export declare function listStacks(cfg?: Config, opts?: {
     timeoutMs?: number;

package/dist/api.js

@@ -155,6 +155,18 @@ export async function devicePost(base, route, json, opts = {}) {
     }
     return { status: res.status, body: parsed };
 }
+export function isPositiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 1;
+}
+/** Append pass selection and SHA filter to a PR review query. */
+export function applyPrReviewQuery(query, opts) {
+    if (opts.afterSha)
+        query.set("after_sha", opts.afterSha);
+    if (opts.pass !== undefined)
+        query.set("pass", String(opts.pass));
+    if (opts.afterPass !== undefined)
+        query.set("after_pass", String(opts.afterPass));
+}
 /**
  * Bearer-writable settings keys, mirroring the `/api/v1/settings` allowlist.
  * The connected flags are read-only there and deliberately absent here.
@@ -283,6 +295,7 @@ export async function getPrVortexReview(owner, repo, prNumber, cfg, opts) {
         repo: cleanRepo,
         pr_number: String(prNumber),
     });
+    applyPrReviewQuery(query, opts ?? {});
     const { status, body, retryAfterSeconds } = await apiFetch(resolved, `/api/v1/stacks/pr-review?${query.toString()}`, { signal: opts?.signal, timeoutMs: opts?.timeoutMs });
     if (status === 404) {
         throw new CommandError(`Vortex review not found: ${cleanOwner}/${cleanRepo}#${prNumber}`, REVIEW_EXIT.failed, "not_found");
@@ -353,7 +366,7 @@ export function stackPolicyBody(policy) {
 /** Adopt an open PR chain (Bearer POST /api/v1/stacks/adopt). */
 export async function adoptStack(owner, repo, prNumber, cfg, policy) {
     const resolved = cfg ?? (await loadConfig());
-    const { status, body } = await apiFetch(resolved, "/api/v1/stacks/adopt", {
+    const { status, body, retryAfterSeconds } = await apiFetch(resolved, "/api/v1/stacks/adopt", {
         method: "POST",
         json: {
             owner,
@@ -365,6 +378,9 @@ export async function adoptStack(owner, repo, prNumber, cfg, policy) {
     if (status === 404) {
         throw new CommandError("Stacks API is not available on this server yet. Deploy the API update or use the dashboard.");
     }
+    if (status === 429) {
+        throw new CommandError(rateLimitedMessage(retryAfterSeconds), REVIEW_EXIT.rate_limited, "rate_limited", { retryAfterSeconds });
+    }
     if (status !== 200) {
         throw new CommandError(`Failed to import stack (HTTP ${status}): ${JSON.stringify(body)}`);
     }

package/dist/automation-catalog.d.ts

@@ -22,6 +22,10 @@ export declare const BEARER_SETTINGS: readonly [{
     readonly key: "cyclone_review_unit_land_prs_enabled";
     readonly flag: "--cyclone-review-unit-land";
     readonly label: "Cyclone Review Unit land PRs";
+}, {
+    readonly key: "cyclone_skip_ci_enabled";
+    readonly flag: "--cyclone-skip-ci";
+    readonly label: "Skip CI on Cyclone commits";
 }, {
     readonly key: "vortex_seam_specialist_enabled";
     readonly flag: "--vortex-seam";

package/dist/automation-catalog.js

@@ -5,6 +5,7 @@ export const BEARER_SETTINGS = [
     { key: "repo_overview_enabled", flag: "--repo-overview", label: "Repo overview" },
     { key: "review_unit_land_prs_enabled", flag: "--review-unit-land", label: "Review Unit land PRs" },
     { key: "cyclone_review_unit_land_prs_enabled", flag: "--cyclone-review-unit-land", label: "Cyclone Review Unit land PRs" },
+    { key: "cyclone_skip_ci_enabled", flag: "--cyclone-skip-ci", label: "Skip CI on Cyclone commits" },
     { key: "vortex_seam_specialist_enabled", flag: "--vortex-seam", label: "Vortex seam specialist" },
     { key: "auto_land_default", flag: "--auto-land", label: "Auto land (new stacks)" },
 ];

package/dist/client/index.d.ts

@@ -2,5 +2,6 @@ export { DEFAULT_API, apiBase, clearConfig, configPath, keyDisplay, loadConfig,
 export { BEARER_SETTINGS, BEARER_SETTINGS_FLAGS, BEARER_SETTINGS_KEYS, BEARER_SETTINGS_LABELS, type BearerSettingsKey, } from "../automation-catalog.js";
 export { API_TIMEOUT_PREFIX, DEFAULT_API_TIMEOUT_MS, SETTINGS_WRITABLE_KEYS, adoptStack, apiFetch, cancelMergeQueueEntry, devicePost, enqueueStack, ensureUpperPark, getEnrichedStack, getMe, getPrVortexReview, getReview, getSettings, landNextStack, listJobs, listMergeQueueEntries, listStacks, listThreads, parseRetryAfterSeconds, patchSettings, restackStack, setStackAutoLand, setStackPolicy, stackPolicyBody, type ApiFetchInit, type ApiFetchResult, type JobListItem, type MeResponse, type MergeQueueBounceDetail, type MergeQueueBounceKind, type MergeQueueEnqueuedBy, type MergeQueueEnqueuedVia, type MergeQueueEntryDto, type MergeQueueEntryState, type PrReviewFinding, type PrReviewFindings, type PrVortexReview, type SettingsPatch, type SettingsResponse, type SettingsWritableKey, type StackDto, type StackPolicyPatch, type ThreadDetail, type ThreadListItem, } from "../api.js";
 export { CommandError, DetachedError, RATE_LIMITED_HINT, REVIEW_EXIT, isCommandErrorCode, rateLimitedMessage, type CommandErrorCode, type CommandErrorExtras, } from "../errors.js";
-export { REVIEW_POLL_BACKOFF_MS, REVIEW_POLL_DEFAULT_TIMEOUT_MS, REVIEW_POLL_INTERVAL_MS, REVIEW_POLL_MAX_INTERVAL_MS, REVIEW_POLL_MAX_TRANSIENT_RETRIES, REVIEW_POLL_STRETCH_AFTER_MS, REVIEW_POLL_STRETCH_SPAN_MS, REVIEW_THREAD_SLUG_RE, PrReviewPollTimeoutError, ReviewPollTimeoutError, collectReviewInput, isTransientReviewPollError, isTransientReviewPollStatus, loadReviewContext, pollPrVortexReview, pollReview, stretchedPollIntervalMs, submitReview, transientRetryWaitMs, type PollReviewOptions, type PollPrVortexReviewOptions, type ReviewInput, type SubmitReviewOptions, } from "../commands/review-client.js";
+export { REVIEW_POLL_BACKOFF_MS, REVIEW_POLL_DEFAULT_TIMEOUT_MS, REVIEW_POLL_INTERVAL_MS, REVIEW_POLL_MAX_INTERVAL_MS, REVIEW_POLL_MAX_TRANSIENT_RETRIES, REVIEW_POLL_STRETCH_AFTER_MS, REVIEW_POLL_STRETCH_SPAN_MS, REVIEW_THREAD_SLUG_RE, PrReviewPollTimeoutError, ReviewPollTimeoutError, collectReviewInput, formatReviewSubmitError, isTransientReviewPollError, isTransientReviewPollStatus, loadReviewContext, pollPrVortexReview, pollReview, stretchedPollIntervalMs, submitReview, transientRetryWaitMs, type PollReviewOptions, type PollPrVortexReviewOptions, type ReviewInput, type SubmitReviewOptions, } from "../commands/review-client.js";
 export { REVIEW_JOB_ENVELOPE_SCHEMA, toReviewJobEnvelope, type ReviewEnvelopeFallbacks, type ReviewJobEnvelope, type ReviewJobRow, } from "../ui/job-envelope.js";
+export { discoverTrunk } from "../git-stack.js";

package/dist/client/index.js

@@ -2,5 +2,6 @@ export { DEFAULT_API, apiBase, clearConfig, configPath, keyDisplay, loadConfig,
 export { BEARER_SETTINGS, BEARER_SETTINGS_FLAGS, BEARER_SETTINGS_KEYS, BEARER_SETTINGS_LABELS, } from "../automation-catalog.js";
 export { API_TIMEOUT_PREFIX, DEFAULT_API_TIMEOUT_MS, SETTINGS_WRITABLE_KEYS, adoptStack, apiFetch, cancelMergeQueueEntry, devicePost, enqueueStack, ensureUpperPark, getEnrichedStack, getMe, getPrVortexReview, getReview, getSettings, landNextStack, listJobs, listMergeQueueEntries, listStacks, listThreads, parseRetryAfterSeconds, patchSettings, restackStack, setStackAutoLand, setStackPolicy, stackPolicyBody, } from "../api.js";
 export { CommandError, DetachedError, RATE_LIMITED_HINT, REVIEW_EXIT, isCommandErrorCode, rateLimitedMessage, } from "../errors.js";
-export { REVIEW_POLL_BACKOFF_MS, REVIEW_POLL_DEFAULT_TIMEOUT_MS, REVIEW_POLL_INTERVAL_MS, REVIEW_POLL_MAX_INTERVAL_MS, REVIEW_POLL_MAX_TRANSIENT_RETRIES, REVIEW_POLL_STRETCH_AFTER_MS, REVIEW_POLL_STRETCH_SPAN_MS, REVIEW_THREAD_SLUG_RE, PrReviewPollTimeoutError, ReviewPollTimeoutError, collectReviewInput, isTransientReviewPollError, isTransientReviewPollStatus, loadReviewContext, pollPrVortexReview, pollReview, stretchedPollIntervalMs, submitReview, transientRetryWaitMs, } from "../commands/review-client.js";
+export { REVIEW_POLL_BACKOFF_MS, REVIEW_POLL_DEFAULT_TIMEOUT_MS, REVIEW_POLL_INTERVAL_MS, REVIEW_POLL_MAX_INTERVAL_MS, REVIEW_POLL_MAX_TRANSIENT_RETRIES, REVIEW_POLL_STRETCH_AFTER_MS, REVIEW_POLL_STRETCH_SPAN_MS, REVIEW_THREAD_SLUG_RE, PrReviewPollTimeoutError, ReviewPollTimeoutError, collectReviewInput, formatReviewSubmitError, isTransientReviewPollError, isTransientReviewPollStatus, loadReviewContext, pollPrVortexReview, pollReview, stretchedPollIntervalMs, submitReview, transientRetryWaitMs, } from "../commands/review-client.js";
 export { REVIEW_JOB_ENVELOPE_SCHEMA, toReviewJobEnvelope, } from "../ui/job-envelope.js";
+export { discoverTrunk } from "../git-stack.js";

package/dist/commands/browse.d.ts

@@ -27,7 +27,7 @@ export declare function buildStatusTabLines(input: StatusTabInput): string[];
 /** In-place job detail for the Jobs tab (same envelope as `status <id>`). */
 export declare function formatJobDetailLines(row: ReviewJobRow): string[];
 /** Human labels for the Config tab and the static `settings` printout. */
-export declare const SETTINGS_LABELS: Record<"auto_review_enabled" | "auto_patch_enabled" | "vortex_show_thinking_traces" | "repo_overview_enabled" | "review_unit_land_prs_enabled" | "cyclone_review_unit_land_prs_enabled" | "vortex_seam_specialist_enabled" | "auto_land_default", string>;
+export declare const SETTINGS_LABELS: Record<"auto_review_enabled" | "auto_patch_enabled" | "vortex_show_thinking_traces" | "repo_overview_enabled" | "review_unit_land_prs_enabled" | "cyclone_review_unit_land_prs_enabled" | "cyclone_skip_ci_enabled" | "vortex_seam_specialist_enabled" | "auto_land_default", string>;
 /** Config rows in a stable order: writable toggles, then connected flags. */
 export declare function buildConfigRows(settings: SettingsResponse): TabsConfigRow[];
 /**

package/dist/commands/browse.js

@@ -3,6 +3,7 @@ import { BEARER_SETTINGS_LABELS } from "../automation-catalog.js";
 import { apiBase, keyDisplay, loadConfig, resolveApiKey } from "../config.js";
 import { CommandError } from "../errors.js";
 import { ansi } from "../ui/ansi.js";
+import { humanSummary } from "../ui/human-summary.js";
 import { toReviewJobEnvelope, } from "../ui/job-envelope.js";
 import { runTabsBrowser, } from "../ui/tabs.js";
 import { formatDaysLeft, formatResetLabel } from "../ui/usage.js";
@@ -90,9 +91,10 @@ export function formatJobDetailLines(row) {
         lines.push(`  Credits  ${e.credits.standard} standard`);
     if (e.error)
         lines.push(ansi.red(`  Error    ${e.error}`));
-    if (e.summary) {
+    const summary = e.summary ? humanSummary(e.summary) : null;
+    if (summary) {
         lines.push("");
-        for (const l of e.summary.split("\n"))
+        for (const l of summary.split("\n"))
             lines.push(`  ${l}`);
     }
     const inline = e.findings?.inline ?? [];
@@ -218,6 +220,7 @@ export async function openTabsBrowser(initial) {
                 plan: me.plan_label_key ?? me.plan_key,
                 used: me.usage.standard.used,
                 limit: me.usage.standard.limit,
+                bonusRemaining: me.usage.bonus?.remaining,
                 resetsAt: me.resets_at,
                 jobs: jobs.slice(0, 5).map(toPanelJob),
                 jobsError: jobsError ?? undefined,

package/dist/commands/credits.js

@@ -36,6 +36,7 @@ export async function cmdCredits(args) {
         plan: me.plan_label_key ?? me.plan_key,
         used: s.used,
         limit: s.limit,
+        bonusRemaining: me.usage.bonus?.remaining,
         resetsAt: me.resets_at,
         jobs: recentJobs.map(toPanelJob),
         columns,

package/dist/commands/pr.d.ts

@@ -6,6 +6,10 @@ export type ParsedPrArgs = {
     format: "json" | "pretty";
     wait: boolean;
     afterSha?: string;
+    /** Exact pass on the head (#2027). */
+    pass?: number;
+    /** Only a pass later than this one on the head (#2027). */
+    afterPass?: number;
     timeoutMs: number;
 };
 export type PrOptions = {

package/dist/commands/pr.js

@@ -3,9 +3,17 @@ import { loadConfig } from "../config.js";
 import { CommandError, REVIEW_EXIT } from "../errors.js";
 import { ansi } from "../ui/ansi.js";
 import { renderFindings } from "../ui/findings.js";
+import { humanSummary } from "../ui/human-summary.js";
 import { PrReviewPollTimeoutError, REVIEW_POLL_DEFAULT_TIMEOUT_MS, pollPrVortexReview, } from "./review-client.js";
 import { parseAdoptTarget } from "./stack.js";
-const PR_USAGE = "usage: mergestorm pr <owner/repo>#<n> [--json] [--wait] [--after-sha <sha>] [--timeout <s>]";
+const PR_USAGE = "usage: mergestorm pr <owner/repo>#<n> [--json] [--wait] [--after-sha <sha>] [--pass <n>] [--after-pass <n>] [--timeout <s>]";
+function parsePassFlag(flag, value) {
+    const parsed = Number(value);
+    if (!value?.trim() || !/^[0-9]+$/.test(value.trim()) || !Number.isSafeInteger(parsed) || parsed < 1) {
+        throw usageError(`${flag} requires a positive integer`);
+    }
+    return parsed;
+}
 function usageError(message = PR_USAGE) {
     return new CommandError(message, REVIEW_EXIT.usage, "usage");
 }
@@ -14,6 +22,8 @@ export function parsePrArgs(args, defaults = { format: "json" }) {
     let format = defaults.format;
     let wait = false;
     let afterSha;
+    let pass;
+    let afterPass;
     let timeoutMs = REVIEW_POLL_DEFAULT_TIMEOUT_MS;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
@@ -42,6 +52,14 @@ export function parsePrArgs(args, defaults = { format: "json" }) {
             }
             continue;
         }
+        if (arg === "--pass" || arg.startsWith("--pass=")) {
+            pass = parsePassFlag("--pass", arg === "--pass" ? args[++i] : arg.slice("--pass=".length));
+            continue;
+        }
+        if (arg === "--after-pass" || arg.startsWith("--after-pass=")) {
+            afterPass = parsePassFlag("--after-pass", arg === "--after-pass" ? args[++i] : arg.slice("--after-pass=".length));
+            continue;
+        }
         if (arg === "--timeout" || arg.startsWith("--timeout=")) {
             const value = arg === "--timeout" ? args[++i] : arg.slice("--timeout=".length);
             const seconds = Number(value);
@@ -58,6 +76,12 @@ export function parsePrArgs(args, defaults = { format: "json" }) {
     }
     if (afterSha && !wait)
         throw usageError("--after-sha requires --wait");
+    if (pass !== undefined && afterPass !== undefined) {
+        throw usageError("--pass and --after-pass are exclusive");
+    }
+    if ((pass !== undefined || afterPass !== undefined) && (!wait || !afterSha)) {
+        throw usageError("--pass and --after-pass require --wait --after-sha");
+    }
     if (target.length < 1 || target.length > 2)
         throw usageError();
     let parsed;
@@ -67,7 +91,7 @@ export function parsePrArgs(args, defaults = { format: "json" }) {
     catch {
         throw usageError();
     }
-    return { ...parsed, format, wait, afterSha, timeoutMs };
+    return { ...parsed, format, wait, afterSha, pass, afterPass, timeoutMs };
 }
 function printPretty(envelope) {
     console.log(`Status:        ${envelope.status}`);
@@ -78,8 +102,9 @@ function printPretty(envelope) {
     console.log(`Finding count: ${envelope.finding_count}`);
     if (envelope.skip_reason)
         console.log(`Skip reason:   ${envelope.skip_reason}`);
-    if (envelope.summary)
-        console.log(envelope.summary);
+    const summary = envelope.summary ? humanSummary(envelope.summary) : null;
+    if (summary)
+        console.log(summary);
     renderFindings(envelope.findings, {
         emptyMessage: envelope.status === "completed",
     });
@@ -96,6 +121,8 @@ export async function cmdPr(args, opts = {}) {
                 timeoutMs: parsed.timeoutMs,
                 intervalMs: opts.pollIntervalMs,
                 afterSha: parsed.afterSha,
+                pass: parsed.pass,
+                afterPass: parsed.afterPass,
                 signal: opts.signal,
                 ...opts.poll,
                 onTick(kind) {
@@ -116,7 +143,7 @@ export async function cmdPr(args, opts = {}) {
             console.log("");
     }
     else {
-        envelope = await getPrVortexReview(parsed.owner, parsed.repo, parsed.prNumber, cfg, { signal: opts.signal });
+        envelope = await getPrVortexReview(parsed.owner, parsed.repo, parsed.prNumber, cfg, { signal: opts.signal, pass: parsed.pass, afterPass: parsed.afterPass });
     }
     if (parsed.format === "json") {
         console.log(JSON.stringify(envelope, null, opts.mode === "shell" ? 2 : undefined));

package/dist/commands/registry.js

@@ -52,6 +52,7 @@ export const COMMAND_REGISTRY = [
             "  [--context text] [--context-file path] [--thread slug]",
             "  [--idempotency-key k] [--webhook-url https://…]",
             "  HTTP 429 exits 7 (rate_limited) with retry_after_seconds",
+            "  Uploads over 1 MB / 1_000_000 are rejected with HTTP 413 and do not create a job",
         ],
         async run(args, ctx) {
             if (ctx.mode === "shell") {
@@ -66,7 +67,8 @@ export const COMMAND_REGISTRY = [
         summary: "Latest Vortex review for a GitHub PR",
         usage: [
             "mergestorm pr <owner/repo>#<n>  Fetch the latest Vortex PR review",
-            "  [--json] [--wait] [--after-sha <sha>] [--timeout <s>]",
+            "  [--json] [--wait] [--after-sha <sha>] [--pass <n>] [--after-pass <n>] [--timeout <s>]",
+            "  --pass reads one attempt on the head; --after-pass waits for a later one (#2027)",
             "  Also accepts: mergestorm pr <owner/repo> <n>",
         ],
         async run(args, ctx) {
@@ -163,8 +165,8 @@ export const COMMAND_REGISTRY = [
             "mergestorm settings [--json]    Read the automation toggles (Config tab on a TTY)",
             "  [--auto-review on|off] [--auto-patch on|off] [--vortex-thinking on|off]",
             "  [--repo-overview on|off] [--review-unit-land on|off]",
-            "  [--cyclone-review-unit-land on|off] [--vortex-seam on|off]",
-            "  [--auto-land on|off]            Auto land default for stacks opened after this",
+            "  [--cyclone-review-unit-land on|off] [--cyclone-skip-ci on|off]",
+            "  [--vortex-seam on|off] [--auto-land on|off]  Auto land default for new stacks",
             "  With flags: PATCH those settings and print the stored result",
         ],
         async run(args, ctx) {

package/dist/commands/review-client.d.ts

@@ -1,4 +1,4 @@
-import { type PrVortexReview } from "../api.js";
+import { type PrReviewPassSelector, type PrVortexReview } from "../api.js";
 import type { Config } from "../config.js";
 import type { ReviewJobRow } from "../ui/job-envelope.js";
 export declare const REVIEW_POLL_INTERVAL_MS = 2000;
@@ -10,6 +10,8 @@ export declare const REVIEW_POLL_STRETCH_AFTER_MS = 60000;
 export declare const REVIEW_POLL_STRETCH_SPAN_MS = 60000;
 /** Same thread slug contract as POST /api/v1/reviews. */
 export declare const REVIEW_THREAD_SLUG_RE: RegExp;
+/** Same product limit as `api/src/v1/reviews.ts` `MAX_DIFF_BYTES`. */
+export declare const MAX_REVIEW_DIFF_BYTES = 1000000;
 export declare const MAX_CONTEXT_TEXT_CHARS = 60000;
 export declare const MAX_CONTEXT_FILES = 10;
 export declare const MAX_CONTEXT_FILE_CHARS = 16000;
@@ -52,7 +54,7 @@ export type LoadReviewContextOptions = {
     contextFiles: string[];
     cwd?: string;
     readStdin?: () => Promise<string>;
-    /** Reject contextFiles that resolve outside this directory (agent-driven callers). */
+    /** Bound contextFiles to this directory; defaults to the canonical repo root. */
     sandboxCwd?: string;
 };
 /** Load --context / --context-file and enforce the API caps client-side. */
@@ -62,6 +64,11 @@ export declare function submitReview(cfg: Config, input: ReviewInput, opts?: Sub
     row: ReviewJobRow;
     retryAfterSeconds?: number;
 }>;
+/**
+ * Human copy for a failed POST /api/v1/reviews.
+ * nginx 413 is HTML, so `submitReview` stores `{}` and used to print `Failed: {}`.
+ */
+export declare function formatReviewSubmitError(status: number, body: unknown): string;
 /** Exponential backoff with jitter in `[0.5, 1.0]` of the base delay. */
 export declare function transientRetryWaitMs(input: {
     retryAfterSeconds?: number;
@@ -98,7 +105,7 @@ export type PollReviewOptions = {
     /** Test seam for backoff jitter; production uses `Math.random`. */
     random?: () => number;
 };
-export type PollPrVortexReviewOptions = PollReviewOptions & {
+export type PollPrVortexReviewOptions = PollReviewOptions & PrReviewPassSelector & {
     afterSha?: string;
 };
 /** Poll the DB-only PR review endpoint until the requested pass is resting. */

package/dist/commands/review-client.js

@@ -1,6 +1,6 @@
 import { readFile, realpath } from "node:fs/promises";
 import { join, relative, resolve, sep } from "node:path";
-import { apiFetch } from "../api.js";
+import { apiFetch, applyPrReviewQuery, isPositiveInteger, } from "../api.js";
 import { CommandError, REVIEW_EXIT, isCommandErrorCode, rateLimitedMessage } from "../errors.js";
 import { changedNamesInSandbox, collectChangedFiles, git, parseGithubOriginRepo, repoRoot, } from "../git.js";
 export const REVIEW_POLL_INTERVAL_MS = 2_000;
@@ -12,6 +12,8 @@ export const REVIEW_POLL_STRETCH_AFTER_MS = 60_000;
 export const REVIEW_POLL_STRETCH_SPAN_MS = 60_000;
 /** Same thread slug contract as POST /api/v1/reviews. */
 export const REVIEW_THREAD_SLUG_RE = /^[a-zA-Z0-9][a-zA-Z0-9._/-]{0,119}$/;
+/** Same product limit as `api/src/v1/reviews.ts` `MAX_DIFF_BYTES`. */
+export const MAX_REVIEW_DIFF_BYTES = 1_000_000;
 export const MAX_CONTEXT_TEXT_CHARS = 60_000;
 export const MAX_CONTEXT_FILES = 10;
 export const MAX_CONTEXT_FILE_CHARS = 16_000;
@@ -25,9 +27,11 @@ export async function collectReviewInput(base, head, cwd = process.cwd(), sandbo
             diff = "";
         }
         else {
-            const root = repoRoot(cwd);
-            const specs = names.map((name) => `:(literal)${relative(cwd, join(root, name))}`);
-            diff = git(["diff", `${base}...${head}`, "--", ...specs], cwd);
+            const canonicalCwd = await realpath(cwd);
+            const root = repoRoot(canonicalCwd);
+            const specs = names.map((name) => `:(literal)${relative(canonicalCwd, join(root, name))}`);
+            // Collection must not execute configured diff or text conversion helpers.
+            diff = git(["diff", "--no-ext-diff", "--no-textconv", `${base}...${head}`, "--", ...specs], cwd);
         }
     }
     catch (err) {
@@ -83,26 +87,28 @@ export async function loadReviewContext(opts) {
     let total = 0;
     for (const rawPath of opts.contextFiles) {
         const abs = resolve(cwd, rawPath);
-        if (opts.sandboxCwd) {
-            let sandboxReal;
-            let targetReal;
-            try {
-                [sandboxReal, targetReal] = await Promise.all([
-                    realpath(resolve(opts.sandboxCwd)),
-                    realpath(abs),
-                ]);
-            }
-            catch {
-                throw contextUsage(`--context-file ${rawPath} must be inside the working directory`);
-            }
-            const relToSandbox = relative(sandboxReal, targetReal);
-            if (relToSandbox === ".." || relToSandbox.startsWith(`..${sep}`)) {
-                throw contextUsage(`--context-file ${rawPath} must be inside the working directory`);
-            }
+        const boundaryLabel = opts.sandboxCwd ? "working directory" : "repo root";
+        let targetReal;
+        let sandboxReal;
+        try {
+            sandboxReal = opts.sandboxCwd ? await realpath(resolve(opts.sandboxCwd)) : repoRoot(cwd);
+        }
+        catch {
+            throw contextUsage(`--context-file ${rawPath} must be inside the ${boundaryLabel}`);
+        }
+        try {
+            targetReal = await realpath(abs);
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            throw contextUsage(`could not read --context-file ${rawPath}: ${detail}`);
+        }
+        if (targetReal !== sandboxReal && !targetReal.startsWith(`${sandboxReal}${sep}`)) {
+            throw contextUsage(`--context-file ${rawPath} must be inside the ${boundaryLabel}`);
         }
         let content;
         try {
-            content = await readFile(abs, "utf8");
+            content = await readFile(targetReal, "utf8");
         }
         catch (err) {
             const detail = err instanceof Error ? err.message : String(err);
@@ -148,6 +154,39 @@ export async function submitReview(cfg, input, opts = {}) {
         ...(retryAfterSeconds !== undefined ? { retryAfterSeconds } : {}),
     };
 }
+function reviewSubmitErrorText(body) {
+    if (body && typeof body === "object") {
+        const rec = body;
+        const message = typeof rec.message === "string" ? rec.message.trim() : "";
+        const error = typeof rec.error === "string" ? rec.error.trim() : "";
+        if (message)
+            return message;
+        if (error)
+            return error;
+    }
+    if (typeof body === "string") {
+        const trimmed = body.trim();
+        if (trimmed && !trimmed.startsWith("<"))
+            return trimmed.slice(0, 240);
+    }
+    return "";
+}
+/**
+ * Human copy for a failed POST /api/v1/reviews.
+ * nginx 413 is HTML, so `submitReview` stores `{}` and used to print `Failed: {}`.
+ */
+export function formatReviewSubmitError(status, body) {
+    const detail = reviewSubmitErrorText(body);
+    if (status === 413) {
+        if (detail)
+            return `${detail} No review job was created and no credits were charged.`;
+        return ("Upload rejected (HTTP 413). nginx stopped the body before a review job was created, " +
+            "so no credits were charged. Max diff size is 1 MB / 1_000_000 bytes.");
+    }
+    if (detail)
+        return `Failed (HTTP ${status}): ${detail}`;
+    return `Failed (HTTP ${status}). The API did not return a JSON error body.`;
+}
 /** Exponential backoff with jitter in `[0.5, 1.0]` of the base delay. */
 export function transientRetryWaitMs(input) {
     const exp = REVIEW_POLL_BACKOFF_MS * 2 ** Math.max(0, input.failureCount - 1);
@@ -242,8 +281,10 @@ export async function pollPrVortexReview(cfg, owner, repo, prNumber, opts = {})
         repo,
         pr_number: String(prNumber),
     });
-    if (opts.afterSha)
-        query.set("after_sha", opts.afterSha);
+    // #2027: the pass selector is fixed for the whole wait. after_pass stays
+    // what the caller handed in on every poll and every retry; it is never
+    // replaced by the pass of an in-progress envelope seen along the way.
+    applyPrReviewQuery(query, opts);
     let transientFailures = 0;
     let lastEnvelope = null;
     const sleepBeforeRetry = async (retryAfterSeconds) => {
@@ -310,10 +351,23 @@ export async function pollPrVortexReview(cfg, owner, repo, prNumber, opts = {})
         if (!poll.body || typeof poll.body !== "object") {
             throw new CommandError("Poll failed: invalid PR review response", REVIEW_EXIT.failed, "review_failed");
         }
-        lastEnvelope = poll.body;
+        const envelope = poll.body;
+        // The server filters by pass; re-check here so a server that ignores the
+        // selector can never satisfy the wait with the wrong pass.
+        if ((opts.pass !== undefined || opts.afterPass !== undefined) &&
+            (!isPositiveInteger(envelope.pass) || (opts.pass !== undefined && envelope.pass !== opts.pass) ||
+                (opts.afterPass !== undefined && envelope.pass <= opts.afterPass))) {
+            opts.onTick?.("progress");
+            await sleepBeforePoll();
+            continue;
+        }
+        lastEnvelope = envelope;
         const resting = (lastEnvelope.raw_status ?? lastEnvelope.status) !== "in_progress";
         const matches = !opts.afterSha || shaMatches(lastEnvelope.head_sha, opts.afterSha);
-        if (resting && matches)
+        // MS-01: A resting completion with newer_pass_pending indicates a newer
+        // attempt is in flight. Do not satisfy the wait from this stale result.
+        const stale = lastEnvelope.newer_pass_pending === true;
+        if (resting && matches && !stale)
             return lastEnvelope;
         opts.onTick?.("progress");
         await sleepBeforePoll();

package/dist/commands/review.js

@@ -4,9 +4,10 @@ import { CommandError, DetachedError, REVIEW_EXIT, isCommandErrorCode, rateLimit
 import { discoverTrunk } from "../git-stack.js";
 import { ansi } from "../ui/ansi.js";
 import { formatFindingsLines } from "../ui/findings.js";
+import { humanSummary } from "../ui/human-summary.js";
 import { present } from "../ui/present.js";
 import { toReviewJobEnvelope, } from "../ui/job-envelope.js";
-import { MAX_IDEMPOTENCY_KEY_CHARS, REVIEW_POLL_DEFAULT_TIMEOUT_MS, REVIEW_POLL_MAX_TRANSIENT_RETRIES, REVIEW_THREAD_SLUG_RE, ReviewPollTimeoutError, collectReviewInput, isTransientReviewPollError, isTransientReviewPollStatus, loadReviewContext, pollReview, submitReview, } from "./review-client.js";
+import { MAX_IDEMPOTENCY_KEY_CHARS, REVIEW_POLL_DEFAULT_TIMEOUT_MS, REVIEW_POLL_MAX_TRANSIENT_RETRIES, REVIEW_THREAD_SLUG_RE, ReviewPollTimeoutError, collectReviewInput, isTransientReviewPollError, isTransientReviewPollStatus, loadReviewContext, pollReview, formatReviewSubmitError, submitReview, } from "./review-client.js";
 export { REVIEW_POLL_MAX_TRANSIENT_RETRIES, isTransientReviewPollError, isTransientReviewPollStatus, };
 /** Same public specialist allowlist as the API contract and migration 117. */
 export const VORTEX_ROUTER_MODES = ["off", "standard", "max", "manual"];
@@ -39,7 +40,8 @@ function normalizeVortexSpecialistIds(value) {
     const selected = new Set(value.filter((id) => typeof id === "string" && VORTEX_SPECIALIST_IDS.includes(id)));
     return VORTEX_SPECIALIST_IDS.filter((id) => selected.has(id));
 }
-const REVIEW_USAGE = "usage: mergestorm review [base] [head] [--json] [--wait|--no-wait] [--timeout seconds] [--router off|standard|max|manual] [--specialists id,id] [--context text] [--context-file path] [--idempotency-key k] [--webhook-url https://…] [--thread slug]";
+const REVIEW_USAGE = "usage: mergestorm review [base] [head] [--json] [--wait|--no-wait] [--timeout seconds] [--router off|standard|max|manual] [--specialists id,id] [--context text] [--context-file path] [--idempotency-key k] [--webhook-url https://…] [--thread slug]\n" +
+    "Uploads over 1 MB / 1_000_000 are rejected with HTTP 413 and do not create a job.";
 function usageError(message = REVIEW_USAGE) {
     return new CommandError(message, REVIEW_EXIT.usage, "usage");
 }
@@ -163,6 +165,9 @@ export function parseReviewArgs(args) {
             thread = slug;
             continue;
         }
+        if (a === "-h" || a === "--help") {
+            throw usageError();
+        }
         if (a.startsWith("-")) {
             throw usageError(`unknown flag: ${a}`);
         }
@@ -226,6 +231,10 @@ function asPollCommandError(err, jobId) {
     return new CommandError(withReviewJobRecovery(`Poll failed: ${detail}`, jobId));
 }
 export async function cmdReview(args, opts = {}) {
+    if (args.includes("-h") || args.includes("--help")) {
+        console.log(REVIEW_USAGE);
+        return;
+    }
     const parsed = parseReviewArgs(args);
     const base = resolveReviewBase(parsed.base);
     const head = parsed.head || "HEAD";
@@ -255,7 +264,6 @@ export async function cmdReview(args, opts = {}) {
     };
     try {
         const cfg = await loadConfig();
-        const meBefore = interactive ? await getMe(cfg) : null;
         progress(`Collecting diff ${base}...${head} …`);
         const input = await collectReviewInput(base, head);
         if (!input) {
@@ -320,7 +328,7 @@ export async function cmdReview(args, opts = {}) {
             });
         }
         if (submitted.status !== 202 && submitted.status !== 200) {
-            const message = `Failed: ${JSON.stringify(submitted.row, null, 2)}`;
+            const message = formatReviewSubmitError(submitted.status, submitted.row);
             if (json)
                 printJson(submitted.row, { status: "failed", error: message });
             throw new CommandError(message, REVIEW_EXIT.failed, "review_failed");
@@ -407,21 +415,24 @@ export async function cmdReview(args, opts = {}) {
         ];
         if (ran.length > 0)
             result.push(ansi.dim(`Specialists: ${ran.join(", ")}`));
-        if (row.summary)
-            result.push(row.summary);
+        const summary = row.summary ? humanSummary(row.summary) : null;
+        if (summary)
+            result.push(summary);
         result.push(...formatFindingsLines(row.findings, {
             emptyMessage: true,
         }));
-        if (interactive && meBefore) {
-            const meAfter = await getMe(cfg);
-            if (meAfter) {
-                const beforeLeft = meBefore.usage.standard.remaining ?? 0;
-                const afterLeft = meAfter.usage.standard.remaining ?? 0;
-                const used = Math.max(0, beforeLeft - afterLeft);
-                if (used > 0) {
-                    result.push(ansi.dim(`${used} credit${used === 1 ? "" : "s"} used · ${afterLeft} remaining`));
-                }
+        if (interactive) {
+            const me = await getMe(cfg);
+            const used = row.credits?.standard;
+            const remaining = me?.usage.standard.remaining;
+            const credits = [];
+            if (used != null) {
+                credits.push(`${used} credit${used === 1 ? "" : "s"} used`);
             }
+            if (remaining != null)
+                credits.push(`${remaining} remaining`);
+            if (credits.length > 0)
+                result.push(ansi.dim(credits.join(" · ")));
         }
         await present("Review", result);
     }

package/dist/commands/settings.d.ts

@@ -3,7 +3,7 @@ import { type SettingsPatch, type SettingsResponse } from "../api.js";
  * CLI flag → Bearer settings key. on|off only. The connected flags are
  * read-only on the API and deliberately have no flag here.
  */
-export declare const SETTINGS_FLAGS: Record<string, "auto_review_enabled" | "auto_patch_enabled" | "vortex_show_thinking_traces" | "repo_overview_enabled" | "review_unit_land_prs_enabled" | "cyclone_review_unit_land_prs_enabled" | "vortex_seam_specialist_enabled" | "auto_land_default">;
+export declare const SETTINGS_FLAGS: Record<string, "auto_review_enabled" | "auto_patch_enabled" | "vortex_show_thinking_traces" | "repo_overview_enabled" | "review_unit_land_prs_enabled" | "cyclone_review_unit_land_prs_enabled" | "cyclone_skip_ci_enabled" | "vortex_seam_specialist_enabled" | "auto_land_default">;
 export type SettingsArgs = {
     json: boolean;
     patch: SettingsPatch;

package/dist/commands/stack.js

@@ -519,6 +519,12 @@ export async function cmdStackCreate(args, deps = {}) {
 }
 export async function cmdStackSubmit(args, deps = {}) {
     const { extend, autoLand, autoReview, autoPatch, asJson } = parseStackSubmitArgs(args);
+    const progress = (message) => {
+        if (asJson)
+            console.error(message);
+        else
+            console.log(message);
+    };
     const cwd = deps.cwd ?? process.cwd();
     const gitTopLevelFn = deps.gitTopLevel ?? gitTopLevel;
     const loadStackMetaFn = deps.loadStackMeta ?? loadStackMeta;
@@ -608,7 +614,7 @@ export async function cmdStackSubmit(args, deps = {}) {
         if (!branchExistsFn(layer.branch, cwd)) {
             throw new CommandError(`Stack layer branch missing locally: ${layer.branch}`);
         }
-        console.log(ansi.dim(`  Pushing ${layer.branch} …`));
+        progress(ansi.dim(`  Pushing ${layer.branch} …`));
         try {
             pushBranchFn(layer.branch, cwd);
         }
@@ -625,7 +631,7 @@ export async function cmdStackSubmit(args, deps = {}) {
     const openLayerPr = (branch, base) => {
         const existing = findOpenPrNumberFn(owner, repo, branch, cwd);
         if (existing != null) {
-            console.log(ansi.dim(`  PR #${existing} already open for ${branch}`));
+            progress(ansi.dim(`  PR #${existing} already open for ${branch}`));
             return { prNumber: existing, created: false };
         }
         const aheadRef = isMgParkBranch(base) ? `origin/${base}` : base;
@@ -653,7 +659,7 @@ export async function cmdStackSubmit(args, deps = {}) {
         }
         const title = tipCommitSubjectFn(branch, cwd);
         const body = buildPrBodyFn(tipCommitMessageFn(branch, cwd));
-        console.log(ansi.dim(`  Opening PR ${branch} → ${base} …`));
+        progress(ansi.dim(`  Opening PR ${branch} → ${base} …`));
         return {
             prNumber: createPrFn({
                 owner,
@@ -679,7 +685,7 @@ export async function cmdStackSubmit(args, deps = {}) {
     let adoptData = null;
     let stackId = plans.find((plan) => plan.stackId)?.stackId ?? null;
     const registerPr = async (prNumber) => {
-        console.log(ansi.dim(`  Registering stack via import (${owner}/${repo}#${prNumber}) …`));
+        progress(ansi.dim(`  Registering stack via import (${owner}/${repo}#${prNumber}) …`));
         const body = await adoptStackFn(owner, repo, prNumber, cfg, policy);
         if (typeof body !== "object" || body === null) {
             throw new CommandError("Unexpected response shape from adopt API");
@@ -703,7 +709,7 @@ export async function cmdStackSubmit(args, deps = {}) {
         if (!stackId) {
             throw new CommandError("Cannot mint a park freeze before the stack is registered. Open layers 1–2 first, then retry.");
         }
-        console.log(ansi.dim(`  Ensuring upper-park freeze for stack ${stackId} …`));
+        progress(ansi.dim(`  Ensuring upper-park freeze for stack ${stackId} …`));
         const park = await ensureUpperParkFn(stackId, cfg);
         for (const plan of pendingPark) {
             const { prNumber, created } = openLayerPr(plan.branch, park.freezeBranch);

package/dist/commands/status.js

@@ -5,6 +5,7 @@ import { canBrowse, formatJobDetailLines } from "./browse.js";
 import { CommandError, DetachedError, REVIEW_EXIT, isCommandErrorCode, } from "../errors.js";
 import { ansi } from "../ui/ansi.js";
 import { renderFindings } from "../ui/findings.js";
+import { humanSummary } from "../ui/human-summary.js";
 import { toReviewJobEnvelope, } from "../ui/job-envelope.js";
 import { REVIEW_POLL_DEFAULT_TIMEOUT_MS, ReviewPollTimeoutError, pollReview, } from "./review-client.js";
 const STATUS_USAGE = "usage: mergestorm status <job_id> [--json] [--wait] [--timeout seconds]";
@@ -71,8 +72,9 @@ function printPretty(row) {
     if (envelope.credits) {
         console.log(`Credits:   ${envelope.credits.standard} standard`);
     }
-    if (envelope.summary)
-        console.log(envelope.summary);
+    const summary = envelope.summary ? humanSummary(envelope.summary) : null;
+    if (summary)
+        console.log(summary);
     if (envelope.error)
         console.log(ansi.red(`Error: ${envelope.error}`));
     renderFindings(envelope.findings, {

package/dist/commands/whoami.js

@@ -1,5 +1,5 @@
 import { getMe } from "../api.js";
-import { apiBase, configPath, loadConfig, resolveApiKey, keyDisplay } from "../config.js";
+import { apiBase, configPath, loadConfig, resolveApiKey } from "../config.js";
 import { CommandError } from "../errors.js";
 import { ansi } from "../ui/ansi.js";
 import { present } from "../ui/present.js";
@@ -16,14 +16,17 @@ export async function cmdWhoami(args, opts = {}) {
         return;
     }
     const me = await getMe(cfg);
+    if (!me) {
+        throw new CommandError("Live account details unavailable. Could not verify account with /me.");
+    }
     const payload = {
-        key_prefix: me?.key.prefix ?? keyDisplay(key),
-        key_name: me?.key.name ?? null,
-        plan_key: me?.plan_key ?? null,
-        plan_label_key: me?.plan_label_key ?? null,
+        key_prefix: me.key.prefix,
+        key_name: me.key.name ?? null,
+        plan_key: me.plan_key ?? null,
+        plan_label_key: me.plan_label_key ?? null,
         api_base: apiBase(cfg),
         config_path: configPath(),
-        usage: me?.usage ?? null,
+        usage: me.usage ?? null,
     };
     if (asJson) {
         const text = JSON.stringify(payload, null, 2);
@@ -42,8 +45,5 @@ export async function cmdWhoami(args, opts = {}) {
     }
     lines.push(`  API      ${payload.api_base}`);
     lines.push(`  Config   ${payload.config_path}`);
-    if (!me) {
-        lines.push(ansi.dim("  (live account details unavailable — older API or offline)"));
-    }
     await present("Account", lines);
 }

package/dist/git.js

@@ -48,7 +48,7 @@ export async function changedNamesInSandbox(base, head, cwd = process.cwd(), san
     // even though their contents cannot be read from the working tree for upload.
     // -z disables core.quotePath quoting and NUL-terminates names, so paths with
     // spaces or non-ASCII characters survive the split verbatim.
-    const names = git(["diff", "--name-only", "-z", "--diff-filter=ACMRDT", `${base}...${head}`], cwd)
+    const names = git(["diff", "--no-ext-diff", "--no-textconv", "--name-only", "-z", "--diff-filter=ACMRDT", `${base}...${head}`], cwd)
         .split("\0")
         .filter(Boolean);
     const kept = [];

package/dist/stack-dto.d.ts

@@ -1,3 +1,11 @@
+export type RestackError = {
+    kind: "rebase_conflict" | "checkout_failed" | "head_unresolved" | "push_failed";
+    detail: string;
+    headSha: string;
+    attemptedAt: string;
+    attempts: number;
+    backupRef: string | null;
+};
 /**
  * Wire types returned by the stack list/enrich HTTP endpoints.
  *
@@ -7,8 +15,12 @@
 export type StackBranchState = "clean" | "needs_restack" | "restacking" | "conflict" | "merged" | "closed";
 export type StackCiStatus = "success" | "pending" | "failure" | "neutral" | "none" | "unknown";
 export type StackReviewStatus = "approved" | "changes_requested" | "reviewed" | "failed" | "none" | "unknown";
-/** `failed` is the newest Vortex `pr_reviews` row. Work paints Review failed. */
-export type StackVortexStatus = "reviewing" | "seam_pending" | "all_clear" | "findings" | "throttled" | "failed";
+/**
+ * `failed` is the newest Vortex `pr_reviews` row. Work paints Review failed.
+ * `incomplete` is a posted verdict whose head still has unreviewed files
+ * (#1947): Work paints Incomplete, never Reviewed or all clear.
+ */
+export type StackVortexStatus = "queued" | "skipped" | "reviewing" | "seam_pending" | "all_clear" | "findings" | "throttled" | "failed" | "incomplete";
 export type StackCycloneStatus = "patching" | "awaiting_fix";
 export type StackTempestStatus = "reviewing" | "findings" | "clear" | "failed" | "stale";
 export type StackAgentName = "vortex" | "cyclone" | "tempest";
@@ -24,6 +36,8 @@ export type StackAgentRun = {
     status: string;
     /** Full SHA when known. UI shortens to 7. */
     sha: string | null;
+    pass?: number | null;
+    skipReason?: string | null;
     startedAt?: string | null;
     finishedAt?: string | null;
     /**
@@ -38,6 +52,15 @@ export type StackAgentRun = {
      * Only on resting Vortex `findings` runs.
      */
     findingCount?: number | null;
+    /**
+     * File coverage at the posted head from `vortex_pr_review_state.file_states`
+     * (#1947): files reviewed at this head over all changed files. Only on
+     * resting Vortex `incomplete` runs, so the chip tooltip can say 21/32.
+     */
+    coverage?: {
+        reviewed: number;
+        total: number;
+    } | null;
 };
 export type StackLayerChecks = {
     total: number;
@@ -118,6 +141,7 @@ export type StackLayerDto = {
      */
     agentRuns?: StackAgentRun[];
     conflictDetail: string | null;
+    restackError?: RestackError | null;
     lastRestackedSha: string | null;
     /** GitHub PR mergeability from enrich; null when unknown. */
     mergeable: boolean | null;
@@ -207,6 +231,7 @@ export type StackUnitDto = {
      */
     landPr: StackLayerDto | null;
 };
+export type CycloneOwnerMatch = "same" | "different" | "none" | "lookup_failed";
 export type StackDto = {
     id: string;
     owner: string;
@@ -234,6 +259,26 @@ export type StackDto = {
      * account `auto_patch_enabled` flag; a boolean wins in both directions.
      */
     autoPatchOverride?: boolean | null;
+    /**
+     * Bearer / stack-row user. Cyclone apply follows this user's auto-patch
+     * policy and credits for an adopted stack (HOUSE-1), even when
+     * `cycloneInstallUserId` is a different Mergestorm account on a shared repo
+     * (LOOP-5).
+     */
+    keyUserId?: string;
+    /**
+     * Cyclone GitHub App install user for this owner/repo, when resolved. Its
+     * installation clones and pushes; it does not decide auto-patch for another
+     * user's stack.
+     */
+    cycloneInstallUserId?: string | null;
+    /**
+     * `same`: the only Cyclone install user is the key user.
+     * `different`: a Cyclone install user is not the key user (or more than one).
+     * `none`: no Cyclone install monitors this repo.
+     * `lookup_failed`: the comparison could not be loaded. Fail closed.
+     */
+    cycloneOwnerMatch?: CycloneOwnerMatch;
     layers: StackLayerDto[];
     /** Present when a review-unit row exists for this stack. */
     unit?: StackUnitDto;

package/dist/stack-dto.js

@@ -1,7 +1 @@
-/**
- * Wire types returned by the stack list/enrich HTTP endpoints.
- *
- * `api/src/stacks.ts#loadStackDtos` is the producer. Keep this file
- * dependency-free and byte-for-byte aligned with the canonical wire contract.
- */
 export {};

package/dist/ui/banner.js

@@ -84,6 +84,12 @@ const WHATS_NEW = {
     "0.3.16": [
         "PR loop: verify each finding, prefer a small diff, post mergestorm-loop: dismiss on skip",
     ],
+    "0.3.17": [
+        "nginx 413 names the upload limit instead of Failed: {}",
+    ],
+    "0.3.18": [
+        "pr --wait fences a stale same-head pass",
+    ],
 };
 function densityFromVariant(variant) {
     if (variant === "mini" || variant === "nano")

package/dist/ui/human-summary.d.ts

@@ -0,0 +1,2 @@
+/** Remove tool/LLM JSON that is unsafe to show in human summary output. */
+export declare function humanSummary(summary: string): string | null;

package/dist/ui/human-summary.js

@@ -0,0 +1,153 @@
+const TOOL_PAYLOAD_KEYS = new Set([
+    "function_call",
+    "tool",
+    "tool_call",
+    "tool_calls",
+]);
+function parseJsonContainer(value) {
+    const trimmed = value.trim();
+    if (!((trimmed.startsWith("{") && trimmed.endsWith("}")) ||
+        (trimmed.startsWith("[") && trimmed.endsWith("]")))) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+}
+function looksLikeToolPayload(value) {
+    if (Array.isArray(value))
+        return value.some(looksLikeToolPayload);
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    const keys = Object.keys(record);
+    if (keys.some((key) => TOOL_PAYLOAD_KEYS.has(key.toLowerCase())))
+        return true;
+    const lower = new Set(keys.map((key) => key.toLowerCase()));
+    if (record.type === "tool_use" && lower.has("name") && lower.has("input"))
+        return true;
+    if (lower.has("verdict") && lower.has("comments"))
+        return true;
+    return Object.values(record).some(looksLikeToolPayload);
+}
+function matchingJsonEnd(text, start) {
+    const open = text[start];
+    if (open !== "{" && open !== "[")
+        return null;
+    const stack = [open];
+    let quoted = false;
+    let escaped = false;
+    for (let i = start + 1; i < text.length; i += 1) {
+        const char = text[i];
+        if (quoted) {
+            if (escaped)
+                escaped = false;
+            else if (char === "\\")
+                escaped = true;
+            else if (char === '"')
+                quoted = false;
+            continue;
+        }
+        if (char === '"') {
+            quoted = true;
+            continue;
+        }
+        if (char === "{" || char === "[")
+            stack.push(char);
+        else if (char === "}" || char === "]") {
+            const expected = char === "}" ? "{" : "[";
+            if (stack.pop() !== expected)
+                return null;
+            if (stack.length === 0)
+                return i + 1;
+        }
+    }
+    return null;
+}
+function fencedLines(text) {
+    const lines = text.split("\n");
+    const protectedLines = new Set();
+    const openFences = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        if (/^\s*```[a-z0-9_-]+\s*$/i.test(lines[i])) {
+            openFences.push(i);
+        }
+        else if (/^\s*```\s*$/.test(lines[i])) {
+            if (openFences.length > 0) {
+                const start = openFences.pop();
+                for (let line = start; line <= i; line += 1)
+                    protectedLines.add(line);
+            }
+            else {
+                openFences.push(i);
+            }
+        }
+    }
+    return protectedLines;
+}
+function stripBoundaryPayload(text) {
+    let result = text;
+    let changed = true;
+    while (changed) {
+        changed = false;
+        const protectedLines = fencedLines(result);
+        for (let start = 0; start < result.length; start += 1) {
+            if (result[start] !== "{" && result[start] !== "[")
+                continue;
+            if (protectedLines.has(result.slice(0, start).split("\n").length - 1))
+                continue;
+            const end = matchingJsonEnd(result, start);
+            if (end == null)
+                continue;
+            const parsed = parseJsonContainer(result.slice(start, end));
+            if (parsed !== undefined &&
+                looksLikeToolPayload(parsed)) {
+                const before = result.slice(0, start);
+                const after = result.slice(end);
+                result = `${before}${before.endsWith("\n") && after.startsWith("\n") ? after.slice(1) : after}`;
+                changed = true;
+                break;
+            }
+        }
+    }
+    return result;
+}
+function stripOrphanLines(text) {
+    const lines = text.split("\n");
+    const keptLines = new Set();
+    const protectedLines = fencedLines(text);
+    for (const line of protectedLines)
+        keptLines.add(line);
+    for (let start = 0; start < text.length; start += 1) {
+        if (text[start] !== "{" && text[start] !== "[")
+            continue;
+        const end = matchingJsonEnd(text, start);
+        if (end == null || parseJsonContainer(text.slice(start, end)) === undefined)
+            continue;
+        const i = text.slice(0, start).split("\n").length - 1;
+        const lastLine = text.slice(0, end).split("\n").length - 1;
+        for (let line = i; line <= lastLine; line += 1) {
+            keptLines.add(line);
+            if (i !== lastLine)
+                protectedLines.add(line);
+        }
+    }
+    return lines
+        .filter((line, i) => protectedLines.has(i) ||
+        (parseJsonContainer(line) === undefined &&
+            (keptLines.has(i) || !/^\s*(?:```|[{}])\s*$/.test(line))))
+        .join("\n");
+}
+/** Remove tool/LLM JSON that is unsafe to show in human summary output. */
+export function humanSummary(summary) {
+    let result = summary.replace(/\r\n?/g, "\n");
+    result = result.replace(/```json[ \t]*\n([\s\S]*?)```/gi, (block, body) => parseJsonContainer(body) === undefined ? block : "");
+    result = stripBoundaryPayload(result);
+    result = stripOrphanLines(result)
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+    return result || null;
+}

package/dist/ui/usage.d.ts

@@ -22,8 +22,6 @@ export declare function nextUtcMonthStart(now?: Date): string;
 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. */
 export declare function usageBarWidth(columns: number): number;
 export type UsagePanelJob = {
@@ -38,6 +36,7 @@ export type UsagePanelInput = {
     plan: string;
     used: number;
     limit: number | null;
+    bonusRemaining?: number;
     resetsAt: string | null | undefined;
     jobs: UsagePanelJob[];
     /** When the jobs fetch failed, show this instead of "No review jobs yet." */

package/dist/ui/usage.js

@@ -83,10 +83,6 @@ export function formatDaysLeft(iso, now = new Date()) {
         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);
@@ -112,6 +108,9 @@ export function formatUsagePanel(input) {
         `  ${identity}`,
         `  ${bar}`,
         `  ${formatResetLabel(input.resetsAt)}`,
+        ...(input.bonusRemaining == null
+            ? []
+            : [`  Bonus credits: ${input.bonusRemaining} remaining`]),
         "",
     ];
     if (input.jobs.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mergestorm",
-  "version": "0.3.16",
+  "version": "0.3.18",
   "description": "Mergestorm CLI (mg) — local reviews & stacked PRs. MIT; build from source: https://github.com/marginsystems/mergestorm-cli",
   "license": "MIT",
   "type": "module",

package/skill/SKILL.md

@@ -62,11 +62,11 @@ Default: omit `router` (account setting).
 
 ## 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.
+Call `review_submit` with `wait: false` (the default) 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`.
+Optional: `thread`, `idempotency_key`, `wait`, `timeout_s`. Submit returns without waiting. Record `job_id` as soon as it returns, then loop `review_wait` with that `job_id` and `timeout_s: 45` until the job finishes. Each call is one 45s slice. On timeout, call `review_wait` again with the same `job_id`. Do not pass 300; hosts drop long MCP calls. Explicit `wait: true` also defaults to one 45s slice.
 
-Use `review_get` or `review_list` to resume a known job.
+Call `review_list` before any resubmit, including when a submit or wait call is interrupted. Resume the existing job with `review_get` or `review_wait`; do not create a second job because a slice died or the submit response was lost.
 
 Status handling:
 

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

@@ -19,29 +19,35 @@ mg skill install --claude --cursor
 
 1. There is an already-open GitHub PR on a Vortex-monitored repo. No PR, wrong skill.
 2. Auto-patch (Cyclone) must be off for this PR so you are the only patcher. Do not take anyone's word for it: the settings API and the PR's stack are the source of truth, and step 1 of the loop verifies them before anything else runs. Cyclone is off for the PR when its adopted stack has `autoPatchOverride` `false`, or when that override is unset and the account `auto_patch_enabled` is `false`.
-3. `whoami` works on the `mergestorm` MCP server (or `mg whoami --json` exits 0). Otherwise stop and ask for install/login.
+3. The Bearer key and the Cyclone GitHub App install must be the same Mergestorm account. `stack_list` / `stack_status` expose `keyUserId`, `cycloneInstallUserId`, and `cycloneOwnerMatch`. Cyclone apply always uses the install account, not the key. If those identities differ, your `settings_get` mute reading is about the wrong person.
+4. `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`.
+1. Find the PR's stack with `stack_list` (the stack whose `layers` contain this PR's `prNumber` for this owner/repo). If you already have its `stack_id`, `stack_status` is the same payload.
+   - If there is no stack and the human asked you to mute Cyclone or continue the loop: call `stack_adopt` with `{ owner, repo, pr_number, auto_patch: false }` (equivalent to `mg stack adopt … --auto-patch off`). Then call `stack_status` with the returned `result.stack.id`, confirm this PR is in the stack and `autoPatchOverride` is `false`. If adoption or verification fails, refuse the loop. Otherwise continue through the ownership check below and the remaining loop steps; do not stop and ask the human to adopt. Do not turn account auto-patch off.
+   - Adoption does not fix installer ≠ key. After adoption, the same `cycloneOwnerMatch` refusal below still applies.
+   - Read `cycloneOwnerMatch` on that stack. If it is missing, `lookup_failed`, or `different`: refuse the loop. Do not wait, patch, or push. Tell the human the API key and the Cyclone GitHub App install are different Mergestorm accounts (or the comparison could not be loaded). Cyclone still patches as the installer. Do not turn account auto-patch off, and do not set `auto_patch: false` to paper over this.
+   - If it is `same` or `none`: continue. `none` means no Cyclone install monitors this repo.
+2. 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`: find the PR's stack with `stack_list`. If its `autoPatchOverride` is `true`, refuse unless the human asked you to turn Cyclone off for this PR; if they did, use the adopted-stack and `stack_set { auto_patch: false }` path below. Otherwise continue. You are the only patcher.
-   - If it is `true`: find the PR's stack with `stack_list` (the stack whose `layers` contain this PR's `prNumber` for this owner/repo) and read its `autoPatchOverride`.
-     - If that stack's `autoPatchOverride` is `false`: continue. Cyclone is pinned off for this stack.
-     - If the PR has no stack, or the override is not `false`, and the human asked you to turn Cyclone off for this PR: the PR must be an adopted stack layer first (if it is not, stop and tell the human to adopt it, for example `mg stack adopt <owner/repo>#<n> --auto-patch off`). Then call `stack_set` with `{ stack_id, auto_patch: false }` on that stack, call `stack_status` with that `stack_id`, and confirm `autoPatchOverride` now reads `false`. Leave the account `auto_patch_enabled` unchanged; other PRs keep their own policy.
+   - If it is `false`: read `autoPatchOverride` on the stack from step 1. If it is `true`, refuse unless the human asked you to turn Cyclone off for this PR; if they did, use the `stack_set { auto_patch: false }` path below. Otherwise continue. You are the only patcher.
+   - If it is `true`: read `autoPatchOverride` on that same stack.
+     - If `autoPatchOverride` is `false`: continue. Cyclone is pinned off for this stack.
+     - If the override is not `false` and the human asked you to turn Cyclone off for this PR: call `stack_set` with `{ stack_id, auto_patch: false }` on that stack, call `stack_status` with that `stack_id`, and confirm `autoPatchOverride` now reads `false`. Leave the account `auto_patch_enabled` unchanged; other PRs keep their own policy.
      - Otherwise: refuse the loop. Do not wait, patch, or push; tell the human Cyclone auto-patch is still on for this PR and that `stack_set` with `auto_patch: false` on its stack turns it off for this PR only.
    - Never set `auto_patch_enabled` with `settings_set` from this skill, in either direction, and never set `auto_patch: true` on a stack.
-2. Call `review_wait_pr` with the PR's owner, repo, pr_number, and `timeout_s` 45 (`review_get_pr` works for a first look at the resting state). A Vortex pass often takes several minutes. If status is `in_progress`, call `review_wait_pr` again with the same args. Do not pass a 300s timeout; hosts drop long MCP calls.
-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. For each finding:
+3. Call `review_wait_pr` with the PR's owner, repo, pr_number, and `timeout_s` 45 (`review_get_pr` works for a first look at the resting state). A Vortex pass often takes several minutes. If status is `in_progress`, call `review_wait_pr` again with the same args. Do not pass a 300s timeout; hosts drop long MCP calls. Review identity is SHA + pass: every envelope carries `head_sha` and `pass` (1 for the first review on a head; a re-review on the same head is the next pass, its own row). Save the `pass` of every resting envelope you act on together with its `head_sha`.
+4. 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 8 with `after_sha` set to that head.
+5. Read `findings.inline` and `findings.offDiff` (or `off_diff`) sorted by severity. For each finding:
    - Verify it against the current checkout. Do not treat the finding text as proven.
    - Prefer the smallest correct patch. Do not refactor around a finding.
    - Patch concrete bugs. A chat-only explanation is not a dismiss.
-   - If you skip a finding (not reproducible, policy fork, or needs a human), post a public GitHub PR comment before you stop. First line: `mergestorm-loop: dismiss`. Then one line per skipped finding (path, severity, why). Do not use the `cyclone-outcome:` prefix.
-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) and `timeout_s` 45. 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.
+   - If you skip a finding (not reproducible, policy fork, or needs a human), post a public GitHub PR comment before you stop. First line: `mergestorm-loop: dismiss`. Then one line per skipped finding (path, severity, why). That first line is the only dismiss marker Vortex reads.
+6. Patch on the PR head branch only.
+7. 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.
+8. Call `review_wait_pr` again with `after_sha` set to the SHA you just pushed (7+ hex) and `timeout_s` 45. If the last envelope you acted on has that same `head_sha` (no new commit, for example a re-review requested on the same head), also pass `after_pass` set to that envelope's saved `pass`, so the wait cannot hand you that attempt again. For a freshly pushed SHA omit `after_pass`; its first pass is 1. Keep `after_sha` and `after_pass` unchanged across 45s timeout retries; never replace `after_pass` with the `pass` of an in-progress envelope. `review_get_pr` accepts the same `after_sha`, `pass`, and `after_pass` filters. An envelope whose `head_sha` is an older commit is a previous pass, not yours; keep waiting.
+9. Repeat from step 4 until a stop rule fires.
 
 ## Stop rules
 
@@ -50,15 +56,16 @@ 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 `in_progress` and the envelope has a `head_sha`: the pass is still running; call `review_wait_pr` again with the same `after_sha` and the same `after_pass`.
+- 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` and the same `after_pass`. 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
-- change the account `auto_patch_enabled` from this skill, for any reason; Cyclone is muted per stack with `stack_set`, never per account
+- land, merge, enqueue, or touch stack authoring beyond adopting the existing PR, or the merge queue
+- change the account `auto_patch_enabled` from this skill, for any reason; Cyclone is muted per stack with `stack_adopt` or `stack_set`, never per account
+- treat the key user's mute or `auto_patch_enabled` as covering a different Cyclone install user
 - set `auto_patch: true` on any stack
 - push any branch other than the PR head
 - force-push, or rebase and retry a push that was rejected because the remote moved
@@ -75,10 +82,10 @@ Verify auto-patch with the CLI instead of `settings_get`:
 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. Run `mg stack list --json` and find the stack whose layers contain this PR. If its `autoPatchOverride` is `false`, continue. If it is unset and the account flag is `false`, continue. If it is `true`, or it is unset while the account flag is `true`, refuse unless the human asked you to turn Cyclone off for this PR; only then run `mg stack set <stack-id> --auto-patch off` (adopt first with `mg stack adopt <owner/repo>#<n> --auto-patch off` when the PR has no stack) and re-read with `mg stack list --json`. Do not run `mg settings --auto-patch off`: that changes the account, not this PR.
+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. Run `mg stack list --json` and find the stack whose layers contain this PR. If there is no stack, or its `cycloneOwnerMatch` is missing, `lookup_failed`, or `different`, refuse the loop. Tell the human the API key and the Cyclone install are different accounts (or adopt first, or the lookup failed). Do not run `mg settings --auto-patch off`. If `cycloneOwnerMatch` is `same` or `none` and `autoPatchOverride` is `false`, continue. If it is unset and the account flag is `false`, continue. If it is `true`, or it is unset while the account flag is `true`, refuse unless the human asked you to turn Cyclone off for this PR; only then run `mg stack set <stack-id> --auto-patch off` and re-read with `mg stack list --json`.
 
 ```bash
-mg pr <owner/repo>#<n> --json --wait --after-sha <sha> --timeout <s>
+mg pr <owner/repo>#<n> --json --wait --after-sha <sha> --after-pass <saved-pass> --timeout <s>
 ```
 
-Parse stdout as one `mergestorm.pr_review/v1` object. Same fields, same stop rules.
+Parse stdout as one `mergestorm.pr_review/v1` object. Same fields, same stop rules. `--after-pass` follows the same rule as `after_pass` above: only when the last envelope you acted on is on that same `head_sha`; omit it for a freshly pushed SHA. `--pass <n>` reads one exact attempt on the head.