mergestorm 0.3.19 → 0.3.21

package/README.md

@@ -45,12 +45,12 @@ On a TTY, bare `mergestorm` (or `mergestorm shell`) opens a branded REPL: a comp
 
 ```
 ╭──────────────────────────────────────────────────────────────────────────────╮
-│ ▟██▛  mergestorm v0.3.19                                                     │
+│ ▟██▛  mergestorm v0.3.21                                                     │
 │  ▜▙   ● 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.19: stack wait and held GET waits                          │
+│       New in v0.3.21: stack wait holds an unchanged queue instead of spinning│
 ╰──────────────────────────────────────────────────────────────────────────────╯
 mergestorm
 ╭──────────────────────────────────────────────────────────────────────────────╮
@@ -94,7 +94,7 @@ mergestorm stack list [--json]  List registered stacks
 mergestorm stack adopt <owner/repo>#<pr>  Import an existing open PR chain
 mergestorm stack restack <stack-id>  Restack descendants
 mergestorm stack land <stack-id>     Land / promote (into review unit when present)
-mergestorm stack wait <stack-id>     Wait for stack attention (default 45s, max 300s)
+mergestorm stack wait <stack-id> [--timeout <s>]  Wait for stack attention (default 45s, max 300s; 0 = one snapshot, no wait)
 mergestorm stack reset --force  Clear local authoring state (not branches/PRs)
 ```
 

package/dist/client/index.d.ts

@@ -7,3 +7,4 @@ export { REVIEW_JOB_ENVELOPE_SCHEMA, toReviewJobEnvelope, type ReviewEnvelopeFal
 export { discoverTrunk } from "../git-stack.js";
 export { BOUNCE_KIND_LABELS, mergeQueueBounceLabel } from "../stack-dto.js";
 export { STACK_WATCH_SCHEMA, STACK_WATCH_DEFAULT_TIMEOUT_MS, StackWatchError, StackWatchTimeoutError, pollStackWatch, type PollStackWatchOptions, type StackWatchCursor, type StackWatchEnvelope, } from "../stack-watch.js";
+export { stackBlockers, stackBlockersSummary, sameHead, type StackBlocker } from "../stack-blockers.js";

package/dist/client/index.js

@@ -7,3 +7,4 @@ export { REVIEW_JOB_ENVELOPE_SCHEMA, toReviewJobEnvelope, } from "../ui/job-enve
 export { discoverTrunk } from "../git-stack.js";
 export { BOUNCE_KIND_LABELS, mergeQueueBounceLabel } from "../stack-dto.js";
 export { STACK_WATCH_SCHEMA, STACK_WATCH_DEFAULT_TIMEOUT_MS, StackWatchError, StackWatchTimeoutError, pollStackWatch, } from "../stack-watch.js";
+export { stackBlockers, stackBlockersSummary, sameHead } from "../stack-blockers.js";

package/dist/commands/registry.js

@@ -223,7 +223,7 @@ export const COMMAND_REGISTRY = [
             "mergestorm stack reset --force  Clear this repo's pre-submit authoring state",
             "mergestorm stack list [--json]  List registered stacks",
             "mergestorm stack status <stack-id> [--json]  Enriched stack status",
-            "mergestorm stack wait <stack-id> [--json] [--timeout <s>]  Wait for stack attention (default 45s, max 300s)",
+            "mergestorm stack wait <stack-id> [--json] [--timeout <s>]  Wait for stack attention (default 45s, max 300s; 0 = one snapshot, no wait)",
             "mergestorm stack set <stack-id> [--auto-land on|off] [--auto-review on|off|default] [--auto-patch on|off|default] [--json]  Per-stack policy",
             "mergestorm stack adopt <owner/repo>#<pr> [--auto-land on|off] [--auto-review on|off] [--auto-patch on|off]  Import an open PR chain",
             "mergestorm stack restack <stack-id>   Restack stack descendants",

package/dist/commands/stack.d.ts

@@ -1,6 +1,6 @@
 import { adoptStack, ensureUpperPark, getEnrichedStack, listStacks, setStackPolicy, type StackDto, type StackPolicyPatch } from "../api.js";
 import { loadConfig } from "../config.js";
-import { createPr, findOpenPrNumber } from "../gh.js";
+import { createPrs, findOpenPrNumber } from "../gh.js";
 import { parseGithubOriginRepo } from "../git.js";
 import { branchExists, commitsAheadOf, createBranchFromHead, currentBranch, defaultLayerBranchName, deleteBranch, discoverTrunk, fetchRemoteBranch, pushBranch, tipCommitMessage, tipCommitSubject, worktreeDirty } from "../git-stack.js";
 import { buildPrBodyFromCommit } from "../pr-body.js";
@@ -59,6 +59,7 @@ export declare function parseStackSubmitArgs(args: string[]): {
     autoLand?: boolean;
     autoReview?: boolean;
     autoPatch?: boolean;
+    rest: boolean;
     asJson: boolean;
 };
 export declare function parseStackAdoptArgs(args: string[]): {
@@ -114,11 +115,12 @@ export type StackSubmitDeps = {
     tipCommitSubject?: typeof tipCommitSubject;
     tipCommitMessage?: typeof tipCommitMessage;
     buildPrBodyFromCommit?: typeof buildPrBodyFromCommit;
-    createPr?: typeof createPr;
+    createPrs?: typeof createPrs;
     loadConfig?: typeof loadConfig;
     listStacks?: typeof listStacks;
     adoptStack?: typeof adoptStack;
     ensureUpperPark?: typeof ensureUpperPark;
+    env?: NodeJS.ProcessEnv;
 };
 export declare function cmdStackSubmit(args: string[], deps?: StackSubmitDeps): Promise<void>;
 export declare function cmdStackWait(args: string[], deps?: {

package/dist/commands/stack.js

@@ -1,7 +1,8 @@
+import { stackBlockersSummary } from "../stack-blockers.js";
 import { adoptStack, ensureUpperPark, getEnrichedStack, landNextStack, listStacks, restackStack, setStackPolicy, } from "../api.js";
 import { loadConfig } from "../config.js";
 import { rateLimitedMessage, REVIEW_EXIT, CommandError } from "../errors.js";
-import { createPr, findOpenPrNumber, requireGh } from "../gh.js";
+import { createPrs, findOpenPrNumber, githubApiFromEnv, requireGh, } from "../gh.js";
 import { parseGithubOriginRepo } from "../git.js";
 import { branchExists, commitsAheadOf, createBranchFromHead, currentBranch, defaultLayerBranchName, deleteBranch, discoverTrunk, fetchRemoteBranch, pushBranch, tipCommitMessage, tipCommitSubject, worktreeDirty, } from "../git-stack.js";
 import { buildPrBodyFromCommit } from "../pr-body.js";
@@ -16,7 +17,7 @@ import { canBrowse } from "./browse.js";
 import { openHelpBrowser } from "./help.js";
 const STACK_USAGE = `usage:
   mergestorm stack create [name] [--onto <branch>] [--trunk <branch>] [--extend] [--auto-land on|off] [--auto-review on|off] [--auto-patch on|off] [--json]
-  mergestorm stack submit [--extend] [--auto-land on|off] [--auto-review on|off] [--auto-patch on|off] [--json]
+  mergestorm stack submit [--extend] [--auto-land on|off] [--auto-review on|off] [--auto-patch on|off] [--rest] [--json]
   mergestorm stack reset --force
   mergestorm stack list [--json]
   mergestorm stack status <stack-id> [--json]
@@ -32,6 +33,8 @@ const STACK_USAGE = `usage:
   stack submit opens PRs with a body generated from each layer tip commit.
   Layers 1–2 use the git parent as GitHub base. Layer 3+ opens onto the
   review-unit park freeze (mg-park-*) so adopt does not retarget after open.
+  stack submit talks to GitHub GraphQL and falls back to the REST API when
+  GraphQL is blocked; --rest (or MERGESTORM_GITHUB_API=rest) forces REST.
   Parenting onto a branch that already belongs to a registered (submitted)
   stack requires --extend on create and submit — otherwise mg starts a new
   stack from trunk. stack land promotes into the review unit when one exists;
@@ -267,6 +270,7 @@ export function parseStackCreateArgs(args) {
 /** Parse `stack submit` argv. Exported for tests. */
 export function parseStackSubmitArgs(args) {
     let extend = false;
+    let rest = false;
     const policy = {};
     let asJson = false;
     for (let i = 0; i < args.length; i++) {
@@ -279,18 +283,23 @@ export function parseStackSubmitArgs(args) {
             extend = true;
             continue;
         }
+        if (a === "--rest") {
+            rest = true;
+            continue;
+        }
         const next = takeOpenPolicyFlag(args, i, policy, "stack submit");
         if (next !== null) {
             i = next - 1;
             continue;
         }
-        throw new CommandError("usage: mergestorm stack submit [--extend] [--auto-land on|off] [--auto-review on|off] [--auto-patch on|off] [--json]");
+        throw new CommandError("usage: mergestorm stack submit [--extend] [--auto-land on|off] [--auto-review on|off] [--auto-patch on|off] [--rest] [--json]");
     }
     return {
         extend,
         autoLand: policy.autoLand,
         autoReview: policy.autoReview,
         autoPatch: policy.autoPatch,
+        rest,
         asJson,
     };
 }
@@ -523,7 +532,8 @@ export async function cmdStackCreate(args, deps = {}) {
     await present("Stack", created);
 }
 export async function cmdStackSubmit(args, deps = {}) {
-    const { extend, autoLand, autoReview, autoPatch, asJson } = parseStackSubmitArgs(args);
+    const { extend, autoLand, autoReview, autoPatch, rest, asJson } = parseStackSubmitArgs(args);
+    const api = rest ? "rest" : githubApiFromEnv(deps.env ?? process.env);
     const progress = (message) => {
         if (asJson)
             console.error(message);
@@ -544,7 +554,7 @@ export async function cmdStackSubmit(args, deps = {}) {
     const tipCommitSubjectFn = deps.tipCommitSubject ?? tipCommitSubject;
     const tipCommitMessageFn = deps.tipCommitMessage ?? tipCommitMessage;
     const buildPrBodyFn = deps.buildPrBodyFromCommit ?? buildPrBodyFromCommit;
-    const createPrFn = deps.createPr ?? createPr;
+    const createPrsFn = deps.createPrs ?? createPrs;
     const loadConfigFn = deps.loadConfig ?? loadConfig;
     const listStacksFn = deps.listStacks ?? listStacks;
     const adoptStackFn = deps.adoptStack ?? adoptStack;
@@ -629,16 +639,11 @@ export async function cmdStackSubmit(args, deps = {}) {
     }
     const opened = [];
     const pendingPark = plans.filter((plan) => {
-        if (findOpenPrNumberFn(owner, repo, plan.branch, cwd) != null)
+        if (findOpenPrNumberFn(owner, repo, plan.branch, cwd, { api }) != null)
             return false;
         return plan.githubBase == null;
     });
-    const openLayerPr = (branch, base) => {
-        const existing = findOpenPrNumberFn(owner, repo, branch, cwd);
-        if (existing != null) {
-            progress(ansi.dim(`  PR #${existing} already open for ${branch}`));
-            return { prNumber: existing, created: false };
-        }
+    const prepareLayerPr = (branch, base) => {
         const aheadRef = isMgParkBranch(base) ? `origin/${base}` : base;
         if (isMgParkBranch(base)) {
             try {
@@ -662,30 +667,44 @@ export async function cmdStackSubmit(args, deps = {}) {
             throw new CommandError(`No commits on \`${branch}\` ahead of \`${base}\`. ` +
                 `Commit your changes, then retry \`mg stack submit\`.`);
         }
-        const title = tipCommitSubjectFn(branch, cwd);
-        const body = buildPrBodyFn(tipCommitMessageFn(branch, cwd));
-        progress(ansi.dim(`  Opening PR ${branch} → ${base} …`));
         return {
-            prNumber: createPrFn({
-                owner,
-                repo,
-                base,
-                head: branch,
-                title,
-                body,
-                cwd,
-            }),
-            created: true,
+            base,
+            head: branch,
+            title: tipCommitSubjectFn(branch, cwd),
+            body: buildPrBodyFn(tipCommitMessageFn(branch, cwd)),
         };
     };
-    for (const plan of plans) {
-        if (plan.githubBase == null && findOpenPrNumberFn(owner, repo, plan.branch, cwd) == null) {
-            continue;
+    const openLayerWave = (wave) => {
+        const rows = [];
+        const pending = [];
+        for (const { branch, base } of wave) {
+            const existing = findOpenPrNumberFn(owner, repo, branch, cwd, { api });
+            if (existing != null) {
+                progress(ansi.dim(`  PR #${existing} already open for ${branch}`));
+                rows.push({ branch, base, prNumber: existing, created: false });
+                continue;
+            }
+            pending.push({ index: rows.length, pr: prepareLayerPr(branch, base) });
+            rows.push({ branch, base, prNumber: 0, created: true });
         }
-        const base = plan.githubBase ?? plan.gitParent;
-        const { prNumber, created } = openLayerPr(plan.branch, base);
-        opened.push({ branch: plan.branch, base, prNumber, created });
-    }
+        if (pending.length === 0)
+            return rows;
+        for (const { pr } of pending) {
+            progress(ansi.dim(`  Opening PR ${pr.head} → ${pr.base} …`));
+        }
+        const numbers = createPrsFn({ owner, repo, prs: pending.map((p) => p.pr), cwd, api });
+        if (numbers.length !== pending.length) {
+            throw new CommandError(`GitHub returned ${numbers.length} PR numbers for ${pending.length} new pull requests.`);
+        }
+        pending.forEach(({ index }, i) => {
+            rows[index].prNumber = numbers[i];
+        });
+        return rows;
+    };
+    opened.push(...openLayerWave(plans
+        .filter((plan) => plan.githubBase != null ||
+        findOpenPrNumberFn(owner, repo, plan.branch, cwd, { api }) != null)
+        .map((plan) => ({ branch: plan.branch, base: plan.githubBase ?? plan.gitParent }))));
     const cfg = await loadConfigFn();
     let adoptData = null;
     let stackId = plans.find((plan) => plan.stackId)?.stackId ?? null;
@@ -716,10 +735,7 @@ export async function cmdStackSubmit(args, deps = {}) {
         }
         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);
-            opened.push({ branch: plan.branch, base: park.freezeBranch, prNumber, created });
-        }
+        opened.push(...openLayerWave(pendingPark.map((plan) => ({ branch: plan.branch, base: park.freezeBranch }))));
         await registerPr(opened[opened.length - 1].prNumber);
     }
     else {
@@ -823,7 +839,7 @@ export async function cmdStackWait(args, deps = {}) {
             ...envelope,
             ...(retryAfterSeconds !== undefined ? { retry_after_seconds: retryAfterSeconds } : {}),
         }, null, 2)
-        : `Stack ${envelope.stackId} · ${envelope.status}${envelope.blocker ? ` · ${envelope.blocker}` : ""}`);
+        : `Stack ${envelope.stackId} · ${envelope.status}${stackBlockersSummary(envelope.blocker && envelope.prNumber != null ? { prNumber: envelope.prNumber, blocker: envelope.blocker } : null, envelope.issues)}${envelope.assessment === "unavailable" ? " · assessment unavailable" : ""}`);
     try {
         print(await (deps.pollStackWatch ?? pollStackWatch)(cfg, stackId, {
             timeoutMs: timeoutS * 1000,
@@ -835,6 +851,10 @@ export async function cmdStackWait(args, deps = {}) {
             print(err.lastEnvelope, err.retryAfterSeconds);
             throw new CommandError(rateLimitedMessage(err.retryAfterSeconds), REVIEW_EXIT.rate_limited, "rate_limited", { retryAfterSeconds: err.retryAfterSeconds });
         }
+        if (err instanceof StackWatchError) {
+            print(err.lastEnvelope);
+            throw err;
+        }
         if (!(err instanceof StackWatchTimeoutError))
             throw err;
         print(err.lastEnvelope);

package/dist/gh.d.ts

@@ -1,20 +1,82 @@
-export declare function runGh(args: string[], cwd?: string): {
+import { CommandError } from "./errors.js";
+export type GhResult = {
     ok: true;
     stdout: string;
 } | {
     ok: false;
     stderr: string;
     status: number | null;
+    stdout?: string;
 };
+export type GhRunner = (args: string[], input?: string) => GhResult;
+export type GithubApi = "graphql" | "rest";
+export declare const GITHUB_API_ENV = "MERGESTORM_GITHUB_API";
+export declare function githubApiFromEnv(env?: NodeJS.ProcessEnv): GithubApi;
+export declare function isGraphqlEndpointBlocked(text: string): boolean;
+export declare class GraphqlBlockedError extends CommandError {
+    readonly opened: readonly number[];
+    constructor(message: string, opened?: readonly number[]);
+}
+type GhSpawn = (command: string, args: string[], options: {
+    cwd: string;
+    encoding: "utf8";
+    input?: string;
+}) => {
+    error?: Error;
+    stdout?: string | null;
+    stderr?: string | null;
+    status: number | null;
+};
+export declare function runGh(args: string[], cwd?: string, input?: string, spawn?: GhSpawn): GhResult;
 export declare function requireGh(cwd?: string): void;
 /** Open PR number for `head` branch in owner/repo, or null. */
-export declare function findOpenPrNumber(owner: string, repo: string, headBranch: string, cwd?: string): number | null;
-export declare function createPr(input: {
-    owner: string;
-    repo: string;
+export declare function findOpenPrNumber(owner: string, repo: string, headBranch: string, cwd?: string, options?: {
+    api?: GithubApi;
+    gh?: GhRunner;
+}): number | null;
+export declare function findOpenPrNumberViaRest(owner: string, repo: string, headBranch: string, gh: GhRunner): number | null;
+export type NewPr = {
     base: string;
     head: string;
     title: string;
-    body?: string;
+    body: string;
+};
+export type GraphqlRequest = {
+    query: string;
+    variables: Record<string, unknown>;
+};
+export type GraphqlResponse = {
+    data?: Record<string, unknown> | null;
+    errors?: {
+        message?: string;
+    }[];
+};
+export type GraphqlRunner = (request: GraphqlRequest) => GraphqlResponse;
+type GraphqlSpawnResult = {
+    error?: Error;
+    stdout?: string | null;
+    stderr?: string | null;
+    status: number | null;
+};
+type GraphqlSpawn = (command: string, args: string[], options: {
+    cwd: string;
+    encoding: "utf8";
+    input: string;
+}) => GraphqlSpawnResult;
+export declare const CREATE_PR_BATCH_SIZE = 5;
+export declare function ghGraphql(request: GraphqlRequest, cwd?: string, spawn?: GraphqlSpawn): GraphqlResponse;
+export declare function chunkCreatePrs<T>(items: readonly T[], size?: number): T[][];
+export declare function buildCreatePrsMutation(repositoryId: string, prs: readonly NewPr[]): GraphqlRequest;
+export declare function fetchRepositoryId(owner: string, repo: string, graphql: GraphqlRunner): string;
+export declare function createPrsOnRepository(repositoryId: string, prs: readonly NewPr[], graphql: GraphqlRunner): number[];
+export declare function createPrsViaRest(owner: string, repo: string, prs: readonly NewPr[], gh: GhRunner, opened?: readonly number[]): number[];
+export declare function createPrs(input: {
+    owner: string;
+    repo: string;
+    prs: readonly NewPr[];
     cwd?: string;
-}): number;
+    api?: GithubApi;
+    graphql?: GraphqlRunner;
+    gh?: GhRunner;
+}): number[];
+export {};

package/dist/gh.js

@@ -1,7 +1,28 @@
 import { spawnSync } from "node:child_process";
 import { CommandError } from "./errors.js";
-export function runGh(args, cwd = process.cwd()) {
-    const result = spawnSync("gh", args, { cwd, encoding: "utf8" });
+export const GITHUB_API_ENV = "MERGESTORM_GITHUB_API";
+export function githubApiFromEnv(env = process.env) {
+    return env[GITHUB_API_ENV]?.trim().toLowerCase() === "rest" ? "rest" : "graphql";
+}
+const GRAPHQL_UNAVAILABLE = /graphql\b[^\n]*\b(?:not available|unavailable|blocked|disabled)\b/i;
+const GRAPHQL_CONTEXT = /\bgraphql\b/i;
+export function isGraphqlEndpointBlocked(text) {
+    return GRAPHQL_UNAVAILABLE.test(text) || (/\bHTTP 403\b/.test(text) && GRAPHQL_CONTEXT.test(text));
+}
+export class GraphqlBlockedError extends CommandError {
+    opened;
+    constructor(message, opened = []) {
+        super(message);
+        this.name = "GraphqlBlockedError";
+        this.opened = opened;
+    }
+}
+export function runGh(args, cwd = process.cwd(), input, spawn = spawnSync) {
+    const result = spawn("gh", args, {
+        cwd,
+        encoding: "utf8",
+        ...(input !== undefined ? { input } : {}),
+    });
     if (result.error) {
         const msg = result.error.message || String(result.error);
         if (result.error.code === "ENOENT") {
@@ -14,6 +35,7 @@ export function runGh(args, cwd = process.cwd()) {
             ok: false,
             stderr: (result.stderr || result.stdout || `gh ${args.join(" ")} failed`).trim(),
             status: result.status,
+            stdout: result.stdout ?? "",
         };
     }
     return { ok: true, stdout: result.stdout ?? "" };
@@ -29,8 +51,23 @@ export function requireGh(cwd = process.cwd()) {
     }
 }
 /** Open PR number for `head` branch in owner/repo, or null. */
-export function findOpenPrNumber(owner, repo, headBranch, cwd = process.cwd()) {
-    const res = runGh([
+export function findOpenPrNumber(owner, repo, headBranch, cwd = process.cwd(), options = {}) {
+    const gh = options.gh ?? ((args, input) => runGh(args, cwd, input));
+    if ((options.api ?? githubApiFromEnv()) === "rest") {
+        return findOpenPrNumberViaRest(owner, repo, headBranch, gh);
+    }
+    try {
+        return findOpenPrNumberViaGraphql(owner, repo, headBranch, gh);
+    }
+    catch (err) {
+        if (err instanceof GraphqlBlockedError) {
+            return findOpenPrNumberViaRest(owner, repo, headBranch, gh);
+        }
+        throw err;
+    }
+}
+function findOpenPrNumberViaGraphql(owner, repo, headBranch, gh) {
+    const res = gh([
         "pr",
         "list",
         "--repo",
@@ -43,12 +80,37 @@ export function findOpenPrNumber(owner, repo, headBranch, cwd = process.cwd()) {
         "number",
         "--limit",
         "1",
-    ], cwd);
+    ]);
+    if (!res.ok) {
+        const message = `Failed to list PRs for ${headBranch}: ${res.stderr}`;
+        if (isGraphqlEndpointBlocked(`${res.stderr}\n${res.stdout ?? ""}`)) {
+            throw new GraphqlBlockedError(message);
+        }
+        throw new CommandError(message);
+    }
+    return firstPrNumber(res.stdout);
+}
+export function findOpenPrNumberViaRest(owner, repo, headBranch, gh) {
+    const res = gh([
+        "api",
+        "-X",
+        "GET",
+        `repos/${owner}/${repo}/pulls`,
+        "-f",
+        `head=${owner}:${headBranch}`,
+        "-f",
+        "state=open",
+        "-f",
+        "per_page=1",
+    ]);
     if (!res.ok) {
         throw new CommandError(`Failed to list PRs for ${headBranch}: ${res.stderr}`);
     }
+    return firstPrNumber(res.stdout);
+}
+function firstPrNumber(stdout) {
     try {
-        const rows = JSON.parse(res.stdout);
+        const rows = JSON.parse(stdout);
         const n = rows[0]?.number;
         return typeof n === "number" && n > 0 ? n : null;
     }
@@ -56,34 +118,173 @@ export function findOpenPrNumber(owner, repo, headBranch, cwd = process.cwd()) {
         throw new CommandError(`Failed to parse PR list response: ${e instanceof Error ? e.message : String(e)}`);
     }
 }
-export function createPr(input) {
+export const CREATE_PR_BATCH_SIZE = 5;
+export function ghGraphql(request, cwd = process.cwd(), spawn = spawnSync) {
+    const result = spawn("gh", ["api", "graphql", "--input", "-"], {
+        cwd,
+        encoding: "utf8",
+        input: JSON.stringify(request),
+    });
+    if (result.error) {
+        throw new CommandError(`gh api graphql failed: ${result.error.message || String(result.error)}`);
+    }
+    const stdout = (result.stdout ?? "").trim();
+    if (result.status !== 0 && isGraphqlEndpointBlocked(result.stderr ?? "")) {
+        return failGraphql(result.stderr ?? null, stdout, result.status, true);
+    }
+    try {
+        const parsed = JSON.parse(stdout);
+        if (parsed && typeof parsed === "object" && ("data" in parsed || "errors" in parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        return failGraphql(result.stderr ?? null, stdout, result.status, isGraphqlEndpointBlocked(stdout));
+    }
+    return failGraphql(result.stderr ?? null, stdout, result.status, isGraphqlEndpointBlocked(stdout));
+}
+function failGraphql(stderr, stdout, status, blocked) {
+    const message = `gh api graphql failed: ${(stderr || stdout || `exit ${status}`).trim()}`;
+    throw blocked ? new GraphqlBlockedError(message) : new CommandError(message);
+}
+export function chunkCreatePrs(items, size = CREATE_PR_BATCH_SIZE) {
+    const chunks = [];
+    for (let i = 0; i < items.length; i += size) {
+        chunks.push(items.slice(i, i + size));
+    }
+    return chunks;
+}
+export function buildCreatePrsMutation(repositoryId, prs) {
+    const params = prs.map((_, i) => `$in${i}: CreatePullRequestInput!`).join(", ");
+    const fields = prs
+        .map((_, i) => `  pr${i}: createPullRequest(input: $in${i}) { pullRequest { number } }`)
+        .join("\n");
+    const variables = {};
+    prs.forEach((pr, i) => {
+        variables[`in${i}`] = {
+            repositoryId,
+            baseRefName: pr.base,
+            headRefName: pr.head,
+            title: pr.title,
+            body: pr.body,
+        };
+    });
+    return { query: `mutation MgStackSubmit(${params}) {\n${fields}\n}`, variables };
+}
+function graphqlErrorText(errors) {
+    const messages = errors.map((e) => e.message?.trim()).filter((m) => !!m);
+    return messages.length > 0 ? messages.join("; ") : "unknown GraphQL error";
+}
+export function fetchRepositoryId(owner, repo, graphql) {
+    const res = graphql({
+        query: "query MgRepositoryId($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { id } }",
+        variables: { owner, name: repo },
+    });
+    const repository = res.data?.repository;
+    if (res.errors?.length || typeof repository?.id !== "string" || !repository.id) {
+        throw new CommandError(`Could not look up GitHub repository ${owner}/${repo}: ${graphqlErrorText(res.errors ?? [])}`);
+    }
+    return repository.id;
+}
+export function createPrsOnRepository(repositoryId, prs, graphql) {
+    const numbers = [];
+    const openedSoFar = () => numbers.map((n, i) => `#${n} (${prs[i].head})`);
+    for (const chunk of chunkCreatePrs(prs)) {
+        let res;
+        try {
+            res = graphql(buildCreatePrsMutation(repositoryId, chunk));
+        }
+        catch (err) {
+            if (err instanceof GraphqlBlockedError)
+                throw new GraphqlBlockedError(err.message, [...numbers]);
+            throw err;
+        }
+        const chunkNumbers = chunk.map((_, i) => {
+            const row = res.data?.[`pr${i}`];
+            const n = row?.pullRequest?.number;
+            return typeof n === "number" && n > 0 ? n : null;
+        });
+        const failed = (res.errors?.length ?? 0) > 0 || chunkNumbers.some((n) => n == null);
+        if (failed) {
+            const partial = chunk
+                .map((pr, i) => (chunkNumbers[i] != null ? `#${chunkNumbers[i]} (${pr.head})` : null))
+                .filter((s) => s != null);
+            const opened = [...openedSoFar(), ...partial];
+            const heads = chunk.map((pr) => `${pr.head} → ${pr.base}`).join(", ");
+            throw new CommandError(`Failed to open PRs ${heads}: ${graphqlErrorText(res.errors ?? [])}` +
+                (opened.length > 0
+                    ? `\nGitHub did open ${opened.join(", ")}; retry \`mg stack submit\` to reuse them.`
+                    : ""));
+        }
+        numbers.push(...chunkNumbers);
+    }
+    return numbers;
+}
+const repositoryIds = new Map();
+function restErrorText(res) {
+    let body;
+    try {
+        body = JSON.parse(res.stdout ?? "");
+    }
+    catch {
+        return res.stderr;
+    }
+    const details = (Array.isArray(body?.errors) ? body.errors : [])
+        .map((e) => (typeof e?.message === "string" ? e.message.trim() : ""))
+        .filter((m) => m.length > 0);
+    if (details.length > 0)
+        return details.join("; ");
+    if (typeof body?.message === "string" && body.message.trim())
+        return body.message.trim();
+    return res.stderr;
+}
+export function createPrsViaRest(owner, repo, prs, gh, opened = []) {
+    const numbers = [...opened];
+    for (const pr of prs.slice(numbers.length)) {
+        const res = gh(["api", "-X", "POST", `repos/${owner}/${repo}/pulls`, "--input", "-"], JSON.stringify({ title: pr.title, head: pr.head, base: pr.base, body: pr.body }));
+        let n = null;
+        if (res.ok) {
+            try {
+                n = JSON.parse(res.stdout).number;
+            }
+            catch {
+                n = null;
+            }
+        }
+        if (typeof n !== "number" || n <= 0) {
+            const reason = res.ok ? "GitHub returned no pull request number" : restErrorText(res);
+            const openedSoFar = numbers.map((num, i) => `#${num} (${prs[i].head})`);
+            throw new CommandError(`Failed to open PRs ${pr.head} → ${pr.base}: ${reason}` +
+                (openedSoFar.length > 0
+                    ? `\nGitHub did open ${openedSoFar.join(", ")}; retry \`mg stack submit\` to reuse them.`
+                    : ""));
+        }
+        numbers.push(n);
+    }
+    return numbers;
+}
+export function createPrs(input) {
+    if (input.prs.length === 0)
+        return [];
     const cwd = input.cwd ?? process.cwd();
-    const args = [
-        "pr",
-        "create",
-        "--repo",
-        `${input.owner}/${input.repo}`,
-        "--base",
-        input.base,
-        "--head",
-        input.head,
-        "--title",
-        input.title,
-        "--body",
-        input.body ?? "",
-    ];
-    const res = runGh(args, cwd);
-    if (!res.ok) {
-        throw new CommandError(`Failed to open PR ${input.head} → ${input.base}: ${res.stderr}`);
-    }
-    // stdout is typically the PR URL
-    const url = res.stdout.trim();
-    const m = /\/pull\/(\d+)/.exec(url);
-    if (m?.[1])
-        return Number(m[1]);
-    // Fallback: re-list
-    const n = findOpenPrNumber(input.owner, input.repo, input.head, cwd);
-    if (n != null)
-        return n;
-    throw new CommandError(`Opened PR at ${url || "(unknown URL)"} but could not determine PR number. Check your repository's pull requests.`);
+    const gh = input.gh ?? ((args, stdin) => runGh(args, cwd, stdin));
+    if ((input.api ?? githubApiFromEnv()) === "rest") {
+        return createPrsViaRest(input.owner, input.repo, input.prs, gh);
+    }
+    const graphql = input.graphql ?? ((request) => ghGraphql(request, cwd));
+    try {
+        const key = `${input.owner}/${input.repo}`.toLowerCase();
+        let repositoryId = repositoryIds.get(key);
+        if (!repositoryId) {
+            repositoryId = fetchRepositoryId(input.owner, input.repo, graphql);
+            repositoryIds.set(key, repositoryId);
+        }
+        return createPrsOnRepository(repositoryId, input.prs, graphql);
+    }
+    catch (err) {
+        if (err instanceof GraphqlBlockedError) {
+            return createPrsViaRest(input.owner, input.repo, input.prs, gh, err.opened);
+        }
+        throw err;
+    }
 }

package/dist/stack-blockers.d.ts

@@ -0,0 +1,25 @@
+import { type MergeQueueEntryDto, type StackDto, type StackLayerDto } from "./stack-dto.js";
+import type { StackWatchCursor } from "./stack-watch.js";
+export type StackBlocker = {
+    prNumber: number;
+    headSha: string | null;
+    blocker: string;
+    bounceKind: string | null;
+};
+export declare function isMgParkBase(branch: string | null | undefined): boolean;
+/** GitHub DIRTY vs an mg-park-* freeze is not a merge conflict, verified or not. */
+export declare function boundDirty(layer: StackLayerDto): boolean;
+export declare function sameHead(a: string | null | undefined, b: string | null | undefined): boolean;
+export declare function currentLayer(stack: StackDto): StackLayerDto | undefined;
+/** Pair-gate attention plus live hard blocks on every other open layer. */
+export declare function stackBlockers(stack: StackDto, entries?: MergeQueueEntryDto[], cursor?: Pick<StackWatchCursor, "bounceId" | "afterFinishedAt">): {
+    attention: StackBlocker | null;
+    issues: StackBlocker[];
+    currentCandidate: {
+        prNumber: number;
+        headSha: string | null;
+    } | null;
+    bounce: MergeQueueEntryDto | undefined;
+};
+/** Compact contract text shared by status and wait summaries. */
+export declare function stackBlockersSummary(attention: Pick<StackBlocker, "prNumber" | "blocker"> | null, issues: StackBlocker[]): string;

package/dist/stack-blockers.js

@@ -0,0 +1,120 @@
+import { mergeQueueBounceLabel, restackRetryPending } from "./stack-dto.js";
+export function isMgParkBase(branch) {
+    return (branch ?? "").trim().toLowerCase().startsWith("mg-park-");
+}
+/** GitHub DIRTY vs an mg-park-* freeze is not a merge conflict, verified or not. */
+export function boundDirty(layer) {
+    if (isMgParkBase(layer.parentBranch))
+        return false;
+    if (layer.mergeable == null)
+        return false;
+    return (!layer.headSha || layer.mergeableHeadSha === layer.headSha) &&
+        (layer.mergeable === false || layer.mergeableState?.toLowerCase() === "dirty");
+}
+export function sameHead(a, b) {
+    const left = a?.trim().toLowerCase();
+    const right = b?.trim().toLowerCase();
+    return !!left && !!right && (left.length === right.length
+        ? left === right
+        : left.startsWith(right) || right.startsWith(left));
+}
+export function currentLayer(stack) {
+    const open = stack.layers.filter((layer) => layer.prNumber > 0 && layer.state !== "merged" && layer.state !== "closed");
+    const promote = open.filter((layer) => layer.prNumber !== stack.unit?.landPrNumber &&
+        !stack.unit?.members?.some((member) => member.prNumber === layer.prNumber && member.promotedHeadSha)).sort((a, b) => a.position - b.position);
+    const land = stack.unit?.landPr;
+    return promote[0] ?? open.find((layer) => layer.prNumber === stack.unit?.landPrNumber) ??
+        (land && land.prNumber > 0 && land.state !== "merged" && land.state !== "closed" ? land : undefined);
+}
+/** Shared live-fact precedence; bounce history is only passed for the candidate. */
+function layerAttention(stack, layer, queue, cursor) {
+    const none = { blocker: null, bounceKind: null };
+    if (stack.archivedAt)
+        return none;
+    const bounce = queue.filter((entry) => entry.state === "bounced")
+        .sort((a, b) => (Date.parse(b.finishedAt ?? "") || 0) - (Date.parse(a.finishedAt ?? "") || 0))[0];
+    const kind = bounce?.bounceDetail?.kind;
+    const recoverable = kind === "head_moved" || kind === "must_consolidate";
+    const hardBlock = (blocker) => ({ blocker, bounceKind: null });
+    if (layer) {
+        if (layer.restackError && layer.state !== "restacking") {
+            if (layer.restackError.kind === "rebase_conflict")
+                return hardBlock("Conflict");
+            if (!restackRetryPending(layer.restackError, layer))
+                return hardBlock("Restack failed");
+        }
+        if (layer.state === "conflict")
+            return hardBlock("Conflict");
+        if (layer.draft)
+            return {
+                blocker: "Draft PR", bounceKind: "pr_draft",
+                ...(kind === "pr_draft" && sameHead(bounce.bounceDetail?.headSha ?? bounce.verifyHeadSha, layer.headSha) &&
+                    (bounce.bounceDetail?.prNumber == null || bounce.bounceDetail.prNumber === layer.prNumber) ? { bounce } : {}),
+            };
+        if (boundDirty(layer))
+            return hardBlock(`Merge conflicts${layer.parentBranch ? ` vs ${layer.parentBranch}` : ""}`);
+        if (layer.ciStatus === "failure" || (layer.checks?.failure ?? 0) > 0) {
+            const name = layer.checks?.failingName?.trim();
+            return hardBlock(`CI failed${name ? ` — ${name}` : ""}`);
+        }
+        const tempest = layer.agentRuns?.find((run) => run.agent === "tempest" &&
+            ["findings", "failed"].includes(run.status) && sameHead(run.sha, layer.headSha));
+        if (tempest)
+            return hardBlock(`Tempest ${tempest.status}`);
+        if (layer.vortexStatus === "failed")
+            return hardBlock("Review failed");
+        if (stack.unit?.landPrNumber === layer.prNumber) {
+            if (stack.unit.landingBlockReason?.trim())
+                return hardBlock(stack.unit.landingBlockReason.trim());
+            if (stack.unit.tempestLandStatus?.toLowerCase() === "failed")
+                return hardBlock("Tempest failed");
+        }
+    }
+    if (!bounce || !kind || recoverable || !layer || queue.some((entry) => ["queued", "running", "waiting"].includes(entry.state)))
+        return none;
+    if ((cursor.bounceId != null && cursor.bounceId === bounce.id) || (cursor.afterFinishedAt &&
+        !(Date.parse(bounce.finishedAt ?? "") > Date.parse(cursor.afterFinishedAt))))
+        return none;
+    // Compare with the observed promote/land head, never the enrollment or verify head.
+    if (!sameHead(bounce.bounceDetail?.headSha ?? bounce.verifyHeadSha, layer.headSha) ||
+        (bounce.bounceDetail?.prNumber != null && bounce.bounceDetail.prNumber !== layer.prNumber))
+        return none;
+    return { blocker: mergeQueueBounceLabel(bounce), bounceKind: kind, bounce };
+}
+/** Pair-gate attention plus live hard blocks on every other open layer. */
+export function stackBlockers(stack, entries = [], cursor = {}) {
+    const candidate = currentLayer(stack);
+    const currentCandidate = candidate ? { prNumber: candidate.prNumber, headSha: candidate.headSha ?? null } : null;
+    const queue = entries.filter((entry) => entry.stackId.trim().toLowerCase() === stack.id.trim().toLowerCase());
+    const open = stack.layers.filter((layer) => layer.prNumber > 0 && !["merged", "closed"].includes(layer.state))
+        .sort((a, b) => a.position - b.position);
+    if (candidate && !open.some((layer) => layer.prNumber === candidate.prNumber))
+        open.push(candidate);
+    const child = candidate && open.filter((layer) => layer.position > candidate.position && layer.parentBranch === candidate.branch &&
+        (boundDirty(layer) || layer.state === "conflict" ||
+            (layer.state !== "restacking" && layer.restackError?.kind === "rebase_conflict"))).sort((a, b) => a.position - b.position)[0];
+    let attention = null;
+    let bounce;
+    const issues = [];
+    for (const layer of open) {
+        const selected = layer.prNumber === candidate?.prNumber;
+        const result = layerAttention(stack, layer, selected ? queue : [], cursor);
+        if (!result.blocker)
+            continue;
+        const issue = { prNumber: layer.prNumber, headSha: layer.headSha ?? null,
+            blocker: result.blocker, bounceKind: result.bounceKind };
+        if (selected || (!attention && layer === child)) {
+            attention = issue;
+            bounce = result.bounce;
+        }
+        else if (!candidate || layer.position > candidate.position)
+            issues.push(issue);
+    }
+    return { attention, issues, currentCandidate, bounce };
+}
+/** Compact contract text shared by status and wait summaries. */
+export function stackBlockersSummary(attention, issues) {
+    const blocked = attention ? ` · blocked: #${attention.prNumber} ${attention.blocker}` : "";
+    const labels = issues.slice(0, 3).map(issue => `#${issue.prNumber} ${issue.blocker}`).join("; ");
+    return blocked + (issues.length ? ` · issues: ${labels}${issues.length > 3 ? `; +${issues.length - 3} more` : ""}` : "");
+}

package/dist/stack-dto.d.ts

@@ -6,6 +6,17 @@ export type RestackError = {
     attempts: number;
     backupRef: string | null;
 };
+export declare function restackAttemptsExhausted(error: Pick<RestackError, "attempts">): boolean;
+export declare function pushRejectionIsRetryable(message: string): boolean;
+export declare function restackRetryPending(error: {
+    kind: string;
+    attempts: number;
+    detail?: string | null;
+    headSha?: string | null;
+}, layer?: {
+    state: string;
+    headSha?: string | null;
+}): boolean;
 /**
  * Wire types returned by the stack list/enrich HTTP endpoints.
  *
@@ -46,7 +57,7 @@ export type StackVortexReviewView = {
     /** Which table spoke: the authority row, a live job, a lease, or nothing. */
     source: "pr_reviews" | "github_webhook_jobs" | "lease" | "none";
 };
-export type StackCycloneStatus = "patching" | "awaiting_fix";
+export type StackCycloneStatus = "patching" | "awaiting_fix" | "failed";
 export type StackTempestStatus = "reviewing" | "findings" | "clear" | "failed" | "stale";
 export type StackAgentName = "vortex" | "cyclone" | "tempest";
 /**

package/dist/stack-dto.js

@@ -1,3 +1,21 @@
+const RESTACK_ATTEMPT_CAP = 3;
+export function restackAttemptsExhausted(error) {
+    return error.attempts >= RESTACK_ATTEMPT_CAP;
+}
+export function pushRejectionIsRetryable(message) {
+    if (/stale info|fetch first/i.test(message))
+        return false;
+    return /commit_refs|remote rejected[^\n]*\(failure\)|HTTP 5\d\d|returned error: 5\d\d|RPC failed|could not resolve host|failed to connect|connection (?:reset|refused|timed out)|operation timed out|early EOF|unexpected disconnect|remote end hung up|SSL_|gnutls/i.test(message);
+}
+export function restackRetryPending(error, layer) {
+    if (error.kind !== "push_failed" || restackAttemptsExhausted(error))
+        return false;
+    if (layer && (layer.state !== "needs_restack" && layer.state !== "restacking" || layer.headSha !== error.headSha))
+        return false;
+    if (error.detail == null)
+        return false;
+    return !/\(origin\/\S+ moved to /.test(error.detail) && pushRejectionIsRetryable(error.detail);
+}
 /** Every bounce kind understood by the shared contract. */
 export const MERGE_QUEUE_BOUNCE_KINDS = [
     "ci_failure",

package/dist/stack-watch.d.ts

@@ -1,3 +1,4 @@
+import { type StackBlocker } from "./stack-blockers.js";
 import { apiFetch } from "./api.js";
 import type { Config } from "./config.js";
 export declare const STACK_WATCH_SCHEMA: "mergestorm.stack_watch/v1";
@@ -18,6 +19,12 @@ export type StackWatchEnvelope = {
     prNumber: number | null;
     headSha: string | null;
     cursor: StackWatchCursor;
+    issues: StackBlocker[];
+    currentCandidate: {
+        prNumber: number;
+        headSha: string | null;
+    } | null;
+    assessment: "available" | "unavailable";
 };
 export type PollStackWatchOptions = {
     timeoutMs?: number;

package/dist/stack-watch.js

@@ -1,7 +1,7 @@
+import { currentLayer, stackBlockers } from "./stack-blockers.js";
 import { setTimeout as sleep } from "node:timers/promises";
 import { apiFetch } from "./api.js";
 import { REVIEW_POLL_INTERVAL_MS, REVIEW_POLL_MAX_TRANSIENT_RETRIES, isTransientReviewPollError, isTransientReviewPollStatus, transientRetryWaitMs, } from "./commands/review-client.js";
-import { mergeQueueBounceLabel } from "./stack-dto.js";
 export const STACK_WATCH_SCHEMA = "mergestorm.stack_watch/v1";
 export const STACK_WATCH_DEFAULT_TIMEOUT_MS = 45_000;
 export class StackWatchTimeoutError extends Error {
@@ -22,72 +22,6 @@ export class StackWatchError extends Error {
         this.name = "StackWatchError";
     }
 }
-function sameHead(a, b) {
-    const left = a?.trim().toLowerCase();
-    const right = b?.trim().toLowerCase();
-    return !!left && !!right && (left.startsWith(right) || right.startsWith(left));
-}
-function currentLayer(stack) {
-    const open = stack.layers.filter((layer) => layer.prNumber > 0 && layer.state !== "merged" && layer.state !== "closed");
-    const promote = open.filter((layer) => layer.prNumber !== stack.unit?.landPrNumber &&
-        !stack.unit?.members.some((member) => member.prNumber === layer.prNumber && member.promotedHeadSha)).sort((a, b) => a.position - b.position);
-    const land = stack.unit?.landPr;
-    return promote[0] ?? open.find((layer) => layer.prNumber === stack.unit?.landPrNumber) ??
-        (land && land.prNumber > 0 && land.state !== "merged" && land.state !== "closed" ? land : undefined);
-}
-/** Keep label text and precedence aligned with MCP stack-summary.blockerLabel. */
-function attention(stack, layer, queue, cursor) {
-    const none = { blocker: null, bounceKind: null };
-    if (stack.archivedAt || queue.some((entry) => ["queued", "running", "waiting"].includes(entry.state)))
-        return none;
-    const bounce = queue.filter((entry) => entry.state === "bounced")
-        .sort((a, b) => (Date.parse(b.finishedAt ?? "") || 0) - (Date.parse(a.finishedAt ?? "") || 0))[0];
-    const kind = bounce?.bounceDetail?.kind;
-    const recoverable = kind === "head_moved" || kind === "must_consolidate";
-    const recoverableSha = kind === "head_moved"
-        ? bounce?.bounceDetail?.headSha ?? bounce?.verifyHeadSha
-        : bounce?.verifyHeadSha ?? bounce?.bounceDetail?.headSha;
-    const currentRecoverable = recoverable && sameHead(layer?.headSha, recoverableSha);
-    const hardBlock = (blocker) => ({ blocker, bounceKind: null });
-    if (layer) {
-        if (layer.restackError && layer.state !== "restacking") {
-            return hardBlock(layer.restackError.kind === "rebase_conflict" ? "Conflict" : "Restack failed");
-        }
-        if (layer.state === "conflict")
-            return hardBlock("Conflict");
-        if (layer.draft)
-            return hardBlock("Draft PR");
-        if ((!layer.headSha || layer.mergeableHeadSha === layer.headSha) &&
-            (layer.mergeable === false || layer.mergeableState?.toLowerCase() === "dirty"))
-            return hardBlock("Merge conflicts");
-        if (!currentRecoverable && (layer.ciStatus === "failure" || (layer.checks?.failure ?? 0) > 0)) {
-            const name = layer.checks?.failingName?.trim();
-            return hardBlock(`CI failed${name ? ` — ${name}` : ""}`);
-        }
-        const tempest = layer.agentRuns?.find((run) => run.agent === "tempest" &&
-            ["findings", "failed"].includes(run.status) && sameHead(run.sha, layer.headSha));
-        if (tempest)
-            return hardBlock(`Tempest ${tempest.status}`);
-        if (layer.vortexStatus === "failed")
-            return hardBlock("Review failed");
-        if (stack.unit?.landPrNumber === layer.prNumber) {
-            if (stack.unit.landingBlockReason?.trim())
-                return hardBlock(stack.unit.landingBlockReason.trim());
-            if (stack.unit.tempestLandStatus?.toLowerCase() === "failed")
-                return hardBlock("Tempest failed");
-        }
-    }
-    if (!bounce || !kind || recoverable || !layer)
-        return none;
-    if (cursor.bounceId === bounce.id || (cursor.afterFinishedAt &&
-        !(Date.parse(bounce.finishedAt ?? "") > Date.parse(cursor.afterFinishedAt))))
-        return none;
-    // Compare with the observed promote/land head, never the enrollment or verify head.
-    if (!sameHead(bounce.bounceDetail?.headSha ?? bounce.verifyHeadSha, layer.headSha) ||
-        (bounce.bounceDetail?.prNumber != null && bounce.bounceDetail.prNumber !== layer.prNumber))
-        return none;
-    return { blocker: mergeQueueBounceLabel(bounce), bounceKind: kind, bounce };
-}
 /** Wait on queue invalidations, then evaluate a fresh stack snapshot. */
 export async function pollStackWatch(cfg, stackId, opts = {}) {
     const id = stackId.trim().toLowerCase();
@@ -110,11 +44,12 @@ export async function pollStackWatch(cfg, stackId, opts = {}) {
         stackId: id,
     });
     let lastEnvelope = {
-        schema: STACK_WATCH_SCHEMA, status: "waiting", stackId: id, blocker: null,
+        schema: STACK_WATCH_SCHEMA, status: "failed", stackId: id, blocker: null,
         bounceKind: null, prNumber: null, headSha: null, cursor,
+        issues: [], currentCandidate: null, assessment: "unavailable",
     };
     let transientFailures = 0;
-    const timeout = () => new StackWatchTimeoutError({ ...lastEnvelope, status: "waiting" });
+    const timeout = () => new StackWatchTimeoutError(lastEnvelope);
     const pause = async (ms) => {
         const remaining = Math.min(ms, Math.max(0, deadline - now()));
         if (remaining > 0)
@@ -136,39 +71,44 @@ export async function pollStackWatch(cfg, stackId, opts = {}) {
             catch (err) {
                 if (opts.signal?.aborted || (err instanceof Error && err.name === "AbortError"))
                     throw err;
-                if (now() >= deadline)
+                if (now() >= deadline && timeoutMs !== 0)
                     throw timeout();
-                if (isTransientReviewPollError(err) && transientFailures < REVIEW_POLL_MAX_TRANSIENT_RETRIES) {
+                if (timeoutMs !== 0 && isTransientReviewPollError(err) && transientFailures < REVIEW_POLL_MAX_TRANSIENT_RETRIES) {
                     transientFailures += 1;
                     opts.onTick?.(lastEnvelope);
                     await pause(transientRetryWaitMs({ failureCount: transientFailures, random: opts.random }));
                     continue;
                 }
-                throw new StackWatchError(err instanceof Error ? err.message : String(err), { ...lastEnvelope, status: "failed" }, { cause: err });
+                throw new StackWatchError(err instanceof Error ? err.message : String(err), { ...lastEnvelope, status: "failed", assessment: "unavailable" }, { cause: err });
             }
             if (response.status === 200)
                 return response.body;
-            if (isTransientReviewPollStatus(response.status) && transientFailures < REVIEW_POLL_MAX_TRANSIENT_RETRIES) {
+            const retryWaitMs = transientRetryWaitMs({
+                failureCount: transientFailures + 1, retryAfterSeconds: response.retryAfterSeconds, random: opts.random,
+            });
+            if (timeoutMs !== 0 && isTransientReviewPollStatus(response.status) && transientFailures < REVIEW_POLL_MAX_TRANSIENT_RETRIES &&
+                (response.status !== 429 || retryWaitMs < deadline - now())) {
                 transientFailures += 1;
                 opts.onTick?.({ ...lastEnvelope, status: response.status === 429 ? "rate_limited" : lastEnvelope.status });
-                await pause(transientRetryWaitMs({
-                    failureCount: transientFailures, retryAfterSeconds: response.retryAfterSeconds, random: opts.random,
-                }));
+                await pause(retryWaitMs);
                 continue;
             }
             throw new StackWatchError(`Stack poll failed (HTTP ${response.status})`, {
                 ...lastEnvelope, status: response.status === 429 ? "rate_limited" : "failed",
+                assessment: "unavailable",
             }, undefined, response.retryAfterSeconds);
         }
         throw timeout();
     };
-    while (now() < deadline) {
-        const snapshot = await request(`/api/v1/stacks/enrich?stackId=${encodeURIComponent(id)}`);
+    let firstSnapshot = true;
+    while (firstSnapshot || now() < deadline) {
+        firstSnapshot = false;
+        const snapshot = await request(`/api/v1/stacks/enrich?stackId=${encodeURIComponent(id)}`, timeoutMs === 0);
         let stack = snapshot && Array.isArray(snapshot.stacks)
             ? snapshot.stacks.find((stack) => stack.id.trim().toLowerCase() === id)
             : undefined;
         if (!stack || !Array.isArray(stack.layers)) {
-            throw new StackWatchError("Stack snapshot missing or invalid", { ...lastEnvelope, status: "failed" });
+            throw new StackWatchError("Stack snapshot missing or invalid", { ...lastEnvelope, status: "failed", assessment: "unavailable" });
         }
         let layer = currentLayer(stack);
         if (!enrolled) {
@@ -176,27 +116,30 @@ export async function pollStackWatch(cfg, stackId, opts = {}) {
             enrolled = true;
         }
         lastEnvelope = { ...lastEnvelope, cursor, prNumber: layer?.prNumber ?? null, headSha: layer?.headSha ?? null };
-        const initialQueue = await request(`/api/v1/stacks/queue?stackId=${encodeURIComponent(id)}`);
+        const initialQueue = await request(`/api/v1/stacks/queue?stackId=${encodeURIComponent(id)}`, timeoutMs === 0);
         if (!initialQueue || !Array.isArray(initialQueue.entries)) {
-            throw new StackWatchError("Invalid merge queue response", { ...lastEnvelope, status: "failed" });
+            throw new StackWatchError("Invalid merge queue response", { ...lastEnvelope, status: "failed", assessment: "unavailable" });
         }
         const initialEntries = initialQueue.entries.filter((entry) => entry.stackId.trim().toLowerCase() === id);
-        const initial = attention(stack, layer, initialEntries, cursor);
-        if (initial.blocker) {
-            const { bounce, ...result } = initial;
-            if (bounce) {
-                cursor = Object.freeze({
-                    ...cursor,
-                    bounceId: bounce.id,
-                    ...(bounce.finishedAt !== undefined ? { afterFinishedAt: bounce.finishedAt } : {}),
-                });
-            }
-            return { ...lastEnvelope, ...result, cursor, status: "attention" };
-        }
+        const evaluate = (stack, entries) => {
+            const { attention, issues, currentCandidate, bounce } = stackBlockers(stack, entries, cursor);
+            if (bounce)
+                cursor = Object.freeze({ ...cursor, bounceId: bounce.id,
+                    ...(bounce.finishedAt !== undefined ? { afterFinishedAt: bounce.finishedAt } : {}) });
+            lastEnvelope = { ...lastEnvelope, cursor, issues, currentCandidate, assessment: "available",
+                blocker: attention?.blocker ?? null, bounceKind: attention?.bounceKind ?? null,
+                prNumber: attention?.prNumber ?? currentCandidate?.prNumber ?? null,
+                headSha: attention ? attention.headSha : currentCandidate?.headSha ?? null,
+                status: attention ? "attention" : entries.some((entry) => ["queued", "running", "waiting"].includes(entry.state))
+                    ? "in_progress" : "waiting" };
+        };
+        evaluate(stack, initialEntries);
+        if (lastEnvelope.status === "attention" || timeoutMs === 0)
+            return lastEnvelope;
         const seconds = Math.min(45, Math.max(1, Math.ceil((deadline - now()) / 1000)));
         const queue = await request(`/api/v1/stacks/queue?stackId=${encodeURIComponent(id)}&wait=${seconds}`);
         if (!queue || !Array.isArray(queue.entries)) {
-            throw new StackWatchError("Invalid merge queue response", { ...lastEnvelope, status: "failed" });
+            throw new StackWatchError("Invalid merge queue response", { ...lastEnvelope, status: "failed", assessment: "unavailable" });
         }
         if (now() < deadline) {
             const refreshed = await request(`/api/v1/stacks/enrich?stackId=${encodeURIComponent(id)}`, true);
@@ -204,26 +147,14 @@ export async function pollStackWatch(cfg, stackId, opts = {}) {
                 ? refreshed.stacks.find((candidate) => candidate.id.trim().toLowerCase() === id)
                 : undefined;
             if (!stack || !Array.isArray(stack.layers)) {
-                throw new StackWatchError("Stack snapshot missing or invalid", { ...lastEnvelope, status: "failed" });
+                throw new StackWatchError("Stack snapshot missing or invalid", { ...lastEnvelope, status: "failed", assessment: "unavailable" });
             }
             layer = currentLayer(stack);
             lastEnvelope = { ...lastEnvelope, prNumber: layer?.prNumber ?? null, headSha: layer?.headSha ?? null };
         }
         transientFailures = 0;
         const entries = queue.entries.filter((entry) => entry.stackId.trim().toLowerCase() === id);
-        const { bounce, ...result } = attention(stack, layer, entries, cursor);
-        if (bounce) {
-            cursor = Object.freeze({
-                ...cursor,
-                bounceId: bounce.id,
-                ...(bounce.finishedAt !== undefined ? { afterFinishedAt: bounce.finishedAt } : {}),
-            });
-        }
-        lastEnvelope = {
-            ...lastEnvelope, ...result, cursor,
-            status: result.blocker ? "attention" : entries.some((entry) => ["queued", "running", "waiting"].includes(entry.state))
-                ? "in_progress" : "waiting",
-        };
+        evaluate(stack, entries);
         if (lastEnvelope.status === "attention")
             return lastEnvelope;
         opts.onTick?.(lastEnvelope);

package/dist/ui/banner.js

@@ -93,6 +93,12 @@ const WHATS_NEW = {
     "0.3.19": [
         "stack wait and held GET waits",
     ],
+    "0.3.20": [
+        "stack watch pair-gate attention and upstack issues",
+    ],
+    "0.3.21": [
+        "stack wait holds an unchanged queue instead of spinning",
+    ],
 };
 function densityFromVariant(variant) {
     if (variant === "mini" || variant === "nano")

package/package.json

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

package/skill/mergestorm-bounce-watch/SKILL.md

@@ -16,11 +16,12 @@ Call `stack_status` with `stack_id`. Require that stack's `autoEnqueueWhenReady`
 ## Watch and patch
 
 1. Call `stack_wait` with the named `stack_id` and `timeout_s: 45`. On initial enrollment, omit the cursor selectors. Save the returned `cursor`: map `cursor.enrolledHeadSha` to `enrolled_head_sha`, `cursor.afterFinishedAt` to `after_finished_at`, and `cursor.bounceId` to `bounce_id` (omit only absent fields; preserve explicit nulls). The shipped tool accepts these selectors, not a nested cursor argument.
-2. Keep the same cursor across retries. Timeout `waiting` is not failure — call `stack_wait` again in 45s slices with the same cursor. Do the same for `in_progress`. Do not replace the enrolled head with a newer snapshot head or advance the timestamp just because a wait timed out. On a surfaced `rate_limited` error, honor the retry delay and retain the cursor; on `failed` or an unrecoverable tool error, stop and report the reason.
-3. On `attention`, inspect the current `blocker`, `prNumber`, `headSha`, and `bounceKind`. Refresh `stack_status`; use `queue_status` with the same `stack_id` when bounce details are needed. Verify the blocker still applies to the current PR head. Never treat `verifyHeadSha` as the current head: it is a queue verification SHA and can be stale or synthetic. Compare the live PR branch head, the current stack layer head, and the checkout before editing.
-4. Fix the current blocker with the smallest patch on that PR's head branch, and run the relevant checks. CI-only fixes may run while Cyclone auto-patch is still on for the stack. Do not fight Cyclone: if the remote head moved, stop and tell the human. Do not take over Cyclone's review-finding work while it is active; if the blocker requires that or a policy/queue action rather than a concrete patch, stop and explain what needs human attention.
-5. Recheck Auto land and the remote PR head immediately before pushing. Commit the patch and push the PR head with an ordinary push. If the remote head moved or the push is rejected because it moved, stop. Do not rebase and retry or force-push.
-6. After your successful push, start a new watch cycle for that named stack with `enrolled_head_sha` set to the SHA you pushed. If you handled a bounce, retain its `finishedAt` as `after_finished_at` so that attempt is not handled again. Keep these selectors unchanged across subsequent retries. Continue watching; do not enqueue or re-arm anything. If further progress requires re-arming, stop and tell the human.
+2. Keep the same cursor across retries. An unread deadline times out as `failed`; stop and report. Timeout `waiting` or `in_progress` after a snapshot is not failure — call `stack_wait` again in 45s slices with the same cursor after inspecting `issues[]`. Inspect `issues[]` on `in_progress` too: a live queue does not erase upstack hard blocks. `waiting` with issues is not idle. If `assessment` is `unavailable`, do not infer that the stack is issue-free; refresh `stack_status`. Do not replace the enrolled head with a newer snapshot head or advance the timestamp just because a wait timed out. On a surfaced `rate_limited` error, honor the retry delay and retain the cursor; on `failed` or an unrecoverable tool error, stop and report the reason.
+3. On `attention`, fix the named PR: `prNumber` and `headSha` identify the blocked PR, while `currentCandidate` identifies the promote candidate. The gate covers the bottom and its direct child only when the child has current-head DIRTY on the live bottom branch. A GitHub DIRTY whose `parentBranch` starts with `mg-park-` is not that gate. Refresh `stack_status`; use `queue_status` with the same `stack_id` when bounce details are needed. Verify the blocker still applies to the current PR head. Never treat `verifyHeadSha` as the current head: it is a queue verification SHA and can be stale or synthetic. Compare the live PR branch head, the current stack layer head, and the checkout before editing. Restack `clean` does not mean mergeable or CI-green. Attention is a diagnosis, not permission to mutate stack or queue policy.
+4. Use a clean worktree on that named PR's head branch and record the remote starting SHA. Fix the current blocker with the smallest patch, and run the relevant checks. For conflicts, the live parent is the sibling PR head or the unit branch — not the DTO `parentBranch` when that field starts with `mg-park-*`. If `parentBranch` is `mg-park-*`, never merge or rebase onto it; if the real live parent is unknown, stop. Otherwise prefer merging that live parent into the PR branch, resolving locally, then an ordinary push. Never use Dashboard Continue. When the live parent is a sibling, never rebase onto trunk or `mg-stack-N` instead. Parked-freeze DIRTY alone needs no conflict patch.
+5. CI-only fixes may run while Cyclone auto-patch is still on for the stack. When the gate is clean, inspect `issues[]` and fix a live upstack CI failure one PR at a time, refreshing the gate before the next PR. Do not use higher-layer bounce history as a patch target. Do not fight Cyclone: if the remote head moved, stop and tell the human. Do not take over Cyclone's review-finding work while it is active; if the blocker requires that or a policy/queue action rather than a concrete patch, stop and explain what needs human attention.
+6. Recheck Auto land and the remote PR head immediately before pushing. Commit the patch and push the PR head with an ordinary push. A rebase onto that same live parent followed by force-with-lease is allowed only if the remote is still exactly the SHA you started from and Cyclone did not move it; use an explicit lease bound to that starting SHA. This exception never permits rebasing onto a parked freeze or substituting trunk / the unit for a sibling parent. If the remote head moved or the push is rejected because it moved, stop; do not rebase and retry.
+7. After your successful push, leave a clean worktree and keep watching the named stack. Start a new watch cycle with `enrolled_head_sha` set to the SHA you pushed. If you handled a bounce, retain its `finishedAt` as `after_finished_at` so that attempt is not handled again. Keep these selectors unchanged across subsequent retries. Continue watching; do not enqueue or re-arm anything. If further progress requires re-arming, stop and tell the human.
 
 ## Bounce kinds
 
@@ -41,10 +42,10 @@ A kind is context, not permission to mutate queue or stack policy. Diagnose the
 
 ## Never
 
-- Do not land, merge, enqueue, run `mg queue add`, `stack land`, or `land-unit`, or call `queue_enqueue` (not a shipped tool).
+- Do not land, merge PRs, enqueue, run `mg queue add`, `stack land`, or `land-unit`, or call `queue_enqueue` (not a shipped tool).
 - Do not call `settings_set`, change account auto-patch settings, or turn account auto-patch off.
 - Do not set `auto_patch: true` on a stack.
 - Do not replace Cyclone or change stack auto-patch policy to take over its work.
 - Do not auto re-arm Auto land or a bounced queue entry.
-- Do not force-push (including force-with-lease), or rebase and retry after the remote head moved.
-- Do not push any branch other than the current blocker's PR head.
+- Do not force-push except the same-live-parent rebase with the explicit starting-SHA lease above. Never rebase and retry after the remote head moved.
+- Do not push any branch other than the named blocker's PR head (or the one selected live CI issue after the gate is clean).

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

@@ -56,7 +56,8 @@ mg skill install --claude --cursor --agents
 
 Map these to `mergestorm.pr_review/v1` envelope fields; do not invent statuses.
 
-- `finding_count` is 0 (empty inline and offDiff): stop. A skipped GitHub review body (account Skip All-clear) is still a completed pass — do not wait for an Approve / All-clear comment. Tell the human the PR is clear and that Auto land owns landing. Never merge it yourself.
+- `finding_count` is 0 and (the pass verdict is `comment` or a finding title in `findings.inline` or `findings.offDiff` is Decision required): stop. Surface the pass, and quote that note when it is present. Do not patch.
+- `finding_count` is 0 and the pass verdict is `approve`: stop. A skipped GitHub review body (account Skip All-clear) is still a completed pass — do not wait for an Approve / All-clear comment. 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` and the same `after_pass`.