mergestorm 0.3.38 → 0.3.40

package/README.md

@@ -45,7 +45,7 @@ On a TTY, bare `mergestorm` (or `mergestorm shell`) opens a branded REPL: a comp
 
 ```
 ╭──────────────────────────────────────────────────────────────────────────────╮
-│  ▀▀▀▀▀▀▀▀▀▀▘  mergestorm v0.3.38                                             │
+│  ▀▀▀▀▀▀▀▀▀▀▘  mergestorm v0.3.40                                             │
 │ ▀▀▀▀▀▀▀▀▀     ● msk_live_… · maelstrom                                       │
 │  ▀▀▀▀▀▀       [████████░░░░░░░░░░░░░░░░░░░░░░] 25% used                      │
 │   ▝▀▀▀▀▀      local reviews + stacked PRs · mergestorm.ai                    │
@@ -137,7 +137,7 @@ Use `mergestorm dismiss` when a Vortex finding is wrong and you have checked it
 
 If the parent branch is already a layer of a **registered** (submitted) stack, `create` and `submit` refuse unless you pass **`--extend`**. That blocks accidentally gluing an unrelated PR onto an open unit. Growing a registered stack on purpose: `mg stack create --onto <tip> --extend` → commit → `mg stack submit --extend`.
 
-`stack submit` walks the **active** local stack: `git push -u origin` each layer, opens a PR with `gh` (`--base` = parent or trunk; adopt then moves the bottom of a 2+ PR stack onto `mg-stack-<n>` — leave it there; skips heads that already have an open PR; body from the tip commit — Summary + Test plan, preserving Fixes/Closes/Resolves), registers the stack with `POST /api/v1/stacks/adopt` internally (Mergestorm API key), then drops that local stack entry so the next create onto trunk is clean. Push is always your local `git` credentials. PRs open as you when `gh` is installed and `gh api user` succeeds; otherwise `stack submit` asks the Mergestorm API (`POST /api/v1/stacks/pulls`) to open them as Cyclone on your behalf, after checking your GitHub account has write access, and assigns you. Without either, submit stops before pushing and links the Cyclone install page.
+`stack submit` walks the **active** local stack: `git push -u origin` each layer, opens a PR with `gh` (`--base` = parent or trunk; adopt then moves the bottom of a 2+ PR stack onto `mg-stack-<n>` — leave it there; skips heads that already have an open PR; body from the tip commit — Summary + Test plan, preserving Fixes/Closes/Resolves), registers the stack with `POST /api/v1/stacks/adopt` internally (Mergestorm API key), then drops that local stack entry so the next create onto trunk is clean. Push is always your local `git` credentials. PRs open as you when `gh` is installed and `gh api user` succeeds; otherwise `stack submit` asks the Mergestorm API (`POST /api/v1/stacks/pulls`) to open them as the Mergestorm infrastructure App on your behalf, after checking your GitHub account has write access, and assigns you. That App is Mergestorm Surge, or Cyclone on accounts not yet moved to Surge; stacks, the merge queue and Auto land run through it, and Cyclone is the auto-patch App. Without either, submit stops before pushing and prints the server's message, which names the App to install and links its install page. `mg settings` prints a `Stacks, merge queue, Auto land` line when the server reports whether that App is ready.
 
 Legacy repo-local `.mergestorm/stack.json` state migrates automatically on the next stack command. If local authoring state is stale or malformed, use `mg stack reset --force`; this clears only pre-submit CLI state and never deletes branches, PRs, or registered stacks.
 

package/dist/api.d.ts

@@ -1,7 +1,8 @@
 import { type Config } from "./config.js";
 import { BEARER_SETTINGS_KEYS as SETTINGS_WRITABLE_KEYS, type BearerSettingsKey as SettingsWritableKey } from "./automation-catalog.js";
+import { CommandError } from "./errors.js";
 import type { MergeQueueEntryDto, StackDto } from "./stack-dto.js";
-export type { MergeQueueBounceDetail, MergeQueueBounceKind, MergeQueueEnqueuedBy, MergeQueueEnqueuedVia, MergeQueueEntryDto, MergeQueueEntryState, StackBranchState, StackCiStatus, StackDto, StackLayerChecks, StackLayerDto, StackReviewStatus, StackTempestStatus, StackUnitDto, StackUnitMemberDto, } from "./stack-dto.js";
+export type { MergeQueueBounceDetail, MergeQueueBounceKind, MergeQueueEnqueuedBy, MergeQueueEnqueuedVia, MergeQueueEntryDto, MergeQueueEntryState, StackBranchState, StackCiStatus, StackDto, StackLayerChecks, StackLayerDto, StackReviewStatus, StackUnitDto, StackUnitMemberDto, } from "./stack-dto.js";
 /** Default per-request timeout so a hung API cannot stall the shell/CI forever. */
 export declare const DEFAULT_API_TIMEOUT_MS = 30000;
 /** Message prefix of the CommandError thrown when a request exceeds its timeout. */
@@ -172,6 +173,7 @@ export type SettingsPatch = Partial<import("./automation-catalog.js").BearerSett
 export type SettingsResponse = import("./automation-catalog.js").BearerSettingsValues & {
     cyclone_connected: boolean;
     github_connected: boolean;
+    stacks_ready?: boolean;
 };
 /**
  * Fetch Bearer /api/v1/settings; null on 404/network/timeouts so panels can
@@ -228,6 +230,9 @@ export type StackPolicyPatch = {
 export declare function stackPolicyBody(policy: StackPolicyPatch | undefined): StackPolicyPatch;
 /** Adopt an open PR chain (Bearer POST /api/v1/stacks/adopt). */
 export declare function adoptStack(owner: string, repo: string, prNumber: number, cfg?: Config, policy?: StackPolicyPatch): Promise<unknown>;
+export declare const SURGE_REFUSAL_FALLBACK = "Mergestorm Surge is not installed or not ready on this repository. Install it from Agents.";
+export declare function surgeRefusal(body: unknown): CommandError | null;
+export declare const GITHUB_UNREADABLE_MESSAGE = "GitHub could not be read just now; try again.";
 /** Mint or reuse the PR3+ park freeze (Bearer POST /api/v1/stacks/:id/ensure-upper-park). */
 export declare function ensureUpperPark(stackId: string, cfg?: Config): Promise<{
     freezeBranch: string;

package/dist/api.js

@@ -1,6 +1,6 @@
 import { apiBase, loadConfig, resolveApiKey } from "./config.js";
 import { BEARER_SETTINGS_KEYS as SETTINGS_WRITABLE_KEYS, } from "./automation-catalog.js";
-import { CommandError, REVIEW_EXIT, rateLimitedMessage, } from "./errors.js";
+import { CommandError, REVIEW_EXIT, rateLimitedMessage, plainServerText, } from "./errors.js";
 /** Default per-request timeout so a hung API cannot stall the shell/CI forever. */
 export const DEFAULT_API_TIMEOUT_MS = 30_000;
 /** Message prefix of the CommandError thrown when a request exceeds its timeout. */
@@ -416,12 +416,53 @@ export async function adoptStack(owner, repo, prNumber, cfg, policy) {
             : code === "supabase_unconfigured"
                 ? "Stacks are not configured on this server."
                 : undefined;
+        const surge = surgeRefusal(body);
+        if (surge)
+            throw surge;
         throw new CommandError(message?.trim()
             ? message
             : fallbackMessage ?? `Failed to import stack (HTTP ${status}): ${JSON.stringify(body)}`, 1, code);
     }
     return body;
 }
+const INFRASTRUCTURE_REFUSAL_CODES = [
+    "cyclone_not_connected",
+    "cyclone_not_installed",
+    "cyclone_permission_missing",
+];
+function refusalReason(body) {
+    const reason = (body && typeof body === "object" ? body.reason : undefined);
+    return typeof reason === "string" && plainServerText(reason).trim() ? plainServerText(reason).trim() : undefined;
+}
+export const SURGE_REFUSAL_FALLBACK = "Mergestorm Surge is not installed or not ready on this repository. Install it from Agents.";
+export function surgeRefusal(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const refusal = body;
+    const reason = refusalReason(body);
+    if (!reason?.startsWith("surge_"))
+        return null;
+    const error = INFRASTRUCTURE_REFUSAL_CODES.find((code) => code === refusal.error);
+    if (!error)
+        return null;
+    const message = serverMessage(refusal.message) ?? SURGE_REFUSAL_FALLBACK;
+    const installUrl = githubAppInstallUrl(refusal.installUrl) ?? "";
+    return new CommandError(installUrl && !message.includes(installUrl) ? `${message} (${installUrl})` : message, 1, error, { reason });
+}
+export const GITHUB_UNREADABLE_MESSAGE = "GitHub could not be read just now; try again.";
+function serverMessage(message) {
+    if (typeof message !== "string")
+        return null;
+    const plain = plainServerText(message).trim();
+    return plain ? plain : null;
+}
+const GITHUB_APP_INSTALL_URL = /https:\/\/github\.com\/apps\/[^\s)]+\/installations\/new/;
+function githubAppInstallUrl(value) {
+    if (typeof value !== "string")
+        return null;
+    const match = GITHUB_APP_INSTALL_URL.exec(plainServerText(value).trim());
+    return match && match.index === 0 ? match[0] : null;
+}
 /** Mint or reuse the PR3+ park freeze (Bearer POST /api/v1/stacks/:id/ensure-upper-park). */
 export async function ensureUpperPark(stackId, cfg) {
     const body = await stackMutation(stackId, "/ensure-upper-park", "POST", {}, "Failed to ensure upper-park freeze", cfg);
@@ -445,10 +486,13 @@ export function cycloneNotInstalledMessage(owner, repo, installUrl = CYCLONE_INS
 function installUrlFrom(message) {
     if (typeof message !== "string")
         return CYCLONE_INSTALL_URL;
-    return message.match(/https:\/\/github\.com\/apps\/[^\s)]+\/installations\/new/)?.[0] ?? CYCLONE_INSTALL_URL;
+    return message.match(GITHUB_APP_INSTALL_URL)?.[0] ?? CYCLONE_INSTALL_URL;
 }
 function stackPullFailure(status, body, owner, repo, failLabel) {
     const rejection = (body && typeof body === "object" ? body : {});
+    const surge = surgeRefusal(body);
+    if (surge)
+        return surge;
     const text = `${String(rejection.error ?? "")} ${String(rejection.message ?? "")}`;
     if (rejection.error === "cyclone_not_installed" ||
         /not installed|installation[^\n]*not found/i.test(text)) {
@@ -500,6 +544,9 @@ async function stackMutation(stackId, pathSuffix, method, json, failLabel, cfg)
         throw new CommandError("Stacks API is not available on this server yet. Deploy the API update or use the dashboard.");
     }
     if (status !== 200) {
+        const surge = surgeRefusal(body);
+        if (surge)
+            throw surge;
         const rejection = body;
         if (method === "PATCH" && rejection?.error === "cyclone_not_connected") {
             throw new CommandError(typeof rejection.message === "string" ? rejection.message : rejection.error, 1, "cyclone_not_connected");
@@ -554,7 +601,7 @@ export async function listMergeQueueEntries(cfg, opts) {
     }
     return entries;
 }
-async function queueMutation(route, failLabel, cfg) {
+async function queueMutation(route, failLabel, cfg, opts = {}) {
     const resolved = cfg ?? (await loadConfig());
     const { status, body } = await apiFetch(resolved, route, {
         method: "POST",
@@ -572,18 +619,27 @@ async function queueMutation(route, failLabel, cfg) {
     }
     if (status === 409) {
         const refusal = body;
-        if (refusal?.error === "conflict_unchanged" && typeof refusal.message === "string") {
+        if ((refusal?.error === "conflict_unchanged" || refusal?.error === "ci_failed") &&
+            typeof refusal.message === "string") {
             throw new CommandError(refusal.message);
         }
     }
+    if (opts.githubUnreadableRefusal &&
+        status === 503 &&
+        body?.error === "github_unreadable") {
+        throw new CommandError(serverMessage(body.message) ?? GITHUB_UNREADABLE_MESSAGE, 1, "github_unreadable");
+    }
     if (status < 200 || status >= 300) {
+        const surge = surgeRefusal(body);
+        if (surge)
+            throw surge;
         throw new CommandError(`${failLabel} (HTTP ${status}): ${JSON.stringify(body)}`);
     }
     return body;
 }
 /** Enqueue a stack for verified landing. */
 export async function enqueueStack(stackId, cfg) {
-    return queueMutation(`/api/v1/stacks/${encodeURIComponent(stackId)}/enqueue`, "Failed to add stack to merge queue", cfg);
+    return queueMutation(`/api/v1/stacks/${encodeURIComponent(stackId)}/enqueue`, "Failed to add stack to merge queue", cfg, { githubUnreadableRefusal: true });
 }
 /** Cancel a live merge-queue entry by entry id. */
 export async function cancelMergeQueueEntry(entryId, cfg) {

package/dist/client/index.d.ts

@@ -2,7 +2,7 @@ export { DEFAULT_API, apiBase, clearConfig, configPath, keyDisplay, loadConfig,
 export { BEARER_SETTINGS, BEARER_BOOLEAN_SETTINGS_KEYS, BEARER_SETTINGS_FLAGS, BEARER_SETTINGS_KEYS, BEARER_SETTINGS_LABELS, type BearerSettingsKey, } from "../automation-catalog.js";
 export { API_TIMEOUT_PREFIX, DEFAULT_API_TIMEOUT_MS, SETTINGS_WRITABLE_KEYS, adoptStack, apiFetch, cancelMergeQueueEntry, devicePost, dismissPrFindings, enqueueStack, ensureUpperPark, getEnrichedStack, getMe, getPrVortexReview, getReview, getSettings, landNextStack, listJobs, listMergeQueueEntries, listStacks, listThreads, parseRetryAfterSeconds, patchSettings, restackStack, setStackAutoLand, setStackPolicy, stackPolicyBody, type ApiFetchInit, type ApiFetchResult, type JobListItem, type MeResponse, type MergeQueueBounceDetail, type MergeQueueBounceKind, type MergeQueueEnqueuedBy, type MergeQueueEnqueuedVia, type MergeQueueEntryDto, type MergeQueueEntryState, type PrDismissedFinding, type PrFindingDismissInput, type PrFindingDismissOutcome, type PrFindingDismissResult, type PrReviewFinding, type PrReviewFindings, type PrVortexReview, type SettingsPatch, type SettingsResponse, type SettingsWritableKey, type StackDto, type StackPolicyPatch, type ThreadDetail, type ThreadListItem, } from "../api.js";
 export { CommandError, DetachedError, RATE_LIMITED_HINT, REVIEW_EXIT, isCommandErrorCode, rateLimitedMessage, type CommandErrorCode, type CommandErrorExtras, } from "../errors.js";
-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_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, noPrReviewYetMessage, 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, deriveStackAgentsBusy, mergeQueueBounceLabel, type StackAgentsBusy } from "../stack-dto.js";

package/dist/client/index.js

@@ -2,7 +2,7 @@ export { DEFAULT_API, apiBase, clearConfig, configPath, keyDisplay, loadConfig,
 export { BEARER_SETTINGS, BEARER_BOOLEAN_SETTINGS_KEYS, BEARER_SETTINGS_FLAGS, BEARER_SETTINGS_KEYS, BEARER_SETTINGS_LABELS, } from "../automation-catalog.js";
 export { API_TIMEOUT_PREFIX, DEFAULT_API_TIMEOUT_MS, SETTINGS_WRITABLE_KEYS, adoptStack, apiFetch, cancelMergeQueueEntry, devicePost, dismissPrFindings, enqueueStack, ensureUpperPark, getEnrichedStack, getMe, getPrVortexReview, getReview, getSettings, landNextStack, listJobs, listMergeQueueEntries, listStacks, listThreads, parseRetryAfterSeconds, patchSettings, restackStack, setStackAutoLand, setStackPolicy, stackPolicyBody, } from "../api.js";
 export { CommandError, DetachedError, RATE_LIMITED_HINT, REVIEW_EXIT, isCommandErrorCode, rateLimitedMessage, } from "../errors.js";
-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_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, noPrReviewYetMessage, 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, deriveStackAgentsBusy, mergeQueueBounceLabel } from "../stack-dto.js";

package/dist/commands/browse.d.ts

@@ -28,6 +28,11 @@ export declare function buildStatusTabLines(input: StatusTabInput): string[];
 export declare function formatJobDetailLines(row: ReviewJobRow): string[];
 /** Human labels for the Config tab and the static `settings` printout. */
 export declare const SETTINGS_LABELS: Record<"auto_review_enabled" | "auto_patch_enabled" | "vortex_show_thinking_traces" | "repo_overview_enabled" | "review_unit_land_prs_enabled" | "cyclone_skip_ci_enabled" | "cyclone_patch_unverified_languages" | "vortex_auto_overflow_enabled" | "vortex_skip_all_clear_comments" | "vortex_seam_specialist_enabled" | "auto_land_default" | "auto_land_settle_seconds" | "merge_queue_batch_enabled" | "merge_queue_batch_size" | "ignored_bot_logins" | "vortex_bot_skip_check" | "vortex_findings_check" | "cyclone_patch_failure_check", string>;
+export declare const STACKS_READY_LABEL = "Stacks, merge queue, Auto land";
+export declare const STACKS_READY_WORDS: {
+    readonly on: "ready";
+    readonly off: "not ready (install Mergestorm Surge)";
+};
 /** Config rows in a stable order: writable toggles, then connected flags. */
 export declare function buildConfigRows(settings: SettingsResponse): TabsConfigRow[];
 /**

package/dist/commands/browse.js

@@ -121,8 +121,14 @@ export function formatJobDetailLines(row) {
 }
 /** Human labels for the Config tab and the static `settings` printout. */
 export const SETTINGS_LABELS = BEARER_SETTINGS_LABELS;
+export const STACKS_READY_LABEL = "Stacks, merge queue, Auto land";
+export const STACKS_READY_WORDS = {
+    on: "ready",
+    off: "not ready (install Mergestorm Surge)",
+};
 /** Config rows in a stable order: writable toggles, then connected flags. */
 export function buildConfigRows(settings) {
+    const stacksReadyKnown = typeof settings.stacks_ready === "boolean";
     return [
         ...BEARER_BOOLEAN_SETTINGS_KEYS.map((key) => ({
             key,
@@ -130,9 +136,20 @@ export function buildConfigRows(settings) {
             value: settings[key] === true,
             writable: true,
         })),
+        ...(stacksReadyKnown
+            ? [
+                {
+                    key: "stacks_ready",
+                    label: STACKS_READY_LABEL,
+                    value: settings.stacks_ready === true,
+                    writable: false,
+                    readOnlyWords: STACKS_READY_WORDS,
+                },
+            ]
+            : []),
         {
             key: "cyclone_connected",
-            label: "Cyclone",
+            label: stacksReadyKnown ? "Cyclone (auto patch)" : "Cyclone",
             value: settings.cyclone_connected === true,
             writable: false,
         },

package/dist/commands/review-client.d.ts

@@ -84,12 +84,19 @@ export declare class ReviewPollTimeoutError extends Error {
     readonly lastRow: ReviewJobRow;
     constructor(jobId: string, lastRow: ReviewJobRow);
 }
+export type PrReviewWaitTarget = {
+    afterSha?: string;
+    pass?: number;
+    afterPass?: number;
+};
+export declare function noPrReviewYetMessage(owner: string, repo: string, prNumber: number, target?: PrReviewWaitTarget): string;
 export declare class PrReviewPollTimeoutError extends Error {
     readonly owner: string;
     readonly repo: string;
     readonly prNumber: number;
     readonly lastEnvelope: PrVortexReview | null;
-    constructor(owner: string, repo: string, prNumber: number, lastEnvelope: PrVortexReview | null);
+    readonly reviewSeen: boolean;
+    constructor(owner: string, repo: string, prNumber: number, lastEnvelope: PrVortexReview | null, target?: PrReviewWaitTarget, reviewSeen?: boolean);
 }
 export type PollReviewOptions = {
     timeoutMs?: number;

package/dist/commands/review-client.js

@@ -249,18 +249,31 @@ export class ReviewPollTimeoutError extends Error {
         this.lastRow = lastRow;
     }
 }
+export function noPrReviewYetMessage(owner, repo, prNumber, target = {}) {
+    const sha = target.afterSha?.trim();
+    const pass = target.pass !== undefined
+        ? `Vortex pass ${target.pass}`
+        : target.afterPass !== undefined ? `Vortex pass after pass ${target.afterPass}` : "Vortex review";
+    return `No ${pass} exists for ${owner}/${repo}#${prNumber}${sha ? ` at ${sha.slice(0, 12)}` : ""} yet. ` +
+        "If the push was in the last few minutes, wait once more. If it is still missing after that, Vortex is not reviewing this head " +
+        "(auto-review may be off for the repo or the stack, or the push did not reach Mergestorm): " +
+        `comment "@mergestorm-vortex review" on the PR to run it, or review the branch locally with mg review; a new push also queues a review.`;
+}
 export class PrReviewPollTimeoutError extends Error {
     owner;
     repo;
     prNumber;
     lastEnvelope;
-    constructor(owner, repo, prNumber, lastEnvelope) {
-        super(`Timed out waiting for PR review ${owner}/${repo}#${prNumber}`);
+    reviewSeen;
+    constructor(owner, repo, prNumber, lastEnvelope, target = {}, reviewSeen = lastEnvelope !== null) {
+        super(`Timed out waiting for PR review ${owner}/${repo}#${prNumber}` +
+            (reviewSeen ? "" : `. ${noPrReviewYetMessage(owner, repo, prNumber, target)}`));
         this.name = "PrReviewPollTimeoutError";
         this.owner = owner;
         this.repo = repo;
         this.prNumber = prNumber;
         this.lastEnvelope = lastEnvelope;
+        this.reviewSeen = reviewSeen;
     }
 }
 function shaMatches(actual, expected) {
@@ -286,6 +299,7 @@ export async function pollPrVortexReview(cfg, owner, repo, prNumber, opts = {})
     applyPrReviewQuery(query, opts);
     let transientFailures = 0;
     let lastEnvelope = null;
+    let apiTimeoutSeen = false;
     const sleepBeforeRetry = async (retryAfterSeconds) => {
         const waitMs = Math.min(transientRetryWaitMs({
             retryAfterSeconds,
@@ -315,6 +329,7 @@ export async function pollPrVortexReview(cfg, owner, repo, prNumber, opts = {})
             if (isCommandErrorCode(err, "api_timeout")) {
                 if (opts.propagateTimeout)
                     throw err;
+                apiTimeoutSeen = true;
                 break;
             }
             if (isTransientReviewPollError(err)) {
@@ -364,7 +379,7 @@ export async function pollPrVortexReview(cfg, owner, repo, prNumber, opts = {})
             return lastEnvelope;
         opts.onTick?.("progress");
     }
-    throw new PrReviewPollTimeoutError(owner, repo, prNumber, lastEnvelope);
+    throw new PrReviewPollTimeoutError(owner, repo, prNumber, lastEnvelope, opts, lastEnvelope !== null || apiTimeoutSeen);
 }
 export async function pollReview(cfg, jobId, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? REVIEW_POLL_DEFAULT_TIMEOUT_MS;

package/dist/commands/review.d.ts

@@ -1,4 +1,4 @@
-import { REVIEW_POLL_MAX_TRANSIENT_RETRIES, isTransientReviewPollError, isTransientReviewPollStatus } from "./review-client.js";
+import { REVIEW_POLL_MAX_TRANSIENT_RETRIES, isTransientReviewPollError, isTransientReviewPollStatus, type PollReviewOptions } from "./review-client.js";
 export { REVIEW_POLL_MAX_TRANSIENT_RETRIES, isTransientReviewPollError, isTransientReviewPollStatus, };
 /** Same public specialist allowlist as the API contract and migration 117. */
 export declare const VORTEX_ROUTER_MODES: readonly ["off", "standard", "max", "manual"];
@@ -43,6 +43,7 @@ export type ReviewOptions = {
     interactive?: boolean;
     /** Test seam; production uses the two-second poll interval. */
     pollIntervalMs?: number;
+    pollClock?: Pick<PollReviewOptions, "sleep" | "now" | "random">;
 };
 export declare function reviewStatusHint(jobId: string): string;
 /** Append recovery hint once a job id exists (idempotent). */

package/dist/commands/review.js

@@ -357,6 +357,7 @@ export async function cmdReview(args, opts = {}) {
             row = await pollReview(cfg, jobId, {
                 timeoutMs: parsed.timeoutMs,
                 intervalMs: opts.pollIntervalMs,
+                ...opts.pollClock,
                 signal: opts.signal,
                 propagateTimeout: interactive,
                 onTick(kind) {

package/dist/commands/settings.js

@@ -3,6 +3,7 @@ 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 { readOnlyRowWords } from "../ui/tabs.js";
 import { buildConfigRows, canBrowse, openTabsBrowser } from "./browse.js";
 /**
  * CLI flag → Bearer settings key. Boolean flags take on|off. The connected flags are
@@ -91,9 +92,7 @@ export function formatSettingsLines(settings) {
                             ? row.value
                                 ? "on"
                                 : "off"
-                            : row.value
-                                ? "connected"
-                                : "not connected";
+                            : readOnlyRowWords(row);
         return `  ${row.label.padEnd(labelWidth + 2)}${value}`;
     });
 }

package/dist/commands/stack.js

@@ -1040,8 +1040,7 @@ export async function cmdStackStatus(args, deps = {}) {
         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}` : ""));
+            (layer.cycloneStatus ? `  Cyclone: ${layer.cycloneStatus}` : ""));
     }
     if (queueWait && !attention)
         lines.push(`  Queue: #${queueWait.prNumber} ${queueWait.text}`);

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" | "cyclone_not_installed" | "pr_merged" | "pr_closed" | "not_stacked" | "draft" | "reserved_branch" | "supabase_unconfigured" | "cyclone_not_connected" | "busy" | "adopt_failed" | "stack_attention";
+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" | "cyclone_permission_missing" | "busy" | "adopt_failed" | "github_unreadable" | "stack_attention";
 /** Stable one-shot exit codes for machine callers of `mergestorm review`. */
 export declare const REVIEW_EXIT: {
     readonly success: 0;
@@ -15,14 +15,17 @@ export declare const REVIEW_EXIT: {
 };
 export type CommandErrorExtras = {
     retryAfterSeconds?: number;
+    reason?: string;
 };
 /** Thrown by command handlers; one-shot mode maps `exitCode` onto process.exitCode. */
 export declare class CommandError extends Error {
     readonly exitCode: number;
     readonly code?: CommandErrorCode;
     readonly retryAfterSeconds?: number;
+    readonly reason?: string;
     constructor(message: string, exitCode?: number, code?: CommandErrorCode, extras?: CommandErrorExtras);
 }
+export declare function plainServerText(text: string): string;
 export declare const RATE_LIMITED_HINT = "Rate limited. Wait for a running review or mergestorm jobs.";
 export declare function rateLimitedMessage(retryAfterSeconds?: number): string;
 export declare function isCommandErrorCode(err: unknown, code: CommandErrorCode): err is CommandError;

package/dist/errors.js

@@ -13,6 +13,7 @@ export class CommandError extends Error {
     exitCode;
     code;
     retryAfterSeconds;
+    reason;
     constructor(message, exitCode = 1, code, extras) {
         super(message);
         this.name = "CommandError";
@@ -21,8 +22,16 @@ export class CommandError extends Error {
         if (extras?.retryAfterSeconds !== undefined) {
             this.retryAfterSeconds = extras.retryAfterSeconds;
         }
+        if (extras?.reason !== undefined) {
+            this.reason = extras.reason;
+        }
     }
 }
+const ANSI_SEQUENCE = /\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)|\u001b\[[0-?]*[ -/]*[@-~]/g;
+const CONTROL_CHARACTER = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
+export function plainServerText(text) {
+    return text.replace(ANSI_SEQUENCE, "").replace(CONTROL_CHARACTER, "");
+}
 export const RATE_LIMITED_HINT = "Rate limited. Wait for a running review or mergestorm jobs.";
 export function rateLimitedMessage(retryAfterSeconds) {
     if (retryAfterSeconds == null || !Number.isFinite(retryAfterSeconds)) {

package/dist/stack-blockers.d.ts

@@ -6,6 +6,10 @@ export type StackBlocker = {
     blocker: string;
     bounceKind: string | null;
 };
+export type StackBlockerReason = "restack_conflict" | "restack_failed" | "draft_pr" | "merge_conflict" | "ci_failed" | "vortex_failed" | "vortex_out_of_quota" | "vortex_skipped" | "vortex_findings_need_person" | "seam_failed" | "seam_findings" | "seam_not_running" | "seam_review_stuck" | "seam_rereview_not_running" | "seam_verdict_stale" | "unit_abandoned" | "land_gate" | "bounce" | "auto_land_off" | "auto_land_ci_pending" | "auto_land_members_remaining" | "auto_land_vortex_wait" | "auto_land_promote_failed" | "auto_land_ci_unreadable" | "auto_land_waited" | "queue_stalled" | "land_pr_missing";
+export type ClassifiedStackBlocker = StackBlocker & {
+    reason: StackBlockerReason;
+};
 export type StackAgentBusy = {
     prNumber: number;
     headSha: string | null;
@@ -47,20 +51,6 @@ export type StackRepairHint = {
     branch: string;
     failingCheck: string | null;
     steps: string;
-} | {
-    kind: "tempest_findings";
-    prNumber: number;
-    headSha: string | null;
-    branch: string;
-    findings: string;
-    steps: string;
-} | {
-    kind: "tempest_rerun";
-    prNumber: number;
-    headSha: string | null;
-    branch: string;
-    stoppedByPerson: boolean;
-    steps: string;
 } | {
     kind: "vortex_findings";
     prNumber: number;
@@ -120,6 +110,20 @@ export type StackRepairHint = {
     since: string | null;
     waitReason: string | null;
     steps: string;
+} | {
+    kind: "members_remaining" | "vortex_failed";
+    prNumber: number;
+    headSha: string | null;
+    branch: string;
+    detail: string | null;
+    steps: string;
+} | {
+    kind: "land_pr_unavailable";
+    prNumber: number;
+    headSha: string | null;
+    branch: string;
+    detail: string | null;
+    steps: string;
 } | {
     kind: "vortex_skipped";
     prNumber: number;
@@ -160,6 +164,11 @@ export declare const VORTEX_FINDINGS_NEED_PERSON = "Vortex findings need a perso
 export declare const VORTEX_AUTO_REVIEW_OFF = "Vortex auto-review is off, so this head was not reviewed";
 export declare const VORTEX_BILLING_SKIPPED = "Vortex skipped this head: it could not confirm billing";
 export declare const VORTEX_REVIEW_INCOMPLETE = "Vortex reviewed only part of this PR";
+export declare const VORTEX_IGNORED_AUTHOR = "Vortex skipped this head: the PR author is on the ignored authors list";
+export declare const VORTEX_REPO_DISABLED = "Vortex skipped this head: reviews are turned off for this repository";
+export declare const VORTEX_RETRY_SCHEDULED = "Vortex hit a temporary error on this head and will retry by itself";
+export declare const VORTEX_REVIEW_FAILED = "Review failed";
+export declare function vortexRetryScheduled(layer: StackLayerDto): boolean;
 export declare const AUTO_LAND_CI_PENDING_ATTENTION_MS: number;
 export declare const AUTO_LAND_VORTEX_WAIT_ATTENTION_MS: number;
 export declare const AUTO_LAND_PROMOTE_FAILED_ATTEMPTS = 3;
@@ -192,8 +201,9 @@ export declare function restackFailedRepairSteps(branch: string, liveParent: str
     kind: string;
     detail?: string | null;
 }): string;
-export declare function agentsCannotClear(blocker: string): boolean;
-export declare function stackRepair(stack: StackDto, attention: StackBlocker | null, layer: StackLayerDto | undefined, bounce: MergeQueueEntryDto | undefined, queueWait?: MergeQueueWait | null): StackRepairHint | null;
+export declare function agentsCannotClear(reason: StackBlockerReason): boolean;
+export declare function stackRepair(stack: StackDto, attention: ClassifiedStackBlocker | null, layer: StackLayerDto | undefined, bounce: MergeQueueEntryDto | undefined, queueWait?: MergeQueueWait | null): StackRepairHint | null;
+export declare const LAND_PR_MISSING_PREFIX = "No open land PR for ";
 /** 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">, nowMs?: number): {
     attention: null;