mergestorm-mcp 0.1.9 → 0.2.0

package/README.md

@@ -1,6 +1,10 @@
 # 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_adopt`, `stack_list`, `stack_set`, `stack_status`, `stack_wait`, `queue_status`, `settings_get`, `settings_set`.
+Stdio MCP server for Mergestorm. Tools: `whoami`, `credits`, `review_list`, `review_submit`, `review_wait`, `review_wait_pr`, `stack_adopt`, `stack_list`, `stack_set`, `stack_status`, `stack_wait`, `queue_status`, `settings_get`, `settings_set`.
+
+Every tool declares MCP `annotations`. The reads carry `readOnlyHint: true`; `review_submit`, `stack_adopt`, `stack_set`, and `settings_set` carry `readOnlyHint: false` and `destructiveHint: false`.
+
+`review_wait({ job_id, timeout_s? })` reads a local review job by the `job_id` that `review_submit` returned. `review_wait_pr({ owner, repo, pr_number, after_sha?, pass?, after_pass?, timeout_s? })` reads the Vortex pass on a GitHub PR. Both poll one 45s slice by default; `timeout_s: 0` reads once without polling.
 
 The stack tools expose reads plus one scoped policy write:
 
@@ -8,7 +12,7 @@ The stack tools expose reads plus one scoped policy write:
 - `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, plus `attention`, `issues`, and `currentCandidate` from the same blocker rules as `stack_wait`, read against that stack's own merge queue. It returns a structured `stack_not_found` or `rate_limited` 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. `timeout_s: 0` returns one snapshot; a positive timeout after a snapshot with no attention returns the current `waiting` or `in_progress` status with selectors to use for the next call. An unread deadline returns `failed`.
+- `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. `timeout_s: 0` returns one snapshot; a positive timeout after a snapshot with no attention returns the current `waiting` or `in_progress` status with selectors to use for the next call. An unread deadline returns `failed`. While Cyclone or Vortex is still working on the blocked PR, `stack_wait` and `stack_status` return `in_progress` instead of `attention`, with `busy[]` naming the PR, blocker, and agent, and `agents` carrying that PR's `vortexStatus`, `cycloneStatus`, `vortexReview`, and busy flags. A nonempty `busy[]` means wait. A queued Vortex run holds for at most 15 minutes, `seam_pending` alone does not hold, and reviewing or patching holds until the run finishes or its lease or check run is cleared. A hold can hide a blocker no agent clears (such as Draft); if it looks stuck, refresh `stack_status` and tell the human.
 
 Auth is `MERGESTORM_API_KEY`, then `~/.mergestorm/config.json` (same as `mg`).
 

package/dist/index.js

@@ -8,6 +8,33 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z as z3 } from "zod";
 import { CommandError as CommandError11, BEARER_SETTINGS as BEARER_SETTINGS2 } from "mergestorm/client";
 
+// src/brand-icons.ts
+var MARK_RECTS = [
+  { x: 103.685, y: 79.639, width: 336.635, height: 32.005 },
+  { x: 71.68, y: 143.816, width: 288.545, height: 32.005 },
+  { x: 103.685, y: 207.993, width: 192.363, height: 32.005 },
+  { x: 151.775, y: 272.002, width: 176.277, height: 32.005 },
+  { x: 215.952, y: 336.179, width: 96.182, height: 32.005 },
+  { x: 264.043, y: 400.356, width: 32.005, height: 32.005 }
+];
+var SITE = "https://mergestorm.ai";
+function markSvg(fill) {
+  const rects = MARK_RECTS.map(
+    (r) => `<rect x="${r.x}" y="${r.y}" width="${r.width}" height="${r.height}" fill="${fill}"/>`
+  ).join("");
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="64 64 384 384">${rects}</svg>`;
+}
+function svgDataUri(svg) {
+  return `data:image/svg+xml;base64,${Buffer.from(svg, "utf8").toString("base64")}`;
+}
+var MCP_SERVER_ICONS = [
+  { src: svgDataUri(markSvg("#000000")), mimeType: "image/svg+xml", sizes: ["any"], theme: "light" },
+  { src: svgDataUri(markSvg("#ffffff")), mimeType: "image/svg+xml", sizes: ["any"], theme: "dark" },
+  { src: `${SITE}/images/android-chrome-192x192.png`, mimeType: "image/png", sizes: ["192x192"] },
+  { src: `${SITE}/images/android-chrome-512x512.png`, mimeType: "image/png", sizes: ["512x512"] }
+];
+var MCP_WEBSITE_URL = SITE;
+
 // src/tools/credits.ts
 import { CommandError, getMe, loadConfig } from "mergestorm/client";
 async function credits(cfg) {
@@ -135,95 +162,43 @@ async function queueStatus(stackId, cfg) {
   }
 }
 
-// src/tools/review-get-pr.ts
-import {
-  CommandError as CommandError3,
-  getPrVortexReview,
-  isCommandErrorCode as isCommandErrorCode2
-} from "mergestorm/client";
-function prReviewTarget(owner, repo, prNumber) {
-  const cleanOwner = owner.trim();
-  const cleanRepo = repo.trim();
-  if (!cleanOwner || !cleanRepo || !Number.isInteger(prNumber) || prNumber <= 0) {
-    throw new CommandError3(
-      "owner, repo, and a positive pr_number are required",
-      2,
-      "usage"
-    );
-  }
-  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: prReviewSummary(owner, repo, prNumber, envelope),
-    data: { ...envelope }
-  };
-}
-function payloadFromPrRateLimit(err, owner, repo, prNumber) {
-  if (!isCommandErrorCode2(err, "rate_limited")) return null;
+// src/tools/review-list.ts
+import { listJobs, toReviewJobEnvelope } from "mergestorm/client";
+async function reviewList(limit = 10, cfg) {
+  const items = await listJobs(limit, cfg);
+  const envelopes = items.map((row) => toReviewJobEnvelope(row));
+  const n = envelopes.length;
   return {
-    summary: `${owner}/${repo}#${prNumber} \xB7 rate_limited`,
-    data: {
-      status: "rate_limited",
-      error: err.message,
-      retry_after_seconds: err.retryAfterSeconds
-    }
+    summary: n === 0 ? "No review jobs" : `${n} review job${n === 1 ? "" : "s"}`,
+    data: { items: envelopes }
   };
 }
-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,
-      { afterSha: opts.afterSha, pass: opts.pass, afterPass: opts.afterPass }
-    );
-    return payloadFromPrReview(
-      target.owner,
-      target.repo,
-      target.prNumber,
-      envelope
-    );
-  } catch (err) {
-    const rateLimited = payloadFromPrRateLimit(
-      err,
-      target.owner,
-      target.repo,
-      target.prNumber
-    );
-    if (rateLimited) return rateLimited;
-    throw err;
-  }
-}
 
-// src/tools/review-get.ts
+// src/tools/review-submit.ts
+import { createHash } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { relative, resolve, sep } from "node:path";
 import {
-  CommandError as CommandError4,
-  getReview,
-  toReviewJobEnvelope as toReviewJobEnvelope2
+  CommandError as CommandError3,
+  REVIEW_THREAD_SLUG_RE,
+  ReviewPollTimeoutError,
+  collectReviewInput,
+  discoverTrunk,
+  formatReviewSubmitError,
+  loadConfig as loadConfig3,
+  loadReviewContext,
+  pollReview,
+  rateLimitedMessage as rateLimitedMessage2,
+  submitReview
 } from "mergestorm/client";
 
 // src/tools/envelope.ts
 import {
-  isCommandErrorCode as isCommandErrorCode3,
-  toReviewJobEnvelope
+  isCommandErrorCode as isCommandErrorCode2,
+  toReviewJobEnvelope as toReviewJobEnvelope2
 } from "mergestorm/client";
 function payloadFromRow(row, fallback = {}) {
-  const envelope = toReviewJobEnvelope(row, fallback);
+  const envelope = toReviewJobEnvelope2(row, fallback);
   const bits = [envelope.status];
   if (envelope.verdict) bits.push(envelope.verdict);
   return {
@@ -232,7 +207,7 @@ function payloadFromRow(row, fallback = {}) {
   };
 }
 function payloadFromRateLimit(err, jobId) {
-  if (!isCommandErrorCode3(err, "rate_limited")) return null;
+  if (!isCommandErrorCode2(err, "rate_limited")) return null;
   return payloadFromRow(null, {
     jobId,
     status: "rate_limited",
@@ -241,57 +216,7 @@ function payloadFromRateLimit(err, jobId) {
   });
 }
 
-// src/tools/review-get.ts
-async function reviewGet(jobId, cfg) {
-  let row;
-  try {
-    row = await getReview(jobId, cfg);
-  } catch (err) {
-    const rateLimited = payloadFromRateLimit(err, jobId);
-    if (rateLimited) return rateLimited;
-    throw err;
-  }
-  if (!row || typeof row !== "object" || typeof row.status !== "string") {
-    throw new CommandError4(`Unexpected response for review ${jobId}.`);
-  }
-  const envelope = toReviewJobEnvelope2(row, { jobId });
-  const bits = [envelope.status];
-  if (envelope.verdict) bits.push(envelope.verdict);
-  return {
-    summary: `${envelope.job_id ?? jobId} \xB7 ${bits.join(" \xB7 ")}`,
-    data: envelope
-  };
-}
-
-// src/tools/review-list.ts
-import { listJobs, toReviewJobEnvelope as toReviewJobEnvelope3 } from "mergestorm/client";
-async function reviewList(limit = 10, cfg) {
-  const items = await listJobs(limit, cfg);
-  const envelopes = items.map((row) => toReviewJobEnvelope3(row));
-  const n = envelopes.length;
-  return {
-    summary: n === 0 ? "No review jobs" : `${n} review job${n === 1 ? "" : "s"}`,
-    data: { items: envelopes }
-  };
-}
-
 // src/tools/review-submit.ts
-import { createHash } from "node:crypto";
-import { realpath } from "node:fs/promises";
-import { relative, resolve, sep } from "node:path";
-import {
-  CommandError as CommandError5,
-  REVIEW_THREAD_SLUG_RE,
-  ReviewPollTimeoutError,
-  collectReviewInput,
-  discoverTrunk,
-  formatReviewSubmitError,
-  loadConfig as loadConfig3,
-  loadReviewContext,
-  pollReview,
-  rateLimitedMessage as rateLimitedMessage2,
-  submitReview
-} from "mergestorm/client";
 var MCP_WAIT_CEILING_S = 300;
 var MCP_PR_WAIT_DEFAULT_S = 45;
 var PINNABLE_SPECIALISTS = [
@@ -309,7 +234,7 @@ function assertPinnableSpecialists(specialists) {
     (id) => !PINNABLE_SPECIALISTS.includes(id)
   );
   if (unknown.length === 0) return;
-  throw new CommandError5(
+  throw new CommandError3(
     `Unknown specialist: ${unknown.join(", ")}. Valid lanes: ${PINNABLE_SPECIALISTS.join(", ")}. governance and seam cannot be requested.`,
     2,
     "usage"
@@ -321,7 +246,7 @@ function mcpSandboxRoot() {
 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");
+    throw new CommandError3("timeout_s must be a positive number of seconds", 2, "usage");
   }
   return Math.max(1, Math.round(Math.min(seconds, MCP_WAIT_CEILING_S) * 1e3));
 }
@@ -354,11 +279,11 @@ async function resolveInput(input) {
     ]);
     const relToSandbox = relative(sandboxReal, cwdReal);
     if (relToSandbox === ".." || relToSandbox.startsWith(`..${sep}`)) {
-      throw new CommandError5("cwd must be inside the configured sandbox root", 2, "usage");
+      throw new CommandError3("cwd must be inside the configured sandbox root", 2, "usage");
     }
   } catch (err) {
-    if (err instanceof CommandError5) throw err;
-    throw new CommandError5("cwd must be inside the configured sandbox root", 2, "usage");
+    if (err instanceof CommandError3) throw err;
+    throw new CommandError3("cwd must be inside the configured sandbox root", 2, "usage");
   }
   const base = input.base?.trim() || discoverTrunk(cwd);
   return collectReviewInput(base, head, cwd, sandboxRoot);
@@ -369,10 +294,10 @@ async function reviewSubmit(input, cfg, opts = {}) {
   const timeoutMs = waitTimeoutMs(input.timeout_s);
   assertPinnableSpecialists(input.specialists);
   if (input.thread && !REVIEW_THREAD_SLUG_RE.test(input.thread)) {
-    throw new CommandError5("thread must be 1\u2013120 chars [A-Za-z0-9._/-]", 2, "usage");
+    throw new CommandError3("thread must be 1\u2013120 chars [A-Za-z0-9._/-]", 2, "usage");
   }
   if (input.context === "-") {
-    throw new CommandError5(
+    throw new CommandError3(
       'context "-" (stdin) is not available over MCP; pass the text directly',
       2,
       "usage"
@@ -422,7 +347,7 @@ async function reviewSubmit(input, cfg, opts = {}) {
     };
   }
   if (!jobId) {
-    throw new CommandError5("Review API returned no job_id");
+    throw new CommandError3("Review API returned no job_id");
   }
   if (!wait) {
     return payloadFromRow(submitted.row, { jobId, status: submitted.row.status ?? "queued" });
@@ -454,9 +379,93 @@ import {
   loadConfig as loadConfig4,
   pollPrVortexReview
 } from "mergestorm/client";
+
+// src/tools/review-get-pr.ts
+import {
+  CommandError as CommandError4,
+  getPrVortexReview,
+  isCommandErrorCode as isCommandErrorCode3
+} from "mergestorm/client";
+function prReviewTarget(owner, repo, prNumber) {
+  const cleanOwner = owner.trim();
+  const cleanRepo = repo.trim();
+  if (!cleanOwner || !cleanRepo || !Number.isInteger(prNumber) || prNumber <= 0) {
+    throw new CommandError4(
+      "owner, repo, and a positive pr_number are required",
+      2,
+      "usage"
+    );
+  }
+  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: prReviewSummary(owner, repo, prNumber, envelope),
+    data: { ...envelope }
+  };
+}
+function payloadFromPrRateLimit(err, owner, repo, prNumber) {
+  if (!isCommandErrorCode3(err, "rate_limited")) return null;
+  return {
+    summary: `${owner}/${repo}#${prNumber} \xB7 rate_limited`,
+    data: {
+      status: "rate_limited",
+      error: err.message,
+      retry_after_seconds: err.retryAfterSeconds
+    }
+  };
+}
+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,
+      { afterSha: opts.afterSha, pass: opts.pass, afterPass: opts.afterPass }
+    );
+    return payloadFromPrReview(
+      target.owner,
+      target.repo,
+      target.prNumber,
+      envelope
+    );
+  } catch (err) {
+    const rateLimited = payloadFromPrRateLimit(
+      err,
+      target.owner,
+      target.repo,
+      target.prNumber
+    );
+    if (rateLimited) return rateLimited;
+    throw err;
+  }
+}
+
+// src/tools/review-wait-pr.ts
 async function reviewWaitPr(owner, repo, prNumber, afterSha, timeout_s, cfg, opts = {}) {
   const target = prReviewTarget(owner, repo, prNumber);
   const resolved = cfg ?? await loadConfig4();
+  if (timeout_s === 0) {
+    return reviewGetPr(target.owner, target.repo, target.prNumber, resolved, {
+      afterSha,
+      pass: opts.pass,
+      afterPass: opts.afterPass
+    });
+  }
   try {
     const envelope = await pollPrVortexReview(
       resolved,
@@ -521,12 +530,42 @@ import {
   loadConfig as loadConfig5,
   pollReview as pollReview2
 } from "mergestorm/client";
+
+// src/tools/review-get.ts
+import {
+  CommandError as CommandError5,
+  getReview,
+  toReviewJobEnvelope as toReviewJobEnvelope3
+} from "mergestorm/client";
+async function reviewGet(jobId, cfg) {
+  let row;
+  try {
+    row = await getReview(jobId, cfg);
+  } catch (err) {
+    const rateLimited = payloadFromRateLimit(err, jobId);
+    if (rateLimited) return rateLimited;
+    throw err;
+  }
+  if (!row || typeof row !== "object" || typeof row.status !== "string") {
+    throw new CommandError5(`Unexpected response for review ${jobId}.`);
+  }
+  const envelope = toReviewJobEnvelope3(row, { jobId });
+  const bits = [envelope.status];
+  if (envelope.verdict) bits.push(envelope.verdict);
+  return {
+    summary: `${envelope.job_id ?? jobId} \xB7 ${bits.join(" \xB7 ")}`,
+    data: envelope
+  };
+}
+
+// src/tools/review-wait.ts
 async function reviewWait(jobId, timeout_s, cfg, opts = {}) {
   const resolved = cfg ?? await loadConfig5();
   const id = jobId.trim();
   if (!id) {
     throw new CommandError6("job_id is required", 2, "usage");
   }
+  if (timeout_s === 0) return reviewGet(id, resolved);
   try {
     const row = await pollReview2(resolved, id, {
       timeoutMs: waitTimeoutMs(timeout_s),
@@ -592,6 +631,17 @@ function settingsPatchFromArgs(args) {
     const value = args[key];
     if (value === void 0) continue;
     const row = BEARER_SETTINGS.find((row2) => row2.key === key);
+    if ("kind" in row && row.kind === "seconds") {
+      if (typeof value !== "number" || !Number.isInteger(value) || value < row.min || value > row.max) {
+        throw new CommandError8(
+          `${key} takes a whole number of seconds from ${row.min} through ${row.max}.`,
+          2,
+          "usage"
+        );
+      }
+      Object.assign(patch, { [key]: value });
+      continue;
+    }
     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");
@@ -744,8 +794,8 @@ function stackSummary(stack, entries = []) {
   if (stack.cycloneOwnerMatch) {
     overrides.push(`cyclone-owner ${stack.cycloneOwnerMatch}`);
   }
-  const { attention, issues } = stackBlockers(stack, entries);
-  return `${stack.owner}/${stack.repo} \xB7 ${layerLabel} \xB7 ${currentState} \xB7 auto-land ${stack.autoEnqueueWhenReady ? "on" : "off"}${overrides.map((label) => ` \xB7 ${label}`).join("")}${stackBlockersSummary(attention, issues)}`;
+  const { attention, issues, busy } = stackBlockers(stack, entries);
+  return `${stack.owner}/${stack.repo} \xB7 ${layerLabel} \xB7 ${currentState} \xB7 auto-land ${stack.autoEnqueueWhenReady ? "on" : "off"}${overrides.map((label) => ` \xB7 ${label}`).join("")}${stackBlockersSummary(attention, issues, busy)}`;
 }
 
 // src/tools/stack-list.ts
@@ -791,6 +841,17 @@ var stackWaitSchema = {
   after_finished_at: z2.string().nullable().optional(),
   bounce_id: z2.string().nullable().optional()
 };
+function stackWaitSummary(envelope) {
+  const base = `Stack ${envelope.stackId} \xB7 ${envelope.status}${stackBlockersSummary2(envelope.blocker && envelope.prNumber != null ? { prNumber: envelope.prNumber, blocker: envelope.blocker } : null, envelope.issues, envelope.busy)}${envelope.assessment === "unavailable" ? " \xB7 assessment unavailable" : ""}`;
+  if (envelope.status !== "waiting" && envelope.status !== "in_progress") return base;
+  const selectors = [
+    `stack_id ${JSON.stringify(envelope.cursor.stackId)}`,
+    `enrolled_head_sha ${JSON.stringify(envelope.cursor.enrolledHeadSha)}`,
+    ...envelope.cursor.afterFinishedAt !== void 0 ? [`after_finished_at ${JSON.stringify(envelope.cursor.afterFinishedAt)}`] : [],
+    ...envelope.cursor.bounceId !== void 0 ? [`bounce_id ${JSON.stringify(envelope.cursor.bounceId)}`] : []
+  ];
+  return `${base} \xB7 watch not finished: call stack_wait again with timeout_s 45 and the same cursor: ${selectors.join(", ")}`;
+}
 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 ? {
@@ -809,7 +870,7 @@ async function stackWait(input, cfg, deps = {}) {
   } catch (err) {
     if (err instanceof StackWatchError) {
       return {
-        summary: `Stack ${err.lastEnvelope.stackId} \xB7 ${err.lastEnvelope.status}${stackBlockersSummary2(err.lastEnvelope.blocker && err.lastEnvelope.prNumber != null ? { prNumber: err.lastEnvelope.prNumber, blocker: err.lastEnvelope.blocker } : null, err.lastEnvelope.issues)}${err.lastEnvelope.assessment === "unavailable" ? " \xB7 assessment unavailable" : ""}`,
+        summary: stackWaitSummary(err.lastEnvelope),
         data: {
           ...err.lastEnvelope,
           ...err.retryAfterSeconds !== void 0 ? { retry_after_seconds: err.retryAfterSeconds } : {}
@@ -821,7 +882,7 @@ async function stackWait(input, cfg, deps = {}) {
     envelope = err.lastEnvelope;
   }
   return {
-    summary: `Stack ${envelope.stackId} \xB7 ${envelope.status}${stackBlockersSummary2(envelope.blocker && envelope.prNumber != null ? { prNumber: envelope.prNumber, blocker: envelope.blocker } : null, envelope.issues)}${envelope.assessment === "unavailable" ? " \xB7 assessment unavailable" : ""}`,
+    summary: stackWaitSummary(envelope),
     data: envelope
   };
 }
@@ -851,10 +912,10 @@ async function stackStatus(stackId, cfg) {
       };
     }
     const entries = await listMergeQueueEntries2(cfg, { stackId: stack.id });
-    const { attention, issues, currentCandidate } = stackBlockers2(stack, entries);
+    const { attention, issues, currentCandidate, busy, agents } = stackBlockers2(stack, entries);
     return {
       summary: stackSummary(stack, entries),
-      data: { stack, attention, issues, currentCandidate }
+      data: { stack, attention, issues, currentCandidate, busy, agents }
     };
   } catch (err) {
     if (isCommandErrorCode5(err, "rate_limited")) {
@@ -916,7 +977,7 @@ 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:",
+  "When you handle Vortex findings from 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.",
@@ -937,13 +998,16 @@ var MCP_STACK_WATCH_INSTRUCTIONS = [
   "- Restack clean does not mean mergeable or CI-green.",
   "- attention names the blocked PR via prNumber/headSha; currentCandidate is the promote candidate. Attention is not a mutation or authorization to change policy.",
   "- verifyHeadSha is a queue verification SHA, not the live PR head.",
+  "- Do not patch a bounced PR while Cyclone or Vortex is still working on it. stack_wait and stack_status enforce this: they return in_progress instead of attention, with busy[] naming the PR, blocker, and agent, and agents carrying that PR's vortexStatus, cycloneStatus, vortexReview, and busy flags. in_progress with a nonempty busy[] means wait. Recheck the live remote PR head right before pushing.",
+  "- seam_pending alone, and a queued Vortex run older than 15 minutes, do not hold. A queued Vortex run holds for at most 15 minutes; reviewing and patching hold until the run finishes or its lease or check run is cleared. A hold can hide a blocker no agent clears, such as a Draft PR; if it looks stuck, refresh stack_status and tell the human.",
+  "- stack.autoEnqueueSettle with action ready or promote means Auto land found Cyclone and Vortex idle on that PR's green head and started its settle clock. action mergeability is published earlier, on a head that may not be green or idle yet.",
   "- mg-park-* is a frozen GitHub base, not a repair target: never merge or rebase onto mg-park-*.",
   "- Use the mergestorm-bounce-watch skill for the fix-then-watch policy."
 ].join("\n");
 
 // src/server.ts
 var MCP_SERVER_NAME = "mergestorm";
-var MCP_SERVER_VERSION = "0.1.9";
+var MCP_SERVER_VERSION = "0.2.0";
 function stripNulls(value) {
   if (Array.isArray(value)) {
     return value.map((item) => stripNulls(item));
@@ -975,7 +1039,10 @@ function createMergestormMcpServer() {
   const server2 = new McpServer(
     {
       name: MCP_SERVER_NAME,
-      version: MCP_SERVER_VERSION
+      title: "Mergestorm",
+      version: MCP_SERVER_VERSION,
+      websiteUrl: MCP_WEBSITE_URL,
+      icons: MCP_SERVER_ICONS
     },
     { instructions: `${MCP_PR_LOOP_INSTRUCTIONS}
 
@@ -988,7 +1055,8 @@ ${MCP_STACK_WATCH_INSTRUCTIONS}` }
     "whoami",
     {
       title: "Who am I",
-      description: "Current Mergestorm API key prefix, plan, and API base."
+      description: "Current Mergestorm API key prefix, plan, and API base.",
+      annotations: { readOnlyHint: true }
     },
     async () => {
       try {
@@ -1002,7 +1070,8 @@ ${MCP_STACK_WATCH_INSTRUCTIONS}` }
     "credits",
     {
       title: "Credits",
-      description: "Current standard-credit usage and reset time."
+      description: "Current standard-credit usage and reset time.",
+      annotations: { readOnlyHint: true }
     },
     async () => {
       try {
@@ -1019,7 +1088,8 @@ ${MCP_STACK_WATCH_INSTRUCTIONS}` }
       description: "List recent Mergestorm review jobs as job envelopes.",
       inputSchema: {
         limit: z3.number().int().min(1).max(50).optional()
-      }
+      },
+      annotations: { readOnlyHint: true }
     },
     async ({ limit }) => {
       try {
@@ -1029,51 +1099,6 @@ ${MCP_STACK_WATCH_INSTRUCTIONS}` }
       }
     }
   );
-  addTool(
-    "review_get",
-    {
-      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: z3.string().min(1)
-      }
-    },
-    async ({ job_id }) => {
-      try {
-        return ok(await reviewGet(job_id));
-      } catch (err) {
-        return fail(err);
-      }
-    }
-  );
-  addTool(
-    "review_get_pr",
-    {
-      title: "Get GitHub PR Vortex review",
-      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: 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, after_sha, pass, after_pass }) => {
-      try {
-        return ok(
-          await reviewGetPr(owner, repo, pr_number, void 0, {
-            afterSha: after_sha,
-            pass,
-            afterPass: after_pass
-          })
-        );
-      } catch (err) {
-        return fail(err);
-      }
-    }
-  );
   addTool(
     "review_submit",
     {
@@ -1092,7 +1117,8 @@ ${MCP_STACK_WATCH_INSTRUCTIONS}` }
         idempotency_key: z3.string().min(1).max(128).optional(),
         wait: z3.boolean().optional(),
         timeout_s: z3.number().positive().max(300).optional()
-      }
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
     },
     async (args) => {
       try {
@@ -1106,11 +1132,12 @@ ${MCP_STACK_WATCH_INSTRUCTIONS}` }
     "review_wait",
     {
       title: "Wait for review",
-      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.",
+      description: "Read one local Mergestorm review job by the job_id that review_submit returned, as a job envelope. timeout_s: 0 reads it once without polling; otherwise it polls 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: z3.string().min(1),
-        timeout_s: z3.number().positive().max(300).optional()
-      }
+        timeout_s: z3.number().min(0).max(300).optional()
+      },
+      annotations: { readOnlyHint: true }
     },
     async ({ job_id, timeout_s }) => {
       try {
@@ -1124,7 +1151,7 @@ ${MCP_STACK_WATCH_INSTRUCTIONS}` }
     "review_wait_pr",
     {
       title: "Wait for GitHub PR Vortex review",
-      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.",
+      description: "Read the Vortex pass on a GitHub PR from the DB-only endpoint; review identity is head SHA + pass. timeout_s: 0 reads it once without polling; otherwise it polls for one 45s slice by default (max 300) and returns in_progress on timeout so you can call again. Pass after_sha for the head you pushed and pass to read one exact attempt; when you already hold a resting envelope for that head, also pass after_pass set to its pass and keep it unchanged across retries; never replace it with the pass of an in-progress envelope, and omit after_pass for a head you hold no envelope for. With timeout_s: 0, a pass that does not exist yet returns not_found, so after a push use a positive timeout. 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: z3.string().min(1),
         repo: z3.string().min(1),
@@ -1132,8 +1159,9 @@ ${MCP_STACK_WATCH_INSTRUCTIONS}` }
         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()
-      }
+        timeout_s: z3.number().min(0).max(300).optional()
+      },
+      annotations: { readOnlyHint: true }
     },
     async ({ owner, repo, pr_number, after_sha, pass, after_pass, timeout_s }) => {
       try {
@@ -1158,7 +1186,8 @@ ${MCP_STACK_WATCH_INSTRUCTIONS}` }
     {
       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. With 2+ PRs, adopt moves the bottom PR's GitHub base to mg-stack-<n> and parks PR3+ on an mg-park-* freeze; a 1-PR stack stays on main. Leave those bases. Never retarget the bottom back to main.",
-      inputSchema: stackAdoptSchema
+      inputSchema: stackAdoptSchema,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false }
     },
     async (args) => {
       try {
@@ -1172,7 +1201,8 @@ ${MCP_STACK_WATCH_INSTRUCTIONS}` }
     "stack_list",
     {
       title: "List stacks",
-      description: "List the current user's Mergestorm stacks. This tool is read-only."
+      description: "List the current user's Mergestorm stacks.",
+      annotations: { readOnlyHint: true }
     },
     async () => {
       try {
@@ -1192,7 +1222,8 @@ ${MCP_STACK_WATCH_INSTRUCTIONS}` }
         auto_land: z3.boolean().optional(),
         auto_review: z3.boolean().nullable().optional(),
         auto_patch: z3.boolean().nullable().optional()
-      }
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true }
     },
     async ({ stack_id, auto_land, auto_review, auto_patch }) => {
       try {
@@ -1212,10 +1243,11 @@ ${MCP_STACK_WATCH_INSTRUCTIONS}` }
     "stack_status",
     {
       title: "Get stack status",
-      description: "Fetch one owned Mergestorm stack with enriched checks and agent state, plus attention, issues, and currentCandidate from the same blocker rules as stack_wait, read against that stack's own merge queue. This tool is read-only. trunkBranch is mg-stack-<n> for an adopted 2+ PR stack and matches the bottom open PR's GitHub base; an mg-park-* parentBranch is a freeze. Neither is drift to fix.",
+      description: "Fetch one owned Mergestorm stack with enriched checks and agent state, plus attention, issues, and currentCandidate from the same blocker rules as stack_wait, read against that stack's own merge queue. trunkBranch is mg-stack-<n> for an adopted 2+ PR stack and matches the bottom open PR's GitHub base; an mg-park-* parentBranch is a freeze. Neither is drift to fix.",
       inputSchema: {
         stack_id: z3.string().min(1)
-      }
+      },
+      annotations: { readOnlyHint: true }
     },
     async ({ stack_id }) => {
       try {
@@ -1229,8 +1261,9 @@ ${MCP_STACK_WATCH_INSTRUCTIONS}` }
     "stack_wait",
     {
       title: "Wait for stack attention",
-      description: "Wait for a stack to need attention. Returns a mergestorm.stack_watch/v1 envelope; timeout_s: 0 returns one snapshot and timeout_s: 1-45 waits up to that many seconds, returning the current status (waiting or in_progress) if a snapshot was read and no attention is found. A timeout with either of those statuses is not a failure. A timeout of failed means no assessment was produced. This tool is read-only. Attention never calls for changing a PR's GitHub base.",
-      inputSchema: stackWaitSchema
+      description: "Wait for a stack to need attention. Returns a mergestorm.stack_watch/v1 envelope; timeout_s: 0 returns one snapshot and timeout_s: 1-45 waits up to that many seconds, returning the current status (waiting or in_progress) if a snapshot was read and no attention is found. A timeout with either of those statuses is not a failure; waiting and in_progress end this slice, and the next call is stack_wait again with the same cursor. A timeout of failed means no assessment was produced. While Cyclone or Vortex is still working on the blocked PR it returns in_progress, not attention, with busy[] naming the PR, blocker, and agent; agents carries that PR's vortexStatus, cycloneStatus, vortexReview, and busy flags. Attention never calls for changing a PR's GitHub base.",
+      inputSchema: stackWaitSchema,
+      annotations: { readOnlyHint: true }
     },
     async (args, extra) => {
       try {
@@ -1245,10 +1278,11 @@ ${MCP_STACK_WATCH_INSTRUCTIONS}` }
     "queue_status",
     {
       title: "Get merge queue status",
-      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.",
+      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.",
       inputSchema: {
         stack_id: z3.string().min(1).optional()
-      }
+      },
+      annotations: { readOnlyHint: true }
     },
     async ({ stack_id }) => {
       try {
@@ -1262,7 +1296,8 @@ ${MCP_STACK_WATCH_INSTRUCTIONS}` }
     "settings_get",
     {
       title: "Get settings",
-      description: "Read the Bearer /api/v1/settings toggles, including auto_patch_enabled and cyclone_connected. This tool is read-only."
+      description: "Read the Bearer /api/v1/settings toggles, including auto_patch_enabled, auto_land_settle_seconds (how long Auto land waits before queueing), and cyclone_connected.",
+      annotations: { readOnlyHint: true }
     },
     async () => {
       try {
@@ -1276,18 +1311,19 @@ ${MCP_STACK_WATCH_INSTRUCTIONS}` }
     "settings_set",
     {
       title: "Update settings",
-      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.",
+      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. cyclone_connected and github_connected are read-only and cannot be set.",
       inputSchema: {
         ...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()
+            ("kind" in row ? row.kind === "logins" ? z3.array(z3.string()) : row.kind === "seconds" ? z3.number().int().min(row.min).max(row.max) : 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()
-      }
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true }
     },
     async (args) => {
       try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mergestorm-mcp",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "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.23",
+    "mergestorm": "0.3.25",
     "zod": "^3.24.2"
   },
   "devDependencies": {