merge-steward 0.14.0 → 0.14.2

package/dist/db/schema.js

@@ -24,6 +24,7 @@ export function ensureSchema(connection) {
       spec_branch TEXT,
       spec_sha TEXT,
       spec_based_on TEXT,
+      wait_detail TEXT,
       post_merge_status TEXT,
       post_merge_sha TEXT,
       post_merge_summary TEXT,
@@ -73,6 +74,7 @@ export function ensureSchema(connection) {
     ensureColumn(connection, "queue_entries", "post_merge_sha", "TEXT");
     ensureColumn(connection, "queue_entries", "post_merge_summary", "TEXT");
     ensureColumn(connection, "queue_entries", "post_merge_checked_at", "TEXT");
+    ensureColumn(connection, "queue_entries", "wait_detail", "TEXT");
     connection.exec(`
     UPDATE queue_entries
        SET post_merge_status = 'pending'

package/dist/db/sqlite-store.d.ts

@@ -12,7 +12,7 @@ export declare class SqliteStore implements QueueStore {
     listActive(repoId: string): QueueEntry[];
     listAll(repoId: string): QueueEntry[];
     insert(entry: QueueEntry): void;
-    transition(entryId: string, to: QueueEntryStatus, patch?: Partial<Pick<QueueEntry, "headSha" | "baseSha" | "ciRunId" | "ciRetries" | "retryAttempts" | "lastFailedBaseSha" | "specBranch" | "specSha" | "specBasedOn" | "postMergeStatus" | "postMergeSha" | "postMergeSummary" | "postMergeCheckedAt">>, detail?: string): void;
+    transition(entryId: string, to: QueueEntryStatus, patch?: Partial<Pick<QueueEntry, "headSha" | "baseSha" | "ciRunId" | "ciRetries" | "retryAttempts" | "lastFailedBaseSha" | "specBranch" | "specSha" | "specBasedOn" | "waitDetail" | "postMergeStatus" | "postMergeSha" | "postMergeSummary" | "postMergeCheckedAt">>, detail?: string): void;
     dequeue(entryId: string): void;
     updateHead(entryId: string, newHeadSha: string): void;
     insertIncident(incident: IncidentRecord): void;

package/dist/db/sqlite-store.js

@@ -22,6 +22,7 @@ function mapEntry(row) {
         specBranch: row.spec_branch === null || row.spec_branch === undefined ? null : String(row.spec_branch),
         specSha: row.spec_sha === null || row.spec_sha === undefined ? null : String(row.spec_sha),
         specBasedOn: row.spec_based_on === null || row.spec_based_on === undefined ? null : String(row.spec_based_on),
+        waitDetail: row.wait_detail === null || row.wait_detail === undefined ? null : String(row.wait_detail),
         postMergeStatus: row.post_merge_status === null || row.post_merge_status === undefined
             ? null
             : String(row.post_merge_status),
@@ -122,10 +123,10 @@ export class SqliteStore {
             this.conn.prepare(`INSERT INTO queue_entries
          (id, repo_id, pr_number, branch, head_sha, base_sha, status, position,
           priority, generation, ci_run_id, ci_retries, retry_attempts,
-          max_retries, last_failed_base_sha, issue_key,
+          max_retries, last_failed_base_sha, issue_key, wait_detail,
           post_merge_status, post_merge_sha, post_merge_summary, post_merge_checked_at,
           enqueued_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(entry.id, entry.repoId, entry.prNumber, entry.branch, entry.headSha, entry.baseSha, entry.status, entry.position, entry.priority, entry.generation, entry.ciRunId, entry.ciRetries, entry.retryAttempts, entry.maxRetries, entry.lastFailedBaseSha, entry.issueKey ?? null, entry.postMergeStatus ?? null, entry.postMergeSha ?? null, entry.postMergeSummary ?? null, entry.postMergeCheckedAt ?? null, entry.enqueuedAt, entry.updatedAt);
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(entry.id, entry.repoId, entry.prNumber, entry.branch, entry.headSha, entry.baseSha, entry.status, entry.position, entry.priority, entry.generation, entry.ciRunId, entry.ciRetries, entry.retryAttempts, entry.maxRetries, entry.lastFailedBaseSha, entry.issueKey ?? null, entry.waitDetail ?? null, entry.postMergeStatus ?? null, entry.postMergeSha ?? null, entry.postMergeSummary ?? null, entry.postMergeCheckedAt ?? null, entry.enqueuedAt, entry.updatedAt);
             this.writeEvent(entry.id, null, entry.status);
         })();
     }
@@ -173,6 +174,13 @@ export class SqliteStore {
                 sets.push("spec_based_on = ?");
                 values.push(patch.specBasedOn);
             }
+            if (patch?.waitDetail !== undefined) {
+                sets.push("wait_detail = ?");
+                values.push(patch.waitDetail);
+            }
+            else if (from !== to) {
+                sets.push("wait_detail = NULL");
+            }
             if (patch?.postMergeStatus !== undefined) {
                 sets.push("post_merge_status = ?");
                 values.push(patch.postMergeStatus);
@@ -210,6 +218,7 @@ export class SqliteStore {
           ci_run_id = NULL, ci_retries = 0, retry_attempts = 0,
           last_failed_base_sha = NULL,
           spec_branch = NULL, spec_sha = NULL, spec_based_on = NULL,
+          wait_detail = NULL,
           post_merge_status = NULL, post_merge_sha = NULL, post_merge_summary = NULL, post_merge_checked_at = NULL,
           updated_at = ?
          WHERE id = ?`).run(newHeadSha, newGen, isoNow(), entryId);

package/dist/reconciler-merge.js

@@ -17,6 +17,7 @@ export async function mergeHead(ctx, entry) {
                 ? "required approval missing"
                 : `review gate not satisfied (${prStatus.reviewDecision ?? "unknown"})`;
         emit(ctx, entry, "merge_waiting_approval", { detail });
+        ctx.store.transition(entry.id, "merging", { waitDetail: detail }, detail);
         return;
     }
     if (prStatus.headSha !== entry.headSha) {
@@ -55,6 +56,7 @@ export async function mergeHead(ctx, entry) {
             // Throwing the spec away here would force a rebuild + re-run of
             // CI that produces the same tree — wasting the speculation.
             emit(ctx, entry, "merge_waiting_main", { detail: "main checks still pending, holding merge" });
+            ctx.store.transition(entry.id, "merging", { waitDetail: "main checks still pending, holding merge" }, "main checks still pending, holding merge");
             return;
         }
         if (mainStatus === "fail") {

package/dist/service-queue.js

@@ -7,6 +7,16 @@ function matchGlob(pattern, value) {
     const regex = new RegExp("^" + pattern.replace(/\*/g, ".*") + "$");
     return regex.test(value);
 }
+function getLatestEvictedEntry(entries, prNumber) {
+    const evicted = entries.filter((entry) => entry.prNumber === prNumber && entry.status === "evicted");
+    evicted.sort((left, right) => {
+        const updatedDelta = Date.parse(right.updatedAt) - Date.parse(left.updatedAt);
+        if (updatedDelta !== 0)
+            return updatedDelta;
+        return right.position - left.position;
+    });
+    return evicted[0];
+}
 export class MergeStewardQueueCommands {
     config;
     policy;
@@ -48,6 +58,7 @@ export class MergeStewardQueueCommands {
             specBranch: null,
             specSha: null,
             specBasedOn: null,
+            waitDetail: null,
             postMergeStatus: null,
             postMergeSha: null,
             postMergeSummary: null,
@@ -100,6 +111,11 @@ export class MergeStewardQueueCommands {
             this.logger.debug({ prNumber }, "PR already queued, skipping admission");
             return false;
         }
+        const latestEvicted = getLatestEvictedEntry(this.store.listAll(this.config.repoId), prNumber);
+        if (latestEvicted?.headSha === headSha) {
+            this.logger.debug({ prNumber, headSha, evictedEntryId: latestEvicted.id }, "PR head matches latest evicted entry, skipping admission until a new push");
+            return false;
+        }
         try {
             const status = await this.github.getStatus(prNumber);
             if (!status.reviewApproved) {

package/dist/store.d.ts

@@ -11,7 +11,7 @@ export interface QueueStore {
     listActive(repoId: string): QueueEntry[];
     listAll(repoId: string): QueueEntry[];
     insert(entry: QueueEntry): void;
-    transition(entryId: string, to: QueueEntryStatus, patch?: Partial<Pick<QueueEntry, "headSha" | "baseSha" | "ciRunId" | "ciRetries" | "retryAttempts" | "lastFailedBaseSha" | "specBranch" | "specSha" | "specBasedOn" | "postMergeStatus" | "postMergeSha" | "postMergeSummary" | "postMergeCheckedAt">>, detail?: string): void;
+    transition(entryId: string, to: QueueEntryStatus, patch?: Partial<Pick<QueueEntry, "headSha" | "baseSha" | "ciRunId" | "ciRetries" | "retryAttempts" | "lastFailedBaseSha" | "specBranch" | "specSha" | "specBasedOn" | "waitDetail" | "postMergeStatus" | "postMergeSha" | "postMergeSummary" | "postMergeCheckedAt">>, detail?: string): void;
     dequeue(entryId: string): void;
     updateHead(entryId: string, newHeadSha: string): void;
     insertIncident(incident: IncidentRecord): void;

package/dist/types.d.ts

@@ -38,6 +38,8 @@ export interface QueueEntry {
     specSha: string | null;
     /** Entry ID of the previous entry this spec branch is based on. Null if based on main. */
     specBasedOn: string | null;
+    /** Optional human-facing wait reason when the entry is blocked inside its current state. */
+    waitDetail?: string | null;
     /** Post-merge verification status for the landed commit on main. */
     postMergeStatus: PostMergeStatus | null;
     /** Commit SHA used when checking post-merge status. */

package/dist/watch/DetailView.js

@@ -17,7 +17,7 @@ export function DetailView({ detail, isHead, activeIndex, activeCount, headPrNum
         headPrNumber,
         queueBlock,
     });
-    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { gap: 2, children: [_jsxs(Text, { bold: true, children: ["#", entry.prNumber] }), entry.issueKey ? _jsx(Text, { children: entry.issueKey }) : null, _jsx(Text, { color: statusColor(entry.status), children: humanStatus(entry.status, entry) }), _jsx(Text, { dimColor: true, children: `· ${nextStepLabel(entry.status, entry)}` })] }), _jsxs(Box, { gap: 2, children: [_jsx(Text, { dimColor: true, children: entry.branch }), _jsxs(Text, { dimColor: true, children: ["head ", shortSha(entry.headSha)] }), _jsxs(Text, { dimColor: true, children: ["base ", shortSha(entry.baseSha)] })] }), entry.specBranch && (_jsxs(Box, { gap: 2, children: [_jsx(Text, { dimColor: true, children: "tested as" }), _jsx(Text, { children: entry.specBranch }), _jsx(Text, { dimColor: true, children: `(${shortSha(entry.specSha)} ← ${entry.specBasedOn ? "PR ahead" : "main"})` })] })), entry.retryAttempts > 0 && (_jsxs(Text, { color: "yellow", children: ["retry ", entry.retryAttempts, "/", entry.maxRetries] })), isHead && queueBlock && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Text, { color: "yellow", children: ["Queue paused: ", summarizeQueueBlock(queueBlock) ?? `waiting for ${queueBlock.baseBranch} checks`, "."] }), _jsx(Text, { dimColor: true, children: queueBlock.missingRequiredChecks.length > 0
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { gap: 2, children: [_jsxs(Text, { bold: true, children: ["#", entry.prNumber] }), entry.issueKey ? _jsx(Text, { children: entry.issueKey }) : null, _jsx(Text, { color: statusColor(entry.status, entry), children: humanStatus(entry.status, entry) }), _jsx(Text, { dimColor: true, children: `· ${nextStepLabel(entry.status, entry)}` })] }), _jsxs(Box, { gap: 2, children: [_jsx(Text, { dimColor: true, children: entry.branch }), _jsxs(Text, { dimColor: true, children: ["head ", shortSha(entry.headSha)] }), _jsxs(Text, { dimColor: true, children: ["base ", shortSha(entry.baseSha)] })] }), entry.specBranch && (_jsxs(Box, { gap: 2, children: [_jsx(Text, { dimColor: true, children: "tested as" }), _jsx(Text, { children: entry.specBranch }), _jsx(Text, { dimColor: true, children: `(${shortSha(entry.specSha)} ← ${entry.specBasedOn ? "PR ahead" : "main"})` })] })), entry.retryAttempts > 0 && (_jsxs(Text, { color: "yellow", children: ["retry ", entry.retryAttempts, "/", entry.maxRetries] })), isHead && queueBlock && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Text, { color: "yellow", children: ["Queue paused: ", summarizeQueueBlock(queueBlock) ?? `waiting for ${queueBlock.baseBranch} checks`, "."] }), _jsx(Text, { dimColor: true, children: queueBlock.missingRequiredChecks.length > 0
                             ? `Fix ${queueBlock.baseBranch} first, then reconcile this repo to resume the queue.`
                             : `Will resume automatically once ${queueBlock.baseBranch} is healthy.` })] })), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "GitHub Policy" }), _jsxs(Text, { dimColor: true, children: ["Required checks: ", githubPolicy.requiredChecks.length > 0 ? githubPolicy.requiredChecks.join(", ") : "(none)"] }), githubPolicy.fetchedAt ? _jsxs(Text, { dimColor: true, children: ["Fetched: ", githubPolicy.fetchedAt] }) : null, githubPolicy.lastRefreshReason ? (_jsxs(Text, { dimColor: true, children: ["Last refresh: ", githubPolicy.lastRefreshReason, githubPolicy.lastRefreshChanged === null ? "" : githubPolicy.lastRefreshChanged ? " (changed)" : " (unchanged)"] })) : null] }), _jsx(EntryStateGraph, { main: graph.main, exits: graph.exits }), _jsx(ExternalRepairObservation, { observations: observations }), incidents.length > 0 && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Incidents" }), incidents.map((incident) => (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: relativeTime(incident.at).padStart(4) }), _jsx(Text, { color: "red", children: incident.failureClass }), _jsx(Text, { dimColor: true, children: incident.outcome })] }, incident.id)))] })), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Events" }), events.length === 0 ? (_jsx(Text, { dimColor: true, children: "No events yet." })) : (events.slice(-16).map((event) => (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: relativeTime(event.at).padStart(4) }), _jsx(Text, { children: formatEntryEvent(event) })] }, event.id ?? `${event.entryId}-${event.at}`))))] })] }));
 }

package/dist/watch/ProjectDetailView.js

@@ -75,7 +75,7 @@ export function ProjectDetailView({ repo, selectedEntryId, detail, filter, }) {
             return `#${entry.prNumber}${ci.icon}`;
         }).join(" ")
         : "empty";
-    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, children: repo.repoId }), _jsx(Text, { children: `  ` }), _jsx(Text, { color: health.color, children: compact ? health.label.slice(0, 5) : health.label })] }), _jsx(Text, { dimColor: true, children: ` ${projectStatsSummary(snapshot, compact)}` }), compact ? null : _jsx(Text, { dimColor: true, children: runtimeSummary(snapshot) }), _jsx(Text, { dimColor: true, children: compact
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, children: repo.repoId }), _jsx(Text, { children: `  ` }), _jsx(Text, { color: health.color, children: health.label })] }), _jsx(Text, { dimColor: true, children: ` ${projectStatsSummary(snapshot, compact)}` }), compact ? null : _jsx(Text, { dimColor: true, children: runtimeSummary(snapshot) }), _jsx(Text, { dimColor: true, children: compact
                     ? `Queue: ${truncate(chainText, width - 10)}`
                     : `Queue: main -> ${truncate(chainText, width - 18)}` }), compact ? null : queueBlockSummary ? _jsx(Text, { color: "yellow", children: queueBlockSummary }) : null, compact ? null : (_jsxs(_Fragment, { children: [_jsxs(Text, { dimColor: true, children: ["GitHub required checks: ", snapshot.githubPolicy.requiredChecks.length > 0 ? snapshot.githubPolicy.requiredChecks.join(", ") : "(none)"] }), snapshot.githubPolicy.fetchedAt ? (_jsxs(Text, { dimColor: true, children: ["Policy fetched ", relativeTime(snapshot.githubPolicy.fetchedAt), " ago", snapshot.githubPolicy.lastRefreshReason
                                 ? ` via ${snapshot.githubPolicy.lastRefreshReason}${snapshot.githubPolicy.lastRefreshChanged === null ? "" : snapshot.githubPolicy.lastRefreshChanged ? " (changed)" : " (unchanged)"}`
@@ -86,8 +86,8 @@ export function ProjectDetailView({ repo, selectedEntryId, detail, filter, }) {
                         const statusColor = entry.status === "evicted" ? "red" : ci.color;
                         const baseStatusText = compact ? compactEntryStatus(entry.status) : humanStatus(entry.status, entry);
                         const statusText = entry.status === "merged" ? `${baseStatusText}: ${postMergeStatusLine(entry)}` : baseStatusText;
-                        return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { color: isSelected ? "cyan" : "gray", children: isSelected ? ">" : " " }), _jsx(Text, { bold: true, children: `#${entry.prNumber}` }), entry.issueKey ? _jsx(Text, { children: ` ${entry.issueKey}` }) : null, _jsx(Text, { children: `  ` }), _jsx(Text, { color: ci.color, children: ci.icon }), _jsx(Text, { color: statusColor, children: ` ${statusText}` }), compact ? null : (_jsxs(_Fragment, { children: [_jsx(Text, { dimColor: true, children: `  updated ${relativeTime(entry.updatedAt)} ago` }), isHead ? _jsx(Text, { dimColor: true, children: `  · ${humanStatus(entry.status, entry)} head` }) : null] }))] }), (isSelected || entry.status === "evicted" || (isHead && queueBlockSummary)) && (_jsx(Box, { paddingLeft: 2, children: _jsx(Text, { dimColor: true, children: truncate(describeEntry(entry, { isHead, queueBlockSummary }), compact ? width - 4 : 110) }) }))] }, entry.id));
+                        return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { color: isSelected ? "cyan" : "gray", children: isSelected ? ">" : " " }), _jsx(Text, { bold: true, children: `#${entry.prNumber}` }), entry.issueKey ? _jsx(Text, { children: ` ${entry.issueKey}` }) : null, _jsx(Text, { children: `  ` }), _jsx(Text, { color: ci.color, children: ci.icon }), _jsx(Text, { color: statusColor, children: ` ${statusText}` }), compact ? null : (_jsxs(_Fragment, { children: [_jsx(Text, { dimColor: true, children: `  updated ${relativeTime(entry.updatedAt)} ago` }), isHead ? _jsx(Text, { dimColor: true, children: `  · ${humanStatus(entry.status, entry)} head` }) : null] }))] }), (isSelected || entry.status === "evicted" || (isHead && queueBlockSummary)) && (_jsx(Box, { paddingLeft: 2, children: _jsx(Text, { dimColor: true, children: describeEntry(entry, { isHead, queueBlockSummary }) }) }))] }, entry.id));
                     }))] }), selectedEntry ? (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: `Selected PR #${selectedEntry.prNumber}` }), compact ? (_jsx(Text, { dimColor: true, children: `head ${shortSha(selectedEntry.headSha)} · base ${shortSha(selectedEntry.baseSha)}` })) : (_jsxs(Text, { dimColor: true, children: [selectedEntry.branch, " \u00B7 head ", shortSha(selectedEntry.headSha), " \u00B7 base ", shortSha(selectedEntry.baseSha)] })), compact ? null : _jsx(Text, { dimColor: true, children: `Test branch: ${specChainLabel(selectedEntry, snapshot.entries)}` }), selectedEntry.status === "merged" ? (_jsx(Text, { dimColor: true, children: `Post-merge: ${postMergeStatusLine(selectedEntry)}${selectedEntry.postMergeCheckedAt ? ` · ${relativeTime(selectedEntry.postMergeCheckedAt)} ago` : ""}` })) : null, detail?.incidents.length
                         ? detail.incidents.slice(-2).map((incident) => (_jsxs(Text, { color: "red", children: [relativeTime(incident.at), " ago \u00B7 ", incident.failureClass, " \u00B7 ", incident.outcome] }, incident.id)))
-                        : null] })) : null, _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: detail ? "Selected PR Activity" : "Recent Project Activity" }), visibleEvents.length === 0 ? (_jsx(Text, { dimColor: true, children: "No queue events yet." })) : (visibleEvents.map((event) => (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: relativeTime(event.at).padStart(4, " ") }), _jsx(Text, { children: truncate(formatEventNarrative(event, selectedEntry ? { prNumber: selectedEntry.prNumber } : {}), compact ? Math.max(12, width - 8) : 106) })] }, "id" in event && event.id ? String(event.id) : `${event.entryId}-${event.at}`))))] })] }));
+                        : null] })) : null, _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: detail ? "Selected PR Activity" : "Recent Project Activity" }), visibleEvents.length === 0 ? (_jsx(Text, { dimColor: true, children: "No queue events yet." })) : (visibleEvents.map((event) => (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: relativeTime(event.at).padStart(4, " ") }), _jsx(Text, { children: formatEventNarrative(event, selectedEntry ? { prNumber: selectedEntry.prNumber } : {}) })] }, "id" in event && event.id ? String(event.id) : `${event.entryId}-${event.at}`))))] })] }));
 }

package/dist/watch/format.d.ts

@@ -2,10 +2,17 @@ import type { CheckResult, PostMergeStatus, QueueBlockState, QueueEntryStatus, Q
 export declare function isPendingMainVerification(block: QueueBlockState | null | undefined): boolean;
 export declare function shortSha(value: string | null | undefined): string;
 export declare function relativeTime(iso: string | null | undefined): string;
-export declare function statusColor(status: QueueEntryStatus): "yellow" | "cyan" | "green" | "red" | "gray";
+export declare function mergeWaitState(entry: {
+    status: QueueEntryStatus;
+    waitDetail?: string | null | undefined;
+} | undefined): "approval" | "main" | null;
+export declare function statusColor(status: QueueEntryStatus, entry?: {
+    waitDetail?: string | null | undefined;
+}): "yellow" | "cyan" | "green" | "red" | "gray";
 export declare function humanStatus(status: QueueEntryStatus, entry?: {
     lastFailedBaseSha: string | null;
     specBranch: string | null;
+    waitDetail?: string | null | undefined;
 }): string;
 export declare function queueProgress(status: QueueEntryStatus): {
     current: number;
@@ -14,6 +21,7 @@ export declare function queueProgress(status: QueueEntryStatus): {
 export declare function nextStepLabel(status: QueueEntryStatus, entry?: {
     lastFailedBaseSha: string | null;
     specBasedOn: string | null;
+    waitDetail?: string | null | undefined;
 }): string;
 /** Describe the spec chain for a queue entry. */
 export declare function specChainLabel(entry: {
@@ -44,6 +52,7 @@ export declare function summarizeCheckNames(checks: CheckResult[], limit?: numbe
 export declare function ciStatusIcon(entry: {
     status: QueueEntryStatus;
     ciRunId: string | null;
+    waitDetail?: string | null | undefined;
     postMergeStatus?: PostMergeStatus | null;
 }): {
     icon: string;

package/dist/watch/format.js

@@ -35,14 +35,28 @@ export function relativeTime(iso) {
     const days = Math.floor(hours / 24);
     return `${days}d`;
 }
-export function statusColor(status) {
+export function mergeWaitState(entry) {
+    if (!entry || entry.status !== "merging" || !entry.waitDetail) {
+        return null;
+    }
+    const detail = entry.waitDetail.toLowerCase();
+    if (detail.includes("approval") || detail.includes("review")) {
+        return "approval";
+    }
+    if (detail.includes("main")) {
+        return "main";
+    }
+    return null;
+}
+export function statusColor(status, entry) {
     switch (status) {
         case "queued":
             return "yellow";
         case "preparing_head":
         case "validating":
-        case "merging":
             return "cyan";
+        case "merging":
+            return mergeWaitState(entry ? { status, waitDetail: entry.waitDetail } : undefined) ? "yellow" : "cyan";
         case "merged":
             return "green";
         case "evicted":
@@ -62,6 +76,12 @@ export function humanStatus(status, entry) {
         case "validating":
             return "testing";
         case "merging":
+            if (mergeWaitState(entry ? { status, waitDetail: entry.waitDetail } : undefined) === "approval") {
+                return "waiting for approval";
+            }
+            if (mergeWaitState(entry ? { status, waitDetail: entry.waitDetail } : undefined) === "main") {
+                return "waiting for main";
+            }
             return "merging";
         case "merged":
             return "merged";
@@ -99,6 +119,12 @@ export function nextStepLabel(status, entry) {
                 ? "CI running, tested together with PRs ahead"
                 : "CI running on combined changes";
         case "merging":
+            if (mergeWaitState(entry ? { status, waitDetail: entry.waitDetail } : undefined) === "approval") {
+                return "waiting for GitHub approval before landing on main";
+            }
+            if (mergeWaitState(entry ? { status, waitDetail: entry.waitDetail } : undefined) === "main") {
+                return "waiting for main checks to settle before landing";
+            }
             return "landing on main";
         case "merged":
             return "landed on main";
@@ -179,6 +205,13 @@ export function formatEventNarrative(event, options = {}) {
         return withDetail(`${prPrefix}started running CI.`, event.detail);
     }
     if (event.toStatus === "merging") {
+        const detail = event.detail?.toLowerCase() ?? "";
+        if (detail.includes("approval") || detail.includes("review")) {
+            return withDetail(`${prPrefix}is waiting for approval before merging to main.`, event.detail);
+        }
+        if (detail.includes("main")) {
+            return withDetail(`${prPrefix}is waiting for main verification before merging.`, event.detail);
+        }
         return withDetail(`${prPrefix}passed CI and started merging to main.`, event.detail);
     }
     if (event.toStatus === "merged") {
@@ -270,7 +303,8 @@ export function ciStatusIcon(entry) {
                 icon: postMergeSymbol(entry.postMergeStatus),
                 color: postMergeColor(entry.postMergeStatus),
             };
-        case "merging": return { icon: "\u2713", color: "cyan" }; // ✓
+        case "merging":
+            return mergeWaitState(entry) ? { icon: QUEUE_SYMBOLS.inProgress, color: "yellow" } : { icon: "\u2713", color: "cyan" };
         case "evicted": return { icon: "\u2717", color: "red" }; // ✗
         case "dequeued": return { icon: "\u2012", color: "gray" }; // ‒
         case "validating":

package/dist/watch/state-visualization.js

@@ -108,7 +108,15 @@ export function buildExternalRepairObservations(detail, options) {
         });
     }
     else if (entry.status === "merging") {
-        observations.push({ tone: "info", text: "CI passed. Landing on main." });
+        if (entry.waitDetail?.toLowerCase().includes("approval") || entry.waitDetail?.toLowerCase().includes("review")) {
+            observations.push({ tone: "warn", text: "CI passed. Merge is blocked until GitHub approval returns." });
+        }
+        else if (entry.waitDetail?.toLowerCase().includes("main")) {
+            observations.push({ tone: "info", text: "CI passed. Waiting for main verification before landing." });
+        }
+        else {
+            observations.push({ tone: "info", text: "CI passed. Landing on main." });
+        }
     }
     return observations.slice(0, 4);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "merge-steward",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "description": "Serial merge queue for GitHub — rebase, CI-gate, and merge PRs one at a time",
   "type": "module",
   "repository": {