mergestorm 0.3.30 → 0.3.31

package/README.md

@@ -45,7 +45,7 @@ On a TTY, bare `mergestorm` (or `mergestorm shell`) opens a branded REPL: a comp
 
 ```
 ╭──────────────────────────────────────────────────────────────────────────────╮
-│  ▀▀▀▀▀▀▀▀▀▀▘  mergestorm v0.3.30                                             │
+│  ▀▀▀▀▀▀▀▀▀▀▘  mergestorm v0.3.31                                             │
 │ ▀▀▀▀▀▀▀▀▀     ● msk_live_… · maelstrom                                       │
 │  ▀▀▀▀▀▀       [████████░░░░░░░░░░░░░░░░░░░░░░] 25% used                      │
 │   ▝▀▀▀▀▀      local reviews + stacked PRs · mergestorm.ai                    │
@@ -129,7 +129,7 @@ Use `mergestorm dismiss` when a Vortex finding is wrong and you have checked it
 - Retrying the same dismissal is safe; it reports the earlier record.
 - The seam gate clears only when every finding of that integration review is dismissed and the review is still the current seam verdict. CI, other reviews and Auto land policy still apply.
 - Vortex does not raise a dismissed finding again on the same diff (the same head, or a restack with an unchanged diff).
-- With `--json`, the result carries `gate` and, for a stack PR, `watch.next` (the next `stack_wait` call).
+- With `--json`, the result carries `gate` and, for a stack PR, `watch.next` (the next `stack_wait` call, plus `watch.next.background`, the `mg stack watch` command to run in the background instead).
 
 `mg` is a short alias for `mergestorm` (same binary), e.g. `mg stack create`. Happy path: **create → commit → submit → restack → land**. On review-unit stacks, `stack land` **promotes** the tip into the unit (same gates as the dashboard); otherwise it lands the bottom open PR. `stack adopt` is for importing a chain that already exists on GitHub (legacy / Graphite). Restack/land use the same login key (`/api/v1/stacks`). Unattended landing is `mg queue add`.
 

package/dist/api.d.ts

@@ -29,6 +29,13 @@ export declare function devicePost(base: string, route: string, json: unknown, o
     status: number;
     body: any;
 }>;
+export type SurgeUsage = {
+    includedMinutes: number;
+    usedMinutes: number;
+    walletMinutes: number;
+    windowStart: string;
+    pricePerMinuteUsd: number;
+};
 export type MeResponse = {
     key: {
         prefix: string;
@@ -50,6 +57,7 @@ export type MeResponse = {
         bonus?: {
             remaining: number;
         };
+        surge?: SurgeUsage;
     };
 };
 export type JobListItem = {

package/dist/client/index.d.ts

@@ -8,4 +8,4 @@ export { discoverTrunk } from "../git-stack.js";
 export { BOUNCE_KIND_LABELS, deriveStackAgentsBusy, mergeQueueBounceLabel, type StackAgentsBusy } from "../stack-dto.js";
 export { STACK_WATCH_SCHEMA, STACK_WATCH_DEFAULT_TIMEOUT_MS, STACK_WATCH_BUSY_RECHECK_S, StackWatchError, StackWatchTimeoutError, pollStackWatch, type PollStackWatchOptions, type StackWatchCursor, type StackWatchEnvelope, } from "../stack-watch.js";
 export { stackBlockers, stackBlockersSummary, sameHead, layerAgents, layerAgentsBusy, conflictLiveParent, stackRepair, agentsCannotClear, type StackAgentBusy, type StackBlocker, type StackBusyAgent, type StackHeldBlocker, type StackLandGatePending, type StackLayerAgents, type StackRepairHint, } from "../stack-blockers.js";
-export { STACK_WATCH_NOT_DONE_SENTENCE, stackTerminalReason, stackWatchNextArgs, stackWatchObligation, type StackWatchDoneReason, type StackWatchNext, type StackWatchNextArgs, type StackWatchObligation, type StackWatchObligationInput, type StackWatchReason, } from "../stack-watch-obligation.js";
+export { STACK_WATCH_NOT_DONE_SENTENCE, STACK_WATCH_NOTIFY_PATTERN, stackWatchBackgroundCommand, stackTerminalReason, stackWatchNextArgs, stackWatchObligation, type StackWatchDoneReason, type StackWatchNext, type StackWatchNextArgs, type StackWatchObligation, type StackWatchObligationInput, type StackWatchReason, } from "../stack-watch-obligation.js";

package/dist/client/index.js

@@ -8,4 +8,4 @@ export { discoverTrunk } from "../git-stack.js";
 export { BOUNCE_KIND_LABELS, deriveStackAgentsBusy, mergeQueueBounceLabel } from "../stack-dto.js";
 export { STACK_WATCH_SCHEMA, STACK_WATCH_DEFAULT_TIMEOUT_MS, STACK_WATCH_BUSY_RECHECK_S, StackWatchError, StackWatchTimeoutError, pollStackWatch, } from "../stack-watch.js";
 export { stackBlockers, stackBlockersSummary, sameHead, layerAgents, layerAgentsBusy, conflictLiveParent, stackRepair, agentsCannotClear, } from "../stack-blockers.js";
-export { STACK_WATCH_NOT_DONE_SENTENCE, stackTerminalReason, stackWatchNextArgs, stackWatchObligation, } from "../stack-watch-obligation.js";
+export { STACK_WATCH_NOT_DONE_SENTENCE, STACK_WATCH_NOTIFY_PATTERN, stackWatchBackgroundCommand, stackTerminalReason, stackWatchNextArgs, stackWatchObligation, } from "../stack-watch-obligation.js";

package/dist/commands/browse.js

@@ -221,6 +221,7 @@ export async function openTabsBrowser(initial) {
                 used: me.usage.standard.used,
                 limit: me.usage.standard.limit,
                 bonusRemaining: me.usage.bonus?.remaining,
+                surge: me.usage.surge,
                 resetsAt: me.resets_at,
                 jobs: jobs.slice(0, 5).map(toPanelJob),
                 jobsError: jobsError ?? undefined,

package/dist/commands/credits.js

@@ -37,6 +37,7 @@ export async function cmdCredits(args) {
         used: s.used,
         limit: s.limit,
         bonusRemaining: me.usage.bonus?.remaining,
+        surge: me.usage.surge,
         resetsAt: me.resets_at,
         jobs: recentJobs.map(toPanelJob),
         columns,

package/dist/commands/dismiss.js

@@ -120,7 +120,7 @@ export function formatDismissResult(result, watch) {
                 : `Seam gate: not blocking (seam_state=${seam.state}).`);
     }
     if (watch?.next)
-        lines.push(`Next: ${watch.next.command}`);
+        lines.push(`Next: ${watch.next.background} as a background command, or ${watch.next.command}`);
     return lines.join("\n");
 }
 export async function cmdDismiss(args, deps = {}) {

package/dist/commands/stack.js

@@ -1,5 +1,5 @@
 import { stackBlockers, stackBlockersSummary } from "../stack-blockers.js";
-import { STACK_WATCH_NOT_DONE_SENTENCE, stackTerminalReason, stackWatchObligation, } from "../stack-watch-obligation.js";
+import { STACK_WATCH_NOT_DONE_SENTENCE, STACK_WATCH_NOTIFY_PATTERN, stackTerminalReason, stackWatchObligation, } from "../stack-watch-obligation.js";
 import { adoptStack, ensureUpperPark, findStackPull, getEnrichedStack, landNextStack, listStacks, openStackPull, restackStack, setStackPolicy, } from "../api.js";
 import { loadConfig } from "../config.js";
 import { rateLimitedMessage, REVIEW_EXIT, CommandError } from "../errors.js";
@@ -36,7 +36,10 @@ export function stackWatchTextLines(watch) {
         return [watch.message];
     const next = watch.next;
     return [
-        ...(next ? [`Next: ${next.command} (MCP: stack_wait ${JSON.stringify(next.args)})`] : []),
+        ...(next ? [
+            `Next: ${next.background} as a background command (notify on ${STACK_WATCH_NOTIFY_PATTERN}, then end your turn)`,
+            `Or poll: ${next.command} (MCP: stack_wait ${JSON.stringify(next.args)})`,
+        ] : []),
         STACK_WATCH_NOT_DONE_SENTENCE,
     ];
 }

package/dist/stack-watch-obligation.d.ts

@@ -1,5 +1,7 @@
 import type { StackDto } from "./stack-dto.js";
 export declare const STACK_WATCH_NOT_DONE_SENTENCE = "This stack is not landed. Your task is not done. Call stack_wait again with this cursor.";
+export declare const STACK_WATCH_NOTIFY_PATTERN = "MS-WATCH (ATTENTION|LANDED)";
+export declare function stackWatchBackgroundCommand(stackId: string): string;
 export type StackWatchDoneReason = "landed" | "closed" | "archived" | "not_found";
 export type StackWatchReason = StackWatchDoneReason | "open" | "attention" | "unread" | "rate_limited" | "failed";
 export type StackWatchNextArgs = {
@@ -13,6 +15,7 @@ export type StackWatchNext = {
     tool: "stack_wait";
     args: StackWatchNextArgs;
     command: string;
+    background: string;
 };
 export type StackWatchObligation = {
     done: boolean;

package/dist/stack-watch-obligation.js

@@ -1,4 +1,8 @@
 export const STACK_WATCH_NOT_DONE_SENTENCE = "This stack is not landed. Your task is not done. Call stack_wait again with this cursor.";
+export const STACK_WATCH_NOTIFY_PATTERN = "MS-WATCH (ATTENTION|LANDED)";
+export function stackWatchBackgroundCommand(stackId) {
+    return `mg stack watch ${stackId}`;
+}
 const DONE_MESSAGES = {
     landed: "This stack is landed. The watch is done; stop calling stack_wait for it.",
     closed: "Every PR in this stack is merged or closed and nothing is left to land, but not every PR landed. The watch is done; tell the human which PRs were closed without landing.",
@@ -49,8 +53,10 @@ export function stackWatchObligation(input) {
         : input.status === "failed"
             ? "failed"
             : input.attention ? "attention" : input.unread ? "unread" : "open";
+    const background = stackWatchBackgroundCommand(input.stackId);
     const parts = [
         STACK_WATCH_NOT_DONE_SENTENCE,
+        `If you cannot hold a long turn open, run \`${background}\` as a background command instead, notify on output matching ${STACK_WATCH_NOTIFY_PATTERN}, and end your turn: it keeps calling stack_wait for you, stays silent while the stack waits, and wakes you on attention or when the watch is done.`,
         `Watch stack ${input.stackId} as a whole until it lands or the human takes it back. A clean push, a submit, or one merged layer does not finish it: merging a lower layer can break a layer above it.`,
     ];
     if (reason === "rate_limited") {
@@ -60,7 +66,7 @@ export function stackWatchObligation(input) {
         parts.push(`This read failed, which does not end the task. Call stack_wait once more with the same cursor; if that fails too, tell the human that stack ${input.stackId} is not landed and is no longer being watched.`);
     }
     else if (reason === "attention" && input.attention) {
-        parts.push(`First fix #${input.attention.prNumber} (${input.attention.blocker}); repair, when present, names the fix. Calling stack_wait again before fixing it returns the same attention. After your push, call stack_wait with this cursor and enrolled_head_sha set to the SHA you pushed.`);
+        parts.push(`First fix #${input.attention.prNumber} (${input.attention.blocker}); repair, when present, names the fix. Calling stack_wait again before fixing it returns the same attention. After your push, call stack_wait with this cursor and enrolled_head_sha set to the SHA you pushed, or start \`${background} --head <pushed-sha>\` in the background.`);
     }
     else if (reason === "unread") {
         parts.push("This tool did not read the stack's state; stack_wait will.");
@@ -73,7 +79,7 @@ export function stackWatchObligation(input) {
         done: false,
         until: "landed",
         reason,
-        next: { tool: "stack_wait", args, command: `mg stack wait ${input.stackId} --json` },
+        next: { tool: "stack_wait", args, command: `mg stack wait ${input.stackId} --json`, background },
         message: parts.join(" "),
     };
 }

package/dist/ui/banner.js

@@ -123,6 +123,9 @@ const WHATS_NEW = {
     "0.3.30": [
         "stack watch --json prints one JSON document",
     ],
+    "0.3.31": [
+        "every stack Next line offers mg stack watch",
+    ],
 };
 function densityFromVariant(variant) {
     if (variant === "mini" || variant === "nano")

package/dist/ui/usage.d.ts

@@ -24,6 +24,12 @@ export declare function formatResetLabel(iso: string | null | undefined, now?: D
 export declare function formatDaysLeft(iso: string | null | undefined, now?: Date): string;
 /** Bar cells so `  [bar] 100% used` stays inside the terminal. */
 export declare function usageBarWidth(columns: number): number;
+export type SurgeUsageSummary = {
+    includedMinutes: number;
+    usedMinutes: number;
+    walletMinutes: number;
+};
+export declare function formatSurgeSummary(surge: SurgeUsageSummary): string;
 export type UsagePanelJob = {
     job: string;
     verdict: string;
@@ -37,6 +43,7 @@ export type UsagePanelInput = {
     used: number;
     limit: number | null;
     bonusRemaining?: number;
+    surge?: SurgeUsageSummary;
     resetsAt: string | null | undefined;
     jobs: UsagePanelJob[];
     /** When the jobs fetch failed, show this instead of "No review jobs yet." */

package/dist/ui/usage.js

@@ -87,6 +87,16 @@ export function formatDaysLeft(iso, now = new Date()) {
 export function usageBarWidth(columns) {
     return Math.max(8, frameWidth(80, columns) - 13);
 }
+function formatMinutes(value) {
+    return value.toLocaleString("en-US", { maximumFractionDigits: 1 });
+}
+export function formatSurgeSummary(surge) {
+    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` +
+        ` · ${wallet}`);
+}
 function clipLine(line, columns) {
     if (visibleWidth(line) <= columns)
         return line;
@@ -111,6 +121,7 @@ export function formatUsagePanel(input) {
         ...(input.bonusRemaining == null
             ? []
             : [`  Bonus credits: ${input.bonusRemaining} remaining`]),
+        ...(input.surge ? [`  ${formatSurgeSummary(input.surge)}`] : []),
         "",
     ];
     if (input.jobs.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mergestorm",
-  "version": "0.3.30",
+  "version": "0.3.31",
   "description": "Mergestorm CLI (mg) — local reviews & stacked PRs. MIT; build from source: https://github.com/marginsystems/mergestorm-cli",
   "license": "MIT",
   "type": "module",

package/skill/mergestorm-bounce-watch/SKILL.md

@@ -15,7 +15,7 @@ A stack watch is done only when the stack is landed, or when the human takes it
 
 If your host cannot hold a long turn open (Cursor, Claude Code, Codex, and other turn-based agents), do not poll `stack_wait` inside your turn and do not subscribe to GitHub events. Hand the waiting to the CLI watcher:
 
-1. Run `mg stack watch <stack-id>` as a background command (add `--head <sha>` right after you pushed that SHA) with a notification on output matching `MS-WATCH (ATTENTION|LANDED)`, then end your turn. The watcher runs the same stack wait against the Mergestorm API in slices of at most 300s, carries the cursor (`enrolled_head_sha`, `after_finished_at`, `bounce_id`) from one slice to the next, and prints nothing while the stack is `waiting` or `in_progress`, including `busy[]` holds and `actAfter: "agents_idle"`. It spends no model tokens while it waits. Ending your turn while it runs is not ending the task.
+1. Run `mg stack watch <stack-id>` as a background command (add `--head <sha>` right after you pushed that SHA) with a notification on output matching `MS-WATCH (ATTENTION|LANDED)`, then end your turn. The watcher runs the same stack wait against the Mergestorm API in slices of at most 300s, carries the cursor (`enrolled_head_sha`, `after_finished_at`, `bounce_id`) from one slice to the next, and prints nothing while the stack is `waiting` or `in_progress`, including `busy[]` holds and `actAfter: "agents_idle"`. It spends no model tokens while it waits. Ending your turn while it runs is not ending the task. Every `watch.next` carries this command as `watch.next.background`.
 2. It prints one line and exits for one of three reasons:
    - `MS-WATCH ATTENTION pr=<n> head=<sha> blocker="<blocker>" repair=<kind>` (exit 3): the watch returned `attention`.
    - `MS-WATCH ATTENTION failed stack=<id> error="<message>"` (exit 3): a read failed and its one retry failed too.