mergestorm 0.3.18 → 0.3.20

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.
  *
@@ -21,6 +32,31 @@ export type StackReviewStatus = "approved" | "changes_requested" | "reviewed" |
  * (#1947): Work paints Incomplete, never Reviewed or all clear.
  */
 export type StackVortexStatus = "queued" | "skipped" | "reviewing" | "seam_pending" | "all_clear" | "findings" | "throttled" | "failed" | "incomplete";
+/**
+ * MS-14 viewer: the one lifecycle status of the Vortex review on a PR head.
+ * `pr_reviews` is the authority when a row exists for the SHA; a leftover
+ * `github_webhook_jobs` row paints `queued` / `reviewing` only when no pass row
+ * exists yet. `none` = never dispatched. `done` = a pass posted; the finer
+ * verdict detail lives on `vortexStatus` / `agentRuns`.
+ */
+export type StackVortexReviewViewStatus = "none" | "queued" | "reviewing" | "skipped" | "done" | "failed";
+export type StackVortexReviewView = {
+    status: StackVortexReviewViewStatus;
+    /** `pr_reviews.skip_reason` for `skipped`; null when the writer recorded none. */
+    skip_reason: string | null;
+    /** SHA + pass identity of the attempt (#2027); null before a pass row exists. */
+    pass: number | null;
+    /** Head the status speaks for; null when neither table named one. */
+    head_sha: string | null;
+    /** In-flight sub-state while `reviewing` (fanout / synthesizing). */
+    phase: string | null;
+    /** Earliest live job start while `reviewing`; null when lease-only. */
+    started_at: string | null;
+    /** Stop control visibility: true only while a pass can actually be cancelled. */
+    stoppable: boolean;
+    /** 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 StackTempestStatus = "reviewing" | "findings" | "clear" | "failed" | "stale";
 export type StackAgentName = "vortex" | "cyclone" | "tempest";
@@ -140,6 +176,12 @@ export type StackLayerDto = {
      * Undefined = producer predates runs (clients fall back to the rollup).
      */
     agentRuns?: StackAgentRun[];
+    /**
+     * MS-14 viewer output for this layer's head. Every surface renders the
+     * lifecycle status from here; `vortexStatus` / `agentRuns` only add verdict
+     * detail once it says `done`. Undefined = producer predates the viewer.
+     */
+    vortexReview?: StackVortexReviewView;
     conflictDetail: string | null;
     restackError?: RestackError | null;
     lastRestackedSha: string | null;
@@ -249,6 +291,21 @@ export type StackDto = {
      * Missing on older payloads is off.
      */
     autoEnqueueWhenReady?: boolean;
+    /**
+     * Auto land Settling certificate. The stacks watcher publishes the identity
+     * of the settle clock it actually started (action, exact PR and head, server
+     * start time) and clears it when that clock is consumed or invalidated.
+     * Absent (older payloads) or `null` means no certified settle: paint nothing.
+     * Remaining time derives from `startedAt`; a refresh never restarts it.
+     * Partial or invalid server rows map to `null`, never to a guessed value.
+     */
+    autoEnqueueSettle?: {
+        action: "ready" | "promote";
+        prNumber: number;
+        headSha: string;
+        /** ISO timestamp of the watcher's clock start. */
+        startedAt: string;
+    } | null;
     /**
      * Per-stack Vortex auto-review override. `null` (or missing) follows the
      * account `auto_review_enabled` flag; a boolean wins in both directions.
@@ -286,7 +343,11 @@ export type StackDto = {
 export type MergeQueueEntryState = "queued" | "running" | "waiting" | "landed" | "bounced" | "cancelled";
 export type MergeQueueEnqueuedBy = "human" | "agent";
 export type MergeQueueEnqueuedVia = "dashboard" | "cli" | "chat" | "api" | "mcp";
-export type MergeQueueBounceKind = "ci_failure" | "ci_timeout" | "head_moved" | "tempest_findings" | "seam_findings" | "restack_conflict" | "pr_draft" | "merge_failed" | "gh_error";
+export type MergeQueueBounceKind = "ci_failure" | "ci_timeout" | "head_moved" | "tempest_findings" | "seam_findings" | "restack_conflict" | "pr_draft" | "must_consolidate" | "merge_failed" | "gh_error";
+/** Every bounce kind understood by the shared contract. */
+export declare const MERGE_QUEUE_BOUNCE_KINDS: readonly ["ci_failure", "ci_timeout", "head_moved", "tempest_findings", "seam_findings", "restack_conflict", "pr_draft", "must_consolidate", "merge_failed", "gh_error"];
+export declare const BOUNCE_KIND_LABELS: Readonly<Record<MergeQueueBounceKind, string>>;
+export declare function mergeQueueBounceLabel(entry: MergeQueueEntryDto): string;
 /** Structured bounce handoff — enough for the bar chip and the chat quote. */
 export type MergeQueueBounceDetail = {
     kind: MergeQueueBounceKind;

package/dist/stack-dto.js

@@ -1 +1,55 @@
-export {};
+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",
+    "ci_timeout",
+    "head_moved",
+    "tempest_findings",
+    "seam_findings",
+    "restack_conflict",
+    "pr_draft",
+    "must_consolidate",
+    "merge_failed",
+    "gh_error",
+];
+export const BOUNCE_KIND_LABELS = {
+    ci_failure: "CI failed",
+    ci_timeout: "CI timed out",
+    head_moved: "head moved",
+    tempest_findings: "Tempest findings",
+    seam_findings: "seam review findings",
+    restack_conflict: "restack conflict",
+    pr_draft: "draft PR",
+    must_consolidate: "needs promote",
+    merge_failed: "merge failed",
+    gh_error: "GitHub error",
+};
+export function mergeQueueBounceLabel(entry) {
+    const detail = entry.bounceDetail;
+    const kindLabel = detail ? BOUNCE_KIND_LABELS[detail.kind] : undefined;
+    if (kindLabel) {
+        const specifics = detail?.failingCheck ??
+            detail?.conflictBranch ??
+            detail?.message ??
+            (detail?.prNumber != null ? `PR #${detail.prNumber}` : null);
+        return specifics ? `${kindLabel} — ${specifics}` : kindLabel;
+    }
+    return entry.bounceReason?.trim() || "bounced";
+}

package/dist/stack-watch.d.ts

@@ -0,0 +1,51 @@
+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";
+export declare const STACK_WATCH_DEFAULT_TIMEOUT_MS = 45000;
+/** Resume selectors are fixed for the entire wait, including transient retries. */
+export type StackWatchCursor = {
+    readonly stackId: string;
+    readonly enrolledHeadSha: string | null;
+    readonly afterFinishedAt?: string | null;
+    readonly bounceId?: string | null;
+};
+export type StackWatchEnvelope = {
+    schema: typeof STACK_WATCH_SCHEMA;
+    status: "attention" | "waiting" | "in_progress" | "rate_limited" | "failed";
+    stackId: string;
+    blocker: string | null;
+    bounceKind: string | null;
+    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;
+    intervalMs?: number;
+    cursor?: StackWatchCursor;
+    signal?: AbortSignal;
+    onTick?: (envelope: StackWatchEnvelope) => void;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    now?: () => number;
+    random?: () => number;
+    /** Test seam at the apiFetch boundary, including HTTP status and Retry-After. */
+    fetch?: typeof apiFetch;
+};
+export declare class StackWatchTimeoutError extends Error {
+    readonly lastEnvelope: StackWatchEnvelope;
+    constructor(lastEnvelope: StackWatchEnvelope);
+}
+export declare class StackWatchError extends Error {
+    readonly lastEnvelope: StackWatchEnvelope;
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(message: string, lastEnvelope: StackWatchEnvelope, options?: ErrorOptions, retryAfterSeconds?: number | undefined);
+}
+/** Wait on queue invalidations, then evaluate a fresh stack snapshot. */
+export declare function pollStackWatch(cfg: Config, stackId: string, opts?: PollStackWatchOptions): Promise<StackWatchEnvelope>;