mergestorm-mcp 0.1.5 → 0.1.7

package/README.md

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

package/dist/index.js

@@ -5,8 +5,8 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z as z2 } from "zod";
-import { CommandError as CommandError11, SETTINGS_WRITABLE_KEYS as SETTINGS_WRITABLE_KEYS2 } from "mergestorm/client";
+import { z as z3 } from "zod";
+import { CommandError as CommandError11, BEARER_SETTINGS as BEARER_SETTINGS2 } from "mergestorm/client";
 
 // src/tools/credits.ts
 import { CommandError, getMe, loadConfig } from "mergestorm/client";
@@ -46,20 +46,29 @@ import {
   REVIEW_EXIT
 } from "mergestorm/client";
 function entrySummary(entry) {
-  const repo = entry.owner && entry.repo ? `${entry.owner}/${entry.repo}` : "unknown repo";
-  const position = entry.position === void 0 ? "queue" : `#${entry.position}`;
-  return `${position} \xB7 ${repo} \xB7 stack ${entry.stackId ?? "unknown"} \xB7 ${entry.state ?? "unknown"}`;
+  const prNumber = entry.bounceDetail?.prNumber;
+  const repo = `${entry.owner}/${entry.repo}${prNumber ? `#${prNumber}` : ""}`;
+  const reason = entry.bounceDetail?.kind ?? entry.bounceReason ?? entry.waitReason ?? void 0;
+  const sha = entry.bounceDetail?.headSha ?? entry.verifyHeadSha ?? void 0;
+  return [
+    entry.state,
+    repo,
+    `stack ${entry.stackId}`,
+    reason,
+    sha?.slice(0, 7)
+  ].filter(Boolean).join(" \xB7 ");
 }
 async function queueStatus(stackId, cfg) {
   try {
     const resolved = cfg ?? await loadConfig2();
+    const id = stackId?.trim();
     const { status, body, retryAfterSeconds } = await apiFetch(
       resolved,
-      "/api/v1/stacks/queue"
+      id ? `/api/v1/stacks/queue?stackId=${encodeURIComponent(id)}` : "/api/v1/stacks/queue"
     );
     if (status === 404) {
       throw new CommandError2(
-        "Merge queue API is not available on this server yet. Deploy the API update or use the dashboard."
+        "Merge queue route returned 404. Deploy the API."
       );
     }
     if (status === 429) {
@@ -81,11 +90,12 @@ async function queueStatus(stackId, cfg) {
         `Failed to get queue status (HTTP 200): ${JSON.stringify(body)}`
       );
     }
-    const id = stackId?.trim();
     if (id) {
-      const entry = entries.find((candidate) => candidate?.stackId === id);
-      if (!entry) {
-        const message = `Live queue entry not found for stack: ${id}`;
+      const matchingEntries = entries.filter(
+        (candidate) => candidate?.stackId?.toLowerCase() === id.toLowerCase()
+      );
+      if (matchingEntries.length === 0) {
+        const message = `Queue entry not found for stack: ${id}`;
         return {
           summary: message,
           data: {
@@ -99,12 +109,12 @@ async function queueStatus(stackId, cfg) {
         };
       }
       return {
-        summary: entrySummary(entry),
-        data: { entry }
+        summary: matchingEntries.map(entrySummary).join("\n"),
+        data: { entries: matchingEntries }
       };
     }
     return {
-      summary: entries.length === 0 ? "No live merge queue entries" : entries.map(entrySummary).join("\n"),
+      summary: entries.length === 0 ? "No merge queue entries (live or bounced)" : entries.map(entrySummary).join("\n"),
       data: { entries }
     };
   } catch (err) {
@@ -469,17 +479,26 @@ async function reviewWaitPr(owner, repo, prNumber, afterSha, timeout_s, cfg, opt
     );
   } catch (err) {
     if (err instanceof PrReviewPollTimeoutError) {
-      const status = err.lastEnvelope?.status ?? "in_progress";
+      const status = "in_progress";
+      const expectedSha = afterSha?.trim().toLowerCase() ?? "";
+      const observedSha = err.lastEnvelope?.head_sha?.trim().toLowerCase() ?? "";
+      const headShaMatches = Boolean(
+        observedSha && expectedSha.length >= 7 && (observedSha.startsWith(expectedSha) || expectedSha.startsWith(observedSha))
+      );
+      const findingCount = headShaMatches ? err.lastEnvelope?.finding_count ?? null : null;
       return {
         summary: prReviewSummary(target.owner, target.repo, target.prNumber, {
           status,
           head_sha: err.lastEnvelope?.head_sha ?? null,
-          finding_count: err.lastEnvelope?.finding_count ?? null,
+          finding_count: findingCount,
           phase: err.lastEnvelope?.phase ?? null
         }),
         data: {
-          ...err.lastEnvelope ?? {},
           status,
+          head_sha: err.lastEnvelope?.head_sha ?? null,
+          pass: headShaMatches ? err.lastEnvelope?.pass ?? null : null,
+          finding_count: findingCount,
+          phase: err.lastEnvelope?.phase ?? null,
           error: err.message
         }
       };
@@ -554,6 +573,7 @@ async function settingsGet(cfg) {
 // src/tools/settings-set.ts
 import {
   CommandError as CommandError8,
+  BEARER_SETTINGS,
   SETTINGS_WRITABLE_KEYS,
   patchSettings
 } from "mergestorm/client";
@@ -571,10 +591,17 @@ function settingsPatchFromArgs(args) {
   for (const key of SETTINGS_WRITABLE_KEYS) {
     const value = args[key];
     if (value === void 0) continue;
+    const row = BEARER_SETTINGS.find((row2) => row2.key === key);
+    if ("kind" in row) {
+      const valid = row.kind === "logins" ? Array.isArray(value) && value.every((login) => typeof login === "string") : typeof value === "string" && row.values.includes(value);
+      if (!valid) throw new CommandError8(`Invalid value for ${key}.`, 2, "usage");
+      Object.assign(patch, { [key]: value });
+      continue;
+    }
     if (typeof value !== "boolean") {
       throw new CommandError8(`${key} takes a boolean.`, 2, "usage");
     }
-    patch[key] = value;
+    Object.assign(patch, { [key]: value });
   }
   if (Object.keys(patch).length === 0) {
     throw new CommandError8(
@@ -653,9 +680,9 @@ var stackAdoptSchema = {
   owner: z.string().trim().min(1),
   repo: z.string().trim().min(1),
   pr_number: z.number().int().min(1),
-  auto_land: z.literal(false).optional(),
+  auto_land: z.boolean().optional(),
   auto_review: z.boolean().nullable().optional(),
-  auto_patch: z.literal(false).nullable().optional()
+  auto_patch: z.boolean().nullable().optional()
 };
 var inputSchema = z.object(stackAdoptSchema);
 async function stackAdopt(input, cfg) {
@@ -694,14 +721,19 @@ async function stackAdopt(input, cfg) {
 }
 
 // src/tools/stack-list.ts
-import { isCommandErrorCode as isCommandErrorCode4, listStacks } from "mergestorm/client";
+import {
+  isCommandErrorCode as isCommandErrorCode4,
+  listMergeQueueEntries,
+  listStacks
+} from "mergestorm/client";
 
 // src/tools/stack-summary.ts
-function stackSummary(stack) {
+import { stackBlockers, stackBlockersSummary } from "mergestorm/client";
+function stackSummary(stack, entries = []) {
   const count = stack.layers.length;
   const layerLabel = `${count} layer${count === 1 ? "" : "s"}`;
   const states = [...new Set(stack.layers.map((layer) => layer.state))];
-  const currentState = states.length > 0 ? `layers: ${states.join(", ")}` : stack.unit ? `unit: ${stack.unit.state}` : "no open layers";
+  const currentState = states.length > 0 ? `restack: ${states.join(", ")}` : stack.unit ? `unit: ${stack.unit.state}` : "no open layers";
   const overrides = [];
   if (typeof stack.autoReviewOverride === "boolean") {
     overrides.push(`auto-review ${stack.autoReviewOverride ? "on" : "off"}`);
@@ -712,15 +744,17 @@ function stackSummary(stack) {
   if (stack.cycloneOwnerMatch) {
     overrides.push(`cyclone-owner ${stack.cycloneOwnerMatch}`);
   }
-  return `${stack.owner}/${stack.repo} \xB7 ${layerLabel} \xB7 ${currentState} \xB7 auto-land ${stack.autoEnqueueWhenReady ? "on" : "off"}${overrides.map((label) => ` \xB7 ${label}`).join("")}`;
+  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)}`;
 }
 
 // src/tools/stack-list.ts
 async function stackList(cfg) {
   try {
     const stacks = await listStacks(cfg);
+    const entries = await listMergeQueueEntries(cfg);
     return {
-      summary: stacks.length === 0 ? "No stacks" : stacks.map((stack) => stackSummary(stack)).join("\n"),
+      summary: stacks.length === 0 ? "No stacks" : stacks.map((stack) => stackSummary(stack, entries)).join("\n"),
       data: { stacks }
     };
   } catch (err) {
@@ -741,8 +775,63 @@ 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()
+};
+async function stackWait(input, cfg, deps = {}) {
+  const args = z2.object(stackWaitSchema).parse(input);
+  const cursor = args.enrolled_head_sha !== void 0 || args.after_finished_at !== void 0 || args.bounce_id !== void 0 ? {
+    stackId: args.stack_id,
+    enrolledHeadSha: args.enrolled_head_sha ?? null,
+    ...args.after_finished_at !== void 0 ? { afterFinishedAt: args.after_finished_at } : {},
+    ...args.bounce_id !== void 0 ? { bounceId: args.bounce_id } : {}
+  } : void 0;
+  let envelope;
+  try {
+    envelope = await (deps.pollStackWatch ?? pollStackWatch)(cfg ?? await loadConfig6(), args.stack_id, {
+      timeoutMs: args.timeout_s * 1e3,
+      cursor,
+      signal: deps.signal
+    });
+  } catch (err) {
+    if (err instanceof StackWatchError) {
+      return {
+        summary: `Stack ${err.lastEnvelope.stackId} \xB7 ${err.lastEnvelope.status}${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" : ""}`,
+        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: `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" : ""}`,
+    data: envelope
+  };
+}
+
 // src/tools/stack-status.ts
-import { getEnrichedStack, isCommandErrorCode as isCommandErrorCode5 } from "mergestorm/client";
+import {
+  getEnrichedStack,
+  listMergeQueueEntries as listMergeQueueEntries2,
+  isCommandErrorCode as isCommandErrorCode5
+} from "mergestorm/client";
 async function stackStatus(stackId, cfg) {
   try {
     const stack = await getEnrichedStack(stackId, cfg);
@@ -760,8 +849,9 @@ async function stackStatus(stackId, cfg) {
         isError: true
       };
     }
+    const entries = await listMergeQueueEntries2(cfg);
     return {
-      summary: stackSummary(stack),
+      summary: stackSummary(stack, entries),
       data: { stack }
     };
   } catch (err) {
@@ -788,11 +878,11 @@ import {
   apiBase,
   configPath,
   getMe as getMe2,
-  loadConfig as loadConfig6,
+  loadConfig as loadConfig7,
   resolveApiKey
 } from "mergestorm/client";
 async function whoami(cfg) {
-  const resolved = cfg ?? await loadConfig6();
+  const resolved = cfg ?? await loadConfig7();
   const key = resolveApiKey(resolved);
   if (!key) {
     throw new CommandError10(
@@ -831,10 +921,20 @@ var MCP_PR_LOOP_INSTRUCTIONS = [
   `- 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_WATCH_INSTRUCTIONS = [
+  "Stack-watch facts (mergestorm.stack_watch/v1):",
+  "- waiting with nonempty issues[] is not idle; in_progress can also carry issues[].",
+  "- assessment unavailable does not mean issue-free. timeout_s: 0 reads one enrich and one queue snapshot.",
+  "- 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.",
+  "- 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.5";
+var MCP_SERVER_VERSION = "0.1.7";
 function stripNulls(value) {
   if (Array.isArray(value)) {
     return value.map((item) => stripNulls(item));
@@ -868,7 +968,9 @@ function createMergestormMcpServer() {
       name: MCP_SERVER_NAME,
       version: MCP_SERVER_VERSION
     },
-    { instructions: MCP_PR_LOOP_INSTRUCTIONS }
+    { instructions: `${MCP_PR_LOOP_INSTRUCTIONS}
+
+${MCP_STACK_WATCH_INSTRUCTIONS}` }
   );
   const addTool = server2.registerTool.bind(server2);
   addTool(
@@ -905,7 +1007,7 @@ function createMergestormMcpServer() {
       title: "List reviews",
       description: "List recent Mergestorm review jobs as job envelopes.",
       inputSchema: {
-        limit: z2.number().int().min(1).max(50).optional()
+        limit: z3.number().int().min(1).max(50).optional()
       }
     },
     async ({ limit }) => {
@@ -922,7 +1024,7 @@ function createMergestormMcpServer() {
       title: "Get review",
       description: "Fetch one Mergestorm review job as a job envelope. On rate_limited, wait retry_after_seconds before trying again.",
       inputSchema: {
-        job_id: z2.string().min(1)
+        job_id: z3.string().min(1)
       }
     },
     async ({ job_id }) => {
@@ -939,12 +1041,12 @@ function createMergestormMcpServer() {
       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: z2.string().min(1),
-        repo: z2.string().min(1),
-        pr_number: z2.number().int().min(1),
-        after_sha: z2.string().optional(),
-        pass: z2.number().int().min(1).optional(),
-        after_pass: z2.number().int().min(1).optional()
+        owner: z3.string().min(1),
+        repo: z3.string().min(1),
+        pr_number: z3.number().int().min(1),
+        after_sha: z3.string().optional(),
+        pass: z3.number().int().min(1).optional(),
+        after_pass: z3.number().int().min(1).optional()
       }
     },
     async ({ owner, repo, pr_number, after_sha, pass, after_pass }) => {
@@ -967,18 +1069,18 @@ function createMergestormMcpServer() {
       title: "Submit review",
       description: "Submit a local git diff (or an explicit diff) as a Mergestorm review job. Does not wait by default; returns job_id immediately after submission. Explicit wait: true polls one 45s slice by default. Record job_id and loop review_wait until done. Do not pass 300; hosts drop long MCP calls. On rate_limited, wait retry_after_seconds and inspect or wait for an in-flight review before resubmitting. specialists may be security, performance, architecture, tests, data, api, frontend. governance and seam cannot be requested.",
       inputSchema: {
-        cwd: z2.string().optional(),
-        base: z2.string().optional(),
-        head: z2.string().optional(),
-        diff: z2.string().optional(),
-        router: z2.enum(["off", "standard", "max", "manual"]).optional(),
-        specialists: z2.array(z2.string().min(1)).max(5).optional(),
-        context: z2.string().optional(),
-        context_files: z2.array(z2.string().min(1)).max(10).optional(),
-        thread: z2.string().min(1).max(120).optional(),
-        idempotency_key: z2.string().min(1).max(128).optional(),
-        wait: z2.boolean().optional(),
-        timeout_s: z2.number().positive().max(300).optional()
+        cwd: z3.string().optional(),
+        base: z3.string().optional(),
+        head: z3.string().optional(),
+        diff: z3.string().optional(),
+        router: z3.enum(["off", "standard", "max", "manual"]).optional(),
+        specialists: z3.array(z3.string().min(1)).max(5).optional(),
+        context: z3.string().optional(),
+        context_files: z3.array(z3.string().min(1)).max(10).optional(),
+        thread: z3.string().min(1).max(120).optional(),
+        idempotency_key: z3.string().min(1).max(128).optional(),
+        wait: z3.boolean().optional(),
+        timeout_s: z3.number().positive().max(300).optional()
       }
     },
     async (args) => {
@@ -995,8 +1097,8 @@ function createMergestormMcpServer() {
       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.",
       inputSchema: {
-        job_id: z2.string().min(1),
-        timeout_s: z2.number().positive().max(300).optional()
+        job_id: z3.string().min(1),
+        timeout_s: z3.number().positive().max(300).optional()
       }
     },
     async ({ job_id, timeout_s }) => {
@@ -1013,13 +1115,13 @@ function createMergestormMcpServer() {
       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.",
       inputSchema: {
-        owner: z2.string().min(1),
-        repo: z2.string().min(1),
-        pr_number: z2.number().int().min(1),
-        after_sha: z2.string().optional(),
-        pass: z2.number().int().min(1).optional(),
-        after_pass: z2.number().int().min(1).optional(),
-        timeout_s: z2.number().positive().max(300).optional()
+        owner: z3.string().min(1),
+        repo: z3.string().min(1),
+        pr_number: z3.number().int().min(1),
+        after_sha: z3.string().optional(),
+        pass: z3.number().int().min(1).optional(),
+        after_pass: z3.number().int().min(1).optional(),
+        timeout_s: z3.number().positive().max(300).optional()
       }
     },
     async ({ owner, repo, pr_number, after_sha, pass, after_pass, timeout_s }) => {
@@ -1044,7 +1146,7 @@ function createMergestormMcpServer() {
     "stack_adopt",
     {
       title: "Adopt PR stack",
-      description: "Adopt an open GitHub PR chain into a Mergestorm stack. auto_land may only be false; auto_review and auto_patch set per-stack policy, and null clears their overrides. Omitted policy keys follow the account settings. Never changes account settings. Read stack_status with result.stack.id afterward to verify policy and Cyclone ownership.",
+      description: "Adopt an open GitHub PR chain into a Mergestorm stack. auto_land is boolean; auto_review and auto_patch accept true, false, or null, where null clears the override. Omitted auto_land seeds from auto_land_default; omitted auto_review and auto_patch overrides are not seeded. Never changes account settings. Adoption requires a Cyclone GitHub App install; without it the API returns cyclone_not_connected \u2014 do not retry, tell the human. Read stack_status with result.stack.id afterward to verify policy and Cyclone ownership.",
       inputSchema: stackAdoptSchema
     },
     async (args) => {
@@ -1075,10 +1177,10 @@ function createMergestormMcpServer() {
       title: "Set stack policy",
       description: "Set per-stack automation on one owned Mergestorm stack: auto_land arms or disarms Auto land; auto_review and auto_patch pin Vortex auto-review or Cyclone auto-patch for this stack only (true or false), and null clears the pin so the stack follows the account setting again. Pass at least one key. Never changes account settings.",
       inputSchema: {
-        stack_id: z2.string().min(1),
-        auto_land: z2.boolean().optional(),
-        auto_review: z2.boolean().nullable().optional(),
-        auto_patch: z2.boolean().nullable().optional()
+        stack_id: z3.string().min(1),
+        auto_land: z3.boolean().optional(),
+        auto_review: z3.boolean().nullable().optional(),
+        auto_patch: z3.boolean().nullable().optional()
       }
     },
     async ({ stack_id, auto_land, auto_review, auto_patch }) => {
@@ -1101,7 +1203,7 @@ function createMergestormMcpServer() {
       title: "Get stack status",
       description: "Fetch one owned Mergestorm stack with enriched checks and agent state. This tool is read-only.",
       inputSchema: {
-        stack_id: z2.string().min(1)
+        stack_id: z3.string().min(1)
       }
     },
     async ({ stack_id }) => {
@@ -1112,13 +1214,29 @@ function createMergestormMcpServer() {
       }
     }
   );
+  addTool(
+    "stack_wait",
+    {
+      title: "Wait for stack attention",
+      description: "Wait for a stack to need attention. Returns a mergestorm.stack_watch/v1 envelope; timeout_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.",
+      inputSchema: stackWaitSchema
+    },
+    async (args, extra) => {
+      try {
+        const payload = await stackWait(args, void 0, { signal: extra.signal });
+        return { ...ok(payload), structuredContent: payload.data };
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  );
   addTool(
     "queue_status",
     {
       title: "Get merge queue status",
-      description: "List live merge queue entries for the current user, optionally filtered by stack. This tool is read-only.",
+      description: "List live merge queue entries (position >= 1) plus the newest bounced entries (position 0) with bounceDetail for the current user, optionally filtered by stack. This tool is read-only.",
       inputSchema: {
-        stack_id: z2.string().min(1).optional()
+        stack_id: z3.string().min(1).optional()
       }
     },
     async ({ stack_id }) => {
@@ -1147,10 +1265,18 @@ function createMergestormMcpServer() {
     "settings_set",
     {
       title: "Update settings",
-      description: "Update writable Bearer /api/v1/settings toggles and return the stored result. At least one key is required. cyclone_connected and github_connected are read-only and cannot be set.",
-      inputSchema: Object.fromEntries(
-        SETTINGS_WRITABLE_KEYS2.map((key) => [key, z2.boolean().optional()])
-      )
+      description: "Update writable Bearer /api/v1/settings values and return the stored result. At least one key is required. cyclone_connected and github_connected are read-only and cannot be set.",
+      inputSchema: {
+        ...Object.fromEntries(
+          BEARER_SETTINGS2.map((row) => [
+            row.key,
+            ("kind" in row ? row.kind === "logins" ? z3.array(z3.string()) : z3.enum(row.values) : z3.boolean()).optional()
+          ])
+        ),
+        // Preserve these args so the handler rejects them even alongside a writable key.
+        cyclone_connected: z3.unknown().optional(),
+        github_connected: z3.unknown().optional()
+      }
     },
     async (args) => {
       try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mergestorm-mcp",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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.17",
+    "mergestorm": "0.3.20",
     "zod": "^3.24.2"
   },
   "devDependencies": {