mergestorm-mcp 0.2.5 → 0.2.7

package/README.md

@@ -24,7 +24,7 @@ The stack tools expose reads plus one scoped policy write:
 - `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 blocker no agent run clears (a merge conflict vs the live parent, a restack `Conflict` or `Restack failed`, a Draft PR, a seam review pending with no review running) 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.
 
-Agents that cannot hold a long turn open should not poll `stack_wait` inside their turn. The server instructions tell them to run `mg stack watch <stack-id>` from the `mergestorm` CLI as a background command, notify on output matching `MS-WATCH (ATTENTION|LANDED)`, and end the turn. The watcher loops the same stack wait against the Mergestorm API with the cursor, stays silent while the stack is waiting or in progress, and exits on attention (exit 3), a failed read that failed again on retry (exit 3), or a finished watch (exit 0). On wake the agent reads `stack_status` once, fixes the blocker, pushes, and restarts the watcher with `--head <pushed-sha>`. The stack is still not done until it lands. Agents are told not to subscribe to GitHub events to wait on a stack.
+Agents that cannot hold a long turn open should not poll `stack_wait` inside their turn. The server instructions tell them to run `mg stack watch <stack-id>` from the `mergestorm` CLI as a background command, notify on output matching `MS-WATCH (ATTENTION|LANDED)`, and end the turn. The watcher loops the same stack wait against the Mergestorm API with the cursor, stays silent while the stack is waiting or in progress, and exits on attention (exit 3), a failed read that failed again on retry (exit 3), or a finished watch (exit 0). Every `watch.next` carries that command as `watch.next.background`, and every not-done `watch.message` offers it before the next `stack_wait` call. On wake the agent reads `stack_status` once, fixes the blocker, pushes, and restarts the watcher with `--head <pushed-sha>`. The stack is still not done until it lands. Agents are told not to subscribe to GitHub events to wait on a stack.
 
 Auth is `MERGESTORM_API_KEY`, then `~/.mergestorm/config.json` (same as `mg`).
 

package/dist/index.js

@@ -37,6 +37,17 @@ var MCP_WEBSITE_URL = SITE;
 
 // src/tools/credits.ts
 import { CommandError, getMe, loadConfig } from "mergestorm/client";
+function formatMinutes(value) {
+  return value.toLocaleString("en-US", { maximumFractionDigits: 1 });
+}
+function surgeSummary(surge) {
+  if (!surge) return "";
+  const wallet = `wallet ${formatMinutes(surge.walletMinutes)} min`;
+  if (surge.includedMinutes <= 0) return `
+Surge: ${wallet}`;
+  return `
+Surge: ${formatMinutes(surge.usedMinutes)} of ${formatMinutes(surge.includedMinutes)} included min this period \xB7 ${wallet}`;
+}
 async function credits(cfg) {
   const resolved = cfg ?? await loadConfig();
   const me = await getMe(resolved);
@@ -53,9 +64,10 @@ async function credits(cfg) {
   const standard = me.usage.standard;
   const remaining = standard.remaining ?? (standard.limit != null ? Math.max(0, standard.limit - standard.used) : null);
   const bonusRemaining = me.usage.bonus?.remaining;
+  const surge = me.usage.surge;
   const bonusSummary = bonusRemaining == null ? "" : ` \xB7 ${bonusRemaining} bonus remaining`;
   return {
-    summary: remaining == null ? `${standard.used} used \xB7 unlimited${bonusSummary}` : `${standard.used} used \xB7 ${remaining} remaining${bonusSummary}`,
+    summary: remaining == null ? `${standard.used} used \xB7 unlimited${bonusSummary}${surgeSummary(surge)}` : `${standard.used} used \xB7 ${remaining} remaining${bonusSummary}${surgeSummary(surge)}`,
     data: {
       usage: me.usage,
       resets_at: me.resets_at ?? null
@@ -175,6 +187,7 @@ import {
   pollStackWatch,
   StackWatchError,
   StackWatchTimeoutError,
+  stackWatchBackgroundCommand,
   stackWatchObligation
 } from "mergestorm/client";
 import { z } from "zod";
@@ -216,7 +229,7 @@ function stackWaitStatusLine(envelope) {
     ...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(", ")}`;
+  return `${base} \xB7 watch not finished: run ${stackWatchBackgroundCommand(envelope.stackId)} as a background command and end your turn, or 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);
@@ -1127,20 +1140,21 @@ var MCP_STACK_WATCH_INSTRUCTIONS = [
   "- mg-park-* is a frozen GitHub base, not a repair target: never merge or rebase onto mg-park-*.",
   "- merge_failed, gh_error, and ci_timeout bounces turn Auto land off, and stack autoLandOff then reads reason bounced with that queue entry's id; any other autoLandOff reason (user, archive, watcher, cancelled, landed) is not a bounce to undo. The watching agent turns Auto land back on with stack_set auto_land: true once it has handled that bounce, at most once per bounce and 3 times per watch; mergestorm-bounce-watch has the conditions.",
   '- While stack autoLandOff reads reason bounced, the watch returns attention: blocker "Auto land off after <kind> bounce", the bounce in issues[], repair kind auto_land_off.',
+  '- A stack whose review unit was abandoned (a human moved its bottom PR off mg-stack-N) returns attention: blocker "Review unit abandoned: based on <base>", repair kind unit_abandoned. Do not patch or retarget; ask the human whether to re-root it. If at least two PRs remain open, tell them that mg stack adopt owner/repo#<bottom PR> re-roots it on a new review unit. With only one open PR, re-adopting will not create a review unit, so tell them to close and resubmit it to create a fresh stack.',
   "- Tempest never patches. Cyclone patches a land PR when auto-patch is on for that stack (its override, else the account setting); otherwise the watching agent fixes tempest_findings on the land PR, and repair kind tempest_findings names it.",
   "- 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.2.5";
+var MCP_SERVER_VERSION = "0.2.7";
 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.';
+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, or run watch.next.background as a background command and end your turn.';
 function stripNulls(value) {
   if (Array.isArray(value)) {
     return value.map((item) => stripNulls(item));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mergestorm-mcp",
-  "version": "0.2.5",
+  "version": "0.2.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.30",
+    "mergestorm": "0.3.34",
     "zod": "^3.24.2"
   },
   "devDependencies": {