mergestorm 0.3.25 → 0.3.26

package/README.md

@@ -45,12 +45,12 @@ On a TTY, bare `mergestorm` (or `mergestorm shell`) opens a branded REPL: a comp
 
 ```
 ╭──────────────────────────────────────────────────────────────────────────────╮
-│ ▟██▛  mergestorm v0.3.25                                                     │
-│  ▜▙   ● msk_live_…  · maelstrom                                              │
-│       [████████░░░░░░░░░░░░░░░░░░░░░░] 25% used · Resets Sep 5, 10:53am (UTC)│
-│                                                                              │
-│       review a diff · usage for tabs · /help for all commands                │
-│       New in v0.3.25: stack wait holds a PR while Cyclone or Vortex works   │
+│  ▀▀▀▀▀▀▀▀▀▀▘  mergestorm v0.3.26                                             │
+│ ▀▀▀▀▀▀▀▀▀     ● msk_live_… · maelstrom                                       │
+│  ▀▀▀▀▀▀       [████████░░░░░░░░░░░░░░░░░░░░░░] 25% used                      │
+│   ▝▀▀▀▀▀      local reviews + stacked PRs · mergestorm.ai                    │
+│     ▝▀▀▘      review a diff · usage for tabs · /help for all commands        │
+│       ▀       New: stack results say the watch ends only at land             │
 ╰──────────────────────────────────────────────────────────────────────────────╯
 mergestorm
 ╭──────────────────────────────────────────────────────────────────────────────╮

package/dist/client/index.d.ts

@@ -7,4 +7,5 @@ export { REVIEW_JOB_ENVELOPE_SCHEMA, toReviewJobEnvelope, type ReviewEnvelopeFal
 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, type StackAgentBusy, type StackBlocker, type StackLayerAgents, } from "../stack-blockers.js";
+export { stackBlockers, stackBlockersSummary, sameHead, layerAgents, layerAgentsBusy, conflictLiveParent, stackRepair, type StackAgentBusy, type StackBlocker, 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";

package/dist/client/index.js

@@ -7,4 +7,5 @@ export { REVIEW_JOB_ENVELOPE_SCHEMA, toReviewJobEnvelope, } from "../ui/job-enve
 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, } from "../stack-blockers.js";
+export { stackBlockers, stackBlockersSummary, sameHead, layerAgents, layerAgentsBusy, conflictLiveParent, stackRepair, } from "../stack-blockers.js";
+export { STACK_WATCH_NOT_DONE_SENTENCE, stackTerminalReason, stackWatchNextArgs, stackWatchObligation, } from "../stack-watch-obligation.js";

package/dist/commands/registry.js

@@ -224,7 +224,7 @@ export const COMMAND_REGISTRY = [
             "mergestorm stack reset --force  Clear this repo's pre-submit authoring state",
             "mergestorm stack list [--json]  List registered stacks",
             "mergestorm stack status <stack-id> [--json]  Enriched stack status",
-            "mergestorm stack wait <stack-id> [--json] [--timeout <s>]  Wait for stack attention (default 45s, max 300s; 0 = one snapshot, no wait)",
+            "mergestorm stack wait <stack-id> [--json] [--timeout <s>]  Wait for stack attention (default 45s, max 300s; 0 = one snapshot, no wait). --json: one document on stdout; timeout notice on stderr, exit 5",
             "mergestorm stack set <stack-id> [--auto-land on|off] [--auto-review on|off|default] [--auto-patch on|off|default] [--json]  Per-stack policy",
             "mergestorm stack adopt <owner/repo>#<pr> [--auto-land on|off] [--auto-review on|off] [--auto-patch on|off]  Import an open PR chain",
             "mergestorm stack restack <stack-id>   Restack stack descendants",

package/dist/commands/stack.d.ts

@@ -1,3 +1,5 @@
+import { type StackRepairHint } from "../stack-blockers.js";
+import { type StackWatchObligation } from "../stack-watch-obligation.js";
 import { adoptStack, ensureUpperPark, findStackPull, getEnrichedStack, listStacks, openStackPull, setStackPolicy, type StackDto, type StackPolicyPatch } from "../api.js";
 import { loadConfig } from "../config.js";
 import { createPrs, findOpenPrNumber } from "../gh.js";
@@ -7,6 +9,11 @@ import { buildPrBodyFromCommit } from "../pr-body.js";
 import { gitTopLevel } from "../repo-identity.js";
 import { loadStackMeta, saveStackMeta } from "../stack-meta.js";
 import { pollStackWatch } from "../stack-watch.js";
+export declare function stackRepairLine(repair: StackRepairHint | null | undefined): string[];
+export declare function stackWatchTextLines(watch: StackWatchObligation | null | undefined): string[];
+export declare function openStackWatch(stackId: string, opts?: {
+    unread?: boolean;
+}): StackWatchObligation;
 /** A registered stack layer that would become the parent of a new layer. */
 export type RegisteredParentHit = {
     stackId: string;
@@ -140,6 +147,7 @@ export type StackSetDeps = {
 };
 /** Human summary lines for a `stack set` write, one per flag. */
 export declare function stackSetSummary(parsed: StackSetArgs): string[];
+export declare function withWatch(body: unknown, watch: StackWatchObligation | null): unknown;
 export declare function cmdStackSet(args: string[], deps?: StackSetDeps): Promise<void>;
 export declare function cmdStack(args: string[], options?: {
     signal?: AbortSignal;

package/dist/commands/stack.js

@@ -1,4 +1,5 @@
-import { stackBlockersSummary } from "../stack-blockers.js";
+import { stackBlockers, stackBlockersSummary } from "../stack-blockers.js";
+import { STACK_WATCH_NOT_DONE_SENTENCE, 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";
@@ -15,6 +16,26 @@ import { runLineTabsBrowser } from "../ui/line-tabs.js";
 import { present } from "../ui/present.js";
 import { canBrowse } from "./browse.js";
 import { openHelpBrowser } from "./help.js";
+export function stackRepairLine(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}`];
+}
+export function stackWatchTextLines(watch) {
+    if (!watch)
+        return [];
+    if (watch.done)
+        return [watch.message];
+    const next = watch.next;
+    return [
+        ...(next ? [`Next: ${next.command} (MCP: stack_wait ${JSON.stringify(next.args)})`] : []),
+        STACK_WATCH_NOT_DONE_SENTENCE,
+    ];
+}
+export function openStackWatch(stackId, opts = {}) {
+    return stackWatchObligation({ stackId, terminal: null, unread: opts.unread, freshCursor: true });
+}
 const STACK_USAGE = `usage:
   mergestorm stack create [name] [--onto <branch>] [--trunk <branch>] [--extend] [--auto-land on|off] [--auto-review on|off] [--auto-patch on|off] [--json]
   mergestorm stack submit [--extend] [--auto-land on|off] [--auto-review on|off] [--auto-patch on|off] [--rest] [--json]
@@ -22,6 +43,8 @@ const STACK_USAGE = `usage:
   mergestorm stack list [--json]
   mergestorm stack status <stack-id> [--json]
   mergestorm stack wait <stack-id> [--json] [--timeout <s>]
+    --json writes exactly one JSON document to stdout. The timeout or error notice goes to stderr
+    (exit 5 on timeout), so do not merge the streams (2>&1) before parsing stdout.
   mergestorm stack set <stack-id> [--auto-land on|off] [--auto-review on|off|default] [--auto-patch on|off|default] [--json]
   mergestorm stack adopt <owner/repo>#<pr> [--auto-land on|off] [--auto-review on|off] [--auto-patch on|off] [--json]
   mergestorm stack restack <stack-id> [--json]
@@ -780,6 +803,7 @@ export async function cmdStackSubmit(args, deps = {}) {
             stackId: stackId ?? null,
             trunk: data.stack?.trunkBranch ?? meta.trunk,
             chain: data.chain ?? null,
+            watch: stackId ? openStackWatch(stackId) : null,
         }, null, 2));
         return;
     }
@@ -799,6 +823,8 @@ export async function cmdStackSubmit(args, deps = {}) {
         summary.push(ansi.dim("  Stack registration returned no stack ID"));
     }
     summary.push(ansi.dim("  Dashboard: https://mergestorm.ai/dashboard"));
+    if (stackId)
+        summary.push(...stackWatchTextLines(openStackWatch(stackId)).map((line) => `  ${line}`));
     await present("Stack", summary);
 }
 async function cmdStackReset(args) {
@@ -868,7 +894,11 @@ export async function cmdStackWait(args, deps = {}) {
             ...envelope,
             ...(retryAfterSeconds !== undefined ? { retry_after_seconds: retryAfterSeconds } : {}),
         }, null, 2)
-        : `Stack ${envelope.stackId} · ${envelope.status}${stackBlockersSummary(envelope.blocker && envelope.prNumber != null ? { prNumber: envelope.prNumber, blocker: envelope.blocker } : null, envelope.issues, envelope.busy)}${envelope.assessment === "unavailable" ? " · assessment unavailable" : ""}`);
+        : [
+            `Stack ${envelope.stackId} · ${envelope.status}${stackBlockersSummary(envelope.blocker && envelope.prNumber != null ? { prNumber: envelope.prNumber, blocker: envelope.blocker } : null, envelope.issues, envelope.busy, envelope.landGatePending ?? null)}${envelope.assessment === "unavailable" ? " · assessment unavailable" : ""}`,
+            ...stackRepairLine(envelope.repair),
+            ...stackWatchTextLines(envelope.watch),
+        ].join("\n"));
     try {
         print(await (deps.pollStackWatch ?? pollStackWatch)(cfg, stackId, {
             timeoutMs: timeoutS * 1000,
@@ -892,6 +922,7 @@ export async function cmdStackWait(args, deps = {}) {
 }
 export async function cmdStackStatus(args, deps = {}) {
     const usage = "usage: mergestorm stack status <stack-id> [--json]";
+    const asJson = args.includes("--json");
     const positional = args.filter((arg) => arg !== "--json");
     if (positional.length !== 1)
         throw new CommandError(usage, 2, "usage");
@@ -899,10 +930,25 @@ export async function cmdStackStatus(args, deps = {}) {
     const cfg = await (deps.loadConfig ?? loadConfig)();
     const stack = await (deps.getEnrichedStack ?? getEnrichedStack)(stackId, cfg);
     if (!stack) {
+        const watch = stackWatchObligation({ stackId, terminal: "not_found" });
+        if (asJson) {
+            console.log(JSON.stringify({ error: { code: "not_found", stack_id: stackId }, watch }, null, 2));
+            process.exitCode = 1;
+            return;
+        }
+        console.log(watch.message);
         throw new CommandError(`Stack not found or not owned by the current user: ${stackId}`, 1, "not_found");
     }
-    if (args.includes("--json")) {
-        console.log(JSON.stringify(stack, null, 2));
+    const { attention, currentCandidate, repair } = stackBlockers(stack);
+    const watch = stackWatchObligation({
+        stackId: stack.id,
+        terminal: stackTerminalReason(stack),
+        cursor: { enrolledHeadSha: currentCandidate?.headSha ?? null },
+        attention: attention ? { prNumber: attention.prNumber, blocker: attention.blocker } : null,
+        freshCursor: true,
+    });
+    if (asJson) {
+        console.log(JSON.stringify({ ...stack, repair, watch }, null, 2));
         return;
     }
     const lines = formatStackHuman(stack, false);
@@ -915,6 +961,7 @@ export async function cmdStackStatus(args, deps = {}) {
             (layer.cycloneStatus ? `  Cyclone: ${layer.cycloneStatus}` : "") +
             (layer.tempestStatus ? `  Tempest: ${layer.tempestStatus}` : ""));
     }
+    lines.push(...[...stackRepairLine(repair), ...stackWatchTextLines(watch)].map((line) => `  ${line}`));
     await present("Stack status", lines);
 }
 /** Human summary lines for a `stack set` write, one per flag. */
@@ -932,6 +979,11 @@ export function stackSetSummary(parsed) {
     }
     return lines;
 }
+export function withWatch(body, watch) {
+    if (!watch || typeof body !== "object" || body === null || Array.isArray(body))
+        return body;
+    return { ...body, watch };
+}
 export async function cmdStackSet(args, deps = {}) {
     const parsed = parseStackSetArgs(args);
     const cfg = await (deps.loadConfig ?? loadConfig)();
@@ -940,18 +992,26 @@ export async function cmdStackSet(args, deps = {}) {
         ...(parsed.autoReview !== undefined ? { autoReviewOverride: parsed.autoReview } : {}),
         ...(parsed.autoPatch !== undefined ? { autoPatchOverride: parsed.autoPatch } : {}),
     }, cfg);
+    const watch = openStackWatch(parsed.stackId, { unread: true });
     if (parsed.asJson) {
-        console.log(JSON.stringify(body, null, 2));
+        console.log(JSON.stringify(withWatch(body, watch), null, 2));
         return;
     }
-    await present("Stack", stackSetSummary(parsed).map((line) => ansi.brightGreen(`  ${line} for ${parsed.stackId}`)));
+    await present("Stack", [
+        ...stackSetSummary(parsed).map((line) => ansi.brightGreen(`  ${line} for ${parsed.stackId}`)),
+        ...stackWatchTextLines(watch).map((line) => `  ${line}`),
+    ]);
 }
 async function cmdStackAdopt(args) {
     const { owner, repo, prNumber, autoLand, autoReview, autoPatch, asJson } = parseStackAdoptArgs(args);
     const cfg = await loadConfig();
     const body = await adoptStack(owner, repo, prNumber, cfg, openPolicyPatch({ autoLand, autoReview, autoPatch }));
+    const adoptedId = typeof body === "object" && body !== null
+        ? body.stack?.id
+        : undefined;
+    const watch = typeof adoptedId === "string" && adoptedId ? openStackWatch(adoptedId, { unread: true }) : null;
     if (asJson) {
-        console.log(JSON.stringify(body, null, 2));
+        console.log(JSON.stringify(withWatch(body, watch), null, 2));
         return;
     }
     if (typeof body !== "object" || body === null) {
@@ -969,6 +1029,7 @@ async function cmdStackAdopt(args) {
         imported.push(ansi.dim(`  trunk: ${stack.trunkBranch}`));
     }
     imported.push(ansi.dim("  Dashboard: https://mergestorm.ai/dashboard"));
+    imported.push(...stackWatchTextLines(watch).map((line) => `  ${line}`));
     await present("Stack", imported);
 }
 async function cmdStackRestack(args) {

package/dist/shell.js

@@ -79,7 +79,7 @@ export async function runShell() {
                     commands: COMMANDS,
                     ...(banner
                         ? {
-                            header: (columns, variant) => banner.rows(columns, variant),
+                            header: (columns, variant, frame) => banner.rows(columns, variant, frame),
                         }
                         : {}),
                 });

package/dist/stack-blockers.d.ts

@@ -27,6 +27,28 @@ export type StackLayerAgents = {
         cyclone: boolean;
     };
 };
+export type StackRepairHint = {
+    kind: "restack_conflict" | "merge_conflict";
+    prNumber: number;
+    headSha: string | null;
+    branch: string;
+    liveParent: string | null;
+    files: string[];
+    steps: string;
+} | {
+    kind: "ci_failure";
+    prNumber: number;
+    headSha: string | null;
+    branch: string;
+    failingCheck: string | null;
+    steps: string;
+};
+export type StackLandGatePending = {
+    prNumber: number;
+    headSha: string | null;
+    reason: string;
+};
+export declare function landGateIsPending(reason: string | null | undefined): boolean;
 export declare function layerAgentsBusy(layer: StackLayerDto): StackAgentsBusy;
 export declare function layerAgents(layer: StackLayerDto): StackLayerAgents;
 export declare function isMgParkBase(branch: string | null | undefined): boolean;
@@ -34,6 +56,9 @@ export declare function isMgParkBase(branch: string | null | undefined): boolean
 export declare function boundDirty(layer: StackLayerDto): boolean;
 export declare function sameHead(a: string | null | undefined, b: string | null | undefined): boolean;
 export declare function currentLayer(stack: StackDto): StackLayerDto | undefined;
+export declare function conflictLiveParent(stack: StackDto, layer: StackLayerDto): string | null;
+export declare function conflictRepairSteps(branch: string, liveParent: string | null): string;
+export declare function stackRepair(stack: StackDto, attention: StackBlocker | null, layer: StackLayerDto | undefined, bounce: MergeQueueEntryDto | undefined): StackRepairHint | null;
 /** Pair-gate attention plus live hard blocks on every other open layer. */
 export declare function stackBlockers(stack: StackDto, entries?: MergeQueueEntryDto[], cursor?: Pick<StackWatchCursor, "bounceId" | "afterFinishedAt">): {
     attention: StackBlocker | null;
@@ -45,6 +70,8 @@ export declare function stackBlockers(stack: StackDto, entries?: MergeQueueEntry
     bounce: MergeQueueEntryDto | undefined;
     busy: StackAgentBusy[];
     agents: StackLayerAgents | null;
+    repair: StackRepairHint | null;
+    landGatePending: StackLandGatePending | null;
 };
 /** Compact contract text shared by status and wait summaries. */
-export declare function stackBlockersSummary(attention: Pick<StackBlocker, "prNumber" | "blocker"> | null, issues: StackBlocker[], busy?: readonly StackAgentBusy[]): string;
+export declare function stackBlockersSummary(attention: Pick<StackBlocker, "prNumber" | "blocker"> | null, issues: StackBlocker[], busy?: readonly StackAgentBusy[], landGatePending?: Pick<StackLandGatePending, "prNumber" | "reason"> | null): string;

package/dist/stack-blockers.js

@@ -1,4 +1,8 @@
 import { deriveStackAgentsBusy, mergeQueueBounceLabel, restackRetryPending, } from "./stack-dto.js";
+export function landGateIsPending(reason) {
+    const token = reason?.trim().replace(/^landing blocked:\s*/i, "").match(/^[a-z_]+/i)?.[0] ?? "";
+    return /_(?:pending|running)$/i.test(token);
+}
 export function layerAgentsBusy(layer) {
     return layer.agentsBusy ?? deriveStackAgentsBusy(layer);
 }
@@ -98,8 +102,9 @@ function layerAttention(stack, layer, queue, cursor) {
         if (seam)
             return hardBlock(seam);
         if (stack.unit?.landPrNumber === layer.prNumber) {
-            if (stack.unit.landingBlockReason?.trim())
-                return hardBlock(stack.unit.landingBlockReason.trim());
+            const landing = stack.unit.landingBlockReason?.trim();
+            if (landing && !landGateIsPending(landing))
+                return hardBlock(landing);
             if (stack.unit.tempestLandStatus?.toLowerCase() === "failed")
                 return hardBlock("Tempest failed");
         }
@@ -115,6 +120,74 @@ function layerAttention(stack, layer, queue, cursor) {
         return none;
     return { blocker: mergeQueueBounceLabel(bounce), bounceKind: kind, bounce };
 }
+function isTerminalLayer(layer) {
+    return layer.state === "merged" || layer.state === "closed";
+}
+export function conflictLiveParent(stack, layer) {
+    const promoted = (candidate) => !!stack.unit?.members?.some((member) => member.prNumber === candidate.prNumber && member.promotedHeadSha?.trim());
+    const sibling = stack.layers
+        .filter((candidate) => candidate.prNumber > 0 && candidate.position < layer.position &&
+        !isTerminalLayer(candidate) && !promoted(candidate))
+        .sort((a, b) => b.position - a.position)[0];
+    if (sibling)
+        return sibling.branch;
+    const retired = new Set([
+        ...stack.layers.filter((candidate) => isTerminalLayer(candidate) || promoted(candidate)).map((candidate) => candidate.branch),
+        ...(stack.unit?.members ?? []).filter((member) => member.promotedHeadSha?.trim()).map((member) => member.branch),
+    ]);
+    const usable = (branch) => !!branch?.trim() && !isMgParkBase(branch) && !retired.has(branch) && branch !== layer.branch;
+    for (const branch of [layer.restackError?.from?.branch, layer.parentBranch, stack.unit?.branch, stack.trunkBranch]) {
+        if (usable(branch))
+            return branch;
+    }
+    return null;
+}
+function conflictFiles(layer, bounce) {
+    const paths = bounce?.bounceDetail?.conflictPaths?.filter((path) => path.trim());
+    if (paths?.length)
+        return [...paths];
+    const detail = layer.restackError?.kind === "rebase_conflict" ? layer.restackError.detail : layer.conflictDetail;
+    const listed = detail?.match(/^conflict in (.+)$/)?.[1];
+    return listed ? listed.split(", ").map((path) => path.trim()).filter(Boolean) : [];
+}
+export function conflictRepairSteps(branch, liveParent) {
+    if (!liveParent) {
+        return `The live parent of ${branch} is unknown (it is never an mg-park-* freeze). Do not merge or rebase anything; stop and tell the human.`;
+    }
+    return `Merge ${liveParent} into ${branch}: git fetch origin, check out ${branch} at its live remote head, git merge origin/${liveParent}, resolve the conflicts, run the tests, then an ordinary git push (no force). Do not rebase onto trunk, main, or mg-park-*, and do not retarget the PR base.`;
+}
+export function stackRepair(stack, attention, layer, bounce) {
+    if (!attention || !layer || attention.prNumber !== layer.prNumber)
+        return null;
+    if (stack.unit && layer.prNumber === stack.unit.landPrNumber && layer.branch === stack.unit.branch)
+        return null;
+    const restackConflict = attention.blocker === "Conflict" || attention.bounceKind === "restack_conflict";
+    const mergeConflict = attention.blocker.startsWith("Merge conflicts");
+    if (restackConflict || mergeConflict) {
+        const liveParent = conflictLiveParent(stack, layer);
+        return {
+            kind: restackConflict ? "restack_conflict" : "merge_conflict",
+            prNumber: layer.prNumber,
+            headSha: layer.headSha ?? null,
+            branch: layer.branch,
+            liveParent,
+            files: conflictFiles(layer, bounce),
+            steps: conflictRepairSteps(layer.branch, liveParent),
+        };
+    }
+    if (attention.blocker.startsWith("CI failed") || attention.bounceKind === "ci_failure") {
+        const failingCheck = bounce?.bounceDetail?.failingCheck?.trim() || layer.checks?.failingName?.trim() || null;
+        return {
+            kind: "ci_failure",
+            prNumber: layer.prNumber,
+            headSha: layer.headSha ?? null,
+            branch: layer.branch,
+            failingCheck,
+            steps: `Read the failing ${failingCheck ? `check ${failingCheck}` : "checks"} on ${layer.branch} (gh run list --branch ${layer.branch}, then gh run view <run-id> --log-failed), fix it on ${layer.branch} with the smallest patch, run that check locally, confirm the remote head is still ${layer.headSha ?? "the head you started from"}, then an ordinary git push. Do not retarget the PR base.`,
+        };
+    }
+    return null;
+}
 /** Pair-gate attention plus live hard blocks on every other open layer. */
 export function stackBlockers(stack, entries = [], cursor = {}) {
     const candidate = currentLayer(stack);
@@ -155,16 +228,26 @@ export function stackBlockers(stack, entries = [], cursor = {}) {
                 busy.push({ prNumber: attention.prNumber, headSha: attention.headSha, agent, blocker: attention.blocker });
         }
     }
+    const landing = stack.unit?.landingBlockReason?.trim();
+    const landLayer = stack.unit?.landPrNumber != null && !stack.archivedAt
+        ? open.find((layer) => layer.prNumber === stack.unit?.landPrNumber)
+        : undefined;
+    const landGatePending = landLayer && landing && landGateIsPending(landing)
+        ? { prNumber: landLayer.prNumber, headSha: landLayer.headSha ?? null, reason: landing }
+        : null;
     if (busy.length)
-        return { attention: null, issues, currentCandidate, bounce: undefined, busy, agents };
-    return { attention, issues, currentCandidate, bounce, busy, agents };
+        return { attention: null, issues, currentCandidate, bounce: undefined, busy, agents, repair: null, landGatePending };
+    return { attention, issues, currentCandidate, bounce, busy, agents, repair: stackRepair(stack, attention, attentionLayer, bounce), landGatePending };
 }
 /** Compact contract text shared by status and wait summaries. */
-export function stackBlockersSummary(attention, issues, busy = []) {
+export function stackBlockersSummary(attention, issues, busy = [], landGatePending = null) {
     const blocked = attention ? ` · blocked: #${attention.prNumber} ${attention.blocker}` : "";
     const working = busy.length
         ? ` · held: #${busy[0].prNumber} ${busy[0].blocker} while ${busy.map((entry) => entry.agent === "cyclone" ? "Cyclone patches" : "Vortex reviews").join(" and ")}`
         : "";
     const labels = issues.slice(0, 3).map(issue => `#${issue.prNumber} ${issue.blocker}`).join("; ");
-    return blocked + working + (issues.length ? ` · issues: ${labels}${issues.length > 3 ? `; +${issues.length - 3} more` : ""}` : "");
+    const gate = landGatePending && !attention
+        ? ` · land gate: #${landGatePending.prNumber} ${landGatePending.reason} (nothing to fix; wait)`
+        : "";
+    return blocked + working + gate + (issues.length ? ` · issues: ${labels}${issues.length > 3 ? `; +${issues.length - 3} more` : ""}` : "");
 }

package/dist/stack-dto.d.ts

@@ -5,6 +5,10 @@ export type RestackError = {
     attemptedAt: string;
     attempts: number;
     backupRef: string | null;
+    from?: {
+        branch: string;
+        oldSha: string;
+    };
 };
 export declare function restackAttemptsExhausted(error: Pick<RestackError, "attempts">): boolean;
 export declare function pushRejectionIsRetryable(message: string): boolean;

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

@@ -0,0 +1,43 @@
+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 type StackWatchDoneReason = "landed" | "closed" | "archived" | "not_found";
+export type StackWatchReason = StackWatchDoneReason | "open" | "attention" | "unread" | "rate_limited" | "failed";
+export type StackWatchNextArgs = {
+    stack_id: string;
+    enrolled_head_sha?: string | null;
+    after_finished_at?: string | null;
+    bounce_id?: string | null;
+    timeout_s: 45;
+};
+export type StackWatchNext = {
+    tool: "stack_wait";
+    args: StackWatchNextArgs;
+    command: string;
+};
+export type StackWatchObligation = {
+    done: boolean;
+    until: "landed";
+    reason: StackWatchReason;
+    next: StackWatchNext | null;
+    message: string;
+};
+export type StackWatchObligationInput = {
+    stackId: string;
+    terminal: StackWatchDoneReason | null;
+    cursor?: {
+        enrolledHeadSha?: string | null;
+        afterFinishedAt?: string | null;
+        bounceId?: string | null;
+    } | null;
+    status?: string;
+    attention?: {
+        prNumber: number;
+        blocker: string;
+    } | null;
+    retryAfterSeconds?: number;
+    unread?: boolean;
+    freshCursor?: boolean;
+};
+export declare function stackTerminalReason(stack: Pick<StackDto, "archivedAt" | "layers" | "unit"> | null | undefined): StackWatchDoneReason | null;
+export declare function stackWatchNextArgs(stackId: string, cursor: StackWatchObligationInput["cursor"]): StackWatchNextArgs;
+export declare function stackWatchObligation(input: StackWatchObligationInput): StackWatchObligation;

package/dist/stack-watch-obligation.js

@@ -0,0 +1,79 @@
+export const STACK_WATCH_NOT_DONE_SENTENCE = "This stack is not landed. Your task is not done. Call stack_wait again with this cursor.";
+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.",
+    archived: "This stack is archived: the human took it back. The watch is done; stop calling stack_wait for it and do not push to its PRs.",
+    not_found: "No stack with this id exists for this account. Mergestorm deletes a stack once none of its layers is open, so a stack you were watching has most likely landed; a mistyped id or another account's stack reads the same. The watch is done; confirm each PR is merged (gh pr view <n> --json state) before reporting it landed.",
+};
+export function stackTerminalReason(stack) {
+    if (!stack)
+        return "not_found";
+    if (stack.archivedAt)
+        return "archived";
+    const layers = stack.layers;
+    if (layers.some((layer) => layer.state !== "merged" && layer.state !== "closed"))
+        return null;
+    const unit = stack.unit;
+    if (layers.length === 0 && !unit)
+        return null;
+    const landPr = unit?.landPr;
+    if (landPr && landPr.prNumber > 0 && landPr.state !== "merged" && landPr.state !== "closed")
+        return null;
+    if (unit && unit.state !== "landed" && unit.state !== "abandoned")
+        return null;
+    const everyLayerMerged = layers.every((layer) => layer.state === "merged");
+    return everyLayerMerged && (!unit || unit.state === "landed") ? "landed" : "closed";
+}
+export function stackWatchNextArgs(stackId, cursor) {
+    return {
+        stack_id: stackId,
+        ...(cursor && cursor.enrolledHeadSha !== undefined ? { enrolled_head_sha: cursor.enrolledHeadSha } : {}),
+        ...(cursor && cursor.afterFinishedAt !== undefined ? { after_finished_at: cursor.afterFinishedAt } : {}),
+        ...(cursor && cursor.bounceId !== undefined ? { bounce_id: cursor.bounceId } : {}),
+        timeout_s: 45,
+    };
+}
+export function stackWatchObligation(input) {
+    if (input.terminal) {
+        return {
+            done: true,
+            until: "landed",
+            reason: input.terminal,
+            next: null,
+            message: DONE_MESSAGES[input.terminal],
+        };
+    }
+    const args = stackWatchNextArgs(input.stackId, input.cursor);
+    const reason = input.status === "rate_limited"
+        ? "rate_limited"
+        : input.status === "failed"
+            ? "failed"
+            : input.attention ? "attention" : input.unread ? "unread" : "open";
+    const parts = [
+        STACK_WATCH_NOT_DONE_SENTENCE,
+        `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") {
+        parts.push(`Wait ${input.retryAfterSeconds !== undefined ? `${input.retryAfterSeconds}s` : "retry_after_seconds"} first, then call stack_wait with the same cursor.`);
+    }
+    else if (reason === "failed") {
+        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.`);
+    }
+    else if (reason === "unread") {
+        parts.push("This tool did not read the stack's state; stack_wait will.");
+    }
+    parts.push(`Next call: stack_wait ${JSON.stringify(args)}.`);
+    if (input.freshCursor) {
+        parts.push("If you already hold a cursor from an earlier stack_wait on this stack, keep passing that cursor instead.");
+    }
+    return {
+        done: false,
+        until: "landed",
+        reason,
+        next: { tool: "stack_wait", args, command: `mg stack wait ${input.stackId} --json` },
+        message: parts.join(" "),
+    };
+}

package/dist/stack-watch.d.ts

@@ -1,4 +1,5 @@
-import { type StackAgentBusy, type StackBlocker, type StackLayerAgents } from "./stack-blockers.js";
+import { type StackAgentBusy, type StackBlocker, type StackLayerAgents, type StackLandGatePending, type StackRepairHint } from "./stack-blockers.js";
+import { type StackWatchObligation } from "./stack-watch-obligation.js";
 import { apiFetch } from "./api.js";
 import type { Config } from "./config.js";
 export declare const STACK_WATCH_SCHEMA: "mergestorm.stack_watch/v1";
@@ -28,6 +29,9 @@ export type StackWatchEnvelope = {
     assessment: "available" | "unavailable";
     busy: StackAgentBusy[];
     agents: StackLayerAgents | null;
+    repair: StackRepairHint | null;
+    landGatePending: StackLandGatePending | null;
+    watch: StackWatchObligation;
 };
 export type PollStackWatchOptions = {
     timeoutMs?: number;

package/dist/stack-watch.js

@@ -1,4 +1,5 @@
 import { currentLayer, layerAgents, stackBlockers, } from "./stack-blockers.js";
+import { stackTerminalReason, stackWatchObligation, } from "./stack-watch-obligation.js";
 import { setTimeout as sleep } from "node:timers/promises";
 import { apiFetch } from "./api.js";
 import { REVIEW_POLL_INTERVAL_MS, REVIEW_POLL_MAX_TRANSIENT_RETRIES, isTransientReviewPollError, isTransientReviewPollStatus, transientRetryWaitMs, } from "./commands/review-client.js";
@@ -47,10 +48,20 @@ export async function pollStackWatch(cfg, stackId, opts = {}) {
     let lastEnvelope = {
         schema: STACK_WATCH_SCHEMA, status: "failed", stackId: id, blocker: null,
         bounceKind: null, prNumber: null, headSha: null, cursor,
-        issues: [], currentCandidate: null, assessment: "unavailable", busy: [], agents: null,
+        issues: [], currentCandidate: null, assessment: "unavailable", busy: [], agents: null, repair: null,
+        landGatePending: null,
     };
+    let terminal = null;
+    const seal = (snapshot, retryAfterSeconds) => ({
+        ...snapshot,
+        watch: stackWatchObligation({
+            stackId: id, terminal, cursor: snapshot.cursor, status: snapshot.status, retryAfterSeconds,
+            attention: snapshot.status === "attention" && snapshot.blocker && snapshot.prNumber != null
+                ? { prNumber: snapshot.prNumber, blocker: snapshot.blocker } : null,
+        }),
+    });
     let transientFailures = 0;
-    const timeout = () => new StackWatchTimeoutError(lastEnvelope);
+    const timeout = () => new StackWatchTimeoutError(seal(lastEnvelope));
     const pause = async (ms) => {
         const remaining = Math.min(ms, Math.max(0, deadline - now()));
         if (remaining > 0)
@@ -76,11 +87,11 @@ export async function pollStackWatch(cfg, stackId, opts = {}) {
                     throw timeout();
                 if (timeoutMs !== 0 && isTransientReviewPollError(err) && transientFailures < REVIEW_POLL_MAX_TRANSIENT_RETRIES) {
                     transientFailures += 1;
-                    opts.onTick?.(lastEnvelope);
+                    opts.onTick?.(seal(lastEnvelope));
                     await pause(transientRetryWaitMs({ failureCount: transientFailures, random: opts.random }));
                     continue;
                 }
-                throw new StackWatchError(err instanceof Error ? err.message : String(err), { ...lastEnvelope, status: "failed", assessment: "unavailable" }, { cause: err });
+                throw new StackWatchError(err instanceof Error ? err.message : String(err), seal({ ...lastEnvelope, status: "failed", assessment: "unavailable" }), { cause: err });
             }
             if (response.status === 200)
                 return response.body;
@@ -90,14 +101,14 @@ export async function pollStackWatch(cfg, stackId, opts = {}) {
             if (timeoutMs !== 0 && isTransientReviewPollStatus(response.status) && transientFailures < REVIEW_POLL_MAX_TRANSIENT_RETRIES &&
                 (response.status !== 429 || retryWaitMs < deadline - now())) {
                 transientFailures += 1;
-                opts.onTick?.({ ...lastEnvelope, status: response.status === 429 ? "rate_limited" : lastEnvelope.status });
+                opts.onTick?.(seal({ ...lastEnvelope, status: response.status === 429 ? "rate_limited" : lastEnvelope.status }, response.status === 429 ? response.retryAfterSeconds : undefined));
                 await pause(retryWaitMs);
                 continue;
             }
-            throw new StackWatchError(`Stack poll failed (HTTP ${response.status})`, {
+            throw new StackWatchError(`Stack poll failed (HTTP ${response.status})`, seal({
                 ...lastEnvelope, status: response.status === 429 ? "rate_limited" : "failed",
                 assessment: "unavailable",
-            }, undefined, response.retryAfterSeconds);
+            }, response.retryAfterSeconds), undefined, response.retryAfterSeconds);
         }
         throw timeout();
     };
@@ -106,16 +117,22 @@ export async function pollStackWatch(cfg, stackId, opts = {}) {
         const stack = snapshot && Array.isArray(snapshot.stacks)
             ? snapshot.stacks.find((candidate) => candidate.id.trim().toLowerCase() === id)
             : undefined;
+        if (snapshot && Array.isArray(snapshot.stacks) && !stack) {
+            terminal = "not_found";
+            throw new StackWatchError("Stack not found or not owned by the current user", seal({ ...lastEnvelope, status: "failed", assessment: "unavailable", blocker: null, issues: [], busy: [],
+                prNumber: null, headSha: null, repair: null, agents: null, currentCandidate: null, landGatePending: null }));
+        }
         if (!stack || !Array.isArray(stack.layers)) {
-            throw new StackWatchError("Stack snapshot missing or invalid", { ...lastEnvelope, status: "failed", assessment: "unavailable" });
+            throw new StackWatchError("Stack snapshot missing or invalid", seal({ ...lastEnvelope, status: "failed", assessment: "unavailable" }));
         }
+        terminal = stackTerminalReason(stack);
         return stack;
     };
     const queueRoute = `/api/v1/stacks/queue?stackId=${encodeURIComponent(id)}`;
     const readQueue = async (route, finalSnapshot = false) => {
         const queue = await request(route, finalSnapshot);
         if (!queue || !Array.isArray(queue.entries)) {
-            throw new StackWatchError("Invalid merge queue response", { ...lastEnvelope, status: "failed", assessment: "unavailable" });
+            throw new StackWatchError("Invalid merge queue response", seal({ ...lastEnvelope, status: "failed", assessment: "unavailable" }));
         }
         return {
             entries: queue.entries.filter((entry) => entry.stackId.trim().toLowerCase() === id),
@@ -123,16 +140,16 @@ export async function pollStackWatch(cfg, stackId, opts = {}) {
         };
     };
     const evaluate = (stack, entries) => {
-        const { attention, issues, currentCandidate, bounce, busy, agents } = stackBlockers(stack, entries, cursor);
+        const { attention, issues, currentCandidate, bounce, busy, agents, repair, landGatePending } = stackBlockers(stack, entries, cursor);
         if (bounce)
             cursor = Object.freeze({ ...cursor, bounceId: bounce.id,
                 ...(bounce.finishedAt !== undefined ? { afterFinishedAt: bounce.finishedAt } : {}) });
         const held = busy[0];
-        lastEnvelope = { ...lastEnvelope, cursor, issues, currentCandidate, assessment: "available", busy, agents,
+        lastEnvelope = { ...lastEnvelope, cursor, issues, currentCandidate, assessment: "available", busy, agents, repair, landGatePending,
             blocker: attention?.blocker ?? null, bounceKind: attention?.bounceKind ?? null,
             prNumber: attention?.prNumber ?? held?.prNumber ?? currentCandidate?.prNumber ?? null,
             headSha: attention ? attention.headSha : held ? held.headSha : currentCandidate?.headSha ?? null,
-            status: attention ? "attention" : busy.length || entries.some((entry) => ["queued", "running", "waiting"].includes(entry.state))
+            status: attention ? "attention" : busy.length || landGatePending || entries.some((entry) => ["queued", "running", "waiting"].includes(entry.state))
                 ? "in_progress" : "waiting" };
     };
     let stack = await enrich(timeoutMs === 0);
@@ -145,8 +162,8 @@ export async function pollStackWatch(cfg, stackId, opts = {}) {
         agents: layer ? layerAgents(layer) : null };
     let queue = await readQueue(queueRoute, timeoutMs === 0);
     evaluate(stack, queue.entries);
-    if (lastEnvelope.status === "attention" || timeoutMs === 0)
-        return lastEnvelope;
+    if (lastEnvelope.status === "attention" || timeoutMs === 0 || terminal)
+        return seal(lastEnvelope);
     while (now() < deadline) {
         const heldAt = now();
         const seconds = Math.min(lastEnvelope.busy.length ? STACK_WATCH_BUSY_RECHECK_S : 45, Math.max(1, Math.ceil((deadline - heldAt) / 1000)));
@@ -162,9 +179,9 @@ export async function pollStackWatch(cfg, stackId, opts = {}) {
             agents: refreshed ? layerAgents(refreshed) : null };
         transientFailures = 0;
         evaluate(stack, queue.entries);
-        if (lastEnvelope.status === "attention")
-            return lastEnvelope;
-        opts.onTick?.(lastEnvelope);
+        if (lastEnvelope.status === "attention" || terminal)
+            return seal(lastEnvelope);
+        opts.onTick?.(seal(lastEnvelope));
     }
     throw timeout();
 }

package/dist/ui/ansi.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Brand ink. xterm-256 77 (#5FAF5F) � muted green that Terminal.app
+ * actually paints. 24-bit `38;2;61;�` was read as palette 61 (purple).
+ */
+export declare const BRAND_GREEN: {
+    readonly hex: "#5FAF5F";
+    readonly index: 77;
+};
+export declare const BRAND_GREEN_SGR: string;
+/** Full-cell fill. Glyphs like ? leave a hairline; a space with this bg does not. */
+export declare const BRAND_FILL_SGR: string;
 export declare const ansi: {
     readonly enabled: boolean;
     green: (t: string) => string;
@@ -7,8 +18,10 @@ export declare const ansi: {
     yellow: (t: string) => string;
     gray: (t: string) => string;
     brightGreen: (t: string) => string;
+    /** Solid cell (space + fg/bg 77). Stacks flush � no ? hairline. */
+    brandFill: (t: string) => string;
     invert: (t: string) => string;
     boldGreen: (t: string) => string;
-    /** Prompt / mark ink. Never 32 — that reads as sick dark green. */
+    /** Prompt / mark ink. Never ANSI 32, 92, or 24-bit. */
     boldBrightGreen: (t: string) => string;
 };

package/dist/ui/ansi.js

@@ -9,7 +9,25 @@ function computeEnabled() {
 function wrap(code, text) {
     if (!computeEnabled())
         return text;
-    return `[${code}m${text}`;
+    return `\x1b[${code}m${text}\x1b[0m`;
+}
+/**
+ * Brand ink. xterm-256 77 (#5FAF5F) � muted green that Terminal.app
+ * actually paints. 24-bit `38;2;61;�` was read as palette 61 (purple).
+ */
+export const BRAND_GREEN = { hex: "#5FAF5F", index: 77 };
+export const BRAND_GREEN_SGR = `38;5;${BRAND_GREEN.index}`;
+/** Full-cell fill. Glyphs like ? leave a hairline; a space with this bg does not. */
+export const BRAND_FILL_SGR = `${BRAND_GREEN_SGR};48;5;${BRAND_GREEN.index}`;
+function brandGreen(text, bold = false) {
+    if (!computeEnabled())
+        return text;
+    return `\x1b[${bold ? "1;" : ""}${BRAND_GREEN_SGR}m${text}\x1b[0m`;
+}
+function brandFill(text) {
+    if (!computeEnabled())
+        return text;
+    return `\x1b[${BRAND_FILL_SGR}m${text}\x1b[0m`;
 }
 export const ansi = {
     get enabled() {
@@ -21,9 +39,11 @@ export const ansi = {
     red: (t) => wrap("31", t),
     yellow: (t) => wrap("33", t),
     gray: (t) => wrap("90", t),
-    brightGreen: (t) => wrap("92", t),
+    brightGreen: (t) => brandGreen(t),
+    /** Solid cell (space + fg/bg 77). Stacks flush � no ? hairline. */
+    brandFill: (t) => brandFill(t),
     invert: (t) => wrap("7", t),
-    boldGreen: (t) => (computeEnabled() ? `${t}` : t),
-    /** Prompt / mark ink. Never 32 — that reads as sick dark green. */
-    boldBrightGreen: (t) => (computeEnabled() ? `${t}` : t),
+    boldGreen: (t) => (computeEnabled() ? `\x1b[1;32m${t}\x1b[0m` : t),
+    /** Prompt / mark ink. Never ANSI 32, 92, or 24-bit. */
+    boldBrightGreen: (t) => brandGreen(t, true),
 };

package/dist/ui/banner.d.ts

@@ -14,7 +14,7 @@ export type BannerDensity = "full" | "compact" | "mini" | "nano";
 export type BannerVariant = boolean | "mini" | "nano";
 /** Handle returned by {@link printBannerHeader}; `rows` reflows for a resize. */
 export type BannerHandle = {
-    rows(columns?: number, variant?: BannerVariant): string[];
+    rows(columns?: number, variant?: BannerVariant, frame?: number): string[];
 };
 /**
  * The whole welcome panel as rows, reflowed to `columns`. Every row fits in
@@ -24,6 +24,7 @@ export type BannerHandle = {
 export declare function buildBannerRows(state: BannerState, columns?: number, opts?: {
     compact?: boolean;
     density?: BannerDensity;
+    frame?: number;
 }): string[];
 /**
  * Print the welcome panel and return a handle whose `rows()` reflows the

package/dist/ui/banner.js

@@ -3,8 +3,8 @@ import { CommandError } from "../errors.js";
 import { keyDisplay, loadConfig, resolveApiKey } from "../config.js";
 import { cliVersion } from "../version.js";
 import { ansi } from "./ansi.js";
-import { frameWidth, padVisible, preferBoxedUi, roundedBox, terminalColumns, visibleWidth, } from "./box.js";
-import { STORM_MARK, STORM_MARK_WIDTH } from "./logo.js";
+import { frameWidth, padVisible, preferBoxedUi, roundedBox, sideBySide, terminalColumns, visibleWidth, } from "./box.js";
+import { paintSpriteRow, TORNADO_LOGO, TORNADO_LOGO_WIDTH } from "./logo.js";
 import { formatResetLabel, usageBar } from "./usage.js";
 const WORDMARK = `
  __  __ ___ ___  ___ ___ ___ _____ ___  ___ __  __
@@ -108,6 +108,9 @@ const WHATS_NEW = {
     "0.3.25": [
         "stack wait holds a PR while Cyclone or Vortex works",
     ],
+    "0.3.26": [
+        "stack results say the watch ends only at land",
+    ],
 };
 function densityFromVariant(variant) {
     if (variant === "mini" || variant === "nano")
@@ -199,57 +202,30 @@ export function buildBannerRows(state, columns, opts) {
     const contentCells = boxed
         ? Math.max(20, outer - 4)
         : Math.max(20, terminalColumns(80, columns) - 1);
-    const indent = STORM_MARK_WIDTH + 2;
-    const pad = " ".repeat(indent);
+    const markLines = TORNADO_LOGO;
+    const markWidth = TORNADO_LOGO_WIDTH;
+    const gap = 2;
+    const rightCells = Math.max(8, contentCells - markWidth - gap);
     const clip = (line) => visibleWidth(line) > contentCells ? padVisible(line, contentCells) : line;
-    const mark = (row) => padVisible(ansi.brightGreen(STORM_MARK[row] ?? ""), indent);
+    const clipRight = (line) => visibleWidth(line) > rightCells ? padVisible(line, rightCells) : line;
     const title = `${ansi.boldBrightGreen("mergestorm")} ${ansi.dim(`v${state.version}`)}`;
-    if (density === "nano") {
-        const one = `${mark(0)}${title}  ${statusLine(state)}`;
-        return [clip(one)];
-    }
-    if (density === "mini") {
-        // Short pane: mark + who you are, then the same cues as the full home.
-        const line0 = clip(`${mark(0)}${title}  ${statusLine(state)}`);
-        const line1 = state.me && !state.keyInvalid
-            ? clip(`${mark(1)}${usageLine(state.me, contentCells, indent)}`)
-            : clip(mark(1));
-        const room = contentCells - indent;
-        const blurb = tagline(room);
-        const tips = tipsLine(room);
-        const fresh = whatsNewLine(state.version, room);
-        return [
-            line0,
-            line1,
-            ...(blurb ? [clip(`${pad}${blurb}`)] : []),
-            ...(tips ? [clip(`${pad}${tips}`)] : []),
-            ...(fresh ? [clip(`${pad}${fresh}`)] : []),
-        ];
-    }
-    const content = [
-        clip(`${pad}${title}`),
-        clip(`${mark(0)}${statusLine(state)}`),
-    ];
+    const right = [clipRight(title), clipRight(statusLine(state))];
     if (state.me && !state.keyInvalid) {
-        content.push(clip(`${mark(1)}${usageLine(state.me, contentCells, indent)}`));
+        right.push(clipRight(usageLine(state.me, rightCells, 0)));
     }
-    else {
-        content.push(clip(mark(1)));
-    }
-    const room = contentCells - indent;
-    const blurb = tagline(room);
-    const tips = tipsLine(room);
-    const fresh = whatsNewLine(state.version, room);
+    const blurb = tagline(rightCells);
+    const tips = tipsLine(rightCells);
+    const fresh = whatsNewLine(state.version, rightCells);
     if (blurb)
-        content.push(clip(`${pad}${blurb}`));
+        right.push(clipRight(blurb));
     if (tips)
-        content.push(clip(`${pad}${tips}`));
+        right.push(clipRight(tips));
     if (fresh)
-        content.push(clip(`${pad}${fresh}`));
-    if (boxed && density === "full") {
-        content.splice(3, 0, "");
-        return [...roundedBox(content, { width: outer, padding: 1 })];
-    }
+        right.push(clipRight(fresh));
+    const markCol = markLines.map((line) => padVisible(paintSpriteRow(line), markWidth));
+    const content = sideBySide(markCol, density === "nano" ? right.slice(0, 3) : right, markWidth, gap).map(clip);
+    if (density === "mini" || density === "nano")
+        return content;
     if (boxed) {
         return [...roundedBox(content, { width: outer, padding: 1 })];
     }
@@ -285,7 +261,7 @@ export async function printBannerHeader(opts) {
         }
     }
     return {
-        rows: (columns, variant) => buildBannerRows(state, columns, { density: densityFromVariant(variant) }),
+        rows: (columns, variant, frame) => buildBannerRows(state, columns, { density: densityFromVariant(variant), frame }),
     };
 }
 export function shellPrompt(_loggedIn) {

package/dist/ui/logo.d.ts

@@ -1,13 +1,18 @@
 /**
- * Compact two-row storm mark (Fable / 0.3.14 home). Colored by the caller.
- * Block elements (U+2580..259F) are one cell each; no emoji, no gradients.
+ * The home mark: a tornado drawn as five horizontal bars and one square tail,
+ * each an upper-half band (▀). One column is one bar-height wide; half-column
+ * ends use the upper quadrants (▝ ▘) so every edge lands where the source art
+ * puts it. Same X/width as the SVG, shifted up half a cell. Painted fg 77.
  */
-export declare const STORM_MARK: string[];
-/** Widest row of the mark, in cells (every mark glyph is single-cell). */
-export declare const STORM_MARK_WIDTH: number;
-/** @deprecated Alias — the home panel uses {@link STORM_MARK}. */
 export declare const TORNADO_LOGO: string[];
-/** @deprecated Alias. */
+/** Single idle frame. Kept for callers that index frames. */
+export declare const TORNADO_FRAMES: string[][];
+/** Every sprite glyph is one column. */
 export declare const TORNADO_LOGO_WIDTH: number;
-/** @deprecated Compact home is the full two-row mark. */
 export declare const TORNADO_LOGO_COMPACT: string[];
+/** @deprecated Use {@link TORNADO_LOGO}. */
+export declare const STORM_MARK: string[];
+/** @deprecated Use {@link TORNADO_LOGO_WIDTH}. */
+export declare const STORM_MARK_WIDTH: number;
+/** Paint one sprite row: each run of glyphs in brand green 77, spaces left bare. */
+export declare function paintSpriteRow(row: string): string;

package/dist/ui/logo.js

@@ -1,16 +1,28 @@
+import { ansi } from "./ansi.js";
 /**
- * Compact two-row storm mark (Fable / 0.3.14 home). Colored by the caller.
- * Block elements (U+2580..259F) are one cell each; no emoji, no gradients.
+ * The home mark: a tornado drawn as five horizontal bars and one square tail,
+ * each an upper-half band (▀). One column is one bar-height wide; half-column
+ * ends use the upper quadrants (▝ ▘) so every edge lands where the source art
+ * puts it. Same X/width as the SVG, shifted up half a cell. Painted fg 77.
  */
-export const STORM_MARK = [
-    "▟██▛",
-    " ▜▙",
+export const TORNADO_LOGO = [
+    " ▀▀▀▀▀▀▀▀▀▀▘",
+    "▀▀▀▀▀▀▀▀▀   ",
+    " ▀▀▀▀▀▀     ",
+    "  ▝▀▀▀▀▀    ",
+    "    ▝▀▀▘    ",
+    "      ▀     ",
 ];
-/** Widest row of the mark, in cells (every mark glyph is single-cell). */
-export const STORM_MARK_WIDTH = Math.max(...STORM_MARK.map((line) => line.length));
-/** @deprecated Alias — the home panel uses {@link STORM_MARK}. */
-export const TORNADO_LOGO = STORM_MARK;
-/** @deprecated Alias. */
-export const TORNADO_LOGO_WIDTH = STORM_MARK_WIDTH;
-/** @deprecated Compact home is the full two-row mark. */
-export const TORNADO_LOGO_COMPACT = STORM_MARK;
+/** Single idle frame. Kept for callers that index frames. */
+export const TORNADO_FRAMES = [TORNADO_LOGO];
+/** Every sprite glyph is one column. */
+export const TORNADO_LOGO_WIDTH = Math.max(...TORNADO_LOGO.map((line) => [...line].length));
+export const TORNADO_LOGO_COMPACT = TORNADO_LOGO;
+/** @deprecated Use {@link TORNADO_LOGO}. */
+export const STORM_MARK = TORNADO_LOGO;
+/** @deprecated Use {@link TORNADO_LOGO_WIDTH}. */
+export const STORM_MARK_WIDTH = TORNADO_LOGO_WIDTH;
+/** Paint one sprite row: each run of glyphs in brand green 77, spaces left bare. */
+export function paintSpriteRow(row) {
+    return row.replace(/[^ ]+/g, (run) => ansi.brightGreen(run));
+}

package/dist/ui/prompt.d.ts

@@ -23,7 +23,7 @@ export interface AskLineOptions {
      * resize cannot desync CUU counts. Pass `true` for compact, `"mini"` /
      * `"nano"` for a short pane that still shows the mark.
      */
-    header?: (columns?: number, variant?: boolean | "mini" | "nano") => string[];
+    header?: (columns?: number, variant?: boolean | "mini" | "nano", frame?: number) => string[];
 }
 /** Thrown when the user asks to close the prompt (Ctrl+D empty, or Ctrl+C twice). */
 export declare class PromptClosedError extends Error {
@@ -47,6 +47,16 @@ export declare function promptClearOverlay(boxed: boolean): string;
  * frame's row count is unknowable after the terminal rewraps.
  */
 export declare const HEADER_REDRAW_PREFIX = "\u001B[H\u001B[0J";
+export declare const MOUSE_ENABLE = "\u001B[?1000h\u001B[?1006h";
+export declare const MOUSE_DISABLE = "\u001B[?1000l\u001B[?1006l";
+export type SpriteRect = {
+    col: number;
+    row: number;
+    width: number;
+    height: number;
+};
+/** SGR coordinates and the rectangle are both 1-based. */
+export declare function hitTestSprite(col: number, row: number, rect: SpriteRect): boolean;
 export declare const DROPDOWN_MAX_COMMAND_ROWS = 8;
 export declare function formatSlashLabel(spec: CommandSpec): string;
 export declare function specMatchesTerm(spec: CommandSpec, term: string): boolean;

package/dist/ui/prompt.js

@@ -1,3 +1,5 @@
+import { PassThrough } from "node:stream";
+import { StringDecoder } from "node:string_decoder";
 import * as readline from "node:readline";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
@@ -37,6 +39,13 @@ export function promptClearOverlay(boxed) {
  * frame's row count is unknowable after the terminal rewraps.
  */
 export const HEADER_REDRAW_PREFIX = `\u001b[H${clearDown}`;
+export const MOUSE_ENABLE = "\u001b[?1000h\u001b[?1006h";
+export const MOUSE_DISABLE = "\u001b[?1000l\u001b[?1006l";
+/** SGR coordinates and the rectangle are both 1-based. */
+export function hitTestSprite(col, row, rect) {
+    return col >= rect.col && col < rect.col + rect.width &&
+        row >= rect.row && row < rect.row + rect.height;
+}
 export const DROPDOWN_MAX_COMMAND_ROWS = 8;
 export function formatSlashLabel(spec) {
     const extra = spec.aliases?.length
@@ -171,9 +180,10 @@ export function fitHomeFrame(params) {
         : params.miniHeader?.length
             ? params.miniHeader
             : [];
+    const header = fallback.slice(0, Math.max(0, rows - 1));
     return {
-        header: fallback,
-        reserve: params.dockBottom ? Math.max(0, rows - fallback.length - 1) : 0,
+        header,
+        reserve: params.dockBottom ? Math.max(0, rows - header.length - 1) : 0,
         boxed: false,
         hasPrompt: false,
         hasHint: false,
@@ -338,7 +348,72 @@ export async function askLine(opts) {
         let exitHint = false;
         const ctrlCExit = new CtrlCExitGate();
         const wasRaw = Boolean(input.isRaw);
-        readline.emitKeypressEvents(input);
+        // Decode keys from a private stream after removing mouse reports. Readline
+        // otherwise emits the numeric tail of SGR reports as ordinary typing.
+        // Never listen for `keypress` on `input` itself: once any TUI has called
+        // emitKeypressEvents(stdin), stdin decodes keys too and every character
+        // (and every mouse report) would land in the buffer twice.
+        const keys = new PassThrough();
+        const decoder = new StringDecoder("utf8");
+        let pending = "";
+        let escapeTimer;
+        readline.emitKeypressEvents(keys);
+        keys.on("keypress", onKeypress);
+        function onData(chunk) {
+            if (finished)
+                return;
+            if (escapeTimer)
+                clearTimeout(escapeTimer);
+            pending += typeof chunk === "string" ? chunk : decoder.write(chunk);
+            while (pending && !finished) {
+                const start = pending.indexOf("\u001b");
+                if (start !== 0) {
+                    const end = start < 0 ? pending.length : start;
+                    const text = pending.slice(0, end);
+                    pending = pending.slice(end);
+                    keys.write(text);
+                    continue;
+                }
+                if (pending.startsWith("\u001b[M")) {
+                    if (pending.length < 6)
+                        return;
+                    pending = pending.slice(6);
+                    continue;
+                }
+                const mouse = /^\u001b\[<(\d+);(\d+);(\d+)([Mm])/.exec(pending);
+                if (mouse) {
+                    pending = pending.slice(mouse[0].length);
+                    continue;
+                }
+                const partialMouse = /^\u001b\[<\d*(?:;\d*){0,2}/.exec(pending);
+                if (partialMouse && pending.length > partialMouse[0].length) {
+                    pending = pending.slice(partialMouse[0].length);
+                    continue;
+                }
+                const csi = /^\u001b\[[0-?]*[ -/]*[@-~]/.exec(pending);
+                const ss3 = /^\u001bO[ -~]/.exec(pending);
+                if (csi || ss3) {
+                    const sequence = csi?.[0] ?? ss3[0];
+                    pending = pending.slice(sequence.length);
+                    keys.write(sequence);
+                    continue;
+                }
+                if (pending === "\u001b" ||
+                    /^\u001b(?:\[[0-?]*[ -/]*|O?)$/.test(pending)) {
+                    // Keep partial mouse reports across chunks. A lone Escape still works.
+                    if (!pending.startsWith("\u001b[<")) {
+                        escapeTimer = setTimeout(() => {
+                            const text = pending;
+                            pending = "";
+                            keys.write(text);
+                        }, 50);
+                    }
+                    return;
+                }
+                keys.write(pending[0]);
+                pending = pending.slice(1);
+            }
+        }
         input.setRawMode(true);
         input.resume();
         function currentDropdown() {
@@ -408,9 +483,8 @@ export async function askLine(opts) {
             // Never write more rows than the pane — that scrolls the welcome
             // tail (tips / what's new) into view and looks like a broken frame.
             if (frame.rows.length > roomRows) {
-                const keep = frame.rows.slice(frame.rows.length - roomRows);
-                const shift = frame.rows.length - keep.length;
-                frame.rows = keep;
+                const shift = frame.rows.length - roomRows;
+                frame.rows = frame.rows.slice(shift);
                 frame.inputRow = Math.max(0, frame.inputRow - shift);
             }
             // Home screen owns the pane: always origin + ED 0. Relative CUU after
@@ -442,7 +516,11 @@ export async function askLine(opts) {
             paint();
         }
         function cleanup() {
-            input.removeListener("keypress", onKeypress);
+            if (escapeTimer)
+                clearTimeout(escapeTimer);
+            input.removeListener("data", onData);
+            keys.removeListener("keypress", onKeypress);
+            keys.destroy();
             output.removeListener("resize", onResize);
             input.setRawMode(wasRaw);
             // emitKeypressEvents leaves stdin flowing; pause it so an idle shell
@@ -599,8 +677,13 @@ export async function askLine(opts) {
                 finish(null, err);
             }
         }
-        input.on("keypress", onKeypress);
+        input.on("data", onData);
         output.on("resize", onResize);
-        render();
+        try {
+            render();
+        }
+        catch (err) {
+            finish(null, err);
+        }
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mergestorm",
-  "version": "0.3.25",
+  "version": "0.3.26",
   "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

@@ -7,6 +7,10 @@ description: Watch stacks explicitly named by the human while Auto land is on, a
 
 Use only these shipped Mergestorm MCP tools: `stack_wait`, `stack_status`, `queue_status`. Use local checkout, test, and Git operations to make the patch. Auto land owns landing.
 
+## Not done until landed
+
+A stack watch is done only when the stack is landed, or when the human takes it back (archives the stack 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, so the obligation covers the whole stack, not the layer you touched. Every `stack_wait` and `stack_status` result carries `watch`: while `watch.done` is `false`, call `stack_wait` again with `watch.next.args` and do not end your task. `watch.done` is `true` only when the stack is landed, every PR is merged or closed with nothing left to land, the stack is archived, or it no longer exists (`reason` `not_found`: confirm the PRs merged before reporting it landed). Then stop.
+
 ## Scope and enrollment
 
 Watch only stacks the human named. If no unambiguous stack ID is available, ask the human to identify it; do not discover and enroll other stacks. Keep a separate cursor for each named stack.
@@ -15,9 +19,9 @@ Call `stack_status` with `stack_id`. Require that stack's `autoEnqueueWhenReady`
 
 ## Watch and patch
 
-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.
-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. 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, stop and report the reason. `queue_status` returning `queue_entry_not_found` is not a failure: an empty queue for the stack is a normal wait.
-3. 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. 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. While `busy[]` holds a PR it can hide a blocker no agent will clear, such as a Draft PR. If a hold looks stuck, refresh `stack_status` and tell the human. Do not turn Cyclone off, and do not turn Auto land off or on, to end the wait. If the remote head moves while you wait, stop and tell the human.
+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. 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`, `tempest_pending`, `tempest_running`, 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, never `mg-park-*`) and the conflicted `files`; a null `liveParent` means stop and tell the human. For `ci_failure` it names the failing check. `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. 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. While `busy[]` holds a PR it can hide a blocker no agent will clear, such as a Draft PR. If a hold looks stuck, refresh `stack_status` and tell the human. Do not turn Cyclone off, and do not turn Auto land off or on, to end the wait. 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. Otherwise prefer merging that live parent into the PR branch, resolving locally, then an ordinary push. Never use Dashboard Continue. 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 — U<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. On `Seam review failed`, do not patch; tell the human, unless a new push already has a seam re-review held in `busy[]`.
 6. Recheck Auto land and the remote PR head (`git ls-remote origin refs/heads/<branch>`) immediately before pushing. 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.