mergestorm 0.3.24 → 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.24                                                     │
-│  ▜▙   ● 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.24: mg settings --auto-land-settle (15-300 seconds)       │
+│  ▀▀▀▀▀▀▀▀▀▀▘  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

@@ -5,6 +5,7 @@ export { CommandError, DetachedError, RATE_LIMITED_HINT, REVIEW_EXIT, isCommandE
 export { REVIEW_POLL_BACKOFF_MS, REVIEW_POLL_DEFAULT_TIMEOUT_MS, REVIEW_POLL_INTERVAL_MS, REVIEW_POLL_MAX_INTERVAL_MS, REVIEW_POLL_MAX_TRANSIENT_RETRIES, REVIEW_POLL_STRETCH_AFTER_MS, REVIEW_POLL_STRETCH_SPAN_MS, REVIEW_THREAD_SLUG_RE, PrReviewPollTimeoutError, ReviewPollTimeoutError, collectReviewInput, formatReviewSubmitError, isTransientReviewPollError, isTransientReviewPollStatus, loadReviewContext, pollPrVortexReview, pollReview, stretchedPollIntervalMs, submitReview, transientRetryWaitMs, type PollReviewOptions, type PollPrVortexReviewOptions, type ReviewInput, type SubmitReviewOptions, } from "../commands/review-client.js";
 export { REVIEW_JOB_ENVELOPE_SCHEMA, toReviewJobEnvelope, type ReviewEnvelopeFallbacks, type ReviewJobEnvelope, type ReviewJobRow, } from "../ui/job-envelope.js";
 export { discoverTrunk } from "../git-stack.js";
-export { BOUNCE_KIND_LABELS, mergeQueueBounceLabel } from "../stack-dto.js";
-export { STACK_WATCH_SCHEMA, STACK_WATCH_DEFAULT_TIMEOUT_MS, StackWatchError, StackWatchTimeoutError, pollStackWatch, type PollStackWatchOptions, type StackWatchCursor, type StackWatchEnvelope, } from "../stack-watch.js";
-export { stackBlockers, stackBlockersSummary, sameHead, type StackBlocker } from "../stack-blockers.js";
+export { BOUNCE_KIND_LABELS, deriveStackAgentsBusy, mergeQueueBounceLabel, type StackAgentsBusy } from "../stack-dto.js";
+export { STACK_WATCH_SCHEMA, STACK_WATCH_DEFAULT_TIMEOUT_MS, STACK_WATCH_BUSY_RECHECK_S, StackWatchError, StackWatchTimeoutError, pollStackWatch, type PollStackWatchOptions, type StackWatchCursor, type StackWatchEnvelope, } from "../stack-watch.js";
+export { stackBlockers, stackBlockersSummary, sameHead, layerAgents, layerAgentsBusy, conflictLiveParent, stackRepair, 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

@@ -5,6 +5,7 @@ export { CommandError, DetachedError, RATE_LIMITED_HINT, REVIEW_EXIT, isCommandE
 export { REVIEW_POLL_BACKOFF_MS, REVIEW_POLL_DEFAULT_TIMEOUT_MS, REVIEW_POLL_INTERVAL_MS, REVIEW_POLL_MAX_INTERVAL_MS, REVIEW_POLL_MAX_TRANSIENT_RETRIES, REVIEW_POLL_STRETCH_AFTER_MS, REVIEW_POLL_STRETCH_SPAN_MS, REVIEW_THREAD_SLUG_RE, PrReviewPollTimeoutError, ReviewPollTimeoutError, collectReviewInput, formatReviewSubmitError, isTransientReviewPollError, isTransientReviewPollStatus, loadReviewContext, pollPrVortexReview, pollReview, stretchedPollIntervalMs, submitReview, transientRetryWaitMs, } from "../commands/review-client.js";
 export { REVIEW_JOB_ENVELOPE_SCHEMA, toReviewJobEnvelope, } from "../ui/job-envelope.js";
 export { discoverTrunk } from "../git-stack.js";
-export { BOUNCE_KIND_LABELS, mergeQueueBounceLabel } from "../stack-dto.js";
-export { STACK_WATCH_SCHEMA, STACK_WATCH_DEFAULT_TIMEOUT_MS, StackWatchError, StackWatchTimeoutError, pollStackWatch, } from "../stack-watch.js";
-export { stackBlockers, stackBlockersSummary, sameHead } from "../stack-blockers.js";
+export { BOUNCE_KIND_LABELS, deriveStackAgentsBusy, mergeQueueBounceLabel } from "../stack-dto.js";
+export { STACK_WATCH_SCHEMA, STACK_WATCH_DEFAULT_TIMEOUT_MS, STACK_WATCH_BUSY_RECHECK_S, StackWatchError, StackWatchTimeoutError, pollStackWatch, } from "../stack-watch.js";
+export { stackBlockers, stackBlockersSummary, sameHead, layerAgents, layerAgentsBusy, conflictLiveParent, stackRepair, } from "../stack-blockers.js";
+export { STACK_WATCH_NOT_DONE_SENTENCE, stackTerminalReason, stackWatchNextArgs, stackWatchObligation, } from "../stack-watch-obligation.js";

package/dist/commands/queue.js

@@ -144,8 +144,12 @@ async function removeQueue(args, asJson) {
         console.log(JSON.stringify(body, null, 2));
         return;
     }
+    const cancelRequested = typeof body === "object" && body !== null &&
+        body.cancelRequested === true;
     await present("Merge queue", [
-        ansi.brightGreen(`  Removed ${entryId} from the merge queue`),
+        cancelRequested
+            ? ansi.brightGreen(`  Cancel requested for ${entryId}: it is merging, and the queue cancels it before the merge call unless the merge already started`)
+            : ansi.brightGreen(`  Removed ${entryId} from the merge queue`),
     ]);
 }
 export async function cmdQueue(args, deps = {}) {

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.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

@@ -1,4 +1,4 @@
-import { type MergeQueueEntryDto, type StackDto, type StackLayerDto } from "./stack-dto.js";
+import { type MergeQueueEntryDto, type StackAgentsBusy, type StackDto, type StackLayerDto } from "./stack-dto.js";
 import type { StackWatchCursor } from "./stack-watch.js";
 export type StackBlocker = {
     prNumber: number;
@@ -6,11 +6,59 @@ export type StackBlocker = {
     blocker: string;
     bounceKind: string | null;
 };
+export type StackAgentBusy = {
+    prNumber: number;
+    headSha: string | null;
+    agent: "vortex" | "cyclone";
+    blocker: string;
+};
+export type StackLayerAgents = {
+    prNumber: number;
+    headSha: string | null;
+    vortexStatus: StackLayerDto["vortexStatus"];
+    cycloneStatus: StackLayerDto["cycloneStatus"];
+    vortexReview: {
+        status: string;
+        headSha: string | null;
+        pass: number | null;
+    } | null;
+    busy: {
+        vortex: boolean;
+        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;
 /** GitHub DIRTY vs an mg-park-* freeze is not a merge conflict, verified or not. */
 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;
@@ -20,6 +68,10 @@ export declare function stackBlockers(stack: StackDto, entries?: MergeQueueEntry
         headSha: string | null;
     } | null;
     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[]): 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,23 @@
-import { mergeQueueBounceLabel, restackRetryPending } from "./stack-dto.js";
+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);
+}
+export function layerAgents(layer) {
+    const busy = layerAgentsBusy(layer);
+    const review = layer.vortexReview;
+    return {
+        prNumber: layer.prNumber,
+        headSha: layer.headSha ?? null,
+        vortexStatus: layer.vortexStatus ?? null,
+        cycloneStatus: layer.cycloneStatus ?? null,
+        vortexReview: review ? { status: review.status, headSha: review.head_sha, pass: review.pass } : null,
+        busy: { vortex: busy.vortex, cyclone: busy.cyclone },
+    };
+}
 export function isMgParkBase(branch) {
     return (branch ?? "").trim().toLowerCase().startsWith("mg-park-");
 }
@@ -26,6 +45,22 @@ export function currentLayer(stack) {
     return promote[0] ?? open.find((layer) => layer.prNumber === stack.unit?.landPrNumber) ??
         (land && land.prNumber > 0 && land.state !== "merged" && land.state !== "closed" ? land : undefined);
 }
+function seamGateBlocker(stack, layer) {
+    const members = stack.unit?.members ?? [];
+    if (layer.prNumber === stack.unit?.landPrNumber)
+        return null;
+    if (!members.some((member) => member.promotedHeadSha?.trim()))
+        return null;
+    const member = members.find((entry) => entry.prNumber === layer.prNumber);
+    if (!member || member.promotedHeadSha?.trim())
+        return null;
+    const seamState = member.seamState?.trim().toLowerCase();
+    if (seamState === "failed")
+        return "Seam review failed";
+    if (seamState === "findings" && sameHead(member.seamReviewedSha, layer.headSha))
+        return "Seam findings";
+    return null;
+}
 /** Shared live-fact precedence; bounce history is only passed for the candidate. */
 function layerAttention(stack, layer, queue, cursor) {
     const none = { blocker: null, bounceKind: null };
@@ -63,9 +98,13 @@ function layerAttention(stack, layer, queue, cursor) {
             return hardBlock(`Tempest ${tempest.status}`);
         if (layer.vortexStatus === "failed")
             return hardBlock("Review failed");
+        const seam = seamGateBlocker(stack, layer);
+        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");
         }
@@ -81,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);
@@ -94,6 +201,7 @@ export function stackBlockers(stack, entries = [], cursor = {}) {
         (boundDirty(layer) || layer.state === "conflict" ||
             (layer.state !== "restacking" && layer.restackError?.kind === "rebase_conflict"))).sort((a, b) => a.position - b.position)[0];
     let attention = null;
+    let attentionLayer;
     let bounce;
     const issues = [];
     for (const layer of open) {
@@ -105,16 +213,41 @@ export function stackBlockers(stack, entries = [], cursor = {}) {
             blocker: result.blocker, bounceKind: result.bounceKind };
         if (selected || (!attention && layer === child)) {
             attention = issue;
+            attentionLayer = layer;
             bounce = result.bounce;
         }
         else if (!candidate || layer.position > candidate.position)
             issues.push(issue);
     }
-    return { attention, issues, currentCandidate, bounce };
+    const focus = attentionLayer ?? candidate;
+    const agents = focus ? layerAgents(focus) : null;
+    const busy = [];
+    if (attention && agents) {
+        for (const agent of ["cyclone", "vortex"]) {
+            if (agents.busy[agent])
+                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, 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) {
+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 + (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;
@@ -98,6 +102,16 @@ export type StackAgentRun = {
         total: number;
     } | null;
 };
+export type StackAgentsBusy = {
+    vortex: boolean;
+    cyclone: boolean;
+    headSha: string | null;
+};
+export declare const STACK_AGENT_QUEUED_STALE_MS: number;
+export declare function deriveStackAgentsBusy(layer: Pick<StackLayerDto, "headSha" | "vortexStatus" | "cycloneStatus" | "agentRuns" | "vortexReview">, opts?: {
+    cycloneClaimed?: boolean;
+    nowMs?: number;
+}): StackAgentsBusy;
 export type StackLayerChecks = {
     total: number;
     success: number;
@@ -182,6 +196,7 @@ export type StackLayerDto = {
      * detail once it says `done`. Undefined = producer predates the viewer.
      */
     vortexReview?: StackVortexReviewView;
+    agentsBusy?: StackAgentsBusy | null;
     conflictDetail: string | null;
     restackError?: RestackError | null;
     lastRestackedSha: string | null;
@@ -357,6 +372,7 @@ export type MergeQueueBounceDetail = {
     failingCheck?: string;
     conflictBranch?: string;
     conflictDetail?: string;
+    conflictPaths?: string[];
     message?: string;
 };
 export type MergeQueueEntryDto = {
@@ -379,5 +395,6 @@ export type MergeQueueEntryDto = {
     verifyHeadSha: string | null;
     /** Target tip included in the verified PR head. Null until recorded. */
     verifyBaseSha: string | null;
+    cancelRequestedAt?: string | null;
     finishedAt: string | null;
 };

package/dist/stack-dto.js

@@ -16,6 +16,33 @@ export function restackRetryPending(error, layer) {
         return false;
     return !/\(origin\/\S+ moved to /.test(error.detail) && pushRejectionIsRetryable(error.detail);
 }
+export const STACK_AGENT_QUEUED_STALE_MS = 15 * 60 * 1000;
+function agentShaMayBeHead(sha, head) {
+    const left = sha?.trim().toLowerCase();
+    const right = head?.trim().toLowerCase();
+    if (!left || !right)
+        return false;
+    return left.startsWith(right) || right.startsWith(left);
+}
+export function deriveStackAgentsBusy(layer, opts = {}) {
+    const headSha = layer.headSha?.trim() || null;
+    const nowMs = opts.nowMs ?? Date.now();
+    const runs = (layer.agentRuns ?? []).filter((run) => !run.finishedAt);
+    const vortexRuns = runs.filter((run) => run.agent === "vortex" && agentShaMayBeHead(run.sha, headSha));
+    const freshQueued = vortexRuns.some((run) => {
+        const queuedAt = Date.parse(run.startedAt ?? "");
+        return run.status === "queued" && Number.isFinite(queuedAt) && nowMs - queuedAt <= STACK_AGENT_QUEUED_STALE_MS;
+    });
+    const review = layer.vortexReview;
+    const reviewOnHead = !!review && agentShaMayBeHead(review.head_sha, headSha);
+    const vortex = (reviewOnHead && review.status === "reviewing") ||
+        vortexRuns.some((run) => run.status === "reviewing") ||
+        freshQueued ||
+        (layer.agentRuns === undefined && review === undefined && layer.vortexStatus === "reviewing");
+    const cyclone = opts.cycloneClaimed === true || layer.cycloneStatus === "patching" ||
+        runs.some((run) => run.agent === "cyclone" && run.status === "patching");
+    return { vortex, cyclone, headSha };
+}
 /** Every bounce kind understood by the shared contract. */
 export const MERGE_QUEUE_BOUNCE_KINDS = [
     "ci_failure",
@@ -47,6 +74,7 @@ export function mergeQueueBounceLabel(entry) {
     if (kindLabel) {
         const specifics = detail?.failingCheck ??
             detail?.conflictBranch ??
+            (detail?.conflictPaths?.length ? detail.conflictPaths.join(", ") : null) ??
             detail?.message ??
             (detail?.prNumber != null ? `PR #${detail.prNumber}` : null);
         return specifics ? `${kindLabel} — ${specifics}` : kindLabel;