mergestorm-mcp 0.1.3 → 0.1.6

package/README.md

@@ -1,11 +1,14 @@
 # mergestorm-mcp
 
-Stdio MCP server for Mergestorm. Tools: `whoami`, `credits`, `review_list`, `review_get`, `review_get_pr`, `review_submit`, `review_wait`, `review_wait_pr`, `stack_list`, `stack_status`, `queue_status`, `settings_get`, `settings_set`.
+Stdio MCP server for Mergestorm. Tools: `whoami`, `credits`, `review_list`, `review_get`, `review_get_pr`, `review_submit`, `review_wait`, `review_wait_pr`, `stack_adopt`, `stack_list`, `stack_set`, `stack_status`, `stack_wait`, `queue_status`, `settings_get`, `settings_set`.
 
-The stack tools are read-only:
+The stack tools expose reads plus one scoped policy write:
 
+- `stack_adopt({ owner, repo, pr_number, auto_land?, auto_review?, auto_patch? })` adopts an open PR chain with optional per-stack policy. Omitted policy does not force Cyclone off. `auto_review` and `auto_patch` accept `true`, `false`, or `null`; `null` clears the override. Read `stack_status` with the returned `result.stack.id` to verify policy and Cyclone ownership.
 - `stack_list` returns the current API key owner's registered stacks.
+- `stack_set({ stack_id, auto_land?, auto_review?, auto_patch? })` sets per-stack policy on one owned stack. `auto_land` flips Auto land. `auto_review` and `auto_patch` pin Vortex auto-review or Cyclone auto-patch for that stack in either direction (`true` or `false`); `null` clears the pin so the stack follows the account setting. Pass at least one key. Account settings are never changed here.
 - `stack_status({ stack_id })` returns one owned stack with enriched checks and agent state, or a structured `stack_not_found` error.
+- `stack_wait({ stack_id, timeout_s?, enrolled_head_sha?, after_finished_at?, bounce_id? })` waits for a stack or queue state change and returns the latest snapshots, or a waiting result with selectors to use for the next call.
 
 Auth is `MERGESTORM_API_KEY`, then `~/.mergestorm/config.json` (same as `mg`).
 

package/dist/index.js

@@ -5,8 +5,8 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { CommandError as CommandError10 } from "mergestorm/client";
+import { z as z3 } from "zod";
+import { CommandError as CommandError11, BEARER_SETTINGS as BEARER_SETTINGS2 } from "mergestorm/client";
 
 // src/tools/credits.ts
 import { CommandError, getMe, loadConfig } from "mergestorm/client";
@@ -25,8 +25,10 @@ async function credits(cfg) {
   }
   const standard = me.usage.standard;
   const remaining = standard.remaining ?? (standard.limit != null ? Math.max(0, standard.limit - standard.used) : null);
+  const bonusRemaining = me.usage.bonus?.remaining;
+  const bonusSummary = bonusRemaining == null ? "" : ` \xB7 ${bonusRemaining} bonus remaining`;
   return {
-    summary: remaining == null ? `${standard.used} used \xB7 unlimited` : `${standard.used} used \xB7 ${remaining} remaining`,
+    summary: remaining == null ? `${standard.used} used \xB7 unlimited${bonusSummary}` : `${standard.used} used \xB7 ${remaining} remaining${bonusSummary}`,
     data: {
       usage: me.usage,
       resets_at: me.resets_at ?? null
@@ -44,20 +46,29 @@ import {
   REVIEW_EXIT
 } from "mergestorm/client";
 function entrySummary(entry) {
-  const repo = entry.owner && entry.repo ? `${entry.owner}/${entry.repo}` : "unknown repo";
-  const position = entry.position === void 0 ? "queue" : `#${entry.position}`;
-  return `${position} \xB7 ${repo} \xB7 stack ${entry.stackId ?? "unknown"} \xB7 ${entry.state ?? "unknown"}`;
+  const prNumber = entry.bounceDetail?.prNumber;
+  const repo = `${entry.owner}/${entry.repo}${prNumber ? `#${prNumber}` : ""}`;
+  const reason = entry.bounceDetail?.kind ?? entry.bounceReason ?? entry.waitReason ?? void 0;
+  const sha = entry.bounceDetail?.headSha ?? entry.verifyHeadSha ?? void 0;
+  return [
+    entry.state,
+    repo,
+    `stack ${entry.stackId}`,
+    reason,
+    sha?.slice(0, 7)
+  ].filter(Boolean).join(" \xB7 ");
 }
 async function queueStatus(stackId, cfg) {
   try {
     const resolved = cfg ?? await loadConfig2();
+    const id = stackId?.trim();
     const { status, body, retryAfterSeconds } = await apiFetch(
       resolved,
-      "/api/v1/stacks/queue"
+      id ? `/api/v1/stacks/queue?stackId=${encodeURIComponent(id)}` : "/api/v1/stacks/queue"
     );
     if (status === 404) {
       throw new CommandError2(
-        "Merge queue API is not available on this server yet. Deploy the API update or use the dashboard."
+        "Merge queue route returned 404. Deploy the API."
       );
     }
     if (status === 429) {
@@ -79,11 +90,12 @@ async function queueStatus(stackId, cfg) {
         `Failed to get queue status (HTTP 200): ${JSON.stringify(body)}`
       );
     }
-    const id = stackId?.trim();
     if (id) {
-      const entry = entries.find((candidate) => candidate?.stackId === id);
-      if (!entry) {
-        const message = `Live queue entry not found for stack: ${id}`;
+      const matchingEntries = entries.filter(
+        (candidate) => candidate?.stackId?.toLowerCase() === id.toLowerCase()
+      );
+      if (matchingEntries.length === 0) {
+        const message = `Queue entry not found for stack: ${id}`;
         return {
           summary: message,
           data: {
@@ -97,12 +109,12 @@ async function queueStatus(stackId, cfg) {
         };
       }
       return {
-        summary: entrySummary(entry),
-        data: { entry }
+        summary: matchingEntries.map(entrySummary).join("\n"),
+        data: { entries: matchingEntries }
       };
     }
     return {
-      summary: entries.length === 0 ? "No live merge queue entries" : entries.map(entrySummary).join("\n"),
+      summary: entries.length === 0 ? "No merge queue entries (live or bounced)" : entries.map(entrySummary).join("\n"),
       data: { entries }
     };
   } catch (err) {
@@ -141,9 +153,21 @@ function prReviewTarget(owner, repo, prNumber) {
   }
   return { owner: cleanOwner, repo: cleanRepo, prNumber };
 }
+function prReviewSummary(owner, repo, prNumber, envelope) {
+  const bits = [`${owner}/${repo}#${prNumber}`, envelope.status];
+  const sha = envelope.head_sha?.trim();
+  if (sha) bits.push(`sha ${sha.slice(0, 7)}`);
+  if (typeof envelope.finding_count === "number") {
+    bits.push(
+      `${envelope.finding_count} finding${envelope.finding_count === 1 ? "" : "s"}`
+    );
+  }
+  if (envelope.phase) bits.push(String(envelope.phase));
+  return bits.join(" \xB7 ");
+}
 function payloadFromPrReview(owner, repo, prNumber, envelope) {
   return {
-    summary: `${owner}/${repo}#${prNumber} \xB7 ${envelope.status}`,
+    summary: prReviewSummary(owner, repo, prNumber, envelope),
     data: { ...envelope }
   };
 }
@@ -158,14 +182,15 @@ function payloadFromPrRateLimit(err, owner, repo, prNumber) {
     }
   };
 }
-async function reviewGetPr(owner, repo, prNumber, cfg) {
+async function reviewGetPr(owner, repo, prNumber, cfg, opts = {}) {
   const target = prReviewTarget(owner, repo, prNumber);
   try {
     const envelope = await getPrVortexReview(
       target.owner,
       target.repo,
       target.prNumber,
-      cfg
+      cfg,
+      { afterSha: opts.afterSha, pass: opts.pass, afterPass: opts.afterPass }
     );
     return payloadFromPrReview(
       target.owner,
@@ -259,6 +284,8 @@ import {
   REVIEW_THREAD_SLUG_RE,
   ReviewPollTimeoutError,
   collectReviewInput,
+  discoverTrunk,
+  formatReviewSubmitError,
   loadConfig as loadConfig3,
   loadReviewContext,
   pollReview,
@@ -266,6 +293,7 @@ import {
   submitReview
 } from "mergestorm/client";
 var MCP_WAIT_CEILING_S = 300;
+var MCP_PR_WAIT_DEFAULT_S = 45;
 var PINNABLE_SPECIALISTS = [
   "security",
   "performance",
@@ -290,8 +318,8 @@ function assertPinnableSpecialists(specialists) {
 function mcpSandboxRoot() {
   return process.env.MERGESTORM_SANDBOX_ROOT?.trim() || process.cwd();
 }
-function waitTimeoutMs(timeout_s) {
-  const seconds = timeout_s ?? MCP_WAIT_CEILING_S;
+function waitTimeoutMs(timeout_s, defaultSeconds = MCP_PR_WAIT_DEFAULT_S) {
+  const seconds = timeout_s ?? defaultSeconds;
   if (!Number.isFinite(seconds) || seconds <= 0) {
     throw new CommandError5("timeout_s must be a positive number of seconds", 2, "usage");
   }
@@ -306,13 +334,18 @@ async function resolveInput(input) {
     return {
       thread,
       branch,
-      baseLabel: input.base?.trim() || "main",
+      baseLabel: input.base?.trim() || (() => {
+        try {
+          return discoverTrunk(cwd);
+        } catch {
+          return "main";
+        }
+      })(),
       headLabel: head,
       diff: input.diff,
       files: []
     };
   }
-  const bases = input.base?.trim() ? [input.base.trim()] : ["main", "master"];
   const sandboxRoot = mcpSandboxRoot();
   try {
     const [sandboxReal, cwdReal] = await Promise.all([
@@ -327,27 +360,12 @@ async function resolveInput(input) {
     if (err instanceof CommandError5) throw err;
     throw new CommandError5("cwd must be inside the configured sandbox root", 2, "usage");
   }
-  let lastErr;
-  let collected = null;
-  let yielded = false;
-  for (const base of bases) {
-    try {
-      const candidate = await collectReviewInput(base, head, cwd, sandboxRoot);
-      yielded = true;
-      if (!collected) collected = candidate;
-    } catch (err) {
-      if (yielded) continue;
-      lastErr = err;
-      if (input.base?.trim()) throw err;
-    }
-  }
-  if (yielded) return collected;
-  if (lastErr) throw lastErr;
-  return null;
+  const base = input.base?.trim() || discoverTrunk(cwd);
+  return collectReviewInput(base, head, cwd, sandboxRoot);
 }
 async function reviewSubmit(input, cfg, opts = {}) {
   const resolved = cfg ?? await loadConfig3();
-  const wait = input.wait !== false;
+  const wait = input.wait === true;
   const timeoutMs = waitTimeoutMs(input.timeout_s);
   assertPinnableSpecialists(input.specialists);
   if (input.thread && !REVIEW_THREAD_SLUG_RE.test(input.thread)) {
@@ -395,7 +413,13 @@ async function reviewSubmit(input, cfg, opts = {}) {
     });
   }
   if (submitted.status !== 202 && submitted.status !== 200) {
-    throw new CommandError5(JSON.stringify(submitted.row));
+    return {
+      ...payloadFromRow({ ...submitted.row, status: "failed" }, {
+        jobId,
+        error: formatReviewSubmitError(submitted.status, submitted.row)
+      }),
+      isError: true
+    };
   }
   if (!jobId) {
     throw new CommandError5("Review API returned no job_id");
@@ -440,8 +464,10 @@ async function reviewWaitPr(owner, repo, prNumber, afterSha, timeout_s, cfg, opt
       target.repo,
       target.prNumber,
       {
-        timeoutMs: waitTimeoutMs(timeout_s),
+        timeoutMs: waitTimeoutMs(timeout_s, MCP_PR_WAIT_DEFAULT_S),
         afterSha,
+        pass: opts.pass,
+        afterPass: opts.afterPass,
         intervalMs: opts.pollIntervalMs
       }
     );
@@ -455,7 +481,12 @@ async function reviewWaitPr(owner, repo, prNumber, afterSha, timeout_s, cfg, opt
     if (err instanceof PrReviewPollTimeoutError) {
       const status = err.lastEnvelope?.status ?? "in_progress";
       return {
-        summary: `${target.owner}/${target.repo}#${target.prNumber} \xB7 ${status}`,
+        summary: prReviewSummary(target.owner, target.repo, target.prNumber, {
+          status,
+          head_sha: err.lastEnvelope?.head_sha ?? null,
+          finding_count: err.lastEnvelope?.finding_count ?? null,
+          phase: err.lastEnvelope?.phase ?? null
+        }),
         data: {
           ...err.lastEnvelope ?? {},
           status,
@@ -533,6 +564,7 @@ async function settingsGet(cfg) {
 // src/tools/settings-set.ts
 import {
   CommandError as CommandError8,
+  BEARER_SETTINGS,
   SETTINGS_WRITABLE_KEYS,
   patchSettings
 } from "mergestorm/client";
@@ -550,13 +582,17 @@ function settingsPatchFromArgs(args) {
   for (const key of SETTINGS_WRITABLE_KEYS) {
     const value = args[key];
     if (value === void 0) continue;
+    const row = BEARER_SETTINGS.find((row2) => row2.key === key);
+    if ("kind" in row) {
+      const valid = row.kind === "logins" ? Array.isArray(value) && value.every((login) => typeof login === "string") : typeof value === "string" && row.values.includes(value);
+      if (!valid) throw new CommandError8(`Invalid value for ${key}.`, 2, "usage");
+      Object.assign(patch, { [key]: value });
+      continue;
+    }
     if (typeof value !== "boolean") {
       throw new CommandError8(`${key} takes a boolean.`, 2, "usage");
     }
-    if (key === "auto_patch_enabled" && value === true) {
-      throw new CommandError8("auto_patch_enabled cannot be enabled by this tool.", 2, "usage");
-    }
-    patch[key] = value;
+    Object.assign(patch, { [key]: value });
   }
   if (Object.keys(patch).length === 0) {
     throw new CommandError8(
@@ -576,24 +612,192 @@ async function settingsSet(args, cfg) {
   };
 }
 
+// src/tools/stack-adopt.ts
+import { adoptStack, CommandError as CommandError9 } from "mergestorm/client";
+import { z } from "zod";
+
+// src/tools/stack-set.ts
+import { setStackPolicy } from "mergestorm/client";
+function triWord(value) {
+  return value === null ? "default" : value ? "on" : "off";
+}
+function stackSetPatch(input) {
+  const patch = {};
+  if (typeof input.auto_land === "boolean") patch.autoEnqueueWhenReady = input.auto_land;
+  if (input.auto_review !== void 0) patch.autoReviewOverride = input.auto_review;
+  if (input.auto_patch !== void 0) patch.autoPatchOverride = input.auto_patch;
+  return patch;
+}
+async function stackSet(stackId, input, cfg) {
+  const patch = stackSetPatch(input);
+  if (Object.keys(patch).length === 0) {
+    return {
+      summary: "stack_set needs at least one of auto_land, auto_review, auto_patch",
+      isError: true,
+      data: {
+        error: {
+          code: "invalid_input",
+          message: "Pass at least one of auto_land, auto_review, auto_patch.",
+          stack_id: stackId
+        }
+      }
+    };
+  }
+  const result = await setStackPolicy(stackId, patch, cfg);
+  const parts = [];
+  if (typeof input.auto_land === "boolean") {
+    parts.push(`Auto land ${input.auto_land ? "on" : "off"}`);
+  }
+  if (input.auto_review !== void 0) {
+    parts.push(`auto-review ${triWord(input.auto_review)}`);
+  }
+  if (input.auto_patch !== void 0) {
+    parts.push(`auto-patch ${triWord(input.auto_patch)}`);
+  }
+  return {
+    summary: `${parts.join(", ")} for stack ${stackId}`,
+    data: {
+      stack_id: stackId,
+      ...typeof input.auto_land === "boolean" ? { auto_land: input.auto_land } : {},
+      ...input.auto_review !== void 0 ? { auto_review: input.auto_review } : {},
+      ...input.auto_patch !== void 0 ? { auto_patch: input.auto_patch } : {},
+      result
+    }
+  };
+}
+
+// src/tools/stack-adopt.ts
+var stackAdoptSchema = {
+  owner: z.string().trim().min(1),
+  repo: z.string().trim().min(1),
+  pr_number: z.number().int().min(1),
+  auto_land: z.boolean().optional(),
+  auto_review: z.boolean().nullable().optional(),
+  auto_patch: z.boolean().nullable().optional()
+};
+var inputSchema = z.object(stackAdoptSchema);
+async function stackAdopt(input, cfg) {
+  const parsed = inputSchema.safeParse(input);
+  if (!parsed.success) {
+    const message = "stack_adopt requires owner, repo, a positive pr_number, and valid policy values";
+    return { summary: message, data: { error: { code: "invalid_input", message } }, isError: true };
+  }
+  const { owner, repo, pr_number } = parsed.data;
+  try {
+    const result = await adoptStack(
+      owner,
+      repo,
+      pr_number,
+      cfg,
+      stackSetPatch(parsed.data)
+    );
+    return {
+      summary: `Adopted stack for ${owner}/${repo}#${pr_number}`,
+      data: { owner, repo, pr_number, result }
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      summary: message,
+      data: {
+        error: {
+          code: err instanceof CommandError9 ? err.code ?? "stack_adopt_failed" : "stack_adopt_failed",
+          message,
+          ...err instanceof CommandError9 && err.retryAfterSeconds !== void 0 ? { retry_after_seconds: err.retryAfterSeconds } : {}
+        }
+      },
+      isError: true
+    };
+  }
+}
+
 // src/tools/stack-list.ts
-import { isCommandErrorCode as isCommandErrorCode4, listStacks } from "mergestorm/client";
+import {
+  isCommandErrorCode as isCommandErrorCode4,
+  listMergeQueueEntries,
+  listStacks
+} from "mergestorm/client";
 
 // src/tools/stack-summary.ts
-function stackSummary(stack) {
+import {
+  BOUNCE_KIND_LABELS,
+  mergeQueueBounceLabel
+} from "mergestorm/client";
+function sameHead(a, b) {
+  const left = a?.trim().toLowerCase();
+  const right = b?.trim().toLowerCase();
+  return !!left && !!right && (left.length === right.length ? left === right : left.startsWith(right) || right.startsWith(left));
+}
+function blockerLabel(stack, entries) {
+  if (stack.archivedAt) return null;
+  const queue = entries.filter((entry) => entry.stackId === stack.id);
+  if (queue.some((entry) => ["queued", "running", "waiting"].includes(entry.state))) return null;
+  const open = stack.layers.filter(
+    (layer2) => layer2.prNumber > 0 && layer2.state !== "merged" && layer2.state !== "closed"
+  );
+  const promote = open.filter(
+    (layer2) => layer2.prNumber !== stack.unit?.landPrNumber && !stack.unit?.members?.some(
+      (member) => member.prNumber === layer2.prNumber && member.promotedHeadSha
+    )
+  ).sort((a, b) => a.position - b.position);
+  const layer = promote[0] ?? open.find((layer2) => layer2.prNumber === stack.unit?.landPrNumber) ?? stack.unit?.landPr;
+  const bounce = queue.filter((entry) => entry.state === "bounced").sort((a, b) => (Date.parse(b.finishedAt ?? "") || 0) - (Date.parse(a.finishedAt ?? "") || 0))[0];
+  const bounceKind = bounce?.bounceDetail?.kind;
+  const recoverableBounceSha = (bounceKind === "head_moved" ? bounce?.bounceDetail?.headSha ?? bounce?.verifyHeadSha : bounce?.verifyHeadSha ?? bounce?.bounceDetail?.headSha)?.trim().toLowerCase();
+  const currentRecoverableBounce = !!recoverableBounceSha && (bounceKind === "head_moved" || bounceKind === "must_consolidate") && !!layer && layer.state !== "merged" && layer.state !== "closed" && sameHead(layer.headSha, recoverableBounceSha);
+  if (layer && layer.state !== "merged" && layer.state !== "closed") {
+    if (layer.restackError && layer.state !== "restacking") {
+      return layer.restackError.kind === "rebase_conflict" ? "Conflict" : "Restack failed";
+    }
+    if (layer.state === "conflict") return "Conflict";
+    if (layer.draft) return "Draft PR";
+    if ((!layer.headSha || layer.mergeableHeadSha === layer.headSha) && (layer.mergeable === false || layer.mergeableState?.toLowerCase() === "dirty")) return "Merge conflicts";
+    if (!currentRecoverableBounce && (layer.ciStatus === "failure" || (layer.checks?.failure ?? 0) > 0)) {
+      const name = layer.checks?.failingName?.trim();
+      return BOUNCE_KIND_LABELS.ci_failure + (name ? ` \u2014 ${name}` : "");
+    }
+    const tempest = layer.agentRuns?.find(
+      (run) => run.agent === "tempest" && ["findings", "failed"].includes(run.status) && sameHead(run.sha, layer.headSha)
+    );
+    if (tempest) return `Tempest ${tempest.status}`;
+    if (layer.vortexStatus === "failed") return "Review failed";
+    if (stack.unit?.landPrNumber === layer.prNumber) {
+      if (stack.unit.landingBlockReason?.trim()) return stack.unit.landingBlockReason.trim();
+      if (stack.unit.tempestLandStatus?.toLowerCase() === "failed") return "Tempest failed";
+    }
+  }
+  const kind = bounceKind;
+  if (!kind || kind === "head_moved" || kind === "must_consolidate") return null;
+  const sha = (bounce.bounceDetail?.headSha ?? bounce.verifyHeadSha)?.trim().toLowerCase();
+  const current = sha && layer && layer.prNumber > 0 && layer.state !== "merged" && layer.state !== "closed" && (bounce.bounceDetail?.prNumber == null || layer.prNumber === bounce.bounceDetail.prNumber) && sameHead(layer.headSha, sha);
+  return current ? mergeQueueBounceLabel(bounce) : null;
+}
+function stackSummary(stack, entries = []) {
   const count = stack.layers.length;
   const layerLabel = `${count} layer${count === 1 ? "" : "s"}`;
   const states = [...new Set(stack.layers.map((layer) => layer.state))];
   const currentState = states.length > 0 ? `layers: ${states.join(", ")}` : stack.unit ? `unit: ${stack.unit.state}` : "no open layers";
-  return `${stack.owner}/${stack.repo} \xB7 ${layerLabel} \xB7 ${currentState}`;
+  const overrides = [];
+  if (typeof stack.autoReviewOverride === "boolean") {
+    overrides.push(`auto-review ${stack.autoReviewOverride ? "on" : "off"}`);
+  }
+  if (typeof stack.autoPatchOverride === "boolean") {
+    overrides.push(`auto-patch ${stack.autoPatchOverride ? "on" : "off"}`);
+  }
+  if (stack.cycloneOwnerMatch) {
+    overrides.push(`cyclone-owner ${stack.cycloneOwnerMatch}`);
+  }
+  const blocker = blockerLabel(stack, entries);
+  return `${stack.owner}/${stack.repo} \xB7 ${layerLabel} \xB7 ${currentState} \xB7 auto-land ${stack.autoEnqueueWhenReady ? "on" : "off"}${overrides.map((label) => ` \xB7 ${label}`).join("")}${blocker ? ` \xB7 blocked: ${blocker}` : ""}`;
 }
 
 // src/tools/stack-list.ts
 async function stackList(cfg) {
   try {
     const stacks = await listStacks(cfg);
+    const entries = await listMergeQueueEntries(cfg);
     return {
-      summary: stacks.length === 0 ? "No stacks" : stacks.map((stack) => stackSummary(stack)).join("\n"),
+      summary: stacks.length === 0 ? "No stacks" : stacks.map((stack) => stackSummary(stack, entries)).join("\n"),
       data: { stacks }
     };
   } catch (err) {
@@ -614,8 +818,62 @@ async function stackList(cfg) {
   }
 }
 
+// src/tools/stack-wait.ts
+import {
+  loadConfig as loadConfig6,
+  pollStackWatch,
+  StackWatchError,
+  StackWatchTimeoutError
+} from "mergestorm/client";
+import { z as z2 } from "zod";
+var stackWaitSchema = {
+  stack_id: z2.string().trim().min(1),
+  timeout_s: z2.number().finite().min(0).max(45).default(45),
+  enrolled_head_sha: z2.string().nullable().optional(),
+  after_finished_at: z2.string().nullable().optional(),
+  bounce_id: z2.string().nullable().optional()
+};
+async function stackWait(input, cfg, deps = {}) {
+  const args = z2.object(stackWaitSchema).parse(input);
+  const cursor = args.enrolled_head_sha !== void 0 || args.after_finished_at !== void 0 || args.bounce_id !== void 0 ? {
+    stackId: args.stack_id,
+    enrolledHeadSha: args.enrolled_head_sha ?? null,
+    ...args.after_finished_at !== void 0 ? { afterFinishedAt: args.after_finished_at } : {},
+    ...args.bounce_id !== void 0 ? { bounceId: args.bounce_id } : {}
+  } : void 0;
+  let envelope;
+  try {
+    envelope = await (deps.pollStackWatch ?? pollStackWatch)(cfg ?? await loadConfig6(), args.stack_id, {
+      timeoutMs: args.timeout_s * 1e3,
+      cursor,
+      signal: deps.signal
+    });
+  } catch (err) {
+    if (err instanceof StackWatchError) {
+      return {
+        summary: `Stack ${err.lastEnvelope.stackId} \xB7 ${err.lastEnvelope.status}`,
+        data: {
+          ...err.lastEnvelope,
+          ...err.retryAfterSeconds !== void 0 ? { retry_after_seconds: err.retryAfterSeconds } : {}
+        },
+        isError: true
+      };
+    }
+    if (!(err instanceof StackWatchTimeoutError)) throw err;
+    envelope = { ...err.lastEnvelope, status: "waiting" };
+  }
+  return {
+    summary: `Stack ${envelope.stackId} \xB7 ${envelope.status}${envelope.blocker ? ` \xB7 ${envelope.blocker}` : ""}`,
+    data: envelope
+  };
+}
+
 // src/tools/stack-status.ts
-import { getEnrichedStack, isCommandErrorCode as isCommandErrorCode5 } from "mergestorm/client";
+import {
+  getEnrichedStack,
+  listMergeQueueEntries as listMergeQueueEntries2,
+  isCommandErrorCode as isCommandErrorCode5
+} from "mergestorm/client";
 async function stackStatus(stackId, cfg) {
   try {
     const stack = await getEnrichedStack(stackId, cfg);
@@ -633,8 +891,9 @@ async function stackStatus(stackId, cfg) {
         isError: true
       };
     }
+    const entries = await listMergeQueueEntries2(cfg);
     return {
-      summary: stackSummary(stack),
+      summary: stackSummary(stack, entries),
       data: { stack }
     };
   } catch (err) {
@@ -657,33 +916,35 @@ async function stackStatus(stackId, cfg) {
 
 // src/tools/whoami.ts
 import {
-  CommandError as CommandError9,
+  CommandError as CommandError10,
   apiBase,
   configPath,
   getMe as getMe2,
-  keyDisplay,
-  loadConfig as loadConfig6,
+  loadConfig as loadConfig7,
   resolveApiKey
 } from "mergestorm/client";
 async function whoami(cfg) {
-  const resolved = cfg ?? await loadConfig6();
+  const resolved = cfg ?? await loadConfig7();
   const key = resolveApiKey(resolved);
   if (!key) {
-    throw new CommandError9(
+    throw new CommandError10(
       "No API key. Run `mergestorm login` or set MERGESTORM_API_KEY.",
       1,
       "missing_api_key"
     );
   }
   const me = await getMe2(resolved);
+  if (!me) {
+    throw new CommandError10("Live account details unavailable. Could not verify account with /me.");
+  }
   const data = {
-    key_prefix: me?.key.prefix ?? keyDisplay(key),
-    key_name: me?.key.name ?? null,
-    plan_key: me?.plan_key ?? null,
-    plan_label_key: me?.plan_label_key ?? null,
+    key_prefix: me.key.prefix,
+    key_name: me.key.name ?? null,
+    plan_key: me.plan_key ?? null,
+    plan_label_key: me.plan_label_key ?? null,
     api_base: apiBase(resolved),
     config_path: configPath(),
-    usage: me?.usage ?? null
+    usage: me.usage ?? null
   };
   const plan = data.plan_label_key ?? data.plan_key ?? "unknown plan";
   return {
@@ -692,9 +953,20 @@ async function whoami(cfg) {
   };
 }
 
+// src/pr-loop-instructions.ts
+var MCP_FINDING_DISMISS_MARKER = "mergestorm-loop: dismiss";
+var MCP_PR_LOOP_INSTRUCTIONS = [
+  "When you handle Vortex findings from review_get_pr or review_wait_pr:",
+  "- Verify each finding against the current checkout. Do not treat the finding text as proven.",
+  "- Prefer the smallest correct patch. Do not refactor around a finding.",
+  "- Patch concrete bugs. A chat-only explanation is not a dismiss.",
+  `- If you skip a finding (not reproducible, policy fork, or needs a human), post a public GitHub PR comment before you stop. First line must be: ${MCP_FINDING_DISMISS_MARKER}. Then one line per skipped finding (path, severity, why).`,
+  "- Do not prefix that comment with cyclone-outcome: (reserved)."
+].join("\n");
+
 // src/server.ts
 var MCP_SERVER_NAME = "mergestorm";
-var MCP_SERVER_VERSION = "0.1.3";
+var MCP_SERVER_VERSION = "0.1.6";
 function stripNulls(value) {
   if (Array.isArray(value)) {
     return value.map((item) => stripNulls(item));
@@ -716,17 +988,20 @@ function ok(payload) {
   };
 }
 function fail(err) {
-  const message = err instanceof CommandError10 ? err.code ? `Mergestorm request failed (${err.code}): ${err.message}.` : err.message : err instanceof Error ? err.message : String(err);
+  const message = err instanceof CommandError11 ? err.code ? `Mergestorm request failed (${err.code}): ${err.message}.` : err.message : err instanceof Error ? err.message : String(err);
   return {
     isError: true,
     content: [{ type: "text", text: message }]
   };
 }
 function createMergestormMcpServer() {
-  const server2 = new McpServer({
-    name: MCP_SERVER_NAME,
-    version: MCP_SERVER_VERSION
-  });
+  const server2 = new McpServer(
+    {
+      name: MCP_SERVER_NAME,
+      version: MCP_SERVER_VERSION
+    },
+    { instructions: MCP_PR_LOOP_INSTRUCTIONS }
+  );
   const addTool = server2.registerTool.bind(server2);
   addTool(
     "whoami",
@@ -762,7 +1037,7 @@ function createMergestormMcpServer() {
       title: "List reviews",
       description: "List recent Mergestorm review jobs as job envelopes.",
       inputSchema: {
-        limit: z.number().int().min(1).max(50).optional()
+        limit: z3.number().int().min(1).max(50).optional()
       }
     },
     async ({ limit }) => {
@@ -779,7 +1054,7 @@ function createMergestormMcpServer() {
       title: "Get review",
       description: "Fetch one Mergestorm review job as a job envelope. On rate_limited, wait retry_after_seconds before trying again.",
       inputSchema: {
-        job_id: z.string().min(1)
+        job_id: z3.string().min(1)
       }
     },
     async ({ job_id }) => {
@@ -794,16 +1069,25 @@ function createMergestormMcpServer() {
     "review_get_pr",
     {
       title: "Get GitHub PR Vortex review",
-      description: "Fetch the latest GitHub PR Vortex pass from the DB-only endpoint. This tool is read-only. On rate_limited, wait retry_after_seconds before trying again.",
+      description: "Fetch the latest GitHub PR Vortex pass from the DB-only endpoint. Review identity is SHA + pass: the envelope carries pass (1 for the first review on a head; a re-review on the same head is the next pass). Pass after_sha to scope to a head, pass to read one exact attempt, or after_pass to read only a later attempt on that head. This tool is read-only. On rate_limited, wait retry_after_seconds before trying again. Verify each finding against the current code; prefer the smallest correct patch; a chat-only skip is not a dismiss (post a PR comment starting with mergestorm-loop: dismiss).",
       inputSchema: {
-        owner: z.string().min(1),
-        repo: z.string().min(1),
-        pr_number: z.number().int().min(1)
+        owner: z3.string().min(1),
+        repo: z3.string().min(1),
+        pr_number: z3.number().int().min(1),
+        after_sha: z3.string().optional(),
+        pass: z3.number().int().min(1).optional(),
+        after_pass: z3.number().int().min(1).optional()
       }
     },
-    async ({ owner, repo, pr_number }) => {
+    async ({ owner, repo, pr_number, after_sha, pass, after_pass }) => {
       try {
-        return ok(await reviewGetPr(owner, repo, pr_number));
+        return ok(
+          await reviewGetPr(owner, repo, pr_number, void 0, {
+            afterSha: after_sha,
+            pass,
+            afterPass: after_pass
+          })
+        );
       } catch (err) {
         return fail(err);
       }
@@ -813,20 +1097,20 @@ function createMergestormMcpServer() {
     "review_submit",
     {
       title: "Submit review",
-      description: "Submit a local git diff (or an explicit diff) as a Mergestorm review job. Default waits up to 300s. On rate_limited, wait retry_after_seconds and inspect or wait for an in-flight review before resubmitting. specialists may be security, performance, architecture, tests, data, api, frontend. governance and seam cannot be requested.",
+      description: "Submit a local git diff (or an explicit diff) as a Mergestorm review job. Does not wait by default; returns job_id immediately after submission. Explicit wait: true polls one 45s slice by default. Record job_id and loop review_wait until done. Do not pass 300; hosts drop long MCP calls. On rate_limited, wait retry_after_seconds and inspect or wait for an in-flight review before resubmitting. specialists may be security, performance, architecture, tests, data, api, frontend. governance and seam cannot be requested.",
       inputSchema: {
-        cwd: z.string().optional(),
-        base: z.string().optional(),
-        head: z.string().optional(),
-        diff: z.string().optional(),
-        router: z.enum(["off", "standard", "max", "manual"]).optional(),
-        specialists: z.array(z.string().min(1)).max(5).optional(),
-        context: z.string().optional(),
-        context_files: z.array(z.string().min(1)).max(10).optional(),
-        thread: z.string().min(1).max(120).optional(),
-        idempotency_key: z.string().min(1).max(128).optional(),
-        wait: z.boolean().optional(),
-        timeout_s: z.number().positive().max(300).optional()
+        cwd: z3.string().optional(),
+        base: z3.string().optional(),
+        head: z3.string().optional(),
+        diff: z3.string().optional(),
+        router: z3.enum(["off", "standard", "max", "manual"]).optional(),
+        specialists: z3.array(z3.string().min(1)).max(5).optional(),
+        context: z3.string().optional(),
+        context_files: z3.array(z3.string().min(1)).max(10).optional(),
+        thread: z3.string().min(1).max(120).optional(),
+        idempotency_key: z3.string().min(1).max(128).optional(),
+        wait: z3.boolean().optional(),
+        timeout_s: z3.number().positive().max(300).optional()
       }
     },
     async (args) => {
@@ -841,10 +1125,10 @@ function createMergestormMcpServer() {
     "review_wait",
     {
       title: "Wait for review",
-      description: "Poll one Mergestorm review job until it finishes, return in_progress after 300s, or return rate_limited with retry_after_seconds.",
+      description: "Poll one Mergestorm review job for one 45s slice by default (max 300s). On timeout, returns in_progress; call again with the same job_id until done. Do not pass 300; hosts drop long MCP calls. On rate_limited, wait retry_after_seconds before trying again.",
       inputSchema: {
-        job_id: z.string().min(1),
-        timeout_s: z.number().positive().max(300).optional()
+        job_id: z3.string().min(1),
+        timeout_s: z3.number().positive().max(300).optional()
       }
     },
     async ({ job_id, timeout_s }) => {
@@ -859,16 +1143,18 @@ function createMergestormMcpServer() {
     "review_wait_pr",
     {
       title: "Wait for GitHub PR Vortex review",
-      description: "Poll the DB-only GitHub PR Vortex pass until it rests. This tool is read-only. On timeout, returns in_progress. On rate_limited, wait retry_after_seconds before trying again.",
+      description: "Poll the DB-only GitHub PR Vortex pass for up to 45s (pass timeout_s to override, max 300). Review identity is SHA + pass. Pass after_sha for the head you pushed. When you already hold an envelope for that same head, also pass after_pass set to its pass so the wait cannot return that attempt again; keep after_pass unchanged across timeout retries and never replace it with the pass of an in-progress envelope. Omit after_pass for a head you have no envelope for (its first pass is 1). This tool is read-only. On timeout, returns in_progress so you can call again. Do not pass 300; hosts drop long MCP calls. On rate_limited, wait retry_after_seconds before trying again. After a resting pass, verify each finding; prefer the smallest correct patch; if you skip, post a PR comment starting with mergestorm-loop: dismiss.",
       inputSchema: {
-        owner: z.string().min(1),
-        repo: z.string().min(1),
-        pr_number: z.number().int().min(1),
-        after_sha: z.string().optional(),
-        timeout_s: z.number().positive().max(300).optional()
+        owner: z3.string().min(1),
+        repo: z3.string().min(1),
+        pr_number: z3.number().int().min(1),
+        after_sha: z3.string().optional(),
+        pass: z3.number().int().min(1).optional(),
+        after_pass: z3.number().int().min(1).optional(),
+        timeout_s: z3.number().positive().max(300).optional()
       }
     },
-    async ({ owner, repo, pr_number, after_sha, timeout_s }) => {
+    async ({ owner, repo, pr_number, after_sha, pass, after_pass, timeout_s }) => {
       try {
         return ok(
           await reviewWaitPr(
@@ -876,7 +1162,9 @@ function createMergestormMcpServer() {
             repo,
             pr_number,
             after_sha,
-            timeout_s
+            timeout_s,
+            void 0,
+            { pass, afterPass: after_pass }
           )
         );
       } catch (err) {
@@ -884,6 +1172,21 @@ function createMergestormMcpServer() {
       }
     }
   );
+  addTool(
+    "stack_adopt",
+    {
+      title: "Adopt PR stack",
+      description: "Adopt an open GitHub PR chain into a Mergestorm stack. auto_land is boolean; auto_review and auto_patch accept true, false, or null, where null clears the override. Omitted auto_land seeds from auto_land_default; omitted auto_review and auto_patch overrides are not seeded. Never changes account settings. Adoption requires a Cyclone GitHub App install; without it the API returns cyclone_not_connected \u2014 do not retry, tell the human. Read stack_status with result.stack.id afterward to verify policy and Cyclone ownership.",
+      inputSchema: stackAdoptSchema
+    },
+    async (args) => {
+      try {
+        return ok(await stackAdopt(args));
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  );
   addTool(
     "stack_list",
     {
@@ -898,13 +1201,39 @@ function createMergestormMcpServer() {
       }
     }
   );
+  addTool(
+    "stack_set",
+    {
+      title: "Set stack policy",
+      description: "Set per-stack automation on one owned Mergestorm stack: auto_land arms or disarms Auto land; auto_review and auto_patch pin Vortex auto-review or Cyclone auto-patch for this stack only (true or false), and null clears the pin so the stack follows the account setting again. Pass at least one key. Never changes account settings.",
+      inputSchema: {
+        stack_id: z3.string().min(1),
+        auto_land: z3.boolean().optional(),
+        auto_review: z3.boolean().nullable().optional(),
+        auto_patch: z3.boolean().nullable().optional()
+      }
+    },
+    async ({ stack_id, auto_land, auto_review, auto_patch }) => {
+      try {
+        return ok(
+          await stackSet(stack_id, {
+            ...auto_land !== void 0 ? { auto_land } : {},
+            ...auto_review !== void 0 ? { auto_review } : {},
+            ...auto_patch !== void 0 ? { auto_patch } : {}
+          })
+        );
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  );
   addTool(
     "stack_status",
     {
       title: "Get stack status",
       description: "Fetch one owned Mergestorm stack with enriched checks and agent state. This tool is read-only.",
       inputSchema: {
-        stack_id: z.string().min(1)
+        stack_id: z3.string().min(1)
       }
     },
     async ({ stack_id }) => {
@@ -915,13 +1244,29 @@ function createMergestormMcpServer() {
       }
     }
   );
+  addTool(
+    "stack_wait",
+    {
+      title: "Wait for stack attention",
+      description: "Wait for a stack to need attention. Returns a mergestorm.stack_watch/v1 envelope; timeout returns waiting. This tool is read-only. Do not pass 300; hosts drop long MCP calls.",
+      inputSchema: stackWaitSchema
+    },
+    async (args, extra) => {
+      try {
+        const payload = await stackWait(args, void 0, { signal: extra.signal });
+        return { ...ok(payload), structuredContent: payload.data };
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  );
   addTool(
     "queue_status",
     {
       title: "Get merge queue status",
-      description: "List live merge queue entries for the current user, optionally filtered by stack. This tool is read-only.",
+      description: "List live merge queue entries (position >= 1) plus the newest bounced entries (position 0) with bounceDetail for the current user, optionally filtered by stack. This tool is read-only.",
       inputSchema: {
-        stack_id: z.string().min(1).optional()
+        stack_id: z3.string().min(1).optional()
       }
     },
     async ({ stack_id }) => {
@@ -950,15 +1295,17 @@ function createMergestormMcpServer() {
     "settings_set",
     {
       title: "Update settings",
-      description: "Update writable Bearer /api/v1/settings toggles and return the stored result. At least one key is required. 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. cyclone_connected and github_connected are read-only and cannot be set.",
       inputSchema: {
-        auto_review_enabled: z.boolean().optional(),
-        auto_patch_enabled: z.boolean().optional(),
-        vortex_show_thinking_traces: z.boolean().optional(),
-        repo_overview_enabled: z.boolean().optional(),
-        review_unit_land_prs_enabled: z.boolean().optional(),
-        cyclone_review_unit_land_prs_enabled: z.boolean().optional(),
-        vortex_seam_specialist_enabled: z.boolean().optional()
+        ...Object.fromEntries(
+          BEARER_SETTINGS2.map((row) => [
+            row.key,
+            ("kind" in row ? row.kind === "logins" ? z3.array(z3.string()) : z3.enum(row.values) : z3.boolean()).optional()
+          ])
+        ),
+        // Preserve these args so the handler rejects them even alongside a writable key.
+        cyclone_connected: z3.unknown().optional(),
+        github_connected: z3.unknown().optional()
       }
     },
     async (args) => {

package/package.json

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