mergestorm-mcp 0.1.10 → 0.2.1

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),
@@ -633,11 +672,100 @@ async function settingsSet(args, cfg) {
 }
 
 // src/tools/stack-adopt.ts
-import { adoptStack, CommandError as CommandError9 } from "mergestorm/client";
+import { adoptStack, CommandError as CommandError9, stackWatchObligation as stackWatchObligation3 } from "mergestorm/client";
+import { z as z2 } from "zod";
+
+// src/tools/stack-set.ts
+import { setStackPolicy, stackWatchObligation as stackWatchObligation2 } from "mergestorm/client";
+
+// src/tools/stack-wait.ts
+import {
+  loadConfig as loadConfig6,
+  stackBlockersSummary,
+  pollStackWatch,
+  StackWatchError,
+  StackWatchTimeoutError,
+  stackWatchObligation
+} from "mergestorm/client";
 import { z } from "zod";
+var stackWaitSchema = {
+  stack_id: z.string().trim().min(1),
+  timeout_s: z.number().finite().min(0).max(45).default(45),
+  enrolled_head_sha: z.string().nullable().optional(),
+  after_finished_at: z.string().nullable().optional(),
+  bounce_id: z.string().nullable().optional()
+};
+function repairSummary(repair) {
+  if (!repair) return "";
+  const files = "files" in repair && repair.files.length ? ` Files: ${repair.files.join(", ")}.` : "";
+  return `
+Repair #${repair.prNumber} (${repair.kind}).${files} ${repair.steps}`;
+}
+function withWatchText(watch, body) {
+  return `${watch.message}
+
+${body}`;
+}
+function envelopeWatch(envelope) {
+  return envelope.watch ?? stackWatchObligation({
+    stackId: envelope.stackId,
+    terminal: null,
+    cursor: envelope.cursor,
+    status: envelope.status
+  });
+}
+function stackWaitSummary(envelope) {
+  return withWatchText(envelopeWatch(envelope), `${stackWaitStatusLine(envelope)}${repairSummary(envelope.repair)}`);
+}
+function stackWaitStatusLine(envelope) {
+  const base = `Stack ${envelope.stackId} \xB7 ${envelope.status}${stackBlockersSummary(envelope.blocker && envelope.prNumber != null ? { prNumber: envelope.prNumber, blocker: envelope.blocker } : null, envelope.issues, envelope.busy, envelope.landGatePending)}${envelope.assessment === "unavailable" ? " \xB7 assessment unavailable" : ""}`;
+  if (envelopeWatch(envelope).done || 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 = z.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) {
+      const envelope2 = { ...err.lastEnvelope, watch: envelopeWatch(err.lastEnvelope) };
+      return {
+        summary: stackWaitSummary(envelope2),
+        data: {
+          ...envelope2,
+          ...err.retryAfterSeconds !== void 0 ? { retry_after_seconds: err.retryAfterSeconds } : {}
+        },
+        isError: !envelope2.watch.done
+      };
+    }
+    if (!(err instanceof StackWatchTimeoutError)) throw err;
+    envelope = err.lastEnvelope;
+  }
+  const sealed = { ...envelope, watch: envelopeWatch(envelope) };
+  return {
+    summary: stackWaitSummary(sealed),
+    data: sealed
+  };
+}
 
 // src/tools/stack-set.ts
-import { setStackPolicy } from "mergestorm/client";
 function triWord(value) {
   return value === null ? "default" : value ? "on" : "off";
 }
@@ -674,28 +802,30 @@ async function stackSet(stackId, input, cfg) {
   if (input.auto_patch !== void 0) {
     parts.push(`auto-patch ${triWord(input.auto_patch)}`);
   }
+  const watch = stackWatchObligation2({ stackId, terminal: null, unread: true, freshCursor: true });
   return {
-    summary: `${parts.join(", ")} for stack ${stackId}`,
+    summary: withWatchText(watch, `${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
+      result,
+      watch
     }
   };
 }
 
 // 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()
+  owner: z2.string().trim().min(1),
+  repo: z2.string().trim().min(1),
+  pr_number: z2.number().int().min(1),
+  auto_land: z2.boolean().optional(),
+  auto_review: z2.boolean().nullable().optional(),
+  auto_patch: z2.boolean().nullable().optional()
 };
-var inputSchema = z.object(stackAdoptSchema);
+var inputSchema = z2.object(stackAdoptSchema);
 async function stackAdopt(input, cfg) {
   const parsed = inputSchema.safeParse(input);
   if (!parsed.success) {
@@ -711,9 +841,15 @@ async function stackAdopt(input, cfg) {
       cfg,
       stackSetPatch(parsed.data)
     );
+    const summary = `Adopted stack for ${owner}/${repo}#${pr_number}`;
+    const stackId = typeof result === "object" && result !== null ? result.stack?.id : void 0;
+    if (typeof stackId !== "string" || !stackId) {
+      return { summary, data: { owner, repo, pr_number, result } };
+    }
+    const watch = stackWatchObligation3({ stackId, terminal: null, unread: true, freshCursor: true });
     return {
-      summary: `Adopted stack for ${owner}/${repo}#${pr_number}`,
-      data: { owner, repo, pr_number, result }
+      summary: withWatchText(watch, summary),
+      data: { owner, repo, pr_number, result, watch }
     };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -739,7 +875,7 @@ import {
 } from "mergestorm/client";
 
 // src/tools/stack-summary.ts
-import { stackBlockers, stackBlockersSummary } from "mergestorm/client";
+import { stackBlockers, stackBlockersSummary as stackBlockersSummary2 } from "mergestorm/client";
 function stackSummary(stack, entries = []) {
   const count = stack.layers.length;
   const layerLabel = `${count} layer${count === 1 ? "" : "s"}`;
@@ -755,8 +891,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, landGatePending } = 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("")}${stackBlockersSummary2(attention, issues, busy, landGatePending)}`;
 }
 
 // src/tools/stack-list.ts
@@ -786,108 +922,65 @@ async function stackList(cfg) {
   }
 }
 
-// src/tools/stack-wait.ts
-import {
-  loadConfig as loadConfig6,
-  stackBlockersSummary as stackBlockersSummary2,
-  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()
-};
-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.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 ? {
-    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: stackWaitSummary(err.lastEnvelope),
-        data: {
-          ...err.lastEnvelope,
-          ...err.retryAfterSeconds !== void 0 ? { retry_after_seconds: err.retryAfterSeconds } : {}
-        },
-        isError: true
-      };
-    }
-    if (!(err instanceof StackWatchTimeoutError)) throw err;
-    envelope = err.lastEnvelope;
-  }
-  return {
-    summary: stackWaitSummary(envelope),
-    data: envelope
-  };
-}
-
 // src/tools/stack-status.ts
 import {
   getEnrichedStack,
   listMergeQueueEntries as listMergeQueueEntries2,
   isCommandErrorCode as isCommandErrorCode5,
-  stackBlockers as stackBlockers2
+  stackBlockers as stackBlockers2,
+  stackTerminalReason,
+  stackWatchObligation as stackWatchObligation4
 } from "mergestorm/client";
 async function stackStatus(stackId, cfg) {
   try {
     const stack = await getEnrichedStack(stackId, cfg);
     if (!stack) {
       const message = `Stack not found or not owned by the current user: ${stackId}`;
+      const watch2 = stackWatchObligation4({ stackId, terminal: "not_found" });
       return {
-        summary: message,
+        summary: withWatchText(watch2, message),
         data: {
           error: {
             code: "stack_not_found",
             message,
             stack_id: stackId
-          }
+          },
+          watch: watch2
         },
         isError: true
       };
     }
     const entries = await listMergeQueueEntries2(cfg, { stackId: stack.id });
-    const { attention, issues, currentCandidate } = stackBlockers2(stack, entries);
+    const { attention, issues, currentCandidate, busy, agents, repair, landGatePending } = stackBlockers2(stack, entries);
+    const watch = stackWatchObligation4({
+      stackId: stack.id,
+      terminal: stackTerminalReason(stack),
+      cursor: { enrolledHeadSha: currentCandidate?.headSha ?? null },
+      attention: attention ? { prNumber: attention.prNumber, blocker: attention.blocker } : null,
+      freshCursor: true
+    });
     return {
-      summary: stackSummary(stack, entries),
-      data: { stack, attention, issues, currentCandidate }
+      summary: withWatchText(watch, `${stackSummary(stack, entries)}${repairSummary(repair)}`),
+      data: { stack, attention, issues, currentCandidate, busy, agents, repair, landGatePending, watch }
     };
   } catch (err) {
     if (isCommandErrorCode5(err, "rate_limited")) {
+      const watch = stackWatchObligation4({
+        stackId,
+        terminal: null,
+        status: "rate_limited",
+        retryAfterSeconds: err.retryAfterSeconds,
+        freshCursor: true
+      });
       return {
-        summary: err.message,
+        summary: withWatchText(watch, err.message),
         data: {
           error: {
             code: "rate_limited",
             message: err.message,
             retry_after_seconds: err.retryAfterSeconds
-          }
+          },
+          watch
         },
         isError: true
       };
@@ -938,13 +1031,19 @@ 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.",
   `- 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");
+var MCP_STACK_DONE_INSTRUCTIONS = [
+  "When stack work is done:",
+  "- Stack work is done only when the stack is landed, or when the human takes it back (archives it or tells you to stop). A clean push, a submit, an adopt, or one merged layer is not done: merging a lower layer can break a layer above it.",
+  "- Every stack_wait, stack_status, stack_adopt, and stack_set result carries watch: {done, until, reason, next, message}. While watch.done is false, keep calling stack_wait with watch.next.args (the returned cursor), 45s at a time, and do not end your task. Stop only when watch.done is true.",
+  "- attention means something for you to fix; repair, when present, names the concrete fix. A pending land gate (landGatePending: ci_pending, tempest_pending, tempest_running) is a wait, not attention."
+].join("\n");
 var MCP_STACK_BASE_INSTRUCTIONS = [
   "Stack PR bases (Mergestorm sets these; leave them):",
   "- Stack of 2+ PRs: after adopt (stack_adopt, mg stack adopt, or mg stack submit) the bottom PR's GitHub base is the owned trunk mg-stack-<n>, not main. That is correct. Layer 2 is based on layer 1; layer 3+ on the mg-park-* freeze; the git parent of layer 2+ is still the layer below. A 1-PR stack stays on main and gets no mg-stack-<n>.",
@@ -959,13 +1058,23 @@ 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.10";
+var MCP_SERVER_VERSION = "0.2.1";
+var MCP_SERVER_INSTRUCTIONS = [
+  MCP_STACK_DONE_INSTRUCTIONS,
+  MCP_PR_LOOP_INSTRUCTIONS,
+  MCP_STACK_BASE_INSTRUCTIONS,
+  MCP_STACK_WATCH_INSTRUCTIONS
+].join("\n\n");
+var STACK_WATCH_RESULT_NOTE = ' The result carries watch {done, until: "landed", reason, next, message}: while watch.done is false the stack is not landed and your task is not done; call stack_wait with watch.next.args.';
 function stripNulls(value) {
   if (Array.isArray(value)) {
     return value.map((item) => stripNulls(item));
@@ -997,20 +1106,20 @@ 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}
-
-${MCP_STACK_BASE_INSTRUCTIONS}
-
-${MCP_STACK_WATCH_INSTRUCTIONS}` }
+    { instructions: MCP_SERVER_INSTRUCTIONS }
   );
   const addTool = server2.registerTool.bind(server2);
   addTool(
     "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 {
@@ -1024,7 +1133,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 {
@@ -1041,7 +1151,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 {
@@ -1051,51 +1162,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",
     {
@@ -1114,7 +1180,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 {
@@ -1128,11 +1195,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 {
@@ -1146,7 +1214,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),
@@ -1154,8 +1222,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 {
@@ -1179,8 +1248,9 @@ ${MCP_STACK_WATCH_INSTRUCTIONS}` }
     "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. 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
+      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." + STACK_WATCH_RESULT_NOTE,
+      inputSchema: stackAdoptSchema,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false }
     },
     async (args) => {
       try {
@@ -1194,7 +1264,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 {
@@ -1208,13 +1279,14 @@ ${MCP_STACK_WATCH_INSTRUCTIONS}` }
     "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.",
+      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." + STACK_WATCH_RESULT_NOTE,
       inputSchema: {
         stack_id: z3.string().min(1),
         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 {
@@ -1234,10 +1306,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. repair names the concrete fix for attention; landGatePending is a wait, not attention." + STACK_WATCH_RESULT_NOTE,
       inputSchema: {
         stack_id: z3.string().min(1)
-      }
+      },
+      annotations: { readOnlyHint: true }
     },
     async ({ stack_id }) => {
       try {
@@ -1251,8 +1324,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; 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. 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. A stack that no longer exists returns status failed with watch.done true (reason not_found) and is not an error. 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. repair names the concrete fix for attention (restack_conflict and merge_conflict carry liveParent, never mg-park-*). A pending land gate (landGatePending) returns in_progress, not attention." + STACK_WATCH_RESULT_NOTE,
+      inputSchema: stackWaitSchema,
+      annotations: { readOnlyHint: true }
     },
     async (args, extra) => {
       try {
@@ -1267,10 +1341,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 {
@@ -1284,7 +1359,8 @@ ${MCP_STACK_WATCH_INSTRUCTIONS}` }
     "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), 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 {
@@ -1309,7 +1385,8 @@ ${MCP_STACK_WATCH_INSTRUCTIONS}` }
         // 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.10",
+  "version": "0.2.1",
   "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.24",
+    "mergestorm": "0.3.26",
     "zod": "^3.24.2"
   },
   "devDependencies": {