mergestorm 0.3.64 → 0.3.67

package/dist/ui/banner.d.ts

@@ -7,11 +7,12 @@ export type BannerState = {
     me: MeResponse | null;
     key: string | undefined;
     keyInvalid: boolean;
+    account?: string | null;
 };
 /** Full welcome, mid pane, or Claude-style short chrome that still shows the mark. */
 export type BannerDensity = "full" | "compact" | "mini" | "nano";
 /** `true` = compact. Strings pick the short-pane densities. */
-export type BannerVariant = boolean | "mini" | "nano";
+type BannerVariant = boolean | "mini" | "nano";
 /** Handle returned by {@link printBannerHeader}; `rows` reflows for a resize. */
 export type BannerHandle = {
     rows(columns?: number, variant?: BannerVariant, frame?: number): string[];
@@ -35,3 +36,4 @@ export declare function printBannerHeader(opts?: {
     paint?: boolean;
 }): Promise<BannerHandle>;
 export declare function shellPrompt(_loggedIn: boolean): string;
+export {};

package/dist/ui/banner.js

@@ -1,6 +1,6 @@
 import { getMe } from "../api.js";
 import { CommandError } from "../errors.js";
-import { keyDisplay, loadConfig, resolveApiKey } from "../config.js";
+import { keyDisplay, loadConfig, resolveApiKey, settleAccountName } from "../config.js";
 import { cliVersion } from "../version.js";
 import { ansi } from "./ansi.js";
 import { frameWidth, padVisible, preferBoxedUi, roundedBox, sideBySide, terminalColumns, visibleWidth, } from "./box.js";
@@ -230,6 +230,15 @@ const WHATS_NEW = {
     "0.3.64": [
         "Memory commands and Overdrive merge batches",
     ],
+    "0.3.65": [
+        "Up to 3 accounts: `account use`, `--account <name>`",
+    ],
+    "0.3.66": [
+        "`issue wait`; submit needs an approved issue",
+    ],
+    "0.3.67": [
+        "Issue review: reply once, then one re-check",
+    ],
 };
 function densityFromVariant(variant) {
     if (variant === "mini" || variant === "nano")
@@ -247,7 +256,7 @@ function statusLine(state) {
     if (state.keyInvalid) {
         return `${ansi.dim("○")} API key invalid or revoked · type ${ansi.brightGreen("login")} to sign in again`;
     }
-    const display = state.me?.key.prefix ?? keyDisplay(state.key) ?? "msk_live_…";
+    const display = state.account ?? state.me?.key.prefix ?? keyDisplay(state.key) ?? "msk_live_…";
     if (!state.me) {
         return `${ansi.brightGreen("●")} ${ansi.bold(display)} ${ansi.dim("· account details unavailable")}`;
     }
@@ -373,7 +382,8 @@ export async function printBannerHeader(opts) {
             }
         }
     }
-    const state = { version: cliVersion(), me, key, keyInvalid };
+    const account = me ? await settleAccountName(cfg, me) : cfg.account;
+    const state = { version: cliVersion(), me, key, keyInvalid, account: account ?? null };
     if (opts?.paint !== false) {
         for (const line of buildBannerRows(state)) {
             console.log(line);

package/dist/ui/box.d.ts

@@ -1,7 +1,5 @@
 import { padVisible, sliceVisible, visibleWidth } from "./width.js";
 export { padVisible, sliceVisible, visibleWidth };
-/** Below this width, boxed chrome wraps on real TTYs — prefer plain output. */
-export declare const MIN_BOXED_COLUMNS = 48;
 /**
  * Usable terminal columns (TTY), with a sensible fallback for pipes/tests.
  * Pass `columns` to measure a stream other than process.stdout (or a

package/dist/ui/box.js

@@ -5,7 +5,7 @@ import { padVisible, sliceVisible, visibleWidth } from "./width.js";
 // importers (banner, prompt) keep working.
 export { padVisible, sliceVisible, visibleWidth };
 /** Below this width, boxed chrome wraps on real TTYs — prefer plain output. */
-export const MIN_BOXED_COLUMNS = 48;
+const MIN_BOXED_COLUMNS = 48;
 /**
  * Usable terminal columns (TTY), with a sensible fallback for pipes/tests.
  * Pass `columns` to measure a stream other than process.stdout (or a

package/dist/ui/prompt.d.ts

@@ -41,10 +41,7 @@ export declare function promptRedrawPrefix(inputRow: number): string;
  * frame's row count is unknowable after the terminal rewraps.
  */
 export declare const HEADER_REDRAW_PREFIX = "\u001B[H\u001B[0J";
-export declare const DROPDOWN_MAX_COMMAND_ROWS = 8;
 export declare function formatSlashLabel(spec: CommandSpec): string;
-export declare function specMatchesTerm(spec: CommandSpec, term: string): boolean;
-export declare function slashToken(buffer: string): string | null;
 export declare function matchSlashCommands(buffer: string, specs: CommandSpec[], dismissed?: boolean): CommandSpec[];
 export declare function isExactSlashCommand(buffer: string, specs: CommandSpec[]): boolean;
 export declare function dropdownViewport(count: number, index: number, maxRows: number): {
@@ -64,8 +61,6 @@ export declare function promptChromeRows(boxed: boolean, hasPrompt: boolean, has
  * passes 0 — do not pad a blank gap between header and prompt.
  */
 export declare function overlayReserve(terminalRows: number | undefined, headerRows: number, boxed: boolean, hasPrompt: boolean): number;
-/** Pad so the slash list sits just above the input bar (Claude-style). */
-export declare function padOverlayRows(rows: OverlayRow[], reserve: number): OverlayRow[];
 export interface HomeFrameFit {
     header: string[];
     reserve: number;
@@ -91,12 +86,6 @@ export declare function fitHomeFrame(params: {
     dockBottom?: boolean;
 }): HomeFrameFit;
 export declare function dropdownOverlayRows(dropdown: CommandSpec[], index: number, maxRows: number): OverlayRow[];
-/** Input prefix glyph (U+203A), kept as an escape so editors can't mangle it. */
-export declare const INPUT_PREFIX_GLYPH = "\u203A";
-/** Cells the `> ` prefix occupies before the buffer. */
-export declare const INPUT_PREFIX_CELLS = 2;
-/** Padding inside the boxed input frame. */
-export declare const INPUT_BOX_PADDING = 1;
 export interface InputWindow {
     /** First buffer cell shown. */
     start: number;

package/dist/ui/prompt.js

@@ -31,19 +31,19 @@ export function promptRedrawPrefix(inputRow) {
  * frame's row count is unknowable after the terminal rewraps.
  */
 export const HEADER_REDRAW_PREFIX = `\u001b[H${clearDown}`;
-export const DROPDOWN_MAX_COMMAND_ROWS = 8;
+const DROPDOWN_MAX_COMMAND_ROWS = 8;
 export function formatSlashLabel(spec) {
     const extra = spec.aliases?.length
         ? ` \u00b7 ${spec.aliases.join(" \u00b7 ")}`
         : "";
     return `/${spec.name}${extra}`;
 }
-export function specMatchesTerm(spec, term) {
+function specMatchesTerm(spec, term) {
     if (spec.name.toLowerCase().startsWith(term))
         return true;
     return (spec.aliases ?? []).some((alias) => alias.toLowerCase().startsWith(term));
 }
-export function slashToken(buffer) {
+function slashToken(buffer) {
     if (!buffer.startsWith("/"))
         return null;
     return buffer.slice(1).split(/\s/, 1)[0].toLowerCase();
@@ -97,7 +97,7 @@ export function overlayReserve(terminalRows, headerRows, boxed, hasPrompt) {
     return Math.max(0, Math.min(DROPDOWN_MAX_COMMAND_ROWS, available));
 }
 /** Pad so the slash list sits just above the input bar (Claude-style). */
-export function padOverlayRows(rows, reserve) {
+function padOverlayRows(rows, reserve) {
     const max = Math.max(0, reserve);
     if (max === 0)
         return [];
@@ -194,11 +194,11 @@ export function dropdownOverlayRows(dropdown, index, maxRows) {
     return rows.slice(0, max);
 }
 /** Input prefix glyph (U+203A), kept as an escape so editors can't mangle it. */
-export const INPUT_PREFIX_GLYPH = "\u203a";
+const INPUT_PREFIX_GLYPH = "\u203a";
 /** Cells the `> ` prefix occupies before the buffer. */
-export const INPUT_PREFIX_CELLS = 2;
+const INPUT_PREFIX_CELLS = 2;
 /** Padding inside the boxed input frame. */
-export const INPUT_BOX_PADDING = 1;
+const INPUT_BOX_PADDING = 1;
 /**
  * Horizontal scroll for a one-row editor: pick the `cells`-wide window of
  * `buffer` that keeps the cursor on screen, moving the previous window only

package/dist/ui/tabs.d.ts

@@ -1,6 +1,5 @@
 import { type UsagePanelInput } from "./usage.js";
 export type TabId = "status" | "usage" | "jobs" | "config";
-export declare const TAB_ORDER: readonly TabId[];
 export type TabsJob = {
     id: string;
     cells: {
@@ -44,7 +43,7 @@ export type TabsData = {
     configNote?: string;
     color?: boolean;
 };
-export type TabsDetail = {
+type TabsDetail = {
     jobId: string;
     rows: string[];
 };
@@ -128,3 +127,4 @@ export type TabsBrowserOptions = {
  * TTY already).
  */
 export declare function runTabsBrowser(opts: TabsBrowserOptions): Promise<void>;
+export {};

package/dist/ui/tabs.js

@@ -5,7 +5,7 @@ import { frameWidth, preferBoxedUi, roundedBox, terminalColumns, } from "./box.j
 import { padVisible, visibleWidth } from "./width.js";
 import { formatUsagePanel } from "./usage.js";
 import { dropdownViewport } from "./prompt.js";
-export const TAB_ORDER = ["status", "usage", "jobs", "config"];
+const TAB_ORDER = ["status", "usage", "jobs", "config"];
 const TAB_LABELS = {
     status: "Status",
     usage: "Usage",

package/dist/ui/width.d.ts

@@ -4,15 +4,6 @@
  * and ZWJ are zero, an astral emoji is one grapheme. Getting this wrong is
  * why the right border of the prompt box drifted on non-Latin input.
  */
-export declare function stripSgr(str: string): string;
-/** Cells for one code point on its own (no cluster context). */
-export declare function codePointWidth(cp: number): number;
-/**
- * Cells one grapheme cluster occupies. A cluster is as wide as its widest
- * base (a ZWJ family emoji is 2, not 6); VS16 promotes a text-style symbol
- * to emoji presentation (2 cells); a cluster of nothing but marks is 0.
- */
-export declare function graphemeWidth(cluster: string): number;
 /** Terminal cells a string occupies, ignoring SGR colour codes. */
 export declare function visibleWidth(str: string): number;
 /**

package/dist/ui/width.js

@@ -6,7 +6,7 @@
  */
 const SGR_PATTERN = /\u001b\[[0-9;]*m/g;
 const SGR_SPLIT = /(\u001b\[[0-9;]*m)/;
-export function stripSgr(str) {
+function stripSgr(str) {
     return str.replace(SGR_PATTERN, "");
 }
 /**
@@ -128,7 +128,7 @@ function isWide(cp) {
     return false;
 }
 /** Cells for one code point on its own (no cluster context). */
-export function codePointWidth(cp) {
+function codePointWidth(cp) {
     if (cp === 0xfe0f)
         return 0; // VS16 handled at cluster level
     const ch = String.fromCodePoint(cp);
@@ -172,7 +172,7 @@ function* graphemes(text) {
  * base (a ZWJ family emoji is 2, not 6); VS16 promotes a text-style symbol
  * to emoji presentation (2 cells); a cluster of nothing but marks is 0.
  */
-export function graphemeWidth(cluster) {
+function graphemeWidth(cluster) {
     let width = 0;
     let vs16 = false;
     for (const ch of cluster) {

package/dist/web-api.d.ts

@@ -0,0 +1,17 @@
+import { type Config } from "./config.js";
+export declare const WEB_SEARCH_KINDS: readonly ["web", "news"];
+export declare const WEB_SEARCH_RECENCIES: readonly ["day", "week", "month", "year"];
+export declare const WEB_SEARCH_PAGE_MAX = 5;
+export type WebSearchKind = (typeof WEB_SEARCH_KINDS)[number];
+export type WebSearchRecency = (typeof WEB_SEARCH_RECENCIES)[number];
+export type WebSearchInput = {
+    query: string;
+    kind?: WebSearchKind;
+    recency?: WebSearchRecency;
+    page?: number;
+};
+export type WebText = {
+    text: string;
+};
+export declare function searchWeb(input: WebSearchInput, cfg?: Config): Promise<WebText>;
+export declare function readWebPage(url: string, cfg?: Config): Promise<WebText>;

package/dist/web-api.js

@@ -0,0 +1,30 @@
+import { apiFetch } from "./api.js";
+import { loadConfig } from "./config.js";
+import { CommandError, REVIEW_EXIT, rateLimitedMessage } from "./errors.js";
+export const WEB_SEARCH_KINDS = ["web", "news"];
+export const WEB_SEARCH_RECENCIES = ["day", "week", "month", "year"];
+export const WEB_SEARCH_PAGE_MAX = 5;
+const KNOWN_CODES = new Set(["invalid_input", "payload_too_large", "web_unavailable"]);
+function webFailure(status, body, retryAfterSeconds, action) {
+    const row = (body && typeof body === "object" ? body : {});
+    if (status === 429 || row.error === "rate_limited") {
+        return new CommandError(rateLimitedMessage(retryAfterSeconds), REVIEW_EXIT.rate_limited, "rate_limited", retryAfterSeconds !== undefined ? { retryAfterSeconds } : undefined);
+    }
+    const message = typeof row.message === "string" && row.message ? row.message : null;
+    const code = typeof row.error === "string" && KNOWN_CODES.has(row.error) ? row.error : undefined;
+    if (status === 404 && !code)
+        return new CommandError("This Mergestorm server does not search the web yet.", 1, "not_found");
+    return new CommandError(message ?? `${action} (HTTP ${status})`, 1, code);
+}
+async function call(cfg, route, json, action) {
+    const { status, body, retryAfterSeconds } = await apiFetch(cfg ?? (await loadConfig()), route, { method: "POST", json });
+    if (status !== 200)
+        throw webFailure(status, body, retryAfterSeconds, action);
+    return body;
+}
+export function searchWeb(input, cfg) {
+    return call(cfg, "/api/v1/web/search", { ...input }, "Could not search the web");
+}
+export function readWebPage(url, cfg) {
+    return call(cfg, "/api/v1/web/page", { url }, "Could not read the page");
+}

package/package.json

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

package/skill/SKILL.md

@@ -13,6 +13,10 @@ Before opening a PR; after a large refactor; when the user says review, audit, s
 
 Not for merging, landing, or pushing. For a PR that is already open on GitHub, use the `mergestorm-pr-loop` skill instead.
 
+## Before the PR: the issue review
+
+Vortex reviews the issue against the repository before any code. Wait for its verdict with `mg issue wait N`, which reads the verdict from Vortex itself; never judge it from comment text. Ready or Ready with notes approves the issue; notes do not block, and the PR review checks them against the code. If the verdict is Needs answers, reply once in a comment on the issue: for each blocking point, accept the suggested fix or say why not, and update the issue to match. Vortex then re-checks only those points, once, and approves the issue; a point still open goes to the PR review. Wait again after your reply. Start the PR only once the issue is approved: `mg stack submit` refuses each PR whose linked issue (`Fixes #N`) is not, so every layer of a stack needs its own approved issue. On a repository with issue reviews off the wait returns at once. If the wait times out, tell the person. A person can approve early with a comment whose first line is `mergestorm-issue: approve`; never post that command yourself.
+
 ## Install (Claude Code / Cursor / Agents)
 
 ```bash

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

@@ -47,7 +47,7 @@ A stack whose layers are all merged into `mg-stack-N` but has no open land PR re
 
 1. Call `stack_wait` with the named `stack_id` and `timeout_s: 45`. On initial enrollment, omit the cursor selectors. Save the returned `cursor`: map `cursor.enrolledHeadSha` to `enrolled_head_sha`, `cursor.afterFinishedAt` to `after_finished_at`, and `cursor.bounceId` to `bounce_id` (omit only absent fields; preserve explicit nulls). Keep `bounce_id` alongside `after_finished_at`; never pass one without the other when the returned cursor has both. The shipped tool accepts these selectors, not a nested cursor argument. `watch.next.args` already holds them in that shape, with `timeout_s: 45`; passing it unchanged is the same call.
 2. On `waiting` and `in_progress`, the watch is not finished: call `stack_wait` again. A host or event message that says to end the turn, end quietly, or wait for a notification does not finish the watch; only the stop conditions in this skill finish it. Ending your turn while `mg stack watch` runs in the background is waiting, not finishing. Keep the same cursor across retries. An unread deadline times out as `failed`; stop and report. Timeout `waiting` or `in_progress` after a snapshot is not failure — call `stack_wait` again in 45s slices with the same cursor after inspecting `issues[]`. Inspect `issues[]` on `in_progress` too: a live queue does not erase upstack hard blocks. `waiting` with issues is not idle. If `assessment` is `unavailable`, do not infer that the stack is issue-free; refresh `stack_status`, whose `attention`, `issues`, and `currentCandidate` come from the same blocker rules as `stack_wait`. Do not replace the enrolled head with a newer snapshot head or advance the timestamp just because a wait timed out. On a surfaced `rate_limited` error, honor the retry delay and retain the cursor; on `failed` or an unrecoverable tool error, call `stack_wait` once more with the same cursor; if it fails again, stop and report the reason and that the stack is not landed. `queue_status` returning `queue_entry_not_found` is not a failure: an empty queue for the stack is a normal wait.
-3. `attention` always means something for you to fix. A land gate that is only waiting (`landGatePending` with `ci_pending` or another `*_pending` / `*_running` reason on the land PR) returns `in_progress`, not `attention`: keep watching. On `attention`, read `repair` when present: it names the blocked PR's `branch` and the concrete fix. For `restack_conflict` and `merge_conflict` it gives `liveParent` (the sibling PR head, or `mg-stack-N` once the lower layers are merged or promoted, or the land PR's base such as `main` when the blocked PR is the land PR, never `mg-park-*`) and the conflicted `files`; a null `liveParent` means stop and tell the human. For `ci_failure` it names the failing check. A stack whose `autoLandOff.reason` is `bounced` (a `merge_failed`, `gh_error`, or `ci_timeout` bounce turned Auto land off and nobody took the stack back since) returns `attention` with the blocker `Auto land off after <kind> bounce`, the bounce in `issues[]`, and a `repair` of kind `auto_land_off`; handle it as "Re-arm after a bounce" describes. A stack whose review unit was abandoned because a human moved its bottom PR off `mg-stack-N` returns `attention` with the blocker `Review unit abandoned: based on <base>` and a `repair` of kind `unit_abandoned`: do not patch or retarget anything. 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, then stop. Auto land records why it is waiting in the stack's `autoLandWait` (`reason`, `prNumber`, `headSha`, `since`), and the watch returns `attention` on that PR when the wait cannot clear on its own: a failing check Auto land reads live on GitHub while the ledger may still show CI green (blocker `CI failed — Auto land reads a failing check on GitHub at this head`, `repair` kind `ci_failure`); a check pending for 45 minutes (`repair` kind `ci_pending`: find the check that never finished and re-run it, or tell the human when no workflow reports it); no approving Vortex review for 30 minutes with no Vortex run working (`repair` kind `vortex_not_green`: fix or dismiss the findings, or tell the human when no review exists at the head); and a promote GitHub refused 3 times with `merge_failed`, after which Auto land stops retrying that head (`repair` kind `promote_failed`: fix the cause on the PR and push a new head, or tell the human when the cause is outside the PR; never toggle Auto land yourself for it). The watch also returns `attention` when GitHub refuses to let Mergestorm read the head's check runs or commit statuses (blocker `Mergestorm cannot read ... on this head`, `repair` kind `ci_unreadable`: do not patch or push; tell the human to grant the Mergestorm GitHub App the permission the repair names), and when any other wait reason has held for 45 minutes, a land gate left pending or running on the land PR included (blocker `Auto land has waited <N>m: <reason in plain words>`, `repair` kind `auto_land_waiting`: read `stack_status`, fix what a commit on the named branch can fix, otherwise tell the human what Auto land waits for and since when). A merge queue entry that has sat queued for 45 minutes with nothing working on it or ahead of it returns `attention` with the blocker `Merge queue stuck: ...` and a `repair` whose kind is queue_stalled: do not patch or push; tell the human. A Vortex review skipped because the PR author is on the ignored authors list, or because reviews are turned off for the repository, returns `attention` at once with a `repair` of kind `vortex_skipped`; a Vortex retry that is scheduled (`Vortex hit a temporary error on this head and will retry by itself`) is a wait listed in `issues[]`, never `attention`. `Review failed` carries a `repair` of kind `vortex_failed`: comment `@mergestorm-vortex review` on the PR or push a new commit, and tell the human if it fails again. A PR open on `mg-stack-N` that is not a layer of the stack returns `attention` at once with the blocker `The land PR cannot be queued: ...` and a `repair` of kind `members_remaining`: do not patch or push; close, retarget or adopt that PR (a draft or fork PR cannot be adopted). A layer whose live head has a Vortex verdict that requests changes after Cyclone left those findings for a person (a hold directive, the Vortex patch cap, auto-patch off, no billing, a batch it gave up on, or a PR state it could not read) returns `attention` with the blocker `Vortex findings need a person` and a `repair` of kind `vortex_findings` naming the Cyclone reason (`handoff`) and where the review is (`findings`): verify each finding against the checkout, fix the real ones with the smallest patch and an ordinary push, and tell the human about the ones you judge wrong. `repair` does not replace the checks below. On `attention`, fix the named PR: `prNumber` and `headSha` identify the blocked PR, while `currentCandidate` identifies the promote candidate. The gate covers the bottom and its direct child only when the child has current-head DIRTY on the live bottom branch. A GitHub DIRTY whose `parentBranch` starts with `mg-park-` is not that gate. Refresh `stack_status`; use `queue_status` with the same `stack_id` when bounce details are needed. Verify the blocker still applies to the current PR head. Never treat `verifyHeadSha` as the current head: it is a queue verification SHA and can be stale or synthetic. Compare the live PR branch head, the current stack layer head, and the checkout before editing. Read the live PR head with `git ls-remote origin refs/heads/<branch>` or `gh api repos/OWNER/REPO/pulls/N --jq .head.sha`. If you need CI logs, use `gh run list --branch <branch>`, `gh run view <run-id> --log-failed`, or `gh api repos/OWNER/REPO/commits/SHA/check-runs`. Read GitHub only through git and these REST calls; do not use other `gh pr` subcommands. Restack `clean` does not mean mergeable or CI-green. Attention is a diagnosis, not permission to mutate stack or queue policy; the only policy change you make is the re-arm in "Re-arm after a bounce". A bounce is the reason to look, not the moment to commit. `stack_wait` and `stack_status` hold the blocked PR's attention themselves while Vortex or Cyclone is still working on that PR, whatever the blocker (a red CI failure, a merge conflict, a bounce, Draft, a failed restack or review): they return `in_progress` instead of `attention`, with `busy[]` naming the PR (`prNumber`, `headSha`), the `blocker`, and the `agent` (`vortex` or `cyclone`), and `agents` carrying that PR's `vortexStatus`, `cycloneStatus`, `vortexReview`, and `busy` flags. `in_progress` with a nonempty `busy[]` means do not patch yet: keep calling `stack_wait` with the same cursor until that work has finished and the watch returns `attention`, then make the follow-up commit. You do not need an extra `stack_status` refresh each slice for this check. A nonempty `busy[]` reports still-working agents on that PR's current head. Vortex holds when `vortexReview` is `reviewing` at the head, an unfinished vortex `agentRuns` row at the head is `reviewing`, or an unfinished vortex run at the head is `queued` and started within the last 15 minutes (with no `agentRuns` or `vortexReview` on the layer, `vortexStatus` `reviewing` holds). Cyclone holds when `cycloneStatus` is `patching`, an unfinished cyclone `agentRuns` row is `patching`, or the server sees a live Cyclone patch lease or an open Cyclone check run on the head. `seam_pending` alone, and a `queued` run older than 15 minutes, are not treated as work in progress. `all_clear`, `findings`, `skipped`, `failed`, `throttled`, `awaiting_fix`, and a null status are finished. 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 blocker no Vortex or Cyclone run can clear is not hidden by the hold: a merge conflict vs the live parent, a restack `Conflict` or `Restack failed` (a parked freeze included), a Draft PR, `Seam review pending, no review running`, or `Review skipped, out of review quota`. For those the envelope stays `in_progress` but names the blocker in the top-level `blocker`, `prNumber`, `headSha`, and `issues[]`, with `actAfter: "agents_idle"`, `waitingOn` listing the busy agents, and `repair` when there is one. Plan the fix from it, but do not patch, merge, or push while `actAfter` is set: keep calling `stack_wait` with the same cursor, and act when a snapshot after the agents finish returns `attention`; a Cyclone push can change or clear the blocker, so re-read it then. Blockers the agents can change (a red CI failure, a failed review, seam findings, a bounce) keep the plain hold: `blocker` is null, `actAfter` is null, and only `busy[]` names them. If a hold looks stuck, refresh `stack_status` and tell the human. Do not turn Cyclone off or Auto land off, and do not turn Auto land on to end the wait; turn it on only as "Re-arm after a bounce" allows. If the remote head moves while you wait, stop and tell the human.
+3. `attention` always means something for you to fix. A land gate that is only waiting (`landGatePending` with `ci_pending` or another `*_pending` / `*_running` reason on the land PR) returns `in_progress`, not `attention`: keep watching. On `attention`, read `repair` when present: it names the blocked PR's `branch` and the concrete fix. For `restack_conflict` and `merge_conflict` it gives `liveParent` (the sibling PR head, or `mg-stack-N` once the lower layers are merged or promoted, or the land PR's base such as `main` when the blocked PR is the land PR, never `mg-park-*`) and the conflicted `files`; a null `liveParent` means stop and tell the human. For `ci_failure` it names the failing check. A stack whose `autoLandOff.reason` is `bounced` (a `merge_failed`, `gh_error`, or `ci_timeout` bounce turned Auto land off and nobody took the stack back since) returns `attention` with the blocker `Auto land off after <kind> bounce`, the bounce in `issues[]`, and a `repair` of kind `auto_land_off`; handle it as "Re-arm after a bounce" describes. A stack whose review unit was abandoned because a human moved its bottom PR off `mg-stack-N` returns `attention` with the blocker `Review unit abandoned: based on <base>` and a `repair` of kind `unit_abandoned`: do not patch or retarget anything. 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, then stop. Auto land records why it is waiting in the stack's `autoLandWait` (`reason`, `prNumber`, `headSha`, `since`), and the watch returns `attention` on that PR when the wait cannot clear on its own: a failing check Auto land reads live on GitHub while the ledger may still show CI green (blocker `CI failed — Auto land reads a failing check on GitHub at this head`, `repair` kind `ci_failure`); a check pending for 45 minutes (`repair` kind `ci_pending`: find the check that never finished and re-run it, or tell the human when no workflow reports it); no approving Vortex review for 30 minutes with no Vortex run working (`repair` kind `vortex_not_green`: fix or dismiss the findings, or tell the human when no review exists at the head); and a promote GitHub refused 3 times with `merge_failed`, after which Auto land stops retrying that head (`repair` kind `promote_failed`: fix the cause on the PR and push a new head, or tell the human when the cause is outside the PR; never toggle Auto land yourself for it). The watch also returns `attention` when GitHub refuses to let Mergestorm read the head's check runs or commit statuses (blocker `Mergestorm cannot read ... on this head`, `repair` kind `ci_unreadable`: do not patch or push; tell the human to grant the Mergestorm GitHub App the permission the repair names), and when any other wait reason has held for 45 minutes, a land gate left pending or running on the land PR included (blocker `Auto land has waited <N>m: <reason in plain words>`, `repair` kind `auto_land_waiting`: read `stack_status`, fix what a commit on the named branch can fix, otherwise tell the human what Auto land waits for and since when). A merge queue entry that has sat queued for 45 minutes with nothing working on it or ahead of it returns `attention` with the blocker `Merge queue stuck: ...` and a `repair` whose kind is queue_stalled: do not patch or push; tell the human. A Vortex review skipped because the PR author is on the ignored authors list, or because reviews are turned off for the repository, returns `attention` at once with a `repair` of kind `vortex_skipped`; a Vortex retry that is scheduled (`Vortex hit a temporary error on this head and will retry by itself`) is a wait listed in `issues[]`, never `attention`. `Review failed` carries a `repair` of kind `vortex_failed`: comment `@mergestorm-vortex review` on the PR or push a new commit, and tell the human if it fails again. A PR open on `mg-stack-N` that is not a layer of the stack returns `attention` at once with the blocker `The land PR cannot be queued: ...` and a `repair` of kind `members_remaining`: do not patch or push; close, retarget or adopt that PR (a draft or fork PR cannot be adopted). A layer whose live head has a Vortex verdict that requests changes after Cyclone left those findings for a person (a hold directive, the Vortex patch cap, auto-patch off, no billing, a batch it gave up on, or a PR state it could not read) returns `attention` with the blocker `Vortex findings need a person` and a `repair` of kind `vortex_findings` naming the Cyclone reason (`handoff`) and where the review is (`findings`): verify each finding against the checkout, fix the real ones with the smallest patch and an ordinary push, and tell the human about the ones you judge wrong. `repair` does not replace the checks below. On `attention`, fix the named PR: `prNumber` and `headSha` identify the blocked PR, while `currentCandidate` identifies the promote candidate. The gate covers the bottom and its direct child only when the child has current-head DIRTY on the live bottom branch. A GitHub DIRTY whose `parentBranch` starts with `mg-park-` is not that gate. Refresh `stack_status`; use `queue_status` with the same `stack_id` when bounce details are needed. Verify the blocker still applies to the current PR head. Never treat `verifyHeadSha` as the current head: it is a queue verification SHA and can be stale or synthetic. Compare the live PR branch head, the current stack layer head, and the checkout before editing. Read the live PR head with `git ls-remote origin refs/heads/<branch>` or `gh api repos/OWNER/REPO/pulls/N --jq .head.sha`. If you need CI logs, use `gh run list --branch <branch>`, `gh run view <run-id> --log-failed`, or `gh api repos/OWNER/REPO/commits/SHA/check-runs`. Read GitHub only through git and these REST calls; do not use other `gh pr` subcommands. Restack `clean` does not mean mergeable or CI-green. Attention is a diagnosis, not permission to mutate stack or queue policy; the only policy change you make is the re-arm in "Re-arm after a bounce". A bounce is the reason to look, not the moment to commit. `stack_wait` and `stack_status` hold the blocked PR's attention themselves while Vortex or Cyclone is still working on that PR, whatever the blocker (a red CI failure, a merge conflict, a bounce, Draft, a failed restack or review): they return `in_progress` instead of `attention`, with `busy[]` naming the PR (`prNumber`, `headSha`), the `blocker`, and the `agent` (`vortex` or `cyclone`), and `agents` carrying that PR's `vortexStatus`, `cycloneStatus`, `vortexReview`, and `busy` flags. `in_progress` with a nonempty `busy[]` means do not patch yet: keep calling `stack_wait` with the same cursor until that work has finished and the watch returns `attention`, then make the follow-up commit. You do not need an extra `stack_status` refresh each slice for this check. A nonempty `busy[]` reports still-working agents on that PR's current head. Vortex holds when `vortexReview` is `reviewing` at the head, an unfinished vortex `agentRuns` row at the head is `reviewing`, or an unfinished vortex run at the head is `queued` and started within the last 15 minutes (with no `agentRuns` or `vortexReview` on the layer, `vortexStatus` `reviewing` holds). Cyclone holds when `cycloneStatus` is `patching`, an unfinished cyclone `agentRuns` row is `patching`, or the server sees a live Cyclone patch lease or an open Cyclone check run on the head. `seam_pending` alone, and a `queued` run older than 15 minutes, are not treated as work in progress. `all_clear`, `findings`, `skipped`, `failed`, `throttled`, `awaiting_fix`, and a null status are finished. 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 Cyclone run still patching after 60 minutes no longer holds: the watch returns `attention` with the blocker `Cyclone stalled: patching <sha> for <N>m with no push or result` and a `repair` of kind `cyclone_stalled`; patch the open Vortex findings yourself with the smallest fix and an ordinary push, and re-read `stack_status` instead of pushing if the branch moves first. A blocker no Vortex or Cyclone run can clear is not hidden by the hold: a merge conflict vs the live parent, a restack `Conflict` or `Restack failed` (a parked freeze included), a Draft PR, `Seam review pending, no review running`, or `Review skipped, out of review quota`. For those the envelope stays `in_progress` but names the blocker in the top-level `blocker`, `prNumber`, `headSha`, and `issues[]`, with `actAfter: "agents_idle"`, `waitingOn` listing the busy agents, and `repair` when there is one. Plan the fix from it, but do not patch, merge, or push while `actAfter` is set: keep calling `stack_wait` with the same cursor, and act when a snapshot after the agents finish returns `attention`; a Cyclone push can change or clear the blocker, so re-read it then. Blockers the agents can change (a red CI failure, a failed review, seam findings, a bounce) keep the plain hold: `blocker` is null, `actAfter` is null, and only `busy[]` names them. If a hold looks stuck, refresh `stack_status` and tell the human. Do not turn Cyclone off or Auto land off, and do not turn Auto land on to end the wait; turn it on only as "Re-arm after a bounce" allows. If the remote head moves while you wait, stop and tell the human.
 4. Use a clean worktree on that named PR's head branch and record the remote starting SHA. Fix the current blocker with the smallest patch, and run the relevant checks. For conflicts, the live parent is the sibling PR head or the unit branch (`mg-stack-N`, Mergestorm's owned trunk, not an alias for main) — not the DTO `parentBranch` when that field starts with `mg-park-*`. If `parentBranch` is `mg-park-*`, never merge or rebase onto it; if the real live parent is unknown, stop. The land PR is the one PR whose head is `mg-stack-N`: its live parent is its base (`main`), and merging that base into `mg-stack-N` with an ordinary push is its conflict repair, the same as for any other layer. Cyclone patches Vortex findings on a land PR when auto-patch is on for that stack; every other land PR blocker, a conflict with main or failing CI included, is yours: when `busy[]` shows no Cyclone run on it, fix it with the smallest patch on `mg-stack-N` and push with an ordinary push, never a force push; while Cyclone is patching findings on it the envelope stays `in_progress` with `busy[]`, so wait. For a conflict, prefer merging that live parent into the PR branch, resolving locally, then an ordinary push. Do not click Dashboard Continue yourself: Continue is a human action, and you relay it to the human only when step 5 or a `repair` names it. When the live parent is a sibling, never rebase onto trunk or `mg-stack-N` instead. Parked-freeze DIRTY alone needs no conflict patch. Leave GitHub bases as Mergestorm set them: the bottom of a 2+ PR stack is based on `mg-stack-N`, layer 2 on layer 1, PR3+ on `mg-park-*`.
 5. CI-only fixes may run while Cyclone auto-patch is still on for the stack. Auto-patch may stay on, and you still wait until the current Vortex run and the current Cyclone run on that PR have finished before the follow-up commit. When the gate is clean, inspect `issues[]` and fix a live upstack CI failure one PR at a time, refreshing the gate before the next PR. Do not use higher-layer bounce history as a patch target. Do not fight Cyclone: if the remote head moved, stop and tell the human. Do not take over Cyclone's review-finding work while it is active; if the blocker requires that or a policy/queue action rather than a concrete patch, stop and explain what needs human attention. On a `Seam findings` blocker, read that PR's seam finding, the Vortex review "Integration review — IU <n> seam" (`gh api repos/OWNER/REPO/pulls/N/reviews` and `gh api repos/OWNER/REPO/pulls/N/comments`), and patch its concrete findings on that PR's head; a "Decision required" seam finding needs a human, so tell them and do not guess. A seam finding you verified is wrong is recorded with `mg dismiss` (the audited dismissal in `mergestorm-pr-loop`) at that PR's live head and that seam review's id; a `mergestorm-loop: dismiss` comment alone does not clear the seam gate. On `Seam review failed`, do not patch; tell the human, unless a new push already has a seam re-review held in `busy[]`. On `Seam review pending, no review running`, do not patch; tell the human: the seam review was skipped (usually because the monthly review limit is reached) and nothing re-runs it until they raise the limit and click Continue on the stack, or push a new head. On `Seam review stuck in reviewing, no review running`, `Seam re-review pending, no review running`, or `Seam verdict is for an older head, no review running` (repair kind `seam_review_stuck`), do not patch or push; tell the human: no seam review is queued or running for that PR's live head, and clicking Continue on the stack re-queues it (a new pushed head also does). On `Review skipped, out of review quota`, do not patch; tell the human: the review credit limit for the period is reached and nothing re-reviews that head until they raise the limit and push a new head or re-run the review.
 6. Recheck Auto land (off is expected only after a disarming bounce you are handling) and the remote PR head (`git ls-remote origin refs/heads/<branch>`) immediately before pushing. Also call `queue_status` with the `stack_id`: while an entry of the stack is `queued`, `running`, or `waiting`, do not push. The queue is verifying the diff that was reviewed when it was queued; a push that changes that diff bounces the entry `head_moved` and stops the batch it is in, which re-runs CI for every PR in that batch. Do not cancel the entry. Keep the fix on a local branch and keep watching: when the entry bounces, push the fix to this PR; when the stack lands, open the fix as a follow-up PR (`mg stack create <name> --onto main`, then `mg stack submit`) and tell the human its number. Commit the patch and push the PR head with an ordinary push. A rebase onto that same live parent followed by force-with-lease is allowed only if the remote is still exactly the SHA you started from and Cyclone did not move it; use an explicit lease bound to that starting SHA. This exception never permits rebasing onto a parked freeze or substituting trunk / the unit for a sibling parent. If the remote head moved or the push is rejected because it moved, stop; do not rebase and retry.