mergestorm 0.3.17 → 0.3.19

package/dist/commands/settings.js

@@ -1,17 +1,25 @@
 import { getSettings, patchSettings, } from "../api.js";
-import { BEARER_SETTINGS_FLAGS } from "../automation-catalog.js";
+import { BEARER_SETTINGS, BEARER_SETTINGS_FLAGS } from "../automation-catalog.js";
 import { loadConfig } from "../config.js";
 import { CommandError } from "../errors.js";
 import { present } from "../ui/present.js";
 import { buildConfigRows, canBrowse, openTabsBrowser } from "./browse.js";
 /**
- * CLI flag → Bearer settings key. on|off only. The connected flags are
+ * CLI flag → Bearer settings key. Boolean flags take on|off. The connected flags are
  * read-only on the API and deliberately have no flag here.
  */
 export const SETTINGS_FLAGS = BEARER_SETTINGS_FLAGS;
-/** Parse `settings` argv. Accepts `--flag on|off` and `--flag=on|off`. */
+function canonicalLogin(raw) {
+    const login = raw.trim().toLowerCase().replace(/\[bot\]$/, "");
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(login)) {
+        throw new CommandError(`Invalid bot login: ${raw}.`, 2, "usage");
+    }
+    return login;
+}
+/** Parse boolean and enum flags plus ordered ignore-list operations. */
 export function parseSettingsArgs(args) {
     let json = false;
+    const ignoreBots = [];
     const patch = {};
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
@@ -26,37 +34,91 @@ export function parseSettingsArgs(args) {
             throw new CommandError(`Unknown settings flag: ${flag}. See \`mergestorm --help\`.`, 2, "usage");
         }
         const value = eq >= 0 ? arg.slice(eq + 1) : args[++i];
+        const row = BEARER_SETTINGS.find((row) => row.key === key);
+        if ("kind" in row && row.kind === "logins") {
+            if (value === "clear")
+                ignoreBots.push({ action: "clear" });
+            else if ((value === "add" || value === "remove") && args[i + 1] && !args[i + 1].startsWith("--")) {
+                ignoreBots.push({ action: value, login: canonicalLogin(args[++i]) });
+            }
+            else {
+                throw new CommandError(`${flag} takes add <login>, remove <login>, or clear.`, 2, "usage");
+            }
+            continue;
+        }
+        if ("kind" in row && row.kind === "enum") {
+            if (value === undefined || !row.values.includes(value)) {
+                throw new CommandError(`${flag} takes ${row.values.join(" or ")}.`, 2, "usage");
+            }
+            Object.assign(patch, { [key]: value });
+            continue;
+        }
         if (value !== "on" && value !== "off") {
             throw new CommandError(`${flag} takes on or off.`, 2, "usage");
         }
-        patch[key] = value === "on";
+        Object.assign(patch, { [key]: value === "on" });
     }
-    return { json, patch };
+    return { json, patch, ...(ignoreBots.length ? { ignoreBots } : {}) };
 }
-/** Static printout of the GET/PATCH response shape (rows match the Config tab). */
+/** Static printout includes the Config toggles plus enum and login settings. */
 export function formatSettingsLines(settings) {
-    const rows = buildConfigRows(settings);
+    const rows = [
+        ...buildConfigRows(settings),
+        ...BEARER_SETTINGS.filter((row) => "kind" in row).map((row) => ({
+            ...row, writable: true, value: settings[row.key],
+        })),
+    ];
     const labelWidth = Math.max(...rows.map((r) => r.label.length));
     return rows.map((row) => {
-        const value = row.writable
-            ? row.value
-                ? "on"
-                : "off"
-            : row.value
-                ? "connected"
-                : "not connected";
+        const value = "kind" in row && row.value === undefined
+            ? "(unavailable)"
+            : Array.isArray(row.value)
+                ? row.value.join(", ") || "(empty)"
+                : typeof row.value === "string"
+                    ? row.value
+                    : row.writable
+                        ? row.value
+                            ? "on"
+                            : "off"
+                        : row.value
+                            ? "connected"
+                            : "not connected";
         return `  ${row.label.padEnd(labelWidth + 2)}${value}`;
     });
 }
 export async function cmdSettings(args, opts = {}) {
-    const { json, patch } = parseSettingsArgs(args);
-    const hasPatch = Object.keys(patch).length > 0;
+    const { json, patch, ignoreBots } = parseSettingsArgs(args);
+    const hasPatch = Object.keys(patch).length > 0 || Boolean(ignoreBots?.length);
     // Bare `settings` on a TTY: the tabbed browser, opened on Config.
     if (!hasPatch && !json && canBrowse()) {
         await openTabsBrowser("config");
         return;
     }
     const cfg = await loadConfig();
+    if (ignoreBots?.length) {
+        // A leading clear needs no read. Otherwise fetch before writing the full list.
+        const current = ignoreBots[0].action === "clear" ? null : await getSettings(cfg);
+        if (ignoreBots[0].action !== "clear" && !current) {
+            throw new CommandError("Settings are not available; cannot update ignored bot logins.");
+        }
+        let logins = [...new Set((current?.ignored_bot_logins ?? []).flatMap((raw) => {
+                try {
+                    return [canonicalLogin(raw)];
+                }
+                catch {
+                    return [];
+                }
+            }))];
+        for (const op of ignoreBots) {
+            if (op.action === "clear")
+                logins = [];
+            else if (op.action === "remove")
+                logins = logins.filter((login) => login !== op.login);
+            else if (!logins.includes(op.login))
+                logins.push(op.login);
+        }
+        patch.ignored_bot_logins = logins;
+    }
     let settings;
     if (hasPatch) {
         settings = await patchSettings(patch, cfg);

package/dist/commands/skill.d.ts

@@ -1,9 +1,10 @@
 export declare const SKILL_NAME = "mergestorm-review";
 export declare const PR_LOOP_SKILL_NAME = "mergestorm-pr-loop";
-export declare const SKILL_NAMES: readonly ["mergestorm-review", "mergestorm-pr-loop"];
+export declare const BOUNCE_WATCH_SKILL_NAME = "mergestorm-bounce-watch";
+export declare const SKILL_NAMES: readonly ["mergestorm-review", "mergestorm-pr-loop", "mergestorm-bounce-watch"];
 export type SkillName = (typeof SKILL_NAMES)[number];
-export declare const SKILL_USAGE = "usage:\n  mergestorm skill install --claude|--cursor [--json]\n\n  Copies mergestorm-review and mergestorm-pr-loop into this repo (git toplevel, else cwd):\n    --claude  .claude/skills/<name>/SKILL.md\n    --cursor  .cursor/skills/<name>/SKILL.md\n  Pass both flags to write both trees. Overwrites existing copies.";
-export type SkillTarget = "claude" | "cursor";
+export declare const SKILL_USAGE: string;
+export type SkillTarget = "claude" | "cursor" | "agents";
 export type SkillInstallRequest = {
     help: boolean;
     json: boolean;

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

@@ -20,7 +20,32 @@ export type StackReviewStatus = "approved" | "changes_requested" | "reviewed" |
  * `incomplete` is a posted verdict whose head still has unreviewed files
  * (#1947): Work paints Incomplete, never Reviewed or all clear.
  */
-export type StackVortexStatus = "reviewing" | "seam_pending" | "all_clear" | "findings" | "throttled" | "failed" | "incomplete";
+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";
@@ -36,6 +61,8 @@ export type StackAgentRun = {
     status: string;
     /** Full SHA when known. UI shortens to 7. */
     sha: string | null;
+    pass?: number | null;
+    skipReason?: string | null;
     startedAt?: string | null;
     finishedAt?: string | null;
     /**
@@ -138,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;
@@ -247,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.
@@ -284,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>;