mergestorm-mcp 0.2.29 → 0.2.31

package/README.md

@@ -18,7 +18,7 @@ Every tool declares MCP `annotations` for read-only access, destructive changes,
 
 `issue_create({ title, body?, labels?, owner?, repo?, cwd? })` opens a GitHub issue through Mergestorm with no GitHub credentials: the Surge App creates it and names the caller in the body. It defaults to the origin repository of `cwd`. Labels must already exist on the repository. The same title again returns the open issue it already made (`created: false`), so a retry does not duplicate it. Then call `issue_review_wait` and open the pull request, with `Fixes #<number>` in the commit or pull request body, only once the issue is approved.
 
-`issue_review_wait({ owner, repo, number, timeout_s? })` reads the Vortex review of an issue: `state` (`approved`, `needs_answers`, `pending`, `unreviewed`, `capped` or `off`), the round, the verdict, up to 8 points, the review comment link and `next`, one sentence saying what to do. `timeout_s: 0` reads it once; otherwise it waits while the review is pending, for up to 45s (the default), and returns `pending` when the slice ends. On `needs_answers` or `unreviewed`, answer the points in a comment on the issue and call it again; Vortex reviews each reply. On `capped`, a person approves with an issue comment whose first line is `mergestorm-issue: approve`. `stack_adopt` and `stack_publish` refuse a pull request whose linked issue is not approved with `issue_not_approved`, naming each issue's state and points.
+`issue_review_wait({ owner, repo, number, timeout_s? })` reads the Vortex review of an issue: `state` (`approved`, `needs_answers`, `pending`, `unreviewed`, `capped` or `off`), the round, the verdict, up to 8 points, the review comment link and `next`, one sentence saying what to do. `timeout_s: 0` reads it once; otherwise it waits while the review is pending, for up to 45s (the default), and returns `pending` when the slice ends. On `needs_answers`, reply once in a comment on the issue, accepting each blocking point's suggested fix or saying why not (notes do not block; the PR review checks them against the code), and call it again; Vortex re-checks only the blocking points, once, and approves the issue. On `unreviewed`, comment on the issue to start a review. A person can approve early with an issue comment whose first line is `mergestorm-issue: approve`. `stack_publish` refuses with `issue_not_approved`, naming each issue's state and points, when it would open a pull request, or register one no stack tracks, whose linked issue is not approved. `stack_adopt` does not check issues.
 
 The agent tools start work on the user's own pull requests and repositories (`POST /api/v1/agents/...`):
 

package/dist/index.js

@@ -138,7 +138,7 @@ async function issueCreate(input, cfg, deps = {}) {
       cfg
     );
     return {
-      summary: `${issue.created ? "Opened" : "Already open:"} ${target2.owner}/${target2.repo}#${issue.number} ${issue.url}. Call issue_review_wait for #${issue.number} and open the pull request only once it is approved, with "Fixes #${issue.number}" in the commit or pull request body.`,
+      summary: `${issue.created ? "Opened" : "Already open:"} ${target2.owner}/${target2.repo}#${issue.number} ${issue.url}. Call issue_review_wait for #${issue.number} and open the pull request once it says you may, with "Fixes #${issue.number}" in the commit or pull request body.`,
       data: { owner: target2.owner, repo: target2.repo, ...issue }
     };
   } catch (err) {
@@ -161,7 +161,10 @@ async function issueCreate(input, cfg, deps = {}) {
 import {
   CommandError as CommandError3,
   IssueReviewTimeoutError,
+  NO_LINKED_ISSUE,
   getIssueReview,
+  issueReviewStallAdvice,
+  issueReviewWaitAfter,
   loadConfig as loadConfig2,
   pollIssueReview
 } from "mergestorm/client";
@@ -171,20 +174,47 @@ var issueReviewWaitSchema = {
   owner: z2.string().trim().regex(/^[A-Za-z0-9_.-]{1,100}$/),
   repo: z2.string().trim().regex(/^[A-Za-z0-9_.-]{1,100}$/),
   number: z2.number().int().min(1),
-  timeout_s: z2.number().min(0).max(ISSUE_REVIEW_WAIT_MAX_S).optional()
+  timeout_s: z2.number().min(0).max(ISSUE_REVIEW_WAIT_MAX_S).optional(),
+  after_round: z2.number().int().min(1).optional(),
+  waiting_since: z2.string().datetime({ offset: true }).optional()
 };
 var inputSchema2 = z2.object(issueReviewWaitSchema);
+function blockingCount(status) {
+  return status.points.filter((point) => point.blocking !== false).length;
+}
 function issueReviewSummary(status) {
   const ref = `${status.owner}/${status.repo}#${status.number}`;
   const round = status.round ? ` (round ${status.round} of ${status.maxRounds})` : "";
-  const head = status.state === "approved" ? `${ref} is approved by ${status.approvedBy === "human" ? "a person" : "Vortex"}; you may open the pull request.` : status.state === "off" ? `Issue reviews are off for ${status.owner}/${status.repo}; ${ref} needs no approval.` : status.state === "pending" ? `${ref}: Vortex is still reviewing${round}; call issue_review_wait again.` : `${ref}: ${status.state}${round}, ${status.points.length} point${status.points.length === 1 ? "" : "s"} to answer. Do not open the pull request yet.`;
+  const wait = status.wait;
+  if (wait.status === "stalled") {
+    const since = wait.minutes !== null ? ` for ${wait.minutes} min` : "";
+    return `${ref}: stalled, no new Vortex round${since} (reason: ${wait.reason}). ${issueReviewStallAdvice(wait.reason, status.mode)} Tell the human once and stop; do not call issue_review_wait in a loop.`;
+  }
+  if (wait.status === "answered_waiting_for_round" && wait.reason === "answer_not_seen") {
+    return `${ref}: Vortex has not seen an answer after round ${wait.verdictRound ?? status.round} yet. If you have not posted your answer, post it now in one issue comment; then call issue_review_wait again with next_args. Do not poll GitHub.`;
+  }
+  if (wait.status === "answered_waiting_for_round") {
+    return `${ref}: Vortex has an answer after round ${wait.verdictRound ?? status.round}; the next round has not finished. Call issue_review_wait again with next_args; do not poll GitHub.`;
+  }
+  if (wait.status === "round_running" && status.state !== "pending") {
+    return `${ref}: Vortex is running a round${round}; call issue_review_wait again with next_args.`;
+  }
+  const head = status.state === "approved" ? status.approvedBy === null ? `The Vortex review of ${ref} failed, so it does not hold the pull request back; you may open it.` : `${ref} is approved by ${status.approvedBy === "human" ? "a person" : "Vortex"}; you may open the pull request.` : status.state === "off" ? `Issue reviews are off for ${status.owner}/${status.repo}; ${ref} needs no approval.` : status.mode === "mention" && status.state === "unreviewed" ? `Issue reviews for ${status.owner}/${status.repo} run on mention; ${ref} needs no approval, so you may open the pull request.` : status.state === "pending" ? `${ref}: Vortex is still reviewing${round}; call issue_review_wait again with next_args.` : `${ref}: ${status.state}${round}, ${blockingCount(status)} point${blockingCount(status) === 1 ? "" : "s"} to answer.${status.mode === "auto" ? " Do not open the pull request yet." : ""} After you answer in one issue comment, call issue_review_wait once with next_args.`;
   return status.next ? `${head} ${status.next}` : head;
 }
-var ISSUE_NOT_APPROVED_HINT = "Do not open the pull request yet: answer the points in a comment on each issue, call issue_review_wait until it returns approved, then try again.";
+var ISSUE_NOT_APPROVED_HINT = "Do not open the pull request yet: reply once in a comment on each issue, accepting each blocking point's suggested fix or saying why not (notes do not block), call issue_review_wait with its next_args until it returns approved or stalled, then try again. Never poll GitHub.";
 function withIssueReviewHint(err, message) {
-  return err instanceof CommandError3 && err.code === "issue_not_approved" ? `${message}
+  return err instanceof CommandError3 && err.code === "issue_not_approved" && err.reason !== NO_LINKED_ISSUE ? `${message}
 ${ISSUE_NOT_APPROVED_HINT}` : message;
 }
+function nextArgs(status, input, waitingSince) {
+  const target2 = { owner: input.owner, repo: input.repo, number: input.number };
+  const wait = status.wait;
+  if (wait.status === "approved" || wait.status === "stalled") return null;
+  if (wait.status === "points") return wait.verdictRound ? { ...target2, after_round: wait.verdictRound } : target2;
+  const after = input.after_round ?? wait.verdictRound ?? void 0;
+  return { ...target2, ...after ? { after_round: after } : {}, waiting_since: waitingSince };
+}
 function failure(code, message, extra = {}) {
   return { summary: message, data: { error: { code, message, ...extra } }, isError: true };
 }
@@ -193,12 +223,22 @@ async function issueReviewWait(input, cfg, deps = {}) {
   if (!parsed.success) {
     return failure("invalid_input", `issue_review_wait needs owner, repo, a positive issue number and timeout_s from 0 to ${ISSUE_REVIEW_WAIT_MAX_S}`);
   }
-  const { owner, repo: repo2, number, timeout_s } = parsed.data;
+  const { owner, repo: repo2, number, timeout_s, after_round, waiting_since } = parsed.data;
   const target2 = { owner, repo: repo2, number };
+  const now = deps.now ?? Date.now;
+  const since = Math.min(waiting_since ? Date.parse(waiting_since) : now(), now());
+  const sinceIso = new Date(since).toISOString();
+  const withNext = (status) => {
+    const next = nextArgs(status, parsed.data, sinceIso);
+    return { summary: issueReviewSummary(status), data: { ...status, ...next ? { next_args: next } : {} } };
+  };
   try {
     const resolved = cfg ?? await loadConfig2();
-    const status = timeout_s === 0 ? await (deps.getIssueReview ?? getIssueReview)(resolved, target2) : await (deps.pollIssueReview ?? pollIssueReview)(resolved, target2, {
+    const read = timeout_s === 0 ? await (deps.getIssueReview ?? getIssueReview)(resolved, target2) : null;
+    const status = timeout_s === 0 ? read && { ...read, wait: issueReviewWaitAfter(read, { afterRound: after_round, waitedMs: now() - since, nowMs: now() }) } : await (deps.pollIssueReview ?? pollIssueReview)(resolved, target2, {
       timeoutMs: Math.max(1, Math.round((timeout_s ?? ISSUE_REVIEW_WAIT_MAX_S) * 1e3)),
+      ...after_round !== void 0 ? { afterRound: after_round } : {},
+      waitingSince: since,
       ...deps.pollIntervalMs !== void 0 ? { intervalMs: deps.pollIntervalMs } : {}
     });
     if (!status) {
@@ -207,11 +247,9 @@ async function issueReviewWait(input, cfg, deps = {}) {
         "This Mergestorm server does not review issues yet. Open the pull request as before."
       );
     }
-    return { summary: issueReviewSummary(status), data: { ...status } };
+    return withNext(status);
   } catch (err) {
-    if (err instanceof IssueReviewTimeoutError) {
-      return { summary: issueReviewSummary(err.lastStatus), data: { ...err.lastStatus } };
-    }
+    if (err instanceof IssueReviewTimeoutError) return withNext(err.lastStatus);
     const message = err instanceof Error ? err.message : String(err);
     return failure(
       err instanceof CommandError3 ? err.code ?? "issue_review_wait_failed" : "issue_review_wait_failed",
@@ -1334,7 +1372,8 @@ var ARG_BY_KEY = {
   merge_queue_batch_size: "merge_queue_batch_size",
   merge_queue_lands_alone_paths: "merge_queue_lands_alone_paths",
   merge_queue_overdrive: "merge_queue_overdrive",
-  issue_review_enabled: "issue_review"
+  issue_review_enabled: "issue_review",
+  issue_auto_review_enabled: "issue_auto_review"
 };
 function parseRepo(raw) {
   const match = typeof raw === "string" ? /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/.exec(raw.trim()) : null;
@@ -1868,7 +1907,7 @@ var MCP_HOSTED_SERVER_INSTRUCTIONS = [
 // src/server.ts
 var BATCH_SIZE_ROW = BEARER_SETTINGS2.find((row) => row.key === "merge_queue_batch_size");
 var MCP_SERVER_NAME = "mergestorm";
-var MCP_SERVER_VERSION = "0.2.29";
+var MCP_SERVER_VERSION = "0.2.31";
 var MCP_TOOL_NAMES = [
   "whoami",
   "credits",
@@ -1953,7 +1992,7 @@ var HOSTED_REVIEW_WAIT_PR_DESCRIPTION = "Read the Vortex pass on a GitHub PR; re
 var HOSTED_REVIEW_DISMISS_DESCRIPTION = `Dismiss Vortex findings you checked and found wrong or not actionable, at the PR's live head: head_sha, review_id, finding_ids (the GitHub review comment ids, offdiff-<n> for a body-only finding; preview: true lists them without writing) or scope "review" to dismiss every finding of that review, and a reason of at least 20 characters. A deferral needs evidence_url set to an open tracking issue in the same repository. Refused, with nothing written, when the head moved, an id is unknown or the user's GitHub account lacks write access; retries are idempotent. Returns which gates cleared (gate.vortex.cleared, else gate.vortex.message) and the stack watch.`;
 var HOSTED_STACK_STATUS_DESCRIPTION = "Read one owned stack: its layers, checks and agent state, with the same attention, issues, repair and currentCandidate as stack_wait. Use it to see where a stack stands now; to wait for a change, use stack_wait.";
 var HOSTED_STACK_WAIT_DESCRIPTION = "Wait up to timeout_s (1-45) for a stack to need attention, or read it once with 0. Returns a mergestorm.stack_watch/v1 envelope: attention names the PR, blocker and repair; waiting or in_progress means call again with watch.next.args; watch.done true means stop (landed, closed, archived or gone).";
-var HOSTED_ISSUE_CREATE_DESCRIPTION = "Open a GitHub issue through Mergestorm with no GitHub credentials: the Surge App creates it and names you in the body. Use it for the issue a pull request must have before it is opened, then put Fixes #<number> in the commit or pull request body. owner and repo name the repository. labels must already exist on the repository; an unknown one is refused with unknown_label and nothing is created. Calling it again with the same title returns the open issue it already made (created: false) when that issue is among the newest 100 open issues of the repository; an older one, or two calls at the same time, can still create a duplicate, so check the returned number before retrying after a lost response. Needs write access to the repository through your linked GitHub account and Surge installed on it. After creating it, call issue_review_wait with the returned number and do not open a pull request until the issue is approved: answer any points in an issue comment (Vortex reviews each reply again), then call issue_review_wait again.";
+var HOSTED_ISSUE_CREATE_DESCRIPTION = "Open a GitHub issue through Mergestorm with no GitHub credentials: the Surge App creates it and names you in the body. Use it for the issue a pull request must have before it is opened, then put Fixes #<number> in the commit or pull request body. owner and repo name the repository. labels must already exist on the repository; an unknown one is refused with unknown_label and nothing is created. Calling it again with the same title returns the open issue it already made (created: false) when that issue is among the newest 100 open issues of the repository; an older one, or two calls at the same time, can still create a duplicate, so check the returned number before retrying after a lost response. Needs write access to the repository through your linked GitHub account and Surge installed on it. After creating it, call issue_review_wait with the returned number and do not open a pull request until the issue is approved: reply once in an issue comment, accepting each blocking point's suggested fix or saying why not (notes do not block; Vortex re-checks the blocking points once and approves), then call issue_review_wait again.";
 function createMergestormMcpServer(options = {}) {
   const { config, hosted = false } = options;
   const chatId = breezeChatId(options.chatId ?? (hosted ? null : process.env.MERGESTORM_CHAT_ID));
@@ -2211,7 +2250,7 @@ function createMergestormMcpServer(options = {}) {
     "issue_create",
     {
       title: "Open GitHub issue",
-      description: hosted ? HOSTED_ISSUE_CREATE_DESCRIPTION : "Open a GitHub issue through Mergestorm with no GitHub credentials: the Surge App creates it and names you in the body. Use it for the issue a pull request must have before it is opened, then put Fixes #<number> in the commit or pull request body. Defaults to the origin repository of cwd; pass owner and repo together to name another. labels must already exist on the repository; an unknown one is refused with unknown_label and nothing is created. Calling it again with the same title returns the open issue it already made (created: false) when that issue is among the newest 100 open issues of the repository; an older one, or two calls at the same time, can still create a duplicate, so check the returned number before retrying after a lost response. Needs write access to the repository through your linked GitHub account and Surge installed on it. After creating it, call issue_review_wait with the returned number and do not open a pull request until the issue is approved: answer any points in an issue comment (Vortex reviews each reply again), then call issue_review_wait again.",
+      description: hosted ? HOSTED_ISSUE_CREATE_DESCRIPTION : "Open a GitHub issue through Mergestorm with no GitHub credentials: the Surge App creates it and names you in the body. Use it for the issue a pull request must have before it is opened, then put Fixes #<number> in the commit or pull request body. Defaults to the origin repository of cwd; pass owner and repo together to name another. labels must already exist on the repository; an unknown one is refused with unknown_label and nothing is created. Calling it again with the same title returns the open issue it already made (created: false) when that issue is among the newest 100 open issues of the repository; an older one, or two calls at the same time, can still create a duplicate, so check the returned number before retrying after a lost response. Needs write access to the repository through your linked GitHub account and Surge installed on it. After creating it, call issue_review_wait with the returned number and do not open a pull request until the issue is approved: reply once in an issue comment, accepting each blocking point's suggested fix or saying why not (notes do not block; Vortex re-checks the blocking points once and approves), then call issue_review_wait again.",
       inputSchema: hosted ? hostedIssueCreateSchema : issueCreateSchema,
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
     },
@@ -2227,7 +2266,7 @@ function createMergestormMcpServer(options = {}) {
     "issue_review_wait",
     {
       title: "Wait for issue review",
-      description: "Read the Vortex review of a GitHub issue, which on repositories with issue reviews on must approve the issue before any pull request is opened for it. Returns the review state (approved, needs_answers, pending, unreviewed, capped or off), the round, the verdict, the summary, up to 8 points, the review comment link and next, one sentence saying what to do. timeout_s: 0 reads it once; otherwise it waits while the review is pending for one slice of up to 45s (the default) and returns pending when the slice ends, so call again. Open the pull request only on approved or off. On needs_answers or unreviewed, answer every point in a comment on the issue, then call again: Vortex reviews each reply, up to maxRounds rounds. On capped, a person approves with an issue comment whose first line is mergestorm-issue: approve.",
+      description: "Wait for the next Vortex verdict on a GitHub issue. Returns the review state (approved, needs_answers, pending, unreviewed or off), the round, the verdict, the summary, up to 8 points, the review comment link, next (one sentence saying what to do), wait.status and, while there is more to wait for, next_args. wait.status is answered_waiting_for_round (Vortex has an answer after the last verdict and the next round has not finished; with wait.reason answer_not_seen Vortex has no answer after the verdict yet, so post yours), round_running, points (a verdict with points to answer), approved (approved, off, a failed review, the round cap, or unreviewed on a mention-mode repo) or stalled (no round started: about 10 minutes after a queued answer, at once when an answer failed or was skipped without starting a round, about 10 minutes into the wait when no review has started at all, or about 10 minutes after the verdict with no answer seen once the wait is at least 2 minutes old; wait.reason says why). timeout_s: 0 reads it once; otherwise it waits for one slice of up to 45s (the default). Call it again with exactly next_args: after_round is the round whose verdict you already saw, so the stale verdict is never returned again, and waiting_since carries the stall clock across slices. Open the pull request only on approved, or when the summary says the issue needs no approval (issue reviews off, or unreviewed on a mention-mode repo). On points, answer in ONE new comment on the issue as the author or a maintainer: for each blocking point, accept its suggested fix or say why not (notes do not block). On a mention-mode repo the comment must tag @mergestorm-vortex and the next round starts at once; on an auto-mode repo it starts about 90s later. Editing the body or an earlier comment starts nothing. Then call once with next_args. On stalled, follow the summary's advice for wait.reason and do not loop on this tool. Never poll GitHub or loop on this tool beyond next_args. A person can also approve with an issue comment whose first line is mergestorm-issue: approve.",
       inputSchema: issueReviewWaitSchema,
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
     },
@@ -2422,7 +2461,7 @@ function createMergestormMcpServer(options = {}) {
     "repo_settings_get",
     {
       title: "Get repository settings",
-      description: "Read the repository-level Auto patch, Auto review, Auto land, merge queue (merge_queue_batch_enabled, merge_queue_batch_size, merge_queue_lands_alone_paths) and merge queue overdrive values for the repositories connected to this account. auto_patch_enabled, auto_review_enabled, auto_land_default, merge_queue_batch_enabled and merge_queue_overdrive are true, false, or null; merge_queue_batch_size is a whole number or null; merge_queue_lands_alone_paths is a list of path patterns or null. null means not set, so the account setting applies. Auto patch and Auto review precedence is the stack override (stack_set), then the repository value, then the account setting (settings_get). The Auto land repository value only seeds new stacks at adoption; it does not override an existing stack. merge_queue_overdrive is the repository value over the account default; while it resolves on, that repository batches up to 10 queued pull requests. issue_review_enabled is true, false, or null: the repository value for Vortex issue reviews over the account default (settings_get issue_review_enabled). Pass repo as owner/repo for one repository, or omit it for all.",
+      description: "Read the repository-level Auto patch, Auto review, Auto land, merge queue (merge_queue_batch_enabled, merge_queue_batch_size, merge_queue_lands_alone_paths) and merge queue overdrive values for the repositories connected to this account. auto_patch_enabled, auto_review_enabled, auto_land_default, merge_queue_batch_enabled and merge_queue_overdrive are true, false, or null; merge_queue_batch_size is a whole number or null; merge_queue_lands_alone_paths is a list of path patterns or null. null means not set, so the account setting applies. Auto patch and Auto review precedence is the stack override (stack_set), then the repository value, then the account setting (settings_get). The Auto land repository value only seeds new stacks at adoption; it does not override an existing stack. merge_queue_overdrive is the repository value over the account default; while it resolves on, that repository batches up to 10 queued pull requests. issue_review_enabled is true, false, or null: the repository value for Vortex issue reviews over the account default (settings_get issue_review_enabled). issue_auto_review_enabled is true, false, or null the same way: while issue reviews are on, true reviews every new issue and reply, and false reviews only when a comment tags @mergestorm-vortex. Pass repo as owner/repo for one repository, or omit it for all.",
       inputSchema: { repo: z8.string().min(3).optional() },
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
     },
@@ -2438,7 +2477,7 @@ function createMergestormMcpServer(options = {}) {
     "repo_settings_set",
     {
       title: "Update repository settings",
-      description: "Set Auto patch (Cyclone), Auto review (Vortex), the Auto land default, or the merge queue settings (merge_queue_batch, merge_queue_batch_size, merge_queue_lands_alone_paths, merge_queue_overdrive) for every stack and pull request in one repository connected to this account, and return the stored result. A value sets the repository value; null clears it so the account setting applies again. A stack override (stack_set) still wins for that stack. auto_patch and auto_review apply to open stacks without an override from their next decision; nothing is cancelled or re-queued. auto_land only seeds new stacks. merge_queue_lands_alone_paths is a list of folder prefixes or globs; a queued pull request that changes a matching file is never batched with others, and an empty list keeps only the built-in rule that a stack with more than one open pull request lands alone. merge_queue_overdrive true makes that repository batch up to 10 queued pull requests, even with batching off; false turns overdrive off for that repository whatever the account default is, and null clears the repository value so the account default (settings_get merge_queue_overdrive) applies again. issue_review true or false turns Vortex issue reviews on or off for that repository whatever the account default is; null clears the repository value so the account default (settings_get issue_review_enabled) applies again. Only the account that connected the repository can change it. Never changes account settings.",
+      description: "Set Auto patch (Cyclone), Auto review (Vortex), the Auto land default, or the merge queue settings (merge_queue_batch, merge_queue_batch_size, merge_queue_lands_alone_paths, merge_queue_overdrive) for every stack and pull request in one repository connected to this account, and return the stored result. A value sets the repository value; null clears it so the account setting applies again. A stack override (stack_set) still wins for that stack. auto_patch and auto_review apply to open stacks without an override from their next decision; nothing is cancelled or re-queued. auto_land only seeds new stacks. merge_queue_lands_alone_paths is a list of folder prefixes or globs; a queued pull request that changes a matching file is never batched with others, and an empty list keeps only the built-in rule that a stack with more than one open pull request lands alone. merge_queue_overdrive true makes that repository batch up to 10 queued pull requests, even with batching off; false turns overdrive off for that repository whatever the account default is, and null clears the repository value so the account default (settings_get merge_queue_overdrive) applies again. issue_review true or false turns Vortex issue reviews on or off for that repository whatever the account default is; null clears the repository value so the account default (settings_get issue_review_enabled) applies again. issue_auto_review false makes those reviews run only when a comment tags @mergestorm-vortex (opening a PR then needs no issue approval), true reviews every new issue and reply, and null inherits the account default (settings_get issue_auto_review_enabled). Only the account that connected the repository can change it. Never changes account settings.",
       inputSchema: {
         repo: z8.string().min(3),
         auto_patch: z8.boolean().nullable().optional(),
@@ -2448,7 +2487,8 @@ function createMergestormMcpServer(options = {}) {
         merge_queue_batch_size: z8.number().int().min(BATCH_SIZE_ROW.min).max(BATCH_SIZE_ROW.max).nullable().optional(),
         merge_queue_lands_alone_paths: z8.array(z8.string()).nullable().optional(),
         merge_queue_overdrive: z8.boolean().nullable().optional(),
-        issue_review: z8.boolean().nullable().optional()
+        issue_review: z8.boolean().nullable().optional(),
+        issue_auto_review: z8.boolean().nullable().optional()
       },
       annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }
     },
@@ -2480,7 +2520,7 @@ function createMergestormMcpServer(options = {}) {
     "settings_get",
     {
       title: "Get settings",
-      description: "Read the Bearer /api/v1/settings toggles, including auto_patch_enabled, auto_land_settle_seconds (how long Auto land waits before queueing), merge_queue_batch_enabled and merge_queue_batch_size (whether the merge queue tests several pull requests on one CI run, and how many), merge_queue_overdrive (the account default for overdrive: the merge queue batches up to 10 queued pull requests per repository; repo_settings_set overrides it per repository), issue_review_enabled (the account default for Vortex issue reviews; repo_settings_set overrides it per repository), cyclone_connected (the Cyclone auto-patch App), and stacks_ready (whether stacks, the merge queue and Auto land can run for this account, which needs Mergestorm Surge).",
+      description: "Read the Bearer /api/v1/settings toggles, including auto_patch_enabled, auto_land_settle_seconds (how long Auto land waits before queueing), merge_queue_batch_enabled and merge_queue_batch_size (whether the merge queue tests several pull requests on one CI run, and how many), merge_queue_overdrive (the account default for overdrive: the merge queue batches up to 10 queued pull requests per repository; repo_settings_set overrides it per repository), issue_review_enabled (the account default for Vortex issue reviews; repo_settings_set overrides it per repository), issue_auto_review_enabled (the account default for whether those reviews run on every issue or only when a comment tags @mergestorm-vortex), cyclone_connected (the Cyclone auto-patch App), and stacks_ready (whether stacks, the merge queue and Auto land can run for this account, which needs Mergestorm Surge).",
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
     },
     async () => {
@@ -2495,7 +2535,7 @@ function createMergestormMcpServer(options = {}) {
     "settings_set",
     {
       title: "Update settings",
-      description: "Update writable Bearer /api/v1/settings values and return the stored result. At least one key is required. auto_land_settle_seconds is a whole number of seconds from 15 through 300; it applies to settle clocks that start after the write. merge_queue_batch_enabled turns merge queue batching on or off for the account, merge_queue_batch_size is a whole number from 2 through 10, merge_queue_lands_alone_paths is the list of folder prefixes or globs whose changed files keep a pull request out of a batch, and merge_queue_overdrive is the account default for overdrive: while it resolves on, a repository batches up to 10 queued pull requests, even with batching off, without changing merge_queue_batch_size, and it stays on until turned off (repo_settings_set overrides each of these per repository). issue_review_enabled is the account default for Vortex issue reviews; repo_settings_set issue_review overrides it per repository. cyclone_connected and github_connected are read-only and cannot be set.",
+      description: "Update writable Bearer /api/v1/settings values and return the stored result. At least one key is required. auto_land_settle_seconds is a whole number of seconds from 15 through 300; it applies to settle clocks that start after the write. merge_queue_batch_enabled turns merge queue batching on or off for the account, merge_queue_batch_size is a whole number from 2 through 10, merge_queue_lands_alone_paths is the list of folder prefixes or globs whose changed files keep a pull request out of a batch, and merge_queue_overdrive is the account default for overdrive: while it resolves on, a repository batches up to 10 queued pull requests, even with batching off, without changing merge_queue_batch_size, and it stays on until turned off (repo_settings_set overrides each of these per repository). issue_review_enabled is the account default for Vortex issue reviews; repo_settings_set issue_review overrides it per repository. issue_auto_review_enabled false makes them run only when a comment tags @mergestorm-vortex; repo_settings_set issue_auto_review overrides it per repository. cyclone_connected and github_connected are read-only and cannot be set.",
       inputSchema: {
         ...Object.fromEntries(
           BEARER_SETTINGS2.map((row) => [

package/dist/lib/server.d.ts

@@ -3,7 +3,7 @@ import { type Config } from "mergestorm/client";
 import { MCP_HOSTED_SERVER_INSTRUCTIONS } from "./pr-loop-instructions.js";
 export { MCP_HOSTED_SERVER_INSTRUCTIONS };
 export declare const MCP_SERVER_NAME = "mergestorm";
-export declare const MCP_SERVER_VERSION = "0.2.29";
+export declare const MCP_SERVER_VERSION = "0.2.31";
 export declare const MCP_TOOL_NAMES: readonly ["whoami", "credits", "review_list", "review_submit", "review_wait", "review_wait_pr", "review_dismiss", "review_start_pr", "review_stop_pr", "cyclone_start", "cyclone_job", "issue_create", "issue_review_wait", "stack_adopt", "stack_enqueue", "stack_list", "stack_publish", "stack_publish_status", "stack_restack", "stack_set", "stack_status", "stack_wait", "queue_status", "settings_get", "settings_set", "repo_settings_get", "repo_settings_set", "surge_setup", "list_memories", "search_memory", "remember", "update_memory", "forget_memory", "get_memory_mode", "set_memory_mode", "web_search", "read_web_page"];
 export declare const MCP_SERVER_INSTRUCTIONS: string;
 export declare function fail(err: unknown): {

package/dist/lib/server.js

@@ -32,7 +32,7 @@ import { whoami } from "./tools/whoami.js";
 import { MCP_FINDING_DEFERRAL_RULE, MCP_HOSTED_SERVER_INSTRUCTIONS, MCP_STACK_DONE_INSTRUCTIONS, MCP_PR_LOOP_INSTRUCTIONS, MCP_STACK_BASE_INSTRUCTIONS, MCP_STACK_WATCH_INSTRUCTIONS, } from "./pr-loop-instructions.js";
 export { MCP_HOSTED_SERVER_INSTRUCTIONS };
 export const MCP_SERVER_NAME = "mergestorm";
-export const MCP_SERVER_VERSION = "0.2.29";
+export const MCP_SERVER_VERSION = "0.2.31";
 export const MCP_TOOL_NAMES = [
     "whoami",
     "credits",
@@ -121,7 +121,7 @@ const HOSTED_REVIEW_WAIT_PR_DESCRIPTION = "Read the Vortex pass on a GitHub PR;
 const HOSTED_REVIEW_DISMISS_DESCRIPTION = "Dismiss Vortex findings you checked and found wrong or not actionable, at the PR's live head: head_sha, review_id, finding_ids (the GitHub review comment ids, offdiff-<n> for a body-only finding; preview: true lists them without writing) or scope \"review\" to dismiss every finding of that review, and a reason of at least 20 characters. A deferral needs evidence_url set to an open tracking issue in the same repository. Refused, with nothing written, when the head moved, an id is unknown or the user's GitHub account lacks write access; retries are idempotent. Returns which gates cleared (gate.vortex.cleared, else gate.vortex.message) and the stack watch.";
 const HOSTED_STACK_STATUS_DESCRIPTION = "Read one owned stack: its layers, checks and agent state, with the same attention, issues, repair and currentCandidate as stack_wait. Use it to see where a stack stands now; to wait for a change, use stack_wait.";
 const HOSTED_STACK_WAIT_DESCRIPTION = "Wait up to timeout_s (1-45) for a stack to need attention, or read it once with 0. Returns a mergestorm.stack_watch/v1 envelope: attention names the PR, blocker and repair; waiting or in_progress means call again with watch.next.args; watch.done true means stop (landed, closed, archived or gone).";
-const HOSTED_ISSUE_CREATE_DESCRIPTION = "Open a GitHub issue through Mergestorm with no GitHub credentials: the Surge App creates it and names you in the body. Use it for the issue a pull request must have before it is opened, then put Fixes #<number> in the commit or pull request body. owner and repo name the repository. labels must already exist on the repository; an unknown one is refused with unknown_label and nothing is created. Calling it again with the same title returns the open issue it already made (created: false) when that issue is among the newest 100 open issues of the repository; an older one, or two calls at the same time, can still create a duplicate, so check the returned number before retrying after a lost response. Needs write access to the repository through your linked GitHub account and Surge installed on it. After creating it, call issue_review_wait with the returned number and do not open a pull request until the issue is approved: answer any points in an issue comment (Vortex reviews each reply again), then call issue_review_wait again.";
+const HOSTED_ISSUE_CREATE_DESCRIPTION = "Open a GitHub issue through Mergestorm with no GitHub credentials: the Surge App creates it and names you in the body. Use it for the issue a pull request must have before it is opened, then put Fixes #<number> in the commit or pull request body. owner and repo name the repository. labels must already exist on the repository; an unknown one is refused with unknown_label and nothing is created. Calling it again with the same title returns the open issue it already made (created: false) when that issue is among the newest 100 open issues of the repository; an older one, or two calls at the same time, can still create a duplicate, so check the returned number before retrying after a lost response. Needs write access to the repository through your linked GitHub account and Surge installed on it. After creating it, call issue_review_wait with the returned number and do not open a pull request until the issue is approved: reply once in an issue comment, accepting each blocking point's suggested fix or saying why not (notes do not block; Vortex re-checks the blocking points once and approves), then call issue_review_wait again.";
 export function createMergestormMcpServer(options = {}) {
     const { config, hosted = false } = options;
     const chatId = breezeChatId(options.chatId ?? (hosted ? null : process.env.MERGESTORM_CHAT_ID));
@@ -338,7 +338,7 @@ export function createMergestormMcpServer(options = {}) {
         title: "Open GitHub issue",
         description: hosted
             ? HOSTED_ISSUE_CREATE_DESCRIPTION
-            : "Open a GitHub issue through Mergestorm with no GitHub credentials: the Surge App creates it and names you in the body. Use it for the issue a pull request must have before it is opened, then put Fixes #<number> in the commit or pull request body. Defaults to the origin repository of cwd; pass owner and repo together to name another. labels must already exist on the repository; an unknown one is refused with unknown_label and nothing is created. Calling it again with the same title returns the open issue it already made (created: false) when that issue is among the newest 100 open issues of the repository; an older one, or two calls at the same time, can still create a duplicate, so check the returned number before retrying after a lost response. Needs write access to the repository through your linked GitHub account and Surge installed on it. After creating it, call issue_review_wait with the returned number and do not open a pull request until the issue is approved: answer any points in an issue comment (Vortex reviews each reply again), then call issue_review_wait again.",
+            : "Open a GitHub issue through Mergestorm with no GitHub credentials: the Surge App creates it and names you in the body. Use it for the issue a pull request must have before it is opened, then put Fixes #<number> in the commit or pull request body. Defaults to the origin repository of cwd; pass owner and repo together to name another. labels must already exist on the repository; an unknown one is refused with unknown_label and nothing is created. Calling it again with the same title returns the open issue it already made (created: false) when that issue is among the newest 100 open issues of the repository; an older one, or two calls at the same time, can still create a duplicate, so check the returned number before retrying after a lost response. Needs write access to the repository through your linked GitHub account and Surge installed on it. After creating it, call issue_review_wait with the returned number and do not open a pull request until the issue is approved: reply once in an issue comment, accepting each blocking point's suggested fix or saying why not (notes do not block; Vortex re-checks the blocking points once and approves), then call issue_review_wait again.",
         inputSchema: hosted ? hostedIssueCreateSchema : issueCreateSchema,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     }, async (args) => {
@@ -351,7 +351,7 @@ export function createMergestormMcpServer(options = {}) {
     });
     addTool("issue_review_wait", {
         title: "Wait for issue review",
-        description: "Read the Vortex review of a GitHub issue, which on repositories with issue reviews on must approve the issue before any pull request is opened for it. Returns the review state (approved, needs_answers, pending, unreviewed, capped or off), the round, the verdict, the summary, up to 8 points, the review comment link and next, one sentence saying what to do. timeout_s: 0 reads it once; otherwise it waits while the review is pending for one slice of up to 45s (the default) and returns pending when the slice ends, so call again. Open the pull request only on approved or off. On needs_answers or unreviewed, answer every point in a comment on the issue, then call again: Vortex reviews each reply, up to maxRounds rounds. On capped, a person approves with an issue comment whose first line is mergestorm-issue: approve.",
+        description: "Wait for the next Vortex verdict on a GitHub issue. Returns the review state (approved, needs_answers, pending, unreviewed or off), the round, the verdict, the summary, up to 8 points, the review comment link, next (one sentence saying what to do), wait.status and, while there is more to wait for, next_args. wait.status is answered_waiting_for_round (Vortex has an answer after the last verdict and the next round has not finished; with wait.reason answer_not_seen Vortex has no answer after the verdict yet, so post yours), round_running, points (a verdict with points to answer), approved (approved, off, a failed review, the round cap, or unreviewed on a mention-mode repo) or stalled (no round started: about 10 minutes after a queued answer, at once when an answer failed or was skipped without starting a round, about 10 minutes into the wait when no review has started at all, or about 10 minutes after the verdict with no answer seen once the wait is at least 2 minutes old; wait.reason says why). timeout_s: 0 reads it once; otherwise it waits for one slice of up to 45s (the default). Call it again with exactly next_args: after_round is the round whose verdict you already saw, so the stale verdict is never returned again, and waiting_since carries the stall clock across slices. Open the pull request only on approved, or when the summary says the issue needs no approval (issue reviews off, or unreviewed on a mention-mode repo). On points, answer in ONE new comment on the issue as the author or a maintainer: for each blocking point, accept its suggested fix or say why not (notes do not block). On a mention-mode repo the comment must tag @mergestorm-vortex and the next round starts at once; on an auto-mode repo it starts about 90s later. Editing the body or an earlier comment starts nothing. Then call once with next_args. On stalled, follow the summary's advice for wait.reason and do not loop on this tool. Never poll GitHub or loop on this tool beyond next_args. A person can also approve with an issue comment whose first line is mergestorm-issue: approve.",
         inputSchema: issueReviewWaitSchema,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async (args) => {
@@ -513,7 +513,7 @@ export function createMergestormMcpServer(options = {}) {
     });
     addTool("repo_settings_get", {
         title: "Get repository settings",
-        description: "Read the repository-level Auto patch, Auto review, Auto land, merge queue (merge_queue_batch_enabled, merge_queue_batch_size, merge_queue_lands_alone_paths) and merge queue overdrive values for the repositories connected to this account. auto_patch_enabled, auto_review_enabled, auto_land_default, merge_queue_batch_enabled and merge_queue_overdrive are true, false, or null; merge_queue_batch_size is a whole number or null; merge_queue_lands_alone_paths is a list of path patterns or null. null means not set, so the account setting applies. Auto patch and Auto review precedence is the stack override (stack_set), then the repository value, then the account setting (settings_get). The Auto land repository value only seeds new stacks at adoption; it does not override an existing stack. merge_queue_overdrive is the repository value over the account default; while it resolves on, that repository batches up to 10 queued pull requests. issue_review_enabled is true, false, or null: the repository value for Vortex issue reviews over the account default (settings_get issue_review_enabled). Pass repo as owner/repo for one repository, or omit it for all.",
+        description: "Read the repository-level Auto patch, Auto review, Auto land, merge queue (merge_queue_batch_enabled, merge_queue_batch_size, merge_queue_lands_alone_paths) and merge queue overdrive values for the repositories connected to this account. auto_patch_enabled, auto_review_enabled, auto_land_default, merge_queue_batch_enabled and merge_queue_overdrive are true, false, or null; merge_queue_batch_size is a whole number or null; merge_queue_lands_alone_paths is a list of path patterns or null. null means not set, so the account setting applies. Auto patch and Auto review precedence is the stack override (stack_set), then the repository value, then the account setting (settings_get). The Auto land repository value only seeds new stacks at adoption; it does not override an existing stack. merge_queue_overdrive is the repository value over the account default; while it resolves on, that repository batches up to 10 queued pull requests. issue_review_enabled is true, false, or null: the repository value for Vortex issue reviews over the account default (settings_get issue_review_enabled). issue_auto_review_enabled is true, false, or null the same way: while issue reviews are on, true reviews every new issue and reply, and false reviews only when a comment tags @mergestorm-vortex. Pass repo as owner/repo for one repository, or omit it for all.",
         inputSchema: { repo: z.string().min(3).optional() },
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async (args) => {
@@ -526,7 +526,7 @@ export function createMergestormMcpServer(options = {}) {
     });
     addTool("repo_settings_set", {
         title: "Update repository settings",
-        description: "Set Auto patch (Cyclone), Auto review (Vortex), the Auto land default, or the merge queue settings (merge_queue_batch, merge_queue_batch_size, merge_queue_lands_alone_paths, merge_queue_overdrive) for every stack and pull request in one repository connected to this account, and return the stored result. A value sets the repository value; null clears it so the account setting applies again. A stack override (stack_set) still wins for that stack. auto_patch and auto_review apply to open stacks without an override from their next decision; nothing is cancelled or re-queued. auto_land only seeds new stacks. merge_queue_lands_alone_paths is a list of folder prefixes or globs; a queued pull request that changes a matching file is never batched with others, and an empty list keeps only the built-in rule that a stack with more than one open pull request lands alone. merge_queue_overdrive true makes that repository batch up to 10 queued pull requests, even with batching off; false turns overdrive off for that repository whatever the account default is, and null clears the repository value so the account default (settings_get merge_queue_overdrive) applies again. issue_review true or false turns Vortex issue reviews on or off for that repository whatever the account default is; null clears the repository value so the account default (settings_get issue_review_enabled) applies again. Only the account that connected the repository can change it. Never changes account settings.",
+        description: "Set Auto patch (Cyclone), Auto review (Vortex), the Auto land default, or the merge queue settings (merge_queue_batch, merge_queue_batch_size, merge_queue_lands_alone_paths, merge_queue_overdrive) for every stack and pull request in one repository connected to this account, and return the stored result. A value sets the repository value; null clears it so the account setting applies again. A stack override (stack_set) still wins for that stack. auto_patch and auto_review apply to open stacks without an override from their next decision; nothing is cancelled or re-queued. auto_land only seeds new stacks. merge_queue_lands_alone_paths is a list of folder prefixes or globs; a queued pull request that changes a matching file is never batched with others, and an empty list keeps only the built-in rule that a stack with more than one open pull request lands alone. merge_queue_overdrive true makes that repository batch up to 10 queued pull requests, even with batching off; false turns overdrive off for that repository whatever the account default is, and null clears the repository value so the account default (settings_get merge_queue_overdrive) applies again. issue_review true or false turns Vortex issue reviews on or off for that repository whatever the account default is; null clears the repository value so the account default (settings_get issue_review_enabled) applies again. issue_auto_review false makes those reviews run only when a comment tags @mergestorm-vortex (opening a PR then needs no issue approval), true reviews every new issue and reply, and null inherits the account default (settings_get issue_auto_review_enabled). Only the account that connected the repository can change it. Never changes account settings.",
         inputSchema: {
             repo: z.string().min(3),
             auto_patch: z.boolean().nullable().optional(),
@@ -537,6 +537,7 @@ export function createMergestormMcpServer(options = {}) {
             merge_queue_lands_alone_paths: z.array(z.string()).nullable().optional(),
             merge_queue_overdrive: z.boolean().nullable().optional(),
             issue_review: z.boolean().nullable().optional(),
+            issue_auto_review: z.boolean().nullable().optional(),
         },
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     }, async (args) => {
@@ -562,7 +563,7 @@ export function createMergestormMcpServer(options = {}) {
     });
     addTool("settings_get", {
         title: "Get settings",
-        description: "Read the Bearer /api/v1/settings toggles, including auto_patch_enabled, auto_land_settle_seconds (how long Auto land waits before queueing), merge_queue_batch_enabled and merge_queue_batch_size (whether the merge queue tests several pull requests on one CI run, and how many), merge_queue_overdrive (the account default for overdrive: the merge queue batches up to 10 queued pull requests per repository; repo_settings_set overrides it per repository), issue_review_enabled (the account default for Vortex issue reviews; repo_settings_set overrides it per repository), cyclone_connected (the Cyclone auto-patch App), and stacks_ready (whether stacks, the merge queue and Auto land can run for this account, which needs Mergestorm Surge).",
+        description: "Read the Bearer /api/v1/settings toggles, including auto_patch_enabled, auto_land_settle_seconds (how long Auto land waits before queueing), merge_queue_batch_enabled and merge_queue_batch_size (whether the merge queue tests several pull requests on one CI run, and how many), merge_queue_overdrive (the account default for overdrive: the merge queue batches up to 10 queued pull requests per repository; repo_settings_set overrides it per repository), issue_review_enabled (the account default for Vortex issue reviews; repo_settings_set overrides it per repository), issue_auto_review_enabled (the account default for whether those reviews run on every issue or only when a comment tags @mergestorm-vortex), cyclone_connected (the Cyclone auto-patch App), and stacks_ready (whether stacks, the merge queue and Auto land can run for this account, which needs Mergestorm Surge).",
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async () => {
         try {
@@ -574,7 +575,7 @@ export function createMergestormMcpServer(options = {}) {
     });
     addTool("settings_set", {
         title: "Update settings",
-        description: "Update writable Bearer /api/v1/settings values and return the stored result. At least one key is required. auto_land_settle_seconds is a whole number of seconds from 15 through 300; it applies to settle clocks that start after the write. merge_queue_batch_enabled turns merge queue batching on or off for the account, merge_queue_batch_size is a whole number from 2 through 10, merge_queue_lands_alone_paths is the list of folder prefixes or globs whose changed files keep a pull request out of a batch, and merge_queue_overdrive is the account default for overdrive: while it resolves on, a repository batches up to 10 queued pull requests, even with batching off, without changing merge_queue_batch_size, and it stays on until turned off (repo_settings_set overrides each of these per repository). issue_review_enabled is the account default for Vortex issue reviews; repo_settings_set issue_review overrides it per repository. cyclone_connected and github_connected are read-only and cannot be set.",
+        description: "Update writable Bearer /api/v1/settings values and return the stored result. At least one key is required. auto_land_settle_seconds is a whole number of seconds from 15 through 300; it applies to settle clocks that start after the write. merge_queue_batch_enabled turns merge queue batching on or off for the account, merge_queue_batch_size is a whole number from 2 through 10, merge_queue_lands_alone_paths is the list of folder prefixes or globs whose changed files keep a pull request out of a batch, and merge_queue_overdrive is the account default for overdrive: while it resolves on, a repository batches up to 10 queued pull requests, even with batching off, without changing merge_queue_batch_size, and it stays on until turned off (repo_settings_set overrides each of these per repository). issue_review_enabled is the account default for Vortex issue reviews; repo_settings_set issue_review overrides it per repository. issue_auto_review_enabled false makes them run only when a comment tags @mergestorm-vortex; repo_settings_set issue_auto_review overrides it per repository. cyclone_connected and github_connected are read-only and cannot be set.",
         inputSchema: {
             ...Object.fromEntries(BEARER_SETTINGS.map((row) => [row.key,
                 ("kind" in row

package/dist/lib/tools/issue-create.js

@@ -31,7 +31,7 @@ export async function issueCreate(input, cfg, deps = {}) {
         }
         const issue = await (deps.openStackIssue ?? openStackIssue)({ owner: target.owner, repo: target.repo, title, body: body ?? "", labels: labels ?? [] }, cfg);
         return {
-            summary: `${issue.created ? "Opened" : "Already open:"} ${target.owner}/${target.repo}#${issue.number} ${issue.url}. Call issue_review_wait for #${issue.number} and open the pull request only once it is approved, with "Fixes #${issue.number}" in the commit or pull request body.`,
+            summary: `${issue.created ? "Opened" : "Already open:"} ${target.owner}/${target.repo}#${issue.number} ${issue.url}. Call issue_review_wait for #${issue.number} and open the pull request once it says you may, with "Fixes #${issue.number}" in the commit or pull request body.`,
             data: { owner: target.owner, repo: target.repo, ...issue },
         };
     }

package/dist/lib/tools/issue-review-wait.d.ts

@@ -7,31 +7,47 @@ export declare const issueReviewWaitSchema: {
     repo: z.ZodString;
     number: z.ZodNumber;
     timeout_s: z.ZodOptional<z.ZodNumber>;
+    after_round: z.ZodOptional<z.ZodNumber>;
+    waiting_since: z.ZodOptional<z.ZodString>;
 };
 declare const inputSchema: z.ZodObject<{
     owner: z.ZodString;
     repo: z.ZodString;
     number: z.ZodNumber;
     timeout_s: z.ZodOptional<z.ZodNumber>;
+    after_round: z.ZodOptional<z.ZodNumber>;
+    waiting_since: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     number: number;
     owner: string;
     repo: string;
     timeout_s?: number | undefined;
+    after_round?: number | undefined;
+    waiting_since?: string | undefined;
 }, {
     number: number;
     owner: string;
     repo: string;
     timeout_s?: number | undefined;
+    after_round?: number | undefined;
+    waiting_since?: string | undefined;
 }>;
 export type IssueReviewWaitInput = z.infer<typeof inputSchema>;
 export type IssueReviewWaitDeps = {
     getIssueReview?: typeof getIssueReview;
     pollIssueReview?: typeof pollIssueReview;
     pollIntervalMs?: number;
+    now?: () => number;
+};
+export type IssueReviewWaitNextArgs = {
+    owner: string;
+    repo: string;
+    number: number;
+    after_round?: number;
+    waiting_since?: string;
 };
 export declare function issueReviewSummary(status: IssueReviewStatus): string;
-export declare const ISSUE_NOT_APPROVED_HINT = "Do not open the pull request yet: answer the points in a comment on each issue, call issue_review_wait until it returns approved, then try again.";
+export declare const ISSUE_NOT_APPROVED_HINT = "Do not open the pull request yet: reply once in a comment on each issue, accepting each blocking point's suggested fix or saying why not (notes do not block), call issue_review_wait with its next_args until it returns approved or stalled, then try again. Never poll GitHub.";
 export declare function withIssueReviewHint(err: unknown, message: string): string;
 export declare function issueReviewWait(input: IssueReviewWaitInput, cfg?: Config, deps?: IssueReviewWaitDeps): Promise<ToolPayload>;
 export {};

package/dist/lib/tools/issue-review-wait.js

@@ -1,4 +1,4 @@
-import { CommandError, IssueReviewTimeoutError, getIssueReview, loadConfig, pollIssueReview, } from "mergestorm/client";
+import { CommandError, IssueReviewTimeoutError, NO_LINKED_ISSUE, getIssueReview, issueReviewStallAdvice, issueReviewWaitAfter, loadConfig, pollIssueReview, } from "mergestorm/client";
 import { z } from "zod";
 export const ISSUE_REVIEW_WAIT_MAX_S = 45;
 export const issueReviewWaitSchema = {
@@ -6,23 +6,56 @@ export const issueReviewWaitSchema = {
     repo: z.string().trim().regex(/^[A-Za-z0-9_.-]{1,100}$/),
     number: z.number().int().min(1),
     timeout_s: z.number().min(0).max(ISSUE_REVIEW_WAIT_MAX_S).optional(),
+    after_round: z.number().int().min(1).optional(),
+    waiting_since: z.string().datetime({ offset: true }).optional(),
 };
 const inputSchema = z.object(issueReviewWaitSchema);
+function blockingCount(status) {
+    return status.points.filter((point) => point.blocking !== false).length;
+}
 export function issueReviewSummary(status) {
     const ref = `${status.owner}/${status.repo}#${status.number}`;
     const round = status.round ? ` (round ${status.round} of ${status.maxRounds})` : "";
+    const wait = status.wait;
+    if (wait.status === "stalled") {
+        const since = wait.minutes !== null ? ` for ${wait.minutes} min` : "";
+        return `${ref}: stalled, no new Vortex round${since} (reason: ${wait.reason}). ${issueReviewStallAdvice(wait.reason, status.mode)} Tell the human once and stop; do not call issue_review_wait in a loop.`;
+    }
+    if (wait.status === "answered_waiting_for_round" && wait.reason === "answer_not_seen") {
+        return `${ref}: Vortex has not seen an answer after round ${wait.verdictRound ?? status.round} yet. If you have not posted your answer, post it now in one issue comment; then call issue_review_wait again with next_args. Do not poll GitHub.`;
+    }
+    if (wait.status === "answered_waiting_for_round") {
+        return `${ref}: Vortex has an answer after round ${wait.verdictRound ?? status.round}; the next round has not finished. Call issue_review_wait again with next_args; do not poll GitHub.`;
+    }
+    if (wait.status === "round_running" && status.state !== "pending") {
+        return `${ref}: Vortex is running a round${round}; call issue_review_wait again with next_args.`;
+    }
     const head = status.state === "approved"
-        ? `${ref} is approved by ${status.approvedBy === "human" ? "a person" : "Vortex"}; you may open the pull request.`
+        ? status.approvedBy === null
+            ? `The Vortex review of ${ref} failed, so it does not hold the pull request back; you may open it.`
+            : `${ref} is approved by ${status.approvedBy === "human" ? "a person" : "Vortex"}; you may open the pull request.`
         : status.state === "off"
             ? `Issue reviews are off for ${status.owner}/${status.repo}; ${ref} needs no approval.`
-            : status.state === "pending"
-                ? `${ref}: Vortex is still reviewing${round}; call issue_review_wait again.`
-                : `${ref}: ${status.state}${round}, ${status.points.length} point${status.points.length === 1 ? "" : "s"} to answer. Do not open the pull request yet.`;
+            : status.mode === "mention" && status.state === "unreviewed"
+                ? `Issue reviews for ${status.owner}/${status.repo} run on mention; ${ref} needs no approval, so you may open the pull request.`
+                : status.state === "pending"
+                    ? `${ref}: Vortex is still reviewing${round}; call issue_review_wait again with next_args.`
+                    : `${ref}: ${status.state}${round}, ${blockingCount(status)} point${blockingCount(status) === 1 ? "" : "s"} to answer.${status.mode === "auto" ? " Do not open the pull request yet." : ""} After you answer in one issue comment, call issue_review_wait once with next_args.`;
     return status.next ? `${head} ${status.next}` : head;
 }
-export const ISSUE_NOT_APPROVED_HINT = "Do not open the pull request yet: answer the points in a comment on each issue, call issue_review_wait until it returns approved, then try again.";
+export const ISSUE_NOT_APPROVED_HINT = "Do not open the pull request yet: reply once in a comment on each issue, accepting each blocking point's suggested fix or saying why not (notes do not block), call issue_review_wait with its next_args until it returns approved or stalled, then try again. Never poll GitHub.";
 export function withIssueReviewHint(err, message) {
-    return err instanceof CommandError && err.code === "issue_not_approved" ? `${message}\n${ISSUE_NOT_APPROVED_HINT}` : message;
+    return err instanceof CommandError && err.code === "issue_not_approved" && err.reason !== NO_LINKED_ISSUE ? `${message}\n${ISSUE_NOT_APPROVED_HINT}` : message;
+}
+function nextArgs(status, input, waitingSince) {
+    const target = { owner: input.owner, repo: input.repo, number: input.number };
+    const wait = status.wait;
+    if (wait.status === "approved" || wait.status === "stalled")
+        return null;
+    if (wait.status === "points")
+        return wait.verdictRound ? { ...target, after_round: wait.verdictRound } : target;
+    const after = input.after_round ?? wait.verdictRound ?? undefined;
+    return { ...target, ...(after ? { after_round: after } : {}), waiting_since: waitingSince };
 }
 function failure(code, message, extra = {}) {
     return { summary: message, data: { error: { code, message, ...extra } }, isError: true };
@@ -32,25 +65,34 @@ export async function issueReviewWait(input, cfg, deps = {}) {
     if (!parsed.success) {
         return failure("invalid_input", `issue_review_wait needs owner, repo, a positive issue number and timeout_s from 0 to ${ISSUE_REVIEW_WAIT_MAX_S}`);
     }
-    const { owner, repo, number, timeout_s } = parsed.data;
+    const { owner, repo, number, timeout_s, after_round, waiting_since } = parsed.data;
     const target = { owner, repo, number };
+    const now = deps.now ?? Date.now;
+    const since = Math.min(waiting_since ? Date.parse(waiting_since) : now(), now());
+    const sinceIso = new Date(since).toISOString();
+    const withNext = (status) => {
+        const next = nextArgs(status, parsed.data, sinceIso);
+        return { summary: issueReviewSummary(status), data: { ...status, ...(next ? { next_args: next } : {}) } };
+    };
     try {
         const resolved = cfg ?? (await loadConfig());
+        const read = timeout_s === 0 ? await (deps.getIssueReview ?? getIssueReview)(resolved, target) : null;
         const status = timeout_s === 0
-            ? await (deps.getIssueReview ?? getIssueReview)(resolved, target)
+            ? read && { ...read, wait: issueReviewWaitAfter(read, { afterRound: after_round, waitedMs: now() - since, nowMs: now() }) }
             : await (deps.pollIssueReview ?? pollIssueReview)(resolved, target, {
                 timeoutMs: Math.max(1, Math.round((timeout_s ?? ISSUE_REVIEW_WAIT_MAX_S) * 1000)),
+                ...(after_round !== undefined ? { afterRound: after_round } : {}),
+                waitingSince: since,
                 ...(deps.pollIntervalMs !== undefined ? { intervalMs: deps.pollIntervalMs } : {}),
             });
         if (!status) {
             return failure("issue_review_unavailable", "This Mergestorm server does not review issues yet. Open the pull request as before.");
         }
-        return { summary: issueReviewSummary(status), data: { ...status } };
+        return withNext(status);
     }
     catch (err) {
-        if (err instanceof IssueReviewTimeoutError) {
-            return { summary: issueReviewSummary(err.lastStatus), data: { ...err.lastStatus } };
-        }
+        if (err instanceof IssueReviewTimeoutError)
+            return withNext(err.lastStatus);
         const message = err instanceof Error ? err.message : String(err);
         return failure(err instanceof CommandError ? err.code ?? "issue_review_wait_failed" : "issue_review_wait_failed", message, err instanceof CommandError && err.retryAfterSeconds !== undefined ? { retry_after_seconds: err.retryAfterSeconds } : {});
     }

package/dist/lib/tools/repo-settings.js

@@ -8,6 +8,7 @@ const ARG_BY_KEY = {
     merge_queue_lands_alone_paths: "merge_queue_lands_alone_paths",
     merge_queue_overdrive: "merge_queue_overdrive",
     issue_review_enabled: "issue_review",
+    issue_auto_review_enabled: "issue_auto_review",
 };
 function parseRepo(raw) {
     const match = typeof raw === "string" ? /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/.exec(raw.trim()) : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mergestorm-mcp",
-  "version": "0.2.29",
+  "version": "0.2.31",
   "description": "Mergestorm MCP server — identity, review, and read-only stack tools over stdio",
   "license": "MIT",
   "type": "module",
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "mergestorm": "0.3.66",
+    "mergestorm": "0.3.68",
     "zod": "^3.24.2"
   },
   "devDependencies": {