mergestorm-mcp 0.2.0 → 0.2.1

package/dist/index.js

@@ -672,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";
 }
@@ -713,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) {
@@ -750,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);
@@ -778,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"}`;
@@ -794,8 +891,8 @@ function stackSummary(stack, entries = []) {
   if (stack.cycloneOwnerMatch) {
     overrides.push(`cyclone-owner ${stack.cycloneOwnerMatch}`);
   }
-  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)}`;
+  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
@@ -825,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.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 ? {
-    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, busy, agents } = 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, busy, agents }
+      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
       };
@@ -984,6 +1038,12 @@ 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_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>.",
@@ -1007,7 +1067,14 @@ var MCP_STACK_WATCH_INSTRUCTIONS = [
 
 // src/server.ts
 var MCP_SERVER_NAME = "mergestorm";
-var MCP_SERVER_VERSION = "0.2.0";
+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));
@@ -1044,11 +1111,7 @@ function createMergestormMcpServer() {
       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(
@@ -1185,7 +1248,7 @@ ${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.",
+      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 }
     },
@@ -1216,7 +1279,7 @@ ${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(),
@@ -1243,7 +1306,7 @@ ${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. 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)
       },
@@ -1261,7 +1324,7 @@ ${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. 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.",
+      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 }
     },

package/package.json

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