mergestorm-mcp 0.1.6 → 0.1.8

package/README.md

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

package/dist/index.js

@@ -479,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
         }
       };
@@ -719,64 +728,12 @@ import {
 } from "mergestorm/client";
 
 // src/tools/stack-summary.ts
-import {
-  BOUNCE_KIND_LABELS,
-  mergeQueueBounceLabel
-} from "mergestorm/client";
-function sameHead(a, b) {
-  const left = a?.trim().toLowerCase();
-  const right = b?.trim().toLowerCase();
-  return !!left && !!right && (left.length === right.length ? left === right : left.startsWith(right) || right.startsWith(left));
-}
-function blockerLabel(stack, entries) {
-  if (stack.archivedAt) return null;
-  const queue = entries.filter((entry) => entry.stackId === stack.id);
-  if (queue.some((entry) => ["queued", "running", "waiting"].includes(entry.state))) return null;
-  const open = stack.layers.filter(
-    (layer2) => layer2.prNumber > 0 && layer2.state !== "merged" && layer2.state !== "closed"
-  );
-  const promote = open.filter(
-    (layer2) => layer2.prNumber !== stack.unit?.landPrNumber && !stack.unit?.members?.some(
-      (member) => member.prNumber === layer2.prNumber && member.promotedHeadSha
-    )
-  ).sort((a, b) => a.position - b.position);
-  const layer = promote[0] ?? open.find((layer2) => layer2.prNumber === stack.unit?.landPrNumber) ?? stack.unit?.landPr;
-  const bounce = queue.filter((entry) => entry.state === "bounced").sort((a, b) => (Date.parse(b.finishedAt ?? "") || 0) - (Date.parse(a.finishedAt ?? "") || 0))[0];
-  const bounceKind = bounce?.bounceDetail?.kind;
-  const recoverableBounceSha = (bounceKind === "head_moved" ? bounce?.bounceDetail?.headSha ?? bounce?.verifyHeadSha : bounce?.verifyHeadSha ?? bounce?.bounceDetail?.headSha)?.trim().toLowerCase();
-  const currentRecoverableBounce = !!recoverableBounceSha && (bounceKind === "head_moved" || bounceKind === "must_consolidate") && !!layer && layer.state !== "merged" && layer.state !== "closed" && sameHead(layer.headSha, recoverableBounceSha);
-  if (layer && layer.state !== "merged" && layer.state !== "closed") {
-    if (layer.restackError && layer.state !== "restacking") {
-      return layer.restackError.kind === "rebase_conflict" ? "Conflict" : "Restack failed";
-    }
-    if (layer.state === "conflict") return "Conflict";
-    if (layer.draft) return "Draft PR";
-    if ((!layer.headSha || layer.mergeableHeadSha === layer.headSha) && (layer.mergeable === false || layer.mergeableState?.toLowerCase() === "dirty")) return "Merge conflicts";
-    if (!currentRecoverableBounce && (layer.ciStatus === "failure" || (layer.checks?.failure ?? 0) > 0)) {
-      const name = layer.checks?.failingName?.trim();
-      return BOUNCE_KIND_LABELS.ci_failure + (name ? ` \u2014 ${name}` : "");
-    }
-    const tempest = layer.agentRuns?.find(
-      (run) => run.agent === "tempest" && ["findings", "failed"].includes(run.status) && sameHead(run.sha, layer.headSha)
-    );
-    if (tempest) return `Tempest ${tempest.status}`;
-    if (layer.vortexStatus === "failed") return "Review failed";
-    if (stack.unit?.landPrNumber === layer.prNumber) {
-      if (stack.unit.landingBlockReason?.trim()) return stack.unit.landingBlockReason.trim();
-      if (stack.unit.tempestLandStatus?.toLowerCase() === "failed") return "Tempest failed";
-    }
-  }
-  const kind = bounceKind;
-  if (!kind || kind === "head_moved" || kind === "must_consolidate") return null;
-  const sha = (bounce.bounceDetail?.headSha ?? bounce.verifyHeadSha)?.trim().toLowerCase();
-  const current = sha && layer && layer.prNumber > 0 && layer.state !== "merged" && layer.state !== "closed" && (bounce.bounceDetail?.prNumber == null || layer.prNumber === bounce.bounceDetail.prNumber) && sameHead(layer.headSha, sha);
-  return current ? mergeQueueBounceLabel(bounce) : null;
-}
+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"}`);
@@ -787,8 +744,8 @@ function stackSummary(stack, entries = []) {
   if (stack.cycloneOwnerMatch) {
     overrides.push(`cyclone-owner ${stack.cycloneOwnerMatch}`);
   }
-  const blocker = blockerLabel(stack, entries);
-  return `${stack.owner}/${stack.repo} \xB7 ${layerLabel} \xB7 ${currentState} \xB7 auto-land ${stack.autoEnqueueWhenReady ? "on" : "off"}${overrides.map((label) => ` \xB7 ${label}`).join("")}${blocker ? ` \xB7 blocked: ${blocker}` : ""}`;
+  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
@@ -821,6 +778,7 @@ async function stackList(cfg) {
 // src/tools/stack-wait.ts
 import {
   loadConfig as loadConfig6,
+  stackBlockersSummary as stackBlockersSummary2,
   pollStackWatch,
   StackWatchError,
   StackWatchTimeoutError
@@ -851,7 +809,7 @@ async function stackWait(input, cfg, deps = {}) {
   } catch (err) {
     if (err instanceof StackWatchError) {
       return {
-        summary: `Stack ${err.lastEnvelope.stackId} \xB7 ${err.lastEnvelope.status}`,
+        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 } : {}
@@ -860,10 +818,10 @@ async function stackWait(input, cfg, deps = {}) {
       };
     }
     if (!(err instanceof StackWatchTimeoutError)) throw err;
-    envelope = { ...err.lastEnvelope, status: "waiting" };
+    envelope = err.lastEnvelope;
   }
   return {
-    summary: `Stack ${envelope.stackId} \xB7 ${envelope.status}${envelope.blocker ? ` \xB7 ${envelope.blocker}` : ""}`,
+    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
   };
 }
@@ -872,7 +830,8 @@ async function stackWait(input, cfg, deps = {}) {
 import {
   getEnrichedStack,
   listMergeQueueEntries as listMergeQueueEntries2,
-  isCommandErrorCode as isCommandErrorCode5
+  isCommandErrorCode as isCommandErrorCode5,
+  stackBlockers as stackBlockers2
 } from "mergestorm/client";
 async function stackStatus(stackId, cfg) {
   try {
@@ -891,10 +850,11 @@ async function stackStatus(stackId, cfg) {
         isError: true
       };
     }
-    const entries = await listMergeQueueEntries2(cfg);
+    const entries = await listMergeQueueEntries2(cfg, { stackId: stack.id });
+    const { attention, issues, currentCandidate } = stackBlockers2(stack, entries);
     return {
       summary: stackSummary(stack, entries),
-      data: { stack }
+      data: { stack, attention, issues, currentCandidate }
     };
   } catch (err) {
     if (isCommandErrorCode5(err, "rate_limited")) {
@@ -963,10 +923,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.6";
+var MCP_SERVER_VERSION = "0.1.8";
 function stripNulls(value) {
   if (Array.isArray(value)) {
     return value.map((item) => stripNulls(item));
@@ -1000,7 +970,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(
@@ -1231,7 +1203,7 @@ function createMergestormMcpServer() {
     "stack_status",
     {
       title: "Get stack status",
-      description: "Fetch one owned Mergestorm stack with enriched checks and agent state. This tool is read-only.",
+      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.",
       inputSchema: {
         stack_id: z3.string().min(1)
       }
@@ -1248,7 +1220,7 @@ function createMergestormMcpServer() {
     "stack_wait",
     {
       title: "Wait for stack attention",
-      description: "Wait for a stack to need attention. Returns a mergestorm.stack_watch/v1 envelope; timeout returns waiting. This tool is read-only. Do not pass 300; hosts drop long MCP calls.",
+      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) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mergestorm-mcp",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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.19",
+    "mergestorm": "0.3.22",
     "zod": "^3.24.2"
   },
   "devDependencies": {