mergestorm 0.3.18 → 0.3.20

package/dist/stack-watch.js

@@ -0,0 +1,163 @@
+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";
+export const STACK_WATCH_SCHEMA = "mergestorm.stack_watch/v1";
+export const STACK_WATCH_DEFAULT_TIMEOUT_MS = 45_000;
+export class StackWatchTimeoutError extends Error {
+    lastEnvelope;
+    constructor(lastEnvelope) {
+        super(`Timed out waiting for stack ${lastEnvelope.stackId}`);
+        this.lastEnvelope = lastEnvelope;
+        this.name = "StackWatchTimeoutError";
+    }
+}
+export class StackWatchError extends Error {
+    lastEnvelope;
+    retryAfterSeconds;
+    constructor(message, lastEnvelope, options, retryAfterSeconds) {
+        super(message, options);
+        this.lastEnvelope = lastEnvelope;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = "StackWatchError";
+    }
+}
+/** Wait on queue invalidations, then evaluate a fresh stack snapshot. */
+export async function pollStackWatch(cfg, stackId, opts = {}) {
+    const id = stackId.trim().toLowerCase();
+    if (!id || (opts.cursor && opts.cursor.stackId.trim().toLowerCase() !== id)) {
+        throw new TypeError("A matching stackId is required");
+    }
+    const timeoutMs = opts.timeoutMs ?? STACK_WATCH_DEFAULT_TIMEOUT_MS;
+    const intervalMs = opts.intervalMs ?? REVIEW_POLL_INTERVAL_MS;
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0 || !Number.isFinite(intervalMs) || intervalMs <= 0) {
+        throw new TypeError("timeoutMs must be nonnegative and intervalMs must be positive");
+    }
+    const now = opts.now ?? Date.now;
+    const wait = opts.sleep ?? ((ms, signal) => sleep(ms, undefined, { signal }));
+    const fetch = opts.fetch ?? apiFetch;
+    const startedAt = now();
+    const deadline = startedAt + timeoutMs;
+    let enrolled = opts.cursor !== undefined;
+    let cursor = Object.freeze({
+        ...(opts.cursor ?? { stackId: id, enrolledHeadSha: null }),
+        stackId: id,
+    });
+    let lastEnvelope = {
+        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);
+    const pause = async (ms) => {
+        const remaining = Math.min(ms, Math.max(0, deadline - now()));
+        if (remaining > 0)
+            await wait(remaining, opts.signal);
+    };
+    const request = async (route, finalSnapshot = false) => {
+        let readAfterDeadline = finalSnapshot;
+        while (readAfterDeadline || now() < deadline) {
+            readAfterDeadline = false;
+            opts.signal?.throwIfAborted();
+            let response;
+            try {
+                response = await fetch(cfg, route, {
+                    signal: opts.signal, timeoutMs: route.includes("&wait=")
+                        ? Number(new URL(route, "https://local").searchParams.get("wait")) * 1000 + 5_000
+                        : finalSnapshot ? 5_000 : Math.max(1, Math.min(30_000, deadline - now())),
+                });
+            }
+            catch (err) {
+                if (opts.signal?.aborted || (err instanceof Error && err.name === "AbortError"))
+                    throw err;
+                if (now() >= deadline && timeoutMs !== 0)
+                    throw timeout();
+                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", assessment: "unavailable" }, { cause: err });
+            }
+            if (response.status === 200)
+                return response.body;
+            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(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();
+    };
+    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", 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}`);
+        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 };
+        }
+        transientFailures = 0;
+        const entries = queue.entries.filter((entry) => entry.stackId.trim().toLowerCase() === id);
+        evaluate(stack, entries);
+        if (lastEnvelope.status === "attention")
+            return lastEnvelope;
+        opts.onTick?.(lastEnvelope);
+    }
+    throw timeout();
+}

package/dist/ui/banner.js

@@ -90,6 +90,12 @@ const WHATS_NEW = {
     "0.3.18": [
         "pr --wait fences a stale same-head pass",
     ],
+    "0.3.19": [
+        "stack wait and held GET waits",
+    ],
+    "0.3.20": [
+        "stack watch pair-gate attention and upstack issues",
+    ],
 };
 function densityFromVariant(variant) {
     if (variant === "mini" || variant === "nano")

package/package.json

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

package/skill/SKILL.md

@@ -13,17 +13,17 @@ Before opening a PR; after a large refactor; when the user says review, audit, s
 
 Not for merging, landing, or pushing. For a PR that is already open on GitHub, use the `mergestorm-pr-loop` skill instead.
 
-## Install (Claude Code / Cursor)
+## Install (Claude Code / Cursor / Agents)
 
 ```bash
 mg skill install --claude
 mg skill install --cursor
-# or both: mg skill install --claude --cursor
+# or all three: mg skill install --claude --cursor --agents
 ```
 
-That writes `.claude/skills/mergestorm-review/SKILL.md` and/or `.cursor/skills/mergestorm-review/SKILL.md` in the current repo.
+That writes `.claude/skills/mergestorm-review/SKILL.md`, `.cursor/skills/mergestorm-review/SKILL.md`, and/or `.agents/skills/mergestorm-review/SKILL.md` in the current repo.
 
-Hand-copy still works: Claude Code project skill `.claude/skills/mergestorm-review/SKILL.md` (or `~/.claude/skills/mergestorm-review/SKILL.md`). Cursor: the same file under `.cursor/skills/mergestorm-review/SKILL.md`; otherwise a rule at `.cursor/rules/mergestorm-review.mdc` with this description and `alwaysApply: false`.
+Hand-copy still works: Claude Code project skill `.claude/skills/mergestorm-review/SKILL.md` (or `~/.claude/skills/mergestorm-review/SKILL.md`). Cursor: the same file under `.cursor/skills/mergestorm-review/SKILL.md`; otherwise a rule at `.cursor/rules/mergestorm-review.mdc` with this description and `alwaysApply: false`. Agents: `.agents/skills/mergestorm-review/SKILL.md`.
 
 MCP server:
 
@@ -51,6 +51,8 @@ Cursor `~/.cursor/mcp.json`:
 1. Prefer the `mergestorm` MCP server. Call `whoami`. If MCP is missing, require `mg` on PATH with `mg whoami --json` exit 0. If neither is available, stop and print the install one-liner above.
 2. Call `credits` (or `mg credits --json`). If remaining standard credits are 0, say so and stop.
 
+Ignored bot authors live in Settings → Vortex ("Ignore bot PR authors"), not Agents. Local `review_submit` is a manual review and is not an ignore-list skip.
+
 ## Hire policy
 
 Default: omit `router` (account setting).

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

@@ -0,0 +1,51 @@
+---
+name: mergestorm-bounce-watch
+description: Watch stacks explicitly named by the human while Auto land is on, and patch the current blocker after a bounce. Use for an ongoing stack watch, without taking over Cyclone or landing the stack.
+---
+
+# Mergestorm bounce watch
+
+Use only these shipped Mergestorm MCP tools: `stack_wait`, `stack_status`, `queue_status`. Use local checkout, test, and Git operations to make the patch. Auto land owns landing.
+
+## Scope and enrollment
+
+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.
+
+## 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.
+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
+
+The kind list is exactly `MERGE_QUEUE_BOUNCE_KINDS` from stack-dto:
+
+- `ci_failure`
+- `ci_timeout`
+- `head_moved`
+- `tempest_findings`
+- `seam_findings`
+- `restack_conflict`
+- `pr_draft`
+- `must_consolidate`
+- `merge_failed`
+- `gh_error`
+
+A kind is context, not permission to mutate queue or stack policy. Diagnose the current blocker rather than blindly retrying its old bounce. A head-moved bounce requires stopping if another actor moved the PR head; a timeout alone does not justify a code change. If there is no concrete patch within this scope, report the blocker and stop.
+
+## Never
+
+- 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 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

@@ -9,10 +9,12 @@ Vortex already reviews every push to an open PR on a monitored repo; nothing her
 
 Two worlds, never mixed: reviewing a local branch before a PR exists is the `mergestorm-review` skill. This skill is only for a PR that is already open on GitHub.
 
-## Install (Claude Code / Cursor)
+The account ignore list and check colors live on Settings; manage the list with `mg settings --ignore-bot add <login>|remove <login>|clear`. The ignore list does not change this loop or its rule against setting `auto_patch_enabled` with `settings_set`.
+
+## Install (Claude Code / Cursor / Agents)
 
 ```bash
-mg skill install --claude --cursor
+mg skill install --claude --cursor --agents
 ```
 
 ## Preconditions (in order)
@@ -25,6 +27,7 @@ mg skill install --claude --cursor
 ## Loop (in order)
 
 1. Find the PR's stack with `stack_list` (the stack whose `layers` contain this PR's `prNumber` for this owner/repo). If you already have its `stack_id`, `stack_status` is the same payload.
+   - Adoption needs the Cyclone GitHub App on the account; without it `stack_adopt` returns `cyclone_not_connected` — stop and tell the human, do not retry.
    - If there is no stack and the human asked you to mute Cyclone or continue the loop: call `stack_adopt` with `{ owner, repo, pr_number, auto_patch: false }` (equivalent to `mg stack adopt … --auto-patch off`). Then call `stack_status` with the returned `result.stack.id`, confirm this PR is in the stack and `autoPatchOverride` is `false`. If adoption or verification fails, refuse the loop. Otherwise continue through the ownership check below and the remaining loop steps; do not stop and ask the human to adopt. Do not turn account auto-patch off.
    - Adoption does not fix installer ≠ key. After adoption, the same `cycloneOwnerMatch` refusal below still applies.
    - Read `cycloneOwnerMatch` on that stack. If it is missing, `lookup_failed`, or `different`: refuse the loop. Do not wait, patch, or push. Tell the human the API key and the Cyclone GitHub App install are different Mergestorm accounts (or the comparison could not be loaded). Cyclone still patches as the installer. Do not turn account auto-patch off, and do not set `auto_patch: false` to paper over this.
@@ -53,12 +56,14 @@ mg skill install --claude --cursor
 
 Map these to `mergestorm.pr_review/v1` envelope fields; do not invent statuses.
 
-- `finding_count` is 0 (empty inline and offDiff): stop. Tell the human the PR is clear and that Auto land owns landing. Never merge it yourself.
+- `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`.
 - status is `in_progress` and the envelope has no `head_sha`: the wait timed out before Vortex wrote a pass for your SHA. Call `review_wait_pr` once more with the same `after_sha` and the same `after_pass`. If it comes back the same way a second time in a row, stop and tell the human that Vortex did not pick up the push. Do not push again to retrigger.
-- status is `skipped`, `stopped`, `trial_expired`, or `synced`: surface the status and reason to the human and stop. Do not patch or push.
+- status is `quota_exceeded` (or its legacy spelling `trial_expired`): the account's review credits are used up for this period; tell the human calmly and stop. It is not an error and not a lapsed trial. Do not patch or push.
+- status is `skipped`, `stopped`, or `synced`: surface the status and reason to the human and stop. Do not patch or push.
 
 ## Never