merge-steward 0.6.0 → 0.8.0

package/dist/watch/App.js

@@ -35,6 +35,14 @@ export function App({ baseUrl, initialPrNumber }) {
         const entries = snapshot?.entries ?? [];
         return filter === "active" ? entries.filter(isActiveEntry) : entries;
     }, [filter, snapshot?.entries]);
+    // Recently completed entries: terminal entries within the last 60 seconds.
+    const recentlyCompleted = useMemo(() => {
+        if (filter !== "active")
+            return [];
+        const entries = snapshot?.entries ?? [];
+        const cutoff = Date.now() - 60_000;
+        return entries.filter((e) => !isActiveEntry(e) && new Date(e.updatedAt).getTime() > cutoff);
+    }, [filter, snapshot?.entries]);
     const selectedEntry = useMemo(() => visibleEntries.find((entry) => entry.id === selectedEntryId) ?? null, [selectedEntryId, visibleEntries]);
     const activeEntries = useMemo(() => (snapshot?.entries ?? []).filter(isActiveEntry), [snapshot?.entries]);
     const selectedActiveIndex = useMemo(() => {
@@ -188,5 +196,5 @@ export function App({ baseUrl, initialPrNumber }) {
             setSelectedEntryId(nextSelection(visibleEntries, selectedEntryId, "prev"));
         }
     });
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(StatusBar, { snapshot: snapshot, connected: connected, filter: filter, lastSnapshotReceivedAt: lastSnapshotReceivedAt, expectedFreshMs: REFRESH_INTERVAL_MS * 2 }), view === "detail" && selectedEntry && (_jsxs(Box, { children: [_jsx(Text, { dimColor: true, children: "Queue" }), _jsx(Text, { dimColor: true, children: " \u203A " }), _jsxs(Text, { bold: true, children: ["#", selectedEntry.prNumber] }), _jsxs(Text, { dimColor: true, children: [" (", selectedEntry.status, ")"] })] })), view === "list" ? (_jsx(QueueListView, { entries: visibleEntries, selectedEntryId: selectedEntryId, recentEvents: snapshot?.recentEvents ?? [], headEntryId: snapshot?.summary.headEntryId ?? null, queueBlock: snapshot?.queueBlock ?? null })) : (_jsx(DetailView, { detail: detail, isHead: isHeadSelected, activeIndex: selectedActiveIndex, activeCount: activeEntries.length, headPrNumber: snapshot?.summary.headPrNumber ?? null, queueBlock: snapshot?.queueBlock ?? null })), flashMessage && (_jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: flashMessage }) })), _jsx(HelpBar, { view: view })] }));
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(StatusBar, { snapshot: snapshot, connected: connected, filter: filter, lastSnapshotReceivedAt: lastSnapshotReceivedAt, expectedFreshMs: REFRESH_INTERVAL_MS * 2 }), view === "detail" && selectedEntry && (_jsxs(Box, { children: [_jsx(Text, { dimColor: true, children: "Queue" }), _jsx(Text, { dimColor: true, children: " \u203A " }), _jsxs(Text, { bold: true, children: ["#", selectedEntry.prNumber] }), _jsxs(Text, { dimColor: true, children: [" (", selectedEntry.status, ")"] })] })), view === "list" ? (_jsx(QueueListView, { entries: visibleEntries, recentlyCompleted: recentlyCompleted, selectedEntryId: selectedEntryId, recentEvents: snapshot?.recentEvents ?? [], headEntryId: snapshot?.summary.headEntryId ?? null, queueBlock: snapshot?.queueBlock ?? null })) : (_jsx(DetailView, { detail: detail, isHead: isHeadSelected, activeIndex: selectedActiveIndex, activeCount: activeEntries.length, headPrNumber: snapshot?.summary.headPrNumber ?? null, queueBlock: snapshot?.queueBlock ?? null })), flashMessage && (_jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: flashMessage }) })), _jsx(HelpBar, { view: view })] }));
 }

package/dist/watch/DetailView.js

@@ -18,5 +18,5 @@ export function DetailView({ detail, isHead, activeIndex, activeCount, headPrNum
         queueBlock,
     });
     const pipeline = queueProgress(entry.status);
-    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) }), _jsxs(Text, { dimColor: true, children: ["pos ", entry.position] }), _jsxs(Text, { dimColor: true, children: ["generation ", entry.generation] }), _jsxs(Text, { dimColor: true, children: ["retry ", entry.retryAttempts, "/", entry.maxRetries] })] }), _jsx(Text, { children: entry.branch }), _jsxs(Box, { gap: 2, children: [_jsxs(Text, { dimColor: true, children: ["head ", shortSha(entry.headSha)] }), _jsxs(Text, { dimColor: true, children: ["base ", shortSha(entry.baseSha)] }), entry.issueKey && _jsx(Text, { dimColor: true, children: entry.issueKey })] }), _jsxs(Box, { gap: 1, marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "progress" }), _jsx(Text, { children: progressBar(pipeline.current, pipeline.total, 12) }), _jsx(Text, { dimColor: true, children: nextStepLabel(entry.status) })] }), isHead && queueBlock && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Text, { color: "yellow", children: ["Queue paused: ", summarizeQueueBlock(queueBlock) ?? "main branch is unhealthy", "."] }), _jsxs(Text, { dimColor: true, children: [queueBlock.baseBranch, queueBlock.baseSha ? ` @ ${shortSha(queueBlock.baseSha)}` : ""] }), _jsxs(Text, { dimColor: true, children: ["Head PR #", queueBlock.headPrNumber ?? entry.prNumber, " will resume automatically once main recovers."] })] })), entry.maxRetries > 0 && (_jsxs(Box, { gap: 1, marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "retry" }), _jsx(Text, { children: progressBar(entry.retryAttempts, entry.maxRetries, 10) }), _jsxs(Text, { dimColor: true, children: [entry.retryAttempts, "/", entry.maxRetries] })] })), _jsx(EntryStateGraph, { main: graph.main, exits: graph.exits }), _jsx(ExternalRepairObservation, { observations: observations }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Incidents" }), incidents.length === 0 ? (_jsx(Text, { dimColor: true, children: "No 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}`))))] })] }));
+    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) }), _jsxs(Text, { dimColor: true, children: ["pos ", entry.position] }), _jsxs(Text, { dimColor: true, children: ["retry ", entry.retryAttempts, "/", entry.maxRetries] })] }), _jsx(Text, { children: entry.branch }), _jsxs(Box, { gap: 2, children: [_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: "spec" }), _jsx(Text, { children: entry.specBranch }), _jsx(Text, { dimColor: true, children: shortSha(entry.specSha) }), _jsx(Text, { dimColor: true, children: "\u2190" }), _jsx(Text, { dimColor: true, children: entry.specBasedOn ? `entry ${shortSha(entry.specBasedOn)}` : "main" })] })), _jsxs(Box, { gap: 1, marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "progress" }), _jsx(Text, { children: progressBar(pipeline.current, pipeline.total, 12) }), _jsx(Text, { dimColor: true, children: nextStepLabel(entry.status, entry) })] }), isHead && queueBlock && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Text, { color: "yellow", children: ["Queue paused: ", summarizeQueueBlock(queueBlock) ?? "main branch is unhealthy", "."] }), _jsxs(Text, { dimColor: true, children: [queueBlock.baseBranch, queueBlock.baseSha ? ` @ ${shortSha(queueBlock.baseSha)}` : ""] }), _jsxs(Text, { dimColor: true, children: ["Head PR #", queueBlock.headPrNumber ?? entry.prNumber, " will resume automatically once main recovers."] })] })), entry.maxRetries > 0 && (_jsxs(Box, { gap: 1, marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "retry" }), _jsx(Text, { children: progressBar(entry.retryAttempts, entry.maxRetries, 10) }), _jsxs(Text, { dimColor: true, children: [entry.retryAttempts, "/", entry.maxRetries] })] })), _jsx(EntryStateGraph, { main: graph.main, exits: graph.exits }), _jsx(ExternalRepairObservation, { observations: observations }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Incidents" }), incidents.length === 0 ? (_jsx(Text, { dimColor: true, children: "No 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/QueueListView.d.ts

@@ -1,10 +1,11 @@
 import type { QueueBlockState, QueueEntry, QueueEventSummary } from "../types.ts";
 interface QueueListViewProps {
     entries: QueueEntry[];
+    recentlyCompleted: QueueEntry[];
     selectedEntryId: string | null;
     recentEvents: QueueEventSummary[];
     headEntryId: string | null;
     queueBlock: QueueBlockState | null;
 }
-export declare function QueueListView({ entries, selectedEntryId, recentEvents, headEntryId, queueBlock, }: QueueListViewProps): React.JSX.Element;
+export declare function QueueListView({ entries, recentlyCompleted, selectedEntryId, recentEvents, headEntryId, queueBlock, }: QueueListViewProps): React.JSX.Element;
 export {};

package/dist/watch/QueueListView.js

@@ -1,29 +1,45 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useMemo } from "react";
 import { Box, Text, useStdout } from "ink";
-import { formatEventSummary, humanStatus, nextStepLabel, progressBar, queueProgress, relativeTime, statusColor, summarizeQueueBlock, truncate } from "./format.js";
+import { ciStatusIcon, formatEventSummary, humanStatus, nextStepLabel, progressBar, queueProgress, relativeTime, specChainLabel, statusColor, summarizeQueueBlock, truncate } from "./format.js";
+import { TERMINAL_STATUSES } from "../types.js";
 const ENTRY_ROW_HEIGHT = 2;
 const CHROME_ROWS = 13;
-function QueueRow({ entry, selected, infoWidth, isHead, queueBlock, }) {
+const RECENTLY_COMPLETED_MAX_AGE_MS = 60_000;
+function QueueRow({ entry, selected, infoWidth, isHead, queueBlock, allEntries, }) {
     const retryText = `${entry.retryAttempts}/${entry.maxRetries}`;
     const ciText = entry.ciRetries > 0 ? `CI retries ${entry.ciRetries}` : null;
     const blockedOnMain = isHead && queueBlock?.reason === "main_broken" && queueBlock.headPrNumber === entry.prNumber;
-    const renderedStatus = blockedOnMain ? "blocked by broken main" : humanStatus(entry.status);
-    const renderedColor = blockedOnMain ? "red" : statusColor(entry.status);
+    const renderedStatus = blockedOnMain ? "blocked by broken main" : humanStatus(entry.status, entry);
+    const renderedColor = blockedOnMain
+        ? "red"
+        : entry.status === "preparing_head" && entry.lastFailedBaseSha ? "yellow"
+            : statusColor(entry.status);
     const progress = queueProgress(entry.status);
-    const branchLabel = truncate(entry.branch, Math.max(12, infoWidth - 34));
+    const specLabel = entry.specBranch
+        ? specChainLabel(entry, allEntries)
+        : truncate(entry.branch, Math.max(12, infoWidth - 34));
     const nextStep = blockedOnMain
         ? summarizeQueueBlock(queueBlock) ?? "waiting for main to recover"
-        : nextStepLabel(entry.status);
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { color: selected ? "cyan" : "gray", children: selected ? "›" : " " }), _jsx(Text, { color: blockedOnMain ? "red" : isHead ? "green" : "gray", children: blockedOnMain ? "!" : isHead ? "#" : " " }), _jsx(Text, { bold: true, children: ` #${entry.prNumber}` }), entry.issueKey ? _jsx(Text, { children: ` ${entry.issueKey}` }) : null, _jsx(Text, { dimColor: true, children: `  pos ${entry.position}` }), _jsx(Text, { dimColor: true, children: `  ${relativeTime(entry.updatedAt)}` }), _jsx(Text, { children: `  ` }), _jsx(Text, { color: renderedColor, children: renderedStatus })] }), _jsxs(Box, { paddingLeft: 2, gap: 1, children: [_jsx(Text, { dimColor: true, children: progressBar(progress.current, progress.total, 8) }), _jsx(Text, { dimColor: true, children: branchLabel }), _jsx(Text, { dimColor: true, children: "|" }), _jsx(Text, { dimColor: true, children: nextStep }), _jsx(Text, { dimColor: true, children: ` | retry ${retryText}` }), ciText ? (_jsxs(_Fragment, { children: [_jsx(Text, { dimColor: true, children: "|" }), _jsx(Text, { dimColor: true, children: ciText })] })) : null] })] }));
+        : nextStepLabel(entry.status, entry);
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { color: selected ? "cyan" : "gray", children: selected ? "›" : " " }), _jsx(Text, { color: blockedOnMain ? "red" : isHead ? "green" : "gray", children: blockedOnMain ? "!" : isHead ? "#" : " " }), _jsx(Text, { bold: true, children: ` #${entry.prNumber}` }), entry.issueKey ? _jsx(Text, { children: ` ${entry.issueKey}` }) : null, _jsx(Text, { dimColor: true, children: `  pos ${entry.position}` }), _jsx(Text, { dimColor: true, children: `  ${relativeTime(entry.updatedAt)}` }), _jsx(Text, { children: `  ` }), _jsx(Text, { color: renderedColor, children: renderedStatus })] }), _jsxs(Box, { paddingLeft: 2, gap: 1, children: [_jsx(Text, { dimColor: true, children: progressBar(progress.current, progress.total, 8) }), _jsx(Text, { dimColor: true, children: specLabel }), _jsx(Text, { dimColor: true, children: "|" }), _jsx(Text, { dimColor: true, children: nextStep }), _jsx(Text, { dimColor: true, children: ` | retry ${retryText}` }), ciText ? (_jsxs(_Fragment, { children: [_jsx(Text, { dimColor: true, children: "|" }), _jsx(Text, { dimColor: true, children: ciText })] })) : null] })] }));
 }
-export function QueueListView({ entries, selectedEntryId, recentEvents, headEntryId, queueBlock, }) {
+export function QueueListView({ entries, recentlyCompleted, selectedEntryId, recentEvents, headEntryId, queueBlock, }) {
     const { stdout } = useStdout();
     const rows = stdout?.rows ?? 24;
     const cols = stdout?.columns ?? 100;
     const infoWidth = Math.max(32, cols - 4);
-    const eventRows = Math.min(8, Math.max(4, rows - (entries.length * ENTRY_ROW_HEIGHT) - CHROME_ROWS));
+    const totalRows = entries.length + recentlyCompleted.length;
+    const eventRows = Math.min(8, Math.max(4, rows - (totalRows * ENTRY_ROW_HEIGHT) - CHROME_ROWS));
     const displayedEvents = useMemo(() => recentEvents.slice(-eventRows), [eventRows, recentEvents]);
     const queueBlockLabel = summarizeQueueBlock(queueBlock);
-    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [queueBlock && (_jsxs(Box, { marginBottom: 1, flexDirection: "column", children: [_jsxs(Text, { color: "yellow", children: ["Queue paused: ", queueBlockLabel ?? "main is unhealthy", queueBlock.baseSha ? ` at ${truncate(queueBlock.baseSha, 10)}` : "", "."] }), _jsxs(Text, { dimColor: true, children: ["Head PR #", queueBlock.headPrNumber ?? "?", " will resume automatically once main recovers."] })] })), entries.length === 0 ? (_jsx(Text, { dimColor: true, children: "No queue entries in this filter." })) : (entries.map((entry) => (_jsx(QueueRow, { entry: entry, selected: entry.id === selectedEntryId, infoWidth: infoWidth, isHead: entry.id === headEntryId, queueBlock: queueBlock }, entry.id)))), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Recent Events" }), displayedEvents.length === 0 ? (_jsx(Text, { dimColor: true, children: "No queue events yet." })) : (displayedEvents.map((event) => (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: relativeTime(event.at).padStart(4, " ") }), _jsx(Text, { children: formatEventSummary(event) })] }, event.id ?? `${event.entryId}-${event.at}`))))] })] }));
+    // Spec chain: main ─ #A ✓ ─ #B ● ─ #C ○
+    const chainEntries = useMemo(() => {
+        const active = entries.filter((e) => !TERMINAL_STATUSES.includes(e.status));
+        return active.sort((a, b) => a.position - b.position);
+    }, [entries]);
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [chainEntries.length > 0 && (_jsxs(Box, { marginBottom: 1, gap: 0, children: [_jsx(Text, { dimColor: true, children: "main" }), chainEntries.map((entry) => {
+                        const ci = ciStatusIcon(entry);
+                        return (_jsxs(Box, { gap: 0, children: [_jsx(Text, { dimColor: true, children: " \u2500 " }), _jsxs(Text, { bold: true, children: ["#", entry.prNumber] }), _jsx(Text, { color: ci.color, children: ` ${ci.icon}` })] }, entry.id));
+                    })] })), queueBlock && (_jsxs(Box, { marginBottom: 1, flexDirection: "column", children: [_jsxs(Text, { color: "yellow", children: ["Queue paused: ", queueBlockLabel ?? "main is unhealthy", queueBlock.baseSha ? ` at ${truncate(queueBlock.baseSha, 10)}` : "", "."] }), _jsxs(Text, { dimColor: true, children: ["Head PR #", queueBlock.headPrNumber ?? "?", " will resume automatically once main recovers."] })] })), entries.length === 0 && recentlyCompleted.length === 0 ? (_jsx(Text, { dimColor: true, children: "No queue entries in this filter." })) : (_jsxs(_Fragment, { children: [entries.map((entry) => (_jsx(QueueRow, { entry: entry, selected: entry.id === selectedEntryId, infoWidth: infoWidth, isHead: entry.id === headEntryId, queueBlock: queueBlock, allEntries: entries }, entry.id))), recentlyCompleted.length > 0 && (_jsx(_Fragment, { children: recentlyCompleted.map((entry) => (_jsx(Box, { flexDirection: "column", children: _jsxs(Box, { children: [_jsx(Text, { dimColor: true, children: "  " }), _jsx(Text, { color: entry.status === "merged" ? "green" : "red", children: entry.status === "merged" ? "\u2713" : "\u2717" }), _jsx(Text, { dimColor: true, children: ` #${entry.prNumber}` }), entry.issueKey ? _jsx(Text, { dimColor: true, children: ` ${entry.issueKey}` }) : null, _jsx(Text, { dimColor: true, children: `  ${humanStatus(entry.status, entry)}  ${relativeTime(entry.updatedAt)}` })] }) }, entry.id))) }))] })), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Recent Events" }), displayedEvents.length === 0 ? (_jsx(Text, { dimColor: true, children: "No queue events yet." })) : (displayedEvents.map((event) => (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: relativeTime(event.at).padStart(4, " ") }), _jsx(Text, { children: formatEventSummary(event) })] }, event.id ?? `${event.entryId}-${event.at}`))))] })] }));
 }

package/dist/watch/format.d.ts

@@ -2,12 +2,28 @@ import type { CheckResult, QueueBlockState, QueueEntryStatus, QueueEventRecord,
 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 humanStatus(status: QueueEntryStatus): string;
+export declare function humanStatus(status: QueueEntryStatus, entry?: {
+    lastFailedBaseSha: string | null;
+    specBranch: string | null;
+}): string;
 export declare function queueProgress(status: QueueEntryStatus): {
     current: number;
     total: number;
 };
-export declare function nextStepLabel(status: QueueEntryStatus): string;
+export declare function nextStepLabel(status: QueueEntryStatus, entry?: {
+    lastFailedBaseSha: string | null;
+    specBasedOn: string | null;
+}): string;
+/** Describe the spec chain for a queue entry. */
+export declare function specChainLabel(entry: {
+    specBranch: string | null;
+    specBasedOn: string | null;
+    specSha: string | null;
+}, allEntries: Array<{
+    id: string;
+    prNumber: number;
+    specBranch: string | null;
+}>): string;
 export declare function runtimeLabel(runtime: QueueRuntimeStatus): string;
 export declare function formatEventSummary(event: QueueEventSummary): string;
 export declare function formatEntryEvent(event: QueueEventRecord): string;
@@ -15,4 +31,12 @@ export declare function formatDuration(ms: number): string;
 export declare function progressBar(current: number, total: number, width: number): string;
 export declare function truncate(value: string, width: number): string;
 export declare function summarizeCheckNames(checks: CheckResult[], limit?: number): string;
+/** CI status icon for the spec chain summary line. */
+export declare function ciStatusIcon(entry: {
+    status: QueueEntryStatus;
+    ciRunId: string | null;
+}): {
+    icon: string;
+    color: string;
+};
 export declare function summarizeQueueBlock(block: QueueBlockState | null | undefined): string | null;

package/dist/watch/format.js

@@ -38,12 +38,14 @@ export function statusColor(status) {
             return "gray";
     }
 }
-export function humanStatus(status) {
+export function humanStatus(status, entry) {
     switch (status) {
         case "queued":
             return "queued";
         case "preparing_head":
-            return "refreshing branch";
+            if (entry?.lastFailedBaseSha)
+                return "retry-gated";
+            return "building spec";
         case "validating":
             return "running CI";
         case "merging":
@@ -71,16 +73,18 @@ export function queueProgress(status) {
             return { current: 4, total: 4 };
     }
 }
-export function nextStepLabel(status) {
+export function nextStepLabel(status, entry) {
     switch (status) {
         case "queued":
             return "waiting for head-of-line turn";
         case "preparing_head":
-            return "refreshing branch with latest main";
+            if (entry?.lastFailedBaseSha)
+                return "waiting for base to advance";
+            return "building cumulative spec branch";
         case "validating":
-            return "waiting for CI result";
+            return "waiting for CI on spec branch";
         case "merging":
-            return "final GitHub merge";
+            return "pushing spec to main";
         case "merged":
             return "landed on main";
         case "evicted":
@@ -89,6 +93,18 @@ export function nextStepLabel(status) {
             return "removed manually";
     }
 }
+/** Describe the spec chain for a queue entry. */
+export function specChainLabel(entry, allEntries) {
+    if (!entry.specBranch)
+        return "no spec yet";
+    const parent = entry.specBasedOn
+        ? allEntries.find((e) => e.id === entry.specBasedOn)
+        : null;
+    const base = parent
+        ? `#${parent.prNumber}`
+        : "main";
+    return `${shortSha(entry.specSha)} \u2190 ${base}`;
+}
 export function runtimeLabel(runtime) {
     if (runtime.tickInProgress) {
         return "running";
@@ -139,6 +155,22 @@ export function summarizeCheckNames(checks, limit = 3) {
         return names.join(", ");
     return `${names.slice(0, limit).join(", ")} +${names.length - limit} more`;
 }
+/** CI status icon for the spec chain summary line. */
+export function ciStatusIcon(entry) {
+    switch (entry.status) {
+        case "merged": return { icon: "\u2713", color: "green" }; // ✓
+        case "merging": return { icon: "\u2713", color: "cyan" }; // ✓
+        case "evicted": return { icon: "\u2717", color: "red" }; // ✗
+        case "dequeued": return { icon: "\u2012", color: "gray" }; // ‒
+        case "validating":
+            return entry.ciRunId ? { icon: "\u25cf", color: "cyan" } : { icon: "\u25cb", color: "gray" }; // ● or ○
+        case "preparing_head":
+            return { icon: "\u25cb", color: "yellow" }; // ○
+        case "queued":
+        default:
+            return { icon: "\u25cb", color: "gray" }; // ○
+    }
+}
 export function summarizeQueueBlock(block) {
     if (!block)
         return null;

package/dist/watch/state-visualization.js

@@ -96,19 +96,25 @@ export function buildExternalRepairObservations(detail, options) {
     if (entry.lastFailedBaseSha) {
         observations.push({
             tone: "warn",
-            text: `Waiting for ${entry.lastFailedBaseSha.slice(0, 7)} on base to change before retrying rebase.`,
+            text: `Retry-gated: conflict on base ${entry.lastFailedBaseSha.slice(0, 7)}. Waiting for base to advance before rebuilding spec.`,
         });
     }
     else if (entry.status === "validating") {
+        const specNote = entry.specBranch
+            ? `CI running on spec branch ${entry.specBranch}.`
+            : "Waiting on CI for the spec branch.";
+        const cascadeNote = entry.specBasedOn
+            ? " Will merge automatically when head clears (cascade)."
+            : "";
         observations.push({
             tone: "info",
-            text: "Waiting on validation CI for the refreshed head branch.",
+            text: `${specNote}${cascadeNote}`,
         });
     }
     else if (entry.status === "merging") {
         observations.push({
             tone: "info",
-            text: "Validation passed; steward is attempting the GitHub merge.",
+            text: "CI passed; pushing spec branch to main (fast-forward).",
         });
     }
     if (entry.generation > 0) {

package/package.json

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