mergestorm 0.3.20 → 0.3.22

package/README.md

@@ -45,12 +45,12 @@ On a TTY, bare `mergestorm` (or `mergestorm shell`) opens a branded REPL: a comp
 
 ```
 ╭──────────────────────────────────────────────────────────────────────────────╮
-│ ▟██▛  mergestorm v0.3.20                                                     │
+│ ▟██▛  mergestorm v0.3.22                                                     │
 │  ▜▙   ● 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.20: stack watch pair-gate attention and upstack issues     │
+│       New in v0.3.22: stack wait holds an unchanged queue instead of spinning│
 ╰──────────────────────────────────────────────────────────────────────────────╯
 mergestorm
 ╭──────────────────────────────────────────────────────────────────────────────╮

package/dist/api.d.ts

@@ -239,7 +239,9 @@ export declare function landNextStack(stackId: string, cfg?: Config, opts?: {
     prNumber?: number;
 }): Promise<unknown>;
 /** List the authenticated user's live merge-queue entries. */
-export declare function listMergeQueueEntries(cfg?: Config): Promise<MergeQueueEntryDto[]>;
+export declare function listMergeQueueEntries(cfg?: Config, opts?: {
+    stackId?: string;
+}): Promise<MergeQueueEntryDto[]>;
 /** Enqueue a stack for verified landing. */
 export declare function enqueueStack(stackId: string, cfg?: Config): Promise<unknown>;
 /** Cancel a live merge-queue entry by entry id. */

package/dist/api.js

@@ -347,7 +347,7 @@ export async function getEnrichedStack(stackId, cfg, opts) {
     if (!Array.isArray(stacks)) {
         throw new CommandError(`Failed to get stack status (HTTP 200): ${JSON.stringify(body)}`);
     }
-    return stacks.find((stack) => stack?.id === id) ?? null;
+    return stacks.find((stack) => typeof stack?.id === "string" && stack.id.trim().toLowerCase() === id.toLowerCase()) ?? null;
 }
 /** Drop undefined keys so the wire body only carries what was requested. */
 export function stackPolicyBody(policy) {
@@ -485,12 +485,16 @@ export async function landNextStack(stackId, cfg, opts) {
     return stackMutation(stackId, "/land-next", "POST", json, "Failed to land next", cfg);
 }
 /** List the authenticated user's live merge-queue entries. */
-export async function listMergeQueueEntries(cfg) {
+export async function listMergeQueueEntries(cfg, opts) {
     const resolved = cfg ?? (await loadConfig());
-    const { status, body } = await apiFetch(resolved, "/api/v1/stacks/queue");
+    const stackId = opts?.stackId?.trim();
+    const { status, body, retryAfterSeconds } = await apiFetch(resolved, stackId ? `/api/v1/stacks/queue?stackId=${encodeURIComponent(stackId)}` : "/api/v1/stacks/queue");
     if (status === 404) {
         throw new CommandError("Merge queue API is not available on this server yet. Deploy the API update or use the dashboard.");
     }
+    if (status === 429) {
+        throw new CommandError(rateLimitedMessage(retryAfterSeconds), REVIEW_EXIT.rate_limited, "rate_limited", { retryAfterSeconds });
+    }
     if (status !== 200) {
         throw new CommandError(`Failed to list merge queue (HTTP ${status}): ${JSON.stringify(body)}`);
     }

package/dist/stack-dto.d.ts

@@ -57,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-watch.js

@@ -100,61 +100,64 @@ export async function pollStackWatch(cfg, stackId, opts = {}) {
         }
         throw timeout();
     };
-    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)
+    const enrich = async (finalSnapshot) => {
+        const snapshot = await request(`/api/v1/stacks/enrich?stackId=${encodeURIComponent(id)}`, finalSnapshot);
+        const stack = snapshot && Array.isArray(snapshot.stacks)
+            ? snapshot.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", assessment: "unavailable" });
         }
-        let layer = currentLayer(stack);
-        if (!enrolled) {
-            cursor = Object.freeze({ stackId: id, enrolledHeadSha: layer?.headSha ?? null });
-            enrolled = true;
-        }
-        lastEnvelope = { ...lastEnvelope, cursor, prNumber: layer?.prNumber ?? null, headSha: layer?.headSha ?? null };
-        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", assessment: "unavailable" });
-        }
-        const initialEntries = initialQueue.entries.filter((entry) => entry.stackId.trim().toLowerCase() === id);
-        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}`);
+        return stack;
+    };
+    const queueRoute = `/api/v1/stacks/queue?stackId=${encodeURIComponent(id)}`;
+    const readQueue = async (route, finalSnapshot = false) => {
+        const queue = await request(route, finalSnapshot);
         if (!queue || !Array.isArray(queue.entries)) {
             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);
-            stack = Array.isArray(refreshed?.stacks)
-                ? 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", assessment: "unavailable" });
-            }
-            layer = currentLayer(stack);
-            lastEnvelope = { ...lastEnvelope, prNumber: layer?.prNumber ?? null, headSha: layer?.headSha ?? null };
+        return {
+            entries: queue.entries.filter((entry) => entry.stackId.trim().toLowerCase() === id),
+            fingerprint: typeof queue.fingerprint === "string" && queue.fingerprint ? queue.fingerprint : null,
+        };
+    };
+    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" };
+    };
+    let stack = await enrich(timeoutMs === 0);
+    const layer = currentLayer(stack);
+    if (!enrolled) {
+        cursor = Object.freeze({ stackId: id, enrolledHeadSha: layer?.headSha ?? null });
+        enrolled = true;
+    }
+    lastEnvelope = { ...lastEnvelope, cursor, prNumber: layer?.prNumber ?? null, headSha: layer?.headSha ?? null };
+    let queue = await readQueue(queueRoute, timeoutMs === 0);
+    evaluate(stack, queue.entries);
+    if (lastEnvelope.status === "attention" || timeoutMs === 0)
+        return lastEnvelope;
+    while (now() < deadline) {
+        const heldAt = now();
+        const seconds = Math.min(45, Math.max(1, Math.ceil((deadline - heldAt) / 1000)));
+        const seen = queue.fingerprint ? `&seen=${encodeURIComponent(queue.fingerprint)}` : "";
+        const held = await readQueue(`${queueRoute}&wait=${seconds}${seen}`);
+        if (JSON.stringify(held.entries) === JSON.stringify(queue.entries)) {
+            await pause(intervalMs - (now() - heldAt));
         }
+        queue = held;
+        stack = await enrich(true);
+        const refreshed = currentLayer(stack);
+        lastEnvelope = { ...lastEnvelope, prNumber: refreshed?.prNumber ?? null, headSha: refreshed?.headSha ?? null };
         transientFailures = 0;
-        const entries = queue.entries.filter((entry) => entry.stackId.trim().toLowerCase() === id);
-        evaluate(stack, entries);
+        evaluate(stack, queue.entries);
         if (lastEnvelope.status === "attention")
             return lastEnvelope;
         opts.onTick?.(lastEnvelope);

package/dist/ui/banner.js

@@ -96,6 +96,9 @@ const WHATS_NEW = {
     "0.3.20": [
         "stack watch pair-gate attention and upstack issues",
     ],
+    "0.3.22": [
+        "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.20",
+  "version": "0.3.22",
   "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

@@ -11,17 +11,17 @@ Use only these shipped Mergestorm MCP tools: `stack_wait`, `stack_status`, `queu
 
 Watch only stacks the human named. If no unambiguous stack ID is available, ask the human to identify it; do not discover and enroll other stacks. Keep a separate cursor for each named stack.
 
-Call `stack_status` with `stack_id`. Require that stack's `autoEnqueueWhenReady` is `true` (Auto land on). If Auto land is off, missing, or cannot be verified, stop and tell the human. Never enable it yourself. Recheck this condition between wait slices and before patching or pushing. Stop when the stack is archived or its PRs are all merged or closed.
+Call `stack_status` with `stack_id`. Require that stack's `autoEnqueueWhenReady` is `true` (Auto land on). If Auto land is off, missing, or cannot be verified, stop and tell the human. Never enable it yourself. Recheck this condition between wait slices and before patching or pushing. If Auto land is off when you recheck, call `queue_status` with the same `stack_id` and report the newest bounce (kind, PR, head, `finishedAt`) before stopping: `merge_failed`, `gh_error`, and `ci_timeout` can disarm Auto land. Stop when the stack is archived or its PRs are all merged or closed.
 
 ## 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. 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.
+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). Keep `bounce_id` alongside `after_finished_at`; never pass one without the other when the returned cursor has both. The shipped tool accepts these selectors, not a nested cursor argument.
+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`, whose `attention`, `issues`, and `currentCandidate` come from the same blocker rules as `stack_wait`. 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. `queue_status` returning `queue_entry_not_found` is not a failure: an empty queue for the stack is a normal wait.
+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. Read the live PR head with `git ls-remote origin refs/heads/<branch>` or `gh api repos/OWNER/REPO/pulls/N --jq .head.sha`. If you need CI logs, use `gh run list --branch <branch>`, `gh run view <run-id> --log-failed`, or `gh api repos/OWNER/REPO/commits/SHA/check-runs`. Read GitHub only through git and these REST calls; do not use other `gh pr` subcommands. 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.
+6. Recheck Auto land and the remote PR head (`git ls-remote origin refs/heads/<branch>`) 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 the returned `cursor.afterFinishedAt` as `after_finished_at` and `cursor.bounceId` as `bounce_id` 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