mergestorm 0.3.18 → 0.3.19

package/dist/commands/skill.js

@@ -7,14 +7,16 @@ import { gitTopLevel } from "../repo-identity.js";
 import { present } from "../ui/present.js";
 export const SKILL_NAME = "mergestorm-review";
 export const PR_LOOP_SKILL_NAME = "mergestorm-pr-loop";
-export const SKILL_NAMES = [SKILL_NAME, PR_LOOP_SKILL_NAME];
+export const BOUNCE_WATCH_SKILL_NAME = "mergestorm-bounce-watch";
+export const SKILL_NAMES = [SKILL_NAME, PR_LOOP_SKILL_NAME, BOUNCE_WATCH_SKILL_NAME];
 export const SKILL_USAGE = `usage:
-  mergestorm skill install --claude|--cursor [--json]
+  mergestorm skill install --claude|--cursor|--agents [--json]
 
-  Copies mergestorm-review and mergestorm-pr-loop into this repo (git toplevel, else cwd):
+  Copies ${SKILL_NAMES.join(", ")} into this repo (git toplevel, else cwd):
     --claude  .claude/skills/<name>/SKILL.md
     --cursor  .cursor/skills/<name>/SKILL.md
-  Pass both flags to write both trees. Overwrites existing copies.`;
+    --agents  .agents/skills/<name>/SKILL.md
+  Pass multiple flags to write multiple trees. Overwrites existing copies.`;
 export function parseSkillArgs(args) {
     const [sub, ...rest] = args;
     if (!sub || sub === "-h" || sub === "--help" || sub === "help") {
@@ -40,13 +42,18 @@ export function parseSkillArgs(args) {
                 targets.push("cursor");
             continue;
         }
+        if (arg === "--agents") {
+            if (!targets.includes("agents"))
+                targets.push("agents");
+            continue;
+        }
         if (arg === "-h" || arg === "--help" || arg === "help") {
             return { help: true, json: false, targets: [] };
         }
         throw new CommandError(`${SKILL_USAGE}\nunknown flag: ${arg}`, 1, "usage");
     }
     if (targets.length === 0) {
-        throw new CommandError(`${SKILL_USAGE}\npass --claude and/or --cursor`, 1, "usage");
+        throw new CommandError(`${SKILL_USAGE}\npass --claude, --cursor, and/or --agents`, 1, "usage");
     }
     return { help: false, json, targets };
 }
@@ -65,6 +72,9 @@ export function skillDestination(root, target, name = SKILL_NAME) {
     if (target === "claude") {
         return path.join(root, ".claude", "skills", name, "SKILL.md");
     }
+    if (target === "agents") {
+        return path.join(root, ".agents", "skills", name, "SKILL.md");
+    }
     return path.join(root, ".cursor", "skills", name, "SKILL.md");
 }
 export function resolveBundledSkillPath(fromFile = import.meta.url, name = SKILL_NAME) {
@@ -90,7 +100,7 @@ export function resolveBundledSkillPath(fromFile = import.meta.url, name = SKILL
 }
 async function assertNoSymlink(dest) {
     const parts = dest.split(path.sep);
-    const marker = parts.findIndex((p) => p === ".claude" || p === ".cursor");
+    const marker = parts.findIndex((p) => p === ".claude" || p === ".cursor" || p === ".agents");
     const first = marker === -1 ? parts.length - 1 : marker;
     for (let i = first; i < parts.length; i++) {
         const candidate = parts.slice(0, i + 1).join(path.sep);

package/dist/commands/stack.d.ts

@@ -1,4 +1,4 @@
-import { adoptStack, ensureUpperPark, listStacks, setStackPolicy, type StackDto, type StackPolicyPatch } from "../api.js";
+import { adoptStack, ensureUpperPark, getEnrichedStack, listStacks, setStackPolicy, type StackDto, type StackPolicyPatch } from "../api.js";
 import { loadConfig } from "../config.js";
 import { createPr, findOpenPrNumber } from "../gh.js";
 import { parseGithubOriginRepo } from "../git.js";
@@ -6,6 +6,7 @@ import { branchExists, commitsAheadOf, createBranchFromHead, currentBranch, defa
 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";
 /** A registered stack layer that would become the parent of a new layer. */
 export type RegisteredParentHit = {
     stackId: string;
@@ -120,6 +121,15 @@ export type StackSubmitDeps = {
     ensureUpperPark?: typeof ensureUpperPark;
 };
 export declare function cmdStackSubmit(args: string[], deps?: StackSubmitDeps): Promise<void>;
+export declare function cmdStackWait(args: string[], deps?: {
+    loadConfig?: typeof loadConfig;
+    pollStackWatch?: typeof pollStackWatch;
+    signal?: AbortSignal;
+}): Promise<void>;
+export declare function cmdStackStatus(args: string[], deps?: {
+    loadConfig?: typeof loadConfig;
+    getEnrichedStack?: typeof getEnrichedStack;
+}): Promise<void>;
 export type StackSetDeps = {
     loadConfig?: typeof loadConfig;
     setStackPolicy?: typeof setStackPolicy;
@@ -127,4 +137,6 @@ export type StackSetDeps = {
 /** Human summary lines for a `stack set` write, one per flag. */
 export declare function stackSetSummary(parsed: StackSetArgs): string[];
 export declare function cmdStackSet(args: string[], deps?: StackSetDeps): Promise<void>;
-export declare function cmdStack(args: string[]): Promise<void>;
+export declare function cmdStack(args: string[], options?: {
+    signal?: AbortSignal;
+}): Promise<void>;

package/dist/commands/stack.js

@@ -1,12 +1,13 @@
-import { adoptStack, ensureUpperPark, landNextStack, listStacks, restackStack, setStackPolicy, } from "../api.js";
+import { adoptStack, ensureUpperPark, getEnrichedStack, landNextStack, listStacks, restackStack, setStackPolicy, } from "../api.js";
 import { loadConfig } from "../config.js";
-import { CommandError } from "../errors.js";
+import { rateLimitedMessage, REVIEW_EXIT, CommandError } from "../errors.js";
 import { createPr, findOpenPrNumber, requireGh } from "../gh.js";
 import { parseGithubOriginRepo } from "../git.js";
 import { branchExists, commitsAheadOf, createBranchFromHead, currentBranch, defaultLayerBranchName, deleteBranch, discoverTrunk, fetchRemoteBranch, pushBranch, tipCommitMessage, tipCommitSubject, worktreeDirty, } from "../git-stack.js";
 import { buildPrBodyFromCommit } from "../pr-body.js";
 import { gitTopLevel } from "../repo-identity.js";
 import { activeLayers, appendLayer, emptyStackMeta, loadStackMeta, removeActiveStack, resetStackMeta, saveStackMeta, selectStackForCreate, setActivePolicy, } from "../stack-meta.js";
+import { pollStackWatch, StackWatchError, StackWatchTimeoutError, } from "../stack-watch.js";
 import { isMgParkBranch, planSubmitLayerBases } from "../submit-pr-base.js";
 import { ansi } from "../ui/ansi.js";
 import { runLineTabsBrowser } from "../ui/line-tabs.js";
@@ -18,6 +19,8 @@ const STACK_USAGE = `usage:
   mergestorm stack submit [--extend] [--auto-land on|off] [--auto-review on|off] [--auto-patch on|off] [--json]
   mergestorm stack reset --force
   mergestorm stack list [--json]
+  mergestorm stack status <stack-id> [--json]
+  mergestorm stack wait <stack-id> [--json] [--timeout <s>]
   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]
@@ -143,7 +146,7 @@ export function stackPolicyLabels(s) {
     }
     return labels;
 }
-function formatStackHuman(s) {
+function formatStackHuman(s, includeLayers = true) {
     const lines = [];
     lines.push(`  ${ansi.bold(`${s.owner}/${s.repo}`)}  trunk=${s.trunkBranch}` +
         stackPolicyLabels(s)
@@ -154,6 +157,8 @@ function formatStackHuman(s) {
         lines.push(ansi.dim("    (no layers)"));
         return lines;
     }
+    if (!includeLayers)
+        return lines;
     for (const layer of s.layers) {
         const title = layer.title ? ` ${layer.title}` : "";
         const pr = layer.prNumber > 0 ? `#${layer.prNumber}` : "—";
@@ -787,6 +792,82 @@ async function cmdStackList(args) {
     listed.push(ansi.dim("  Dashboard: https://mergestorm.ai/dashboard"));
     await present("Stacks", listed);
 }
+export async function cmdStackWait(args, deps = {}) {
+    const usage = "usage: mergestorm stack wait <stack-id> [--json] [--timeout <s>]";
+    const positional = [];
+    let timeoutS = 45;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            continue;
+        if (arg === "--timeout" || arg.startsWith("--timeout=")) {
+            const value = arg === "--timeout" ? args[++i] : arg.slice("--timeout=".length);
+            timeoutS = value?.trim() ? Number(value) : NaN;
+            if (!Number.isFinite(timeoutS) || timeoutS < 0 || timeoutS > 300) {
+                throw new CommandError(`${usage}\n--timeout must be between 0 and 300 seconds`, REVIEW_EXIT.usage, "usage");
+            }
+        }
+        else if (arg.startsWith("-")) {
+            throw new CommandError(usage, REVIEW_EXIT.usage, "usage");
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    if (positional.length !== 1)
+        throw new CommandError(usage, REVIEW_EXIT.usage, "usage");
+    const stackId = requireStackId(positional[0], usage);
+    const cfg = await (deps.loadConfig ?? loadConfig)();
+    const print = (envelope, retryAfterSeconds) => console.log(args.includes("--json")
+        ? JSON.stringify({
+            ...envelope,
+            ...(retryAfterSeconds !== undefined ? { retry_after_seconds: retryAfterSeconds } : {}),
+        }, null, 2)
+        : `Stack ${envelope.stackId} · ${envelope.status}${envelope.blocker ? ` · ${envelope.blocker}` : ""}`);
+    try {
+        print(await (deps.pollStackWatch ?? pollStackWatch)(cfg, stackId, {
+            timeoutMs: timeoutS * 1000,
+            signal: deps.signal,
+        }));
+    }
+    catch (err) {
+        if (err instanceof StackWatchError && err.lastEnvelope.status === "rate_limited") {
+            print(err.lastEnvelope, err.retryAfterSeconds);
+            throw new CommandError(rateLimitedMessage(err.retryAfterSeconds), REVIEW_EXIT.rate_limited, "rate_limited", { retryAfterSeconds: err.retryAfterSeconds });
+        }
+        if (!(err instanceof StackWatchTimeoutError))
+            throw err;
+        print(err.lastEnvelope);
+        throw new CommandError(err.message, REVIEW_EXIT.timeout, "review_timeout");
+    }
+}
+export async function cmdStackStatus(args, deps = {}) {
+    const usage = "usage: mergestorm stack status <stack-id> [--json]";
+    const positional = args.filter((arg) => arg !== "--json");
+    if (positional.length !== 1)
+        throw new CommandError(usage, 2, "usage");
+    const stackId = requireStackId(positional[0], usage);
+    const cfg = await (deps.loadConfig ?? loadConfig)();
+    const stack = await (deps.getEnrichedStack ?? getEnrichedStack)(stackId, cfg);
+    if (!stack) {
+        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));
+        return;
+    }
+    const lines = formatStackHuman(stack, false);
+    for (const layer of stack.layers) {
+        const head = layer.headSha ? `@${layer.headSha.slice(0, 7)}` : "";
+        const pr = layer.prNumber > 0 ? `#${layer.prNumber}` : "—";
+        lines.push(`    ${String(layer.position).padStart(2)}  ${pr}${head}  ${layer.state.padEnd(14)}  ${layer.branch}` +
+            `  CI: ${layer.ciStatus ?? "unknown"}  review: ${layer.reviewStatus ?? "unknown"}` +
+            (layer.vortexStatus ? `  Vortex: ${layer.vortexStatus}` : "") +
+            (layer.cycloneStatus ? `  Cyclone: ${layer.cycloneStatus}` : "") +
+            (layer.tempestStatus ? `  Tempest: ${layer.tempestStatus}` : ""));
+    }
+    await present("Stack status", lines);
+}
 /** Human summary lines for a `stack set` write, one per flag. */
 export function stackSetSummary(parsed) {
     const tri = (value) => value === null ? "default (account setting)" : value ? "on" : "off";
@@ -885,7 +966,7 @@ async function cmdStackLand(args) {
             ` on ${id}`),
     ]);
 }
-export async function cmdStack(args) {
+export async function cmdStack(args, options = {}) {
     const sub = args[0]?.toLowerCase();
     const rest = args.slice(1);
     // Help must exit 0 — print usage, do not throw CommandError.
@@ -905,6 +986,10 @@ export async function cmdStack(args) {
         return cmdStackReset(rest);
     if (sub === "list" || sub === "ls")
         return cmdStackList(rest);
+    if (sub === "status")
+        return cmdStackStatus(rest);
+    if (sub === "wait")
+        return cmdStackWait(rest, { signal: options.signal });
     if (sub === "set")
         return cmdStackSet(rest);
     if (sub === "adopt")

package/dist/errors.d.ts

@@ -2,7 +2,7 @@
  * Stable machine codes for CommandError control flow.
  * UX copy in `message` may change freely; match on `code`, never on message text.
  */
-export type CommandErrorCode = "auth_invalid" | "api_timeout" | "not_a_repo" | "not_found" | "missing_api_key" | "registered_parent" | "usage" | "review_quota" | "review_failed" | "review_timeout" | "rate_limited";
+export type CommandErrorCode = "auth_invalid" | "api_timeout" | "not_a_repo" | "not_found" | "missing_api_key" | "registered_parent" | "usage" | "review_quota" | "review_failed" | "review_timeout" | "rate_limited" | "cyclone_not_installed" | "pr_merged" | "pr_closed" | "not_stacked" | "draft" | "reserved_branch" | "supabase_unconfigured" | "cyclone_not_connected" | "busy" | "adopt_failed";
 /** Stable one-shot exit codes for machine callers of `mergestorm review`. */
 export declare const REVIEW_EXIT: {
     readonly success: 0;

package/dist/stack-dto.d.ts

@@ -21,6 +21,31 @@ export type StackReviewStatus = "approved" | "changes_requested" | "reviewed" |
  * (#1947): Work paints Incomplete, never Reviewed or all clear.
  */
 export type StackVortexStatus = "queued" | "skipped" | "reviewing" | "seam_pending" | "all_clear" | "findings" | "throttled" | "failed" | "incomplete";
+/**
+ * MS-14 viewer: the one lifecycle status of the Vortex review on a PR head.
+ * `pr_reviews` is the authority when a row exists for the SHA; a leftover
+ * `github_webhook_jobs` row paints `queued` / `reviewing` only when no pass row
+ * exists yet. `none` = never dispatched. `done` = a pass posted; the finer
+ * verdict detail lives on `vortexStatus` / `agentRuns`.
+ */
+export type StackVortexReviewViewStatus = "none" | "queued" | "reviewing" | "skipped" | "done" | "failed";
+export type StackVortexReviewView = {
+    status: StackVortexReviewViewStatus;
+    /** `pr_reviews.skip_reason` for `skipped`; null when the writer recorded none. */
+    skip_reason: string | null;
+    /** SHA + pass identity of the attempt (#2027); null before a pass row exists. */
+    pass: number | null;
+    /** Head the status speaks for; null when neither table named one. */
+    head_sha: string | null;
+    /** In-flight sub-state while `reviewing` (fanout / synthesizing). */
+    phase: string | null;
+    /** Earliest live job start while `reviewing`; null when lease-only. */
+    started_at: string | null;
+    /** Stop control visibility: true only while a pass can actually be cancelled. */
+    stoppable: boolean;
+    /** Which table spoke: the authority row, a live job, a lease, or nothing. */
+    source: "pr_reviews" | "github_webhook_jobs" | "lease" | "none";
+};
 export type StackCycloneStatus = "patching" | "awaiting_fix";
 export type StackTempestStatus = "reviewing" | "findings" | "clear" | "failed" | "stale";
 export type StackAgentName = "vortex" | "cyclone" | "tempest";
@@ -140,6 +165,12 @@ export type StackLayerDto = {
      * Undefined = producer predates runs (clients fall back to the rollup).
      */
     agentRuns?: StackAgentRun[];
+    /**
+     * MS-14 viewer output for this layer's head. Every surface renders the
+     * lifecycle status from here; `vortexStatus` / `agentRuns` only add verdict
+     * detail once it says `done`. Undefined = producer predates the viewer.
+     */
+    vortexReview?: StackVortexReviewView;
     conflictDetail: string | null;
     restackError?: RestackError | null;
     lastRestackedSha: string | null;
@@ -249,6 +280,21 @@ export type StackDto = {
      * Missing on older payloads is off.
      */
     autoEnqueueWhenReady?: boolean;
+    /**
+     * Auto land Settling certificate. The stacks watcher publishes the identity
+     * of the settle clock it actually started (action, exact PR and head, server
+     * start time) and clears it when that clock is consumed or invalidated.
+     * Absent (older payloads) or `null` means no certified settle: paint nothing.
+     * Remaining time derives from `startedAt`; a refresh never restarts it.
+     * Partial or invalid server rows map to `null`, never to a guessed value.
+     */
+    autoEnqueueSettle?: {
+        action: "ready" | "promote";
+        prNumber: number;
+        headSha: string;
+        /** ISO timestamp of the watcher's clock start. */
+        startedAt: string;
+    } | null;
     /**
      * Per-stack Vortex auto-review override. `null` (or missing) follows the
      * account `auto_review_enabled` flag; a boolean wins in both directions.
@@ -286,7 +332,11 @@ export type StackDto = {
 export type MergeQueueEntryState = "queued" | "running" | "waiting" | "landed" | "bounced" | "cancelled";
 export type MergeQueueEnqueuedBy = "human" | "agent";
 export type MergeQueueEnqueuedVia = "dashboard" | "cli" | "chat" | "api" | "mcp";
-export type MergeQueueBounceKind = "ci_failure" | "ci_timeout" | "head_moved" | "tempest_findings" | "seam_findings" | "restack_conflict" | "pr_draft" | "merge_failed" | "gh_error";
+export type MergeQueueBounceKind = "ci_failure" | "ci_timeout" | "head_moved" | "tempest_findings" | "seam_findings" | "restack_conflict" | "pr_draft" | "must_consolidate" | "merge_failed" | "gh_error";
+/** Every bounce kind understood by the shared contract. */
+export declare const MERGE_QUEUE_BOUNCE_KINDS: readonly ["ci_failure", "ci_timeout", "head_moved", "tempest_findings", "seam_findings", "restack_conflict", "pr_draft", "must_consolidate", "merge_failed", "gh_error"];
+export declare const BOUNCE_KIND_LABELS: Readonly<Record<MergeQueueBounceKind, string>>;
+export declare function mergeQueueBounceLabel(entry: MergeQueueEntryDto): string;
 /** Structured bounce handoff — enough for the bar chip and the chat quote. */
 export type MergeQueueBounceDetail = {
     kind: MergeQueueBounceKind;

package/dist/stack-dto.js

@@ -1 +1,37 @@
-export {};
+/** Every bounce kind understood by the shared contract. */
+export const MERGE_QUEUE_BOUNCE_KINDS = [
+    "ci_failure",
+    "ci_timeout",
+    "head_moved",
+    "tempest_findings",
+    "seam_findings",
+    "restack_conflict",
+    "pr_draft",
+    "must_consolidate",
+    "merge_failed",
+    "gh_error",
+];
+export const BOUNCE_KIND_LABELS = {
+    ci_failure: "CI failed",
+    ci_timeout: "CI timed out",
+    head_moved: "head moved",
+    tempest_findings: "Tempest findings",
+    seam_findings: "seam review findings",
+    restack_conflict: "restack conflict",
+    pr_draft: "draft PR",
+    must_consolidate: "needs promote",
+    merge_failed: "merge failed",
+    gh_error: "GitHub error",
+};
+export function mergeQueueBounceLabel(entry) {
+    const detail = entry.bounceDetail;
+    const kindLabel = detail ? BOUNCE_KIND_LABELS[detail.kind] : undefined;
+    if (kindLabel) {
+        const specifics = detail?.failingCheck ??
+            detail?.conflictBranch ??
+            detail?.message ??
+            (detail?.prNumber != null ? `PR #${detail.prNumber}` : null);
+        return specifics ? `${kindLabel} — ${specifics}` : kindLabel;
+    }
+    return entry.bounceReason?.trim() || "bounced";
+}

package/dist/stack-watch.d.ts

@@ -0,0 +1,44 @@
+import { apiFetch } from "./api.js";
+import type { Config } from "./config.js";
+export declare const STACK_WATCH_SCHEMA: "mergestorm.stack_watch/v1";
+export declare const STACK_WATCH_DEFAULT_TIMEOUT_MS = 45000;
+/** Resume selectors are fixed for the entire wait, including transient retries. */
+export type StackWatchCursor = {
+    readonly stackId: string;
+    readonly enrolledHeadSha: string | null;
+    readonly afterFinishedAt?: string | null;
+    readonly bounceId?: string | null;
+};
+export type StackWatchEnvelope = {
+    schema: typeof STACK_WATCH_SCHEMA;
+    status: "attention" | "waiting" | "in_progress" | "rate_limited" | "failed";
+    stackId: string;
+    blocker: string | null;
+    bounceKind: string | null;
+    prNumber: number | null;
+    headSha: string | null;
+    cursor: StackWatchCursor;
+};
+export type PollStackWatchOptions = {
+    timeoutMs?: number;
+    intervalMs?: number;
+    cursor?: StackWatchCursor;
+    signal?: AbortSignal;
+    onTick?: (envelope: StackWatchEnvelope) => void;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    now?: () => number;
+    random?: () => number;
+    /** Test seam at the apiFetch boundary, including HTTP status and Retry-After. */
+    fetch?: typeof apiFetch;
+};
+export declare class StackWatchTimeoutError extends Error {
+    readonly lastEnvelope: StackWatchEnvelope;
+    constructor(lastEnvelope: StackWatchEnvelope);
+}
+export declare class StackWatchError extends Error {
+    readonly lastEnvelope: StackWatchEnvelope;
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(message: string, lastEnvelope: StackWatchEnvelope, options?: ErrorOptions, retryAfterSeconds?: number | undefined);
+}
+/** Wait on queue invalidations, then evaluate a fresh stack snapshot. */
+export declare function pollStackWatch(cfg: Config, stackId: string, opts?: PollStackWatchOptions): Promise<StackWatchEnvelope>;

package/dist/stack-watch.js

@@ -0,0 +1,232 @@
+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";
+import { mergeQueueBounceLabel } from "./stack-dto.js";
+export const STACK_WATCH_SCHEMA = "mergestorm.stack_watch/v1";
+export const STACK_WATCH_DEFAULT_TIMEOUT_MS = 45_000;
+export class StackWatchTimeoutError extends Error {
+    lastEnvelope;
+    constructor(lastEnvelope) {
+        super(`Timed out waiting for stack ${lastEnvelope.stackId}`);
+        this.lastEnvelope = lastEnvelope;
+        this.name = "StackWatchTimeoutError";
+    }
+}
+export class StackWatchError extends Error {
+    lastEnvelope;
+    retryAfterSeconds;
+    constructor(message, lastEnvelope, options, retryAfterSeconds) {
+        super(message, options);
+        this.lastEnvelope = lastEnvelope;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = "StackWatchError";
+    }
+}
+function sameHead(a, b) {
+    const left = a?.trim().toLowerCase();
+    const right = b?.trim().toLowerCase();
+    return !!left && !!right && (left.startsWith(right) || right.startsWith(left));
+}
+function currentLayer(stack) {
+    const open = stack.layers.filter((layer) => layer.prNumber > 0 && layer.state !== "merged" && layer.state !== "closed");
+    const promote = open.filter((layer) => layer.prNumber !== stack.unit?.landPrNumber &&
+        !stack.unit?.members.some((member) => member.prNumber === layer.prNumber && member.promotedHeadSha)).sort((a, b) => a.position - b.position);
+    const land = stack.unit?.landPr;
+    return promote[0] ?? open.find((layer) => layer.prNumber === stack.unit?.landPrNumber) ??
+        (land && land.prNumber > 0 && land.state !== "merged" && land.state !== "closed" ? land : undefined);
+}
+/** Keep label text and precedence aligned with MCP stack-summary.blockerLabel. */
+function attention(stack, layer, queue, cursor) {
+    const none = { blocker: null, bounceKind: null };
+    if (stack.archivedAt || queue.some((entry) => ["queued", "running", "waiting"].includes(entry.state)))
+        return none;
+    const bounce = queue.filter((entry) => entry.state === "bounced")
+        .sort((a, b) => (Date.parse(b.finishedAt ?? "") || 0) - (Date.parse(a.finishedAt ?? "") || 0))[0];
+    const kind = bounce?.bounceDetail?.kind;
+    const recoverable = kind === "head_moved" || kind === "must_consolidate";
+    const recoverableSha = kind === "head_moved"
+        ? bounce?.bounceDetail?.headSha ?? bounce?.verifyHeadSha
+        : bounce?.verifyHeadSha ?? bounce?.bounceDetail?.headSha;
+    const currentRecoverable = recoverable && sameHead(layer?.headSha, recoverableSha);
+    const hardBlock = (blocker) => ({ blocker, bounceKind: null });
+    if (layer) {
+        if (layer.restackError && layer.state !== "restacking") {
+            return hardBlock(layer.restackError.kind === "rebase_conflict" ? "Conflict" : "Restack failed");
+        }
+        if (layer.state === "conflict")
+            return hardBlock("Conflict");
+        if (layer.draft)
+            return hardBlock("Draft PR");
+        if ((!layer.headSha || layer.mergeableHeadSha === layer.headSha) &&
+            (layer.mergeable === false || layer.mergeableState?.toLowerCase() === "dirty"))
+            return hardBlock("Merge conflicts");
+        if (!currentRecoverable && (layer.ciStatus === "failure" || (layer.checks?.failure ?? 0) > 0)) {
+            const name = layer.checks?.failingName?.trim();
+            return hardBlock(`CI failed${name ? ` — ${name}` : ""}`);
+        }
+        const tempest = layer.agentRuns?.find((run) => run.agent === "tempest" &&
+            ["findings", "failed"].includes(run.status) && sameHead(run.sha, layer.headSha));
+        if (tempest)
+            return hardBlock(`Tempest ${tempest.status}`);
+        if (layer.vortexStatus === "failed")
+            return hardBlock("Review failed");
+        if (stack.unit?.landPrNumber === layer.prNumber) {
+            if (stack.unit.landingBlockReason?.trim())
+                return hardBlock(stack.unit.landingBlockReason.trim());
+            if (stack.unit.tempestLandStatus?.toLowerCase() === "failed")
+                return hardBlock("Tempest failed");
+        }
+    }
+    if (!bounce || !kind || recoverable || !layer)
+        return none;
+    if (cursor.bounceId === bounce.id || (cursor.afterFinishedAt &&
+        !(Date.parse(bounce.finishedAt ?? "") > Date.parse(cursor.afterFinishedAt))))
+        return none;
+    // Compare with the observed promote/land head, never the enrollment or verify head.
+    if (!sameHead(bounce.bounceDetail?.headSha ?? bounce.verifyHeadSha, layer.headSha) ||
+        (bounce.bounceDetail?.prNumber != null && bounce.bounceDetail.prNumber !== layer.prNumber))
+        return none;
+    return { blocker: mergeQueueBounceLabel(bounce), bounceKind: kind, bounce };
+}
+/** Wait on queue invalidations, then evaluate a fresh stack snapshot. */
+export async function pollStackWatch(cfg, stackId, opts = {}) {
+    const id = stackId.trim().toLowerCase();
+    if (!id || (opts.cursor && opts.cursor.stackId.trim().toLowerCase() !== id)) {
+        throw new TypeError("A matching stackId is required");
+    }
+    const timeoutMs = opts.timeoutMs ?? STACK_WATCH_DEFAULT_TIMEOUT_MS;
+    const intervalMs = opts.intervalMs ?? REVIEW_POLL_INTERVAL_MS;
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0 || !Number.isFinite(intervalMs) || intervalMs <= 0) {
+        throw new TypeError("timeoutMs must be nonnegative and intervalMs must be positive");
+    }
+    const now = opts.now ?? Date.now;
+    const wait = opts.sleep ?? ((ms, signal) => sleep(ms, undefined, { signal }));
+    const fetch = opts.fetch ?? apiFetch;
+    const startedAt = now();
+    const deadline = startedAt + timeoutMs;
+    let enrolled = opts.cursor !== undefined;
+    let cursor = Object.freeze({
+        ...(opts.cursor ?? { stackId: id, enrolledHeadSha: null }),
+        stackId: id,
+    });
+    let lastEnvelope = {
+        schema: STACK_WATCH_SCHEMA, status: "waiting", stackId: id, blocker: null,
+        bounceKind: null, prNumber: null, headSha: null, cursor,
+    };
+    let transientFailures = 0;
+    const timeout = () => new StackWatchTimeoutError({ ...lastEnvelope, status: "waiting" });
+    const pause = async (ms) => {
+        const remaining = Math.min(ms, Math.max(0, deadline - now()));
+        if (remaining > 0)
+            await wait(remaining, opts.signal);
+    };
+    const request = async (route, finalSnapshot = false) => {
+        let readAfterDeadline = finalSnapshot;
+        while (readAfterDeadline || now() < deadline) {
+            readAfterDeadline = false;
+            opts.signal?.throwIfAborted();
+            let response;
+            try {
+                response = await fetch(cfg, route, {
+                    signal: opts.signal, timeoutMs: route.includes("&wait=")
+                        ? Number(new URL(route, "https://local").searchParams.get("wait")) * 1000 + 5_000
+                        : finalSnapshot ? 5_000 : Math.max(1, Math.min(30_000, deadline - now())),
+                });
+            }
+            catch (err) {
+                if (opts.signal?.aborted || (err instanceof Error && err.name === "AbortError"))
+                    throw err;
+                if (now() >= deadline)
+                    throw timeout();
+                if (isTransientReviewPollError(err) && transientFailures < REVIEW_POLL_MAX_TRANSIENT_RETRIES) {
+                    transientFailures += 1;
+                    opts.onTick?.(lastEnvelope);
+                    await pause(transientRetryWaitMs({ failureCount: transientFailures, random: opts.random }));
+                    continue;
+                }
+                throw new StackWatchError(err instanceof Error ? err.message : String(err), { ...lastEnvelope, status: "failed" }, { cause: err });
+            }
+            if (response.status === 200)
+                return response.body;
+            if (isTransientReviewPollStatus(response.status) && transientFailures < REVIEW_POLL_MAX_TRANSIENT_RETRIES) {
+                transientFailures += 1;
+                opts.onTick?.({ ...lastEnvelope, status: response.status === 429 ? "rate_limited" : lastEnvelope.status });
+                await pause(transientRetryWaitMs({
+                    failureCount: transientFailures, retryAfterSeconds: response.retryAfterSeconds, random: opts.random,
+                }));
+                continue;
+            }
+            throw new StackWatchError(`Stack poll failed (HTTP ${response.status})`, {
+                ...lastEnvelope, status: response.status === 429 ? "rate_limited" : "failed",
+            }, undefined, response.retryAfterSeconds);
+        }
+        throw timeout();
+    };
+    while (now() < deadline) {
+        const snapshot = await request(`/api/v1/stacks/enrich?stackId=${encodeURIComponent(id)}`);
+        let stack = snapshot && Array.isArray(snapshot.stacks)
+            ? snapshot.stacks.find((stack) => stack.id.trim().toLowerCase() === id)
+            : undefined;
+        if (!stack || !Array.isArray(stack.layers)) {
+            throw new StackWatchError("Stack snapshot missing or invalid", { ...lastEnvelope, status: "failed" });
+        }
+        let layer = currentLayer(stack);
+        if (!enrolled) {
+            cursor = Object.freeze({ stackId: id, enrolledHeadSha: layer?.headSha ?? null });
+            enrolled = true;
+        }
+        lastEnvelope = { ...lastEnvelope, cursor, prNumber: layer?.prNumber ?? null, headSha: layer?.headSha ?? null };
+        const initialQueue = await request(`/api/v1/stacks/queue?stackId=${encodeURIComponent(id)}`);
+        if (!initialQueue || !Array.isArray(initialQueue.entries)) {
+            throw new StackWatchError("Invalid merge queue response", { ...lastEnvelope, status: "failed" });
+        }
+        const initialEntries = initialQueue.entries.filter((entry) => entry.stackId.trim().toLowerCase() === id);
+        const initial = attention(stack, layer, initialEntries, cursor);
+        if (initial.blocker) {
+            const { bounce, ...result } = initial;
+            if (bounce) {
+                cursor = Object.freeze({
+                    ...cursor,
+                    bounceId: bounce.id,
+                    ...(bounce.finishedAt !== undefined ? { afterFinishedAt: bounce.finishedAt } : {}),
+                });
+            }
+            return { ...lastEnvelope, ...result, cursor, status: "attention" };
+        }
+        const seconds = Math.min(45, Math.max(1, Math.ceil((deadline - now()) / 1000)));
+        const queue = await request(`/api/v1/stacks/queue?stackId=${encodeURIComponent(id)}&wait=${seconds}`);
+        if (!queue || !Array.isArray(queue.entries)) {
+            throw new StackWatchError("Invalid merge queue response", { ...lastEnvelope, status: "failed" });
+        }
+        if (now() < deadline) {
+            const refreshed = await request(`/api/v1/stacks/enrich?stackId=${encodeURIComponent(id)}`, true);
+            stack = Array.isArray(refreshed?.stacks)
+                ? refreshed.stacks.find((candidate) => candidate.id.trim().toLowerCase() === id)
+                : undefined;
+            if (!stack || !Array.isArray(stack.layers)) {
+                throw new StackWatchError("Stack snapshot missing or invalid", { ...lastEnvelope, status: "failed" });
+            }
+            layer = currentLayer(stack);
+            lastEnvelope = { ...lastEnvelope, prNumber: layer?.prNumber ?? null, headSha: layer?.headSha ?? null };
+        }
+        transientFailures = 0;
+        const entries = queue.entries.filter((entry) => entry.stackId.trim().toLowerCase() === id);
+        const { bounce, ...result } = attention(stack, layer, entries, cursor);
+        if (bounce) {
+            cursor = Object.freeze({
+                ...cursor,
+                bounceId: bounce.id,
+                ...(bounce.finishedAt !== undefined ? { afterFinishedAt: bounce.finishedAt } : {}),
+            });
+        }
+        lastEnvelope = {
+            ...lastEnvelope, ...result, cursor,
+            status: result.blocker ? "attention" : entries.some((entry) => ["queued", "running", "waiting"].includes(entry.state))
+                ? "in_progress" : "waiting",
+        };
+        if (lastEnvelope.status === "attention")
+            return lastEnvelope;
+        opts.onTick?.(lastEnvelope);
+    }
+    throw timeout();
+}

package/dist/ui/banner.js

@@ -90,6 +90,9 @@ const WHATS_NEW = {
     "0.3.18": [
         "pr --wait fences a stale same-head pass",
     ],
+    "0.3.19": [
+        "stack wait and held GET waits",
+    ],
 };
 function densityFromVariant(variant) {
     if (variant === "mini" || variant === "nano")