mergestorm-mcp 0.2.0 → 0.2.2

package/README.md

@@ -1,18 +1,28 @@
 # mergestorm-mcp
 
-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`.
+Stdio MCP server for Mergestorm. Tools: `whoami`, `credits`, `review_list`, `review_submit`, `review_wait`, `review_wait_pr`, `review_dismiss`, `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`.
+Every tool declares MCP `annotations`. The reads carry `readOnlyHint: true`; `review_submit`, `review_dismiss`, `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.
 
+`review_dismiss({ owner, repo, pr_number, head_sha, review_id, finding_ids?, scope?, reason?, evidence_url?, preview? })` records an audited dismissal of Vortex findings the agent verified are wrong. The rules:
+
+- **Exact identity.** `head_sha` is the PR's live head and `review_id` is a Vortex review (Core or seam) made at that head. `finding_ids` are that review's GitHub review comment ids (`offdiff-<n>` for a finding listed only in the review body, `review` for a body-only review). `scope: "review"` with no `finding_ids` covers every finding of the review.
+- **Preview first.** `preview: true` lists the review's finding ids and the seam gate, and writes nothing.
+- **Authorization.** The API key's account must monitor the repository or own the PR's stack, and its linked GitHub account needs write access to the repository.
+- **Refusals.** A moved head (`stale_head`), another review (`review_mismatch`, `review_not_found`), an id outside that review (`unknown_finding`), a thin `reason` (`invalid_input`) or a missing permission (`forbidden`) is refused, and nothing is written.
+- **Audit and retries.** Each finding is stored with the actor's GitHub login, the reason, `evidence_url`, the scope and the time. A retry reports the earlier record under `already_dismissed`.
+- **Gates.** `gate.seam.cleared` is true only when every finding of that integration review is dismissed and it is still the member's current seam verdict. CI, other reviews and Auto land policy are unchanged (`gate.other_gates: "unchanged"`). For a stack PR the result carries `watch` with the next `stack_wait` call.
+- **No resurfacing.** Vortex does not raise a dismissed finding again on the same diff: the same head, or a restack whose diff is unchanged.
+
 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, 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`. 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.
+- `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 blocker no agent run clears (a merge conflict vs the live parent, a restack `Conflict` or `Restack failed`, a Draft PR) is still named during that `in_progress`, in `blocker`, `prNumber`, `headSha`, and `issues[]`, with `actAfter: "agents_idle"` and `waitingOn` listing the busy agents; act when a snapshot after the agents finish returns `attention`, re-reading the blocker then. `repair` is included when a concrete repair hint is available. Blockers the agents can change keep `blocker` and `actAfter` null. If a hold 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

@@ -162,6 +162,153 @@ async function queueStatus(stackId, cfg) {
   }
 }
 
+// src/tools/review-dismiss.ts
+import {
+  dismissPrFindings,
+  stackWatchObligation as stackWatchObligation2
+} from "mergestorm/client";
+
+// src/tools/stack-wait.ts
+import {
+  loadConfig as loadConfig3,
+  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.actAfter ?? null)}${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 loadConfig3(), 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/review-dismiss.ts
+function findingText(finding) {
+  return `${finding.finding_id} (${finding.path ?? "review body"}: ${finding.title})`;
+}
+function reviewDismissSummary(result) {
+  const pr = `${result.owner}/${result.repo}#${result.pr_number}`;
+  const kind = result.review_kind === "seam" ? "seam review" : "Vortex review";
+  const head = `${kind} ${result.review_id} at ${result.head_sha.slice(0, 7)}`;
+  const lines = [];
+  if (result.status === "preview") {
+    lines.push(`${pr} ${head}: ${result.remaining.length} open finding(s). Nothing was written.`);
+    for (const finding of result.remaining) lines.push(`- ${findingText(finding)}`);
+  } else {
+    lines.push(
+      `${pr} ${head}: dismissed ${result.dismissed.length}, already dismissed ${result.already_dismissed.length}, still open ${result.remaining.length}.`
+    );
+    for (const finding of result.remaining) lines.push(`- open: ${findingText(finding)}`);
+  }
+  const seam = result.gate.seam;
+  if (seam) {
+    lines.push(
+      seam.cleared ? "Seam gate cleared at this head. CI, other reviews and Auto land policy are unchanged." : seam.blocking ? `Seam gate still blocking (seam_state=${seam.state}).` : `Seam gate not blocking (seam_state=${seam.state}).`
+    );
+  }
+  return lines.join("\n");
+}
+async function reviewDismiss(input, cfg) {
+  const request = {
+    owner: input.owner,
+    repo: input.repo,
+    prNumber: input.pr_number,
+    headSha: input.head_sha,
+    reviewId: input.review_id,
+    ...input.scope ? { scope: input.scope } : {},
+    ...input.finding_ids ? { findingIds: input.finding_ids } : {},
+    ...input.reason !== void 0 ? { reason: input.reason } : {},
+    ...input.evidence_url ? { evidenceUrl: input.evidence_url } : {},
+    ...input.preview ? { preview: true } : {}
+  };
+  const outcome = await dismissPrFindings(request, cfg);
+  if (!outcome.ok) {
+    return {
+      summary: `review_dismiss refused (${outcome.error}): ${outcome.message}`,
+      isError: true,
+      data: { error: { code: outcome.error, message: outcome.message, status: outcome.status } }
+    };
+  }
+  const result = outcome.result;
+  const summary = reviewDismissSummary(result);
+  if (!result.stack_id) return { summary, data: { ...result } };
+  const watch = stackWatchObligation2({ stackId: result.stack_id, terminal: null, unread: true, freshCursor: true });
+  return { summary: withWatchText(watch, summary), data: { ...result, watch } };
+}
+
 // src/tools/review-list.ts
 import { listJobs, toReviewJobEnvelope } from "mergestorm/client";
 async function reviewList(limit = 10, cfg) {
@@ -185,7 +332,7 @@ import {
   collectReviewInput,
   discoverTrunk,
   formatReviewSubmitError,
-  loadConfig as loadConfig3,
+  loadConfig as loadConfig4,
   loadReviewContext,
   pollReview,
   rateLimitedMessage as rateLimitedMessage2,
@@ -289,7 +436,7 @@ async function resolveInput(input) {
   return collectReviewInput(base, head, cwd, sandboxRoot);
 }
 async function reviewSubmit(input, cfg, opts = {}) {
-  const resolved = cfg ?? await loadConfig3();
+  const resolved = cfg ?? await loadConfig4();
   const wait = input.wait === true;
   const timeoutMs = waitTimeoutMs(input.timeout_s);
   assertPinnableSpecialists(input.specialists);
@@ -376,7 +523,7 @@ async function reviewSubmit(input, cfg, opts = {}) {
 // src/tools/review-wait-pr.ts
 import {
   PrReviewPollTimeoutError,
-  loadConfig as loadConfig4,
+  loadConfig as loadConfig5,
   pollPrVortexReview
 } from "mergestorm/client";
 
@@ -458,7 +605,7 @@ async function reviewGetPr(owner, repo, prNumber, cfg, opts = {}) {
 // 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();
+  const resolved = cfg ?? await loadConfig5();
   if (timeout_s === 0) {
     return reviewGetPr(target.owner, target.repo, target.prNumber, resolved, {
       afterSha,
@@ -527,7 +674,7 @@ async function reviewWaitPr(owner, repo, prNumber, afterSha, timeout_s, cfg, opt
 import {
   CommandError as CommandError6,
   ReviewPollTimeoutError as ReviewPollTimeoutError2,
-  loadConfig as loadConfig5,
+  loadConfig as loadConfig6,
   pollReview as pollReview2
 } from "mergestorm/client";
 
@@ -560,7 +707,7 @@ async function reviewGet(jobId, cfg) {
 
 // src/tools/review-wait.ts
 async function reviewWait(jobId, timeout_s, cfg, opts = {}) {
-  const resolved = cfg ?? await loadConfig5();
+  const resolved = cfg ?? await loadConfig6();
   const id = jobId.trim();
   if (!id) {
     throw new CommandError6("job_id is required", 2, "usage");
@@ -672,11 +819,11 @@ async function settingsSet(args, cfg) {
 }
 
 // src/tools/stack-adopt.ts
-import { adoptStack, CommandError as CommandError9 } from "mergestorm/client";
-import { z } from "zod";
+import { adoptStack, CommandError as CommandError9, stackWatchObligation as stackWatchObligation4 } from "mergestorm/client";
+import { z as z2 } from "zod";
 
 // src/tools/stack-set.ts
-import { setStackPolicy } from "mergestorm/client";
+import { setStackPolicy, stackWatchObligation as stackWatchObligation3 } from "mergestorm/client";
 function triWord(value) {
   return value === null ? "default" : value ? "on" : "off";
 }
@@ -713,28 +860,30 @@ async function stackSet(stackId, input, cfg) {
   if (input.auto_patch !== void 0) {
     parts.push(`auto-patch ${triWord(input.auto_patch)}`);
   }
+  const watch = stackWatchObligation3({ 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 +899,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 = stackWatchObligation4({ 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 +933,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 +949,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, held, 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 ?? held, issues, busy, landGatePending, held?.actAfter ?? null)}`;
 }
 
 // src/tools/stack-list.ts
@@ -825,108 +980,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 stackWatchObligation5
 } 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 = stackWatchObligation5({ 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, held, issues, currentCandidate, busy, agents, repair, landGatePending } = stackBlockers2(stack, entries);
+    const watch = stackWatchObligation5({
+      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, held, issues, currentCandidate, busy, agents, repair, landGatePending, watch }
     };
   } catch (err) {
     if (isCommandErrorCode5(err, "rate_limited")) {
+      const watch = stackWatchObligation5({
+        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
       };
@@ -982,13 +1094,21 @@ var MCP_PR_LOOP_INSTRUCTIONS = [
   "- 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)."
+  "- Do not prefix that comment with cyclone-outcome: (reserved).",
+  "- A finding you verified is wrong can be dismissed on the record with review_dismiss (or mg dismiss): pass the PR's live head_sha, the review_id, the finding_ids (preview: true lists them) and a reason. That is the only agent path that clears a seam gate, and only once every finding of that seam review is dismissed. The dismiss comment alone resumes the review but does not clear the seam gate.",
+  "- Never dismiss a finding you did not check, one a human must decide, or findings of a newer review."
+].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>.",
   "- Never retarget a stack PR's GitHub base (gh pr edit --base, a REST base change, or the UI). Moving the bottom to main makes Mergestorm abandon the stack's review unit; setting mg-stack-<n> again does not restore it. If a base was already moved, stop and tell the human; do not run stack land or re-adopt to repair it.",
-  "- mg-stack-<n> is the bottom PR's live parent: merging it into the bottom branch is that PR's conflict repair (bounce-watch rules). Never push to mg-stack-<n>, and never rebase or merge layer 2+ onto it or onto main. mg-park-* is never a merge or rebase target.",
+  "- mg-stack-<n> is the bottom PR's live parent: merging it into the bottom branch is that PR's conflict repair (bounce-watch rules). Never push to mg-stack-<n> except as the land PR's own repair: once every layer is promoted, the land PR's head is mg-stack-<n> and its live parent is its base (main), so merging main into mg-stack-<n>, or a CI fix on it, with an ordinary push (no force) is that repair. Never rebase or merge layer 2+ onto mg-stack-<n> or onto main. mg-park-* is never a merge or rebase target.",
   "- mg stack submit prints the base each PR opened with; the bottom moves to mg-stack-<n> right after. stack_status trunkBranch is the current trunk."
 ].join("\n");
 var MCP_STACK_WATCH_INSTRUCTIONS = [
@@ -999,7 +1119,8 @@ var MCP_STACK_WATCH_INSTRUCTIONS = [
   "- 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.",
+  "- 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; if it looks stuck, refresh stack_status and tell the human.",
+  '- A blocker no Vortex or Cyclone run clears (a merge conflict vs the live parent, a restack Conflict or Restack failed, a Draft PR) stays in_progress during the hold but is named in blocker, prNumber, headSha, and issues[], with actAfter: "agents_idle" and waitingOn listing the busy agents. Plan the fix; act only when a snapshot after the agents finish returns attention, and re-read the blocker then. Blockers the agents can change keep blocker null and appear only in busy[].',
   "- 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."
@@ -1007,7 +1128,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.2";
+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 +1172,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(
@@ -1181,11 +1305,38 @@ ${MCP_STACK_WATCH_INSTRUCTIONS}` }
       }
     }
   );
+  addTool(
+    "review_dismiss",
+    {
+      title: "Dismiss Vortex findings",
+      description: `Record an audited dismissal of Vortex findings you verified are wrong or not actionable on a GitHub PR. Identity is exact: head_sha must be the PR's live head, review_id a Vortex review (Core or seam) made at that head, and finding_ids the GitHub review comment ids of that review (offdiff-<n> for a body-only finding), or scope "review" with no finding_ids to dismiss every finding of that review. reason must say why (at least 20 characters); evidence_url is optional. Call with preview: true first to list the review's finding ids and the seam gate without writing. The caller's linked GitHub account needs write access to the repository. A moved head, another review, an unknown id or a missing permission is refused and nothing is written. Retries are idempotent. The seam gate clears only when every finding of that integration review is dismissed; CI, other reviews and Auto land policy are unchanged. Vortex does not raise a dismissed finding again on the same diff. Never dismiss a finding you did not check.` + STACK_WATCH_RESULT_NOTE,
+      inputSchema: {
+        owner: z3.string().min(1),
+        repo: z3.string().min(1),
+        pr_number: z3.number().int().min(1),
+        head_sha: z3.string().regex(/^[0-9a-fA-F]{40}$/),
+        review_id: z3.number().int().min(1),
+        finding_ids: z3.array(z3.string().min(1)).max(50).optional(),
+        scope: z3.enum(["findings", "review"]).optional(),
+        reason: z3.string().optional(),
+        evidence_url: z3.string().url().optional(),
+        preview: z3.boolean().optional()
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true }
+    },
+    async (args) => {
+      try {
+        return ok(await reviewDismiss(args));
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  );
   addTool(
     "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 +1367,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 +1394,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. held names a blocker no agent run clears while Vortex or Cyclone is still busy on that PR (actAfter agents_idle, waitingOn); repair then describes the fix to plan, not to apply yet." + STACK_WATCH_RESULT_NOTE,
       inputSchema: {
         stack_id: z3.string().min(1)
       },
@@ -1261,7 +1412,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. A blocker no agent run clears (a merge conflict vs the live parent, a restack Conflict or Restack failed, a Draft PR) is still named during that in_progress, in blocker, prNumber, headSha, and issues[], with actAfter: "agents_idle" and waitingOn listing the busy agents: plan the fix, and act when a snapshot after the agents finish returns attention, re-reading the blocker then. Blockers the agents can change keep blocker and actAfter null. Attention never calls for changing a PR's GitHub base. When present, 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.2",
   "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.27",
     "zod": "^3.24.2"
   },
   "devDependencies": {