@outputai/cli 0.9.0 → 0.9.1-next.2091eae.0

package/dist/services/workflow_history.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/workflow_history.spec.js

@@ -0,0 +1,87 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { getWorkflowIdHistory } from '#api/generated/api.js';
+import { fetchWorkflowHistory } from '#services/workflow_history.js';
+vi.mock('#api/generated/api.js', () => ({ getWorkflowIdHistory: vi.fn() }));
+// The real correlator runs (only the API client is mocked), so spans are derived
+// from the events below — letting us assert duration/offset behaviour end to end.
+const mockGet = getWorkflowIdHistory;
+const T0 = Date.parse('2026-06-22T12:00:00.000Z');
+const at = (seconds) => new Date(T0 + (seconds * 1000)).toISOString();
+const page = (data) => ({ status: 200, data });
+const started = (id, scheduledEventId, sec) => ({
+    eventId: id, eventTypeName: 'ACTIVITY_TASK_STARTED', eventTime: at(sec),
+    activityTaskStartedEventAttributes: { scheduledEventId, attempt: 1 }
+});
+const completed = (id, scheduledEventId, sec) => ({
+    eventId: id, eventTypeName: 'ACTIVITY_TASK_COMPLETED', eventTime: at(sec),
+    activityTaskCompletedEventAttributes: { scheduledEventId }
+});
+const scheduled = (id, name, sec) => ({
+    eventId: id, eventTypeName: 'ACTIVITY_TASK_SCHEDULED', eventTime: at(sec),
+    activityTaskScheduledEventAttributes: { activityType: { name }, activityId: `act-${id}` }
+});
+const workflowStarted = (sec) => ({ eventId: '1', eventTypeName: 'WORKFLOW_EXECUTION_STARTED', eventTime: at(sec) });
+beforeEach(() => mockGet.mockReset());
+describe('fetchWorkflowHistory', () => {
+    it('pages through results, pinning the resolved runId after the first page', async () => {
+        mockGet
+            .mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-123', runId: 'run-456', status: 'completed', startTime: at(0), closeTime: at(300) },
+            runId: 'run-456',
+            events: [workflowStarted(0), scheduled('2', 'contentBrief#compressText', 0)],
+            nextPageToken: 'token-2'
+        }))
+            .mockResolvedValueOnce(page({
+            workflow: null,
+            runId: 'run-456',
+            events: [started('3', '2', 0), completed('4', '2', 27)],
+            nextPageToken: null
+        }));
+        const result = await fetchWorkflowHistory({ workflowId: 'wf-123' });
+        expect(mockGet).toHaveBeenCalledTimes(2);
+        expect(mockGet).toHaveBeenNthCalledWith(1, 'wf-123', { runId: undefined, pageSize: 50, pageToken: undefined, includePayloads: false });
+        // Page 2 echoes the runId the first page resolved (the endpoint requires it once a pageToken is used).
+        expect(mockGet).toHaveBeenNthCalledWith(2, 'wf-123', { runId: 'run-456', pageSize: 50, pageToken: 'token-2', includePayloads: false });
+        expect(result.runId).toBe('run-456');
+        expect(result.workflow?.workflowId).toBe('wf-123'); // metadata is taken from the first page only
+        expect(result.events).toHaveLength(4);
+        expect(result.totalDurationMs).toBe(300_000); // closeTime - startTime
+        expect(result.spans).toHaveLength(1);
+        expect(result.spans[0].durationMs).toBe(27_000);
+    });
+    it('forwards an explicit runId and includePayloads, stopping after a single page', async () => {
+        mockGet.mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-9', runId: 'run-1', status: 'running', startTime: at(0) },
+            runId: 'run-1', events: [], nextPageToken: null
+        }));
+        const result = await fetchWorkflowHistory({ workflowId: 'wf-9', runId: 'run-1', includePayloads: true });
+        expect(mockGet).toHaveBeenCalledTimes(1);
+        expect(mockGet).toHaveBeenCalledWith('wf-9', { runId: 'run-1', pageSize: 50, pageToken: undefined, includePayloads: true });
+        expect(result.runId).toBe('run-1');
+    });
+    it('falls back to the last span end for total duration when there is no closeTime', async () => {
+        mockGet.mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-2', runId: 'run-2', status: 'running', startTime: at(0) },
+            runId: 'run-2',
+            events: [scheduled('2', 'wf#step', 0), started('3', '2', 0), completed('4', '2', 12)],
+            nextPageToken: null
+        }));
+        const result = await fetchWorkflowHistory({ workflowId: 'wf-2' });
+        expect(result.totalDurationMs).toBe(12_000);
+    });
+    it('derives the timeline origin from WORKFLOW_EXECUTION_STARTED when metadata lacks a startTime', async () => {
+        mockGet.mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-3', runId: 'run-3', status: 'completed' }, // no startTime / closeTime
+            runId: 'run-3',
+            events: [workflowStarted(0), scheduled('2', 'wf#step', 5), started('3', '2', 5), completed('4', '2', 10)],
+            nextPageToken: null
+        }));
+        const result = await fetchWorkflowHistory({ workflowId: 'wf-3' });
+        expect(result.spans[0].startOffsetMs).toBe(5_000);
+        expect(result.totalDurationMs).toBe(10_000);
+    });
+    it('throws when the response has no data', async () => {
+        mockGet.mockResolvedValueOnce({ status: 200 });
+        await expect(fetchWorkflowHistory({ workflowId: 'wf-x' })).rejects.toThrow(/invalid response/);
+    });
+});

package/dist/utils/span_labels.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A step's name is per step-TYPE, so a fan-out of N identical activities (e.g.
+ * 9× "Scrape Serp Page") all share one label and become indistinguishable.
+ * Number the repeats in chronological order so each instance is addressable —
+ * "Scrape Serp Page #1", "#2", …. Labels that occur once are left untouched.
+ *
+ * Pass spans in their stored (chronological) order so #1 is the earliest. A
+ * TypeScript port of Atlas's `buildSpanLabels`.
+ */
+import type { Span } from '#services/workflow_history/correlator.js';
+export default function buildSpanLabels(spans: Span[]): Map<string, string>;

package/dist/utils/span_labels.js

@@ -0,0 +1,22 @@
+const baseLabel = (span) => span.description ?? span.name;
+export default function buildSpanLabels(spans) {
+    const totals = new Map();
+    for (const span of spans) {
+        const label = baseLabel(span);
+        totals.set(label, (totals.get(label) ?? 0) + 1);
+    }
+    const seen = new Map();
+    const labels = new Map();
+    for (const span of spans) {
+        const label = baseLabel(span);
+        if ((totals.get(label) ?? 0) > 1) {
+            const n = (seen.get(label) ?? 0) + 1;
+            seen.set(label, n);
+            labels.set(span.id, `${label} #${n}`);
+        }
+        else {
+            labels.set(span.id, label);
+        }
+    }
+    return labels;
+}

package/dist/utils/span_labels.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/span_labels.spec.js

@@ -0,0 +1,36 @@
+import { describe, it, expect } from 'vitest';
+import buildSpanLabels from './span_labels.js';
+const span = (id, name) => ({
+    id,
+    name,
+    technicalName: name,
+    description: null,
+    status: 'completed',
+    kind: 'activity',
+    attempt: 1,
+    startedAt: null,
+    scheduledAt: null,
+    completedAt: null,
+    startOffsetMs: 0,
+    endOffsetMs: 0,
+    durationMs: 0,
+    failureMessage: null
+});
+describe('buildSpanLabels', () => {
+    it('numbers repeated labels chronologically and leaves unique labels untouched', () => {
+        const spans = [
+            span('a', 'Compress Text'),
+            span('b', 'Scrape Serp Page'),
+            span('c', 'Scrape Serp Page'),
+            span('d', 'Scrape Serp Page')
+        ];
+        const labels = buildSpanLabels(spans);
+        expect(labels.get('a')).toBe('Compress Text');
+        expect(labels.get('b')).toBe('Scrape Serp Page #1');
+        expect(labels.get('c')).toBe('Scrape Serp Page #2');
+        expect(labels.get('d')).toBe('Scrape Serp Page #3');
+    });
+    it('returns an empty map for no spans', () => {
+        expect(buildSpanLabels([]).size).toBe(0);
+    });
+});

package/dist/utils/waterfall.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Renders a workflow's correlated spans as a terminal waterfall/Gantt chart —
+ * a text analog of the Agents HQ "Timeline" view. Each row is a step, drawn as
+ * a colored bar positioned by its start offset and sized by its duration, on a
+ * shared time axis.
+ *
+ * The tick math (TICK_STEPS_MS / pickTickStep / formatTickLabel) is a port of
+ * Atlas's `StepGantt`; the bar geometry mirrors its leftPct/widthPct as integer
+ * terminal columns.
+ */
+import type { Span } from '#services/workflow_history/correlator.js';
+export interface WaterfallOptions {
+    width: number;
+    color: boolean;
+    header?: string;
+    labels?: Map<string, string>;
+}
+export interface BarGeometry {
+    startCol: number;
+    barLen: number;
+    instantaneous: boolean;
+}
+export declare const FULL_BLOCK = "\u2588";
+export declare const THIN_BLOCK = "\u258F";
+export declare function pickTickStep(totalMs: number): number;
+export declare function buildTicks(totalMs: number): number[];
+export declare function formatTickLabel(ms: number): string;
+export declare function formatDurationLabel(ms: number): string;
+export declare function computeBar(startOffsetMs: number, endOffsetMs: number, totalMs: number, trackW: number): BarGeometry;
+export declare function buildRulerLine(totalMs: number, trackW: number): string;
+export default function renderWaterfall(spans: Span[], totalDurationMs: number, options: WaterfallOptions): string;

package/dist/utils/waterfall.js

@@ -0,0 +1,192 @@
+const LABEL_MIN = 14;
+const LABEL_MAX = 28;
+const MIN_TRACK = 10;
+export const FULL_BLOCK = '█';
+export const THIN_BLOCK = '▏';
+// Human-friendly step sizes, smallest → largest. Pick the smallest step that
+// yields ~TARGET_TICKS or fewer labels.
+const TICK_STEPS_MS = [
+    100, 250, 500,
+    1_000, 2_000, 5_000, 10_000, 15_000, 30_000,
+    60_000, 2 * 60_000, 5 * 60_000, 10 * 60_000, 15 * 60_000, 30 * 60_000,
+    60 * 60_000, 2 * 60 * 60_000, 6 * 60 * 60_000, 12 * 60 * 60_000, 24 * 60 * 60_000
+];
+const TARGET_TICKS = 8;
+const ANSI = {
+    completed: '',
+    running: '',
+    failed: '',
+    pending: '',
+    dim: '',
+    reset: ''
+};
+function clamp(value, lo, hi) {
+    return Math.min(Math.max(value, lo), hi);
+}
+export function pickTickStep(totalMs) {
+    if (totalMs <= 0) {
+        return 1_000;
+    }
+    const ideal = totalMs / TARGET_TICKS;
+    return TICK_STEPS_MS.find(s => s >= ideal) ?? TICK_STEPS_MS[TICK_STEPS_MS.length - 1];
+}
+export function buildTicks(totalMs) {
+    const step = pickTickStep(totalMs);
+    const count = Math.floor(totalMs / step);
+    return Array.from({ length: count + 1 }, (_, i) => i * step);
+}
+// Round to whole units *before* splitting so a remainder that rounds up to a
+// full unit carries instead of rendering "1m60s" / "1h60m".
+function formatClock(ms) {
+    const totalSec = Math.round(ms / 1_000);
+    if (totalSec < 60) {
+        return `${totalSec}s`;
+    }
+    if (totalSec < 3_600) {
+        const m = Math.floor(totalSec / 60);
+        const s = totalSec % 60;
+        return s === 0 ? `${m}m` : `${m}m${s}s`;
+    }
+    const totalMin = Math.round(ms / 60_000);
+    const h = Math.floor(totalMin / 60);
+    const m = totalMin % 60;
+    return m === 0 ? `${h}h` : `${h}h${m}m`;
+}
+export function formatTickLabel(ms) {
+    if (ms === 0) {
+        return '0';
+    }
+    if (ms < 1_000) {
+        return `${ms}ms`;
+    }
+    return formatClock(ms);
+}
+export function formatDurationLabel(ms) {
+    if (ms < 1_000) {
+        return `${Math.max(0, Math.round(ms))}ms`;
+    }
+    return formatClock(ms);
+}
+// Map a span's [startOffset, endOffset] onto integer columns of a `trackW`-wide
+// lane. Both edges are positioned by their own offset and the length is the gap
+// between them — so the bar always spans start→end. (Rounding a separate width
+// off the start, as before, let the right edge drift past the true end time.)
+// A zero-width span still draws a 1-col marker, clamped to stay inside the lane.
+export function computeBar(startOffsetMs, endOffsetMs, totalMs, trackW) {
+    const safeTotal = Math.max(totalMs, 1);
+    const startCol = clamp(Math.round((startOffsetMs / safeTotal) * trackW), 0, Math.max(0, trackW - 1));
+    const endCol = clamp(Math.round((endOffsetMs / safeTotal) * trackW), startCol, trackW);
+    const span = endCol - startCol;
+    const instantaneous = span <= 0;
+    const barLen = Math.min(Math.max(span, 1), trackW - startCol);
+    return { startCol, barLen, instantaneous };
+}
+function padOrTruncate(text, width) {
+    if (text.length === width) {
+        return text;
+    }
+    if (text.length < width) {
+        return text.padEnd(width);
+    }
+    return `${text.slice(0, width - 1)}…`;
+}
+function truncate(text, width) {
+    return text.length <= width ? text : `${text.slice(0, Math.max(0, width - 1))}…`;
+}
+// First tick aligns left, last tick aligns right, middle ticks center on their
+// position — so labels at 0 % and 100 % don't overflow the lane.
+function tickRawStart(idx, count, col, labelLen, trackW) {
+    if (idx === 0) {
+        return 0;
+    }
+    if (idx === count - 1) {
+        return trackW - labelLen;
+    }
+    return col - Math.floor(labelLen / 2);
+}
+function tickStart(idx, count, col, labelLen, trackW) {
+    return clamp(tickRawStart(idx, count, col, labelLen, trackW), 0, trackW - labelLen);
+}
+// The trackW-wide time-axis ruler (no label gutter, no colour). Exported so the
+// TUI overlay header can render the same ticks the CLI string renderer uses.
+export function buildRulerLine(totalMs, trackW) {
+    const safeTotal = Math.max(totalMs, 1);
+    const ticks = buildTicks(safeTotal);
+    const placements = ticks.reduce((acc, t, idx) => {
+        const label = formatTickLabel(t);
+        const col = Math.min(Math.round((t / safeTotal) * trackW), trackW - 1);
+        const start = tickStart(idx, ticks.length, col, label.length, trackW);
+        if (start <= acc.writtenUntil) {
+            return acc;
+        }
+        return { writtenUntil: start + label.length, items: [...acc.items, { start, label }] };
+    }, { writtenUntil: -1, items: [] });
+    const chars = Array.from({ length: trackW }, () => ' ');
+    for (const { start, label } of placements.items) {
+        [...label].forEach((ch, i) => {
+            chars[start + i] = ch;
+        });
+    }
+    return chars.join('');
+}
+function renderRuler(totalMs, labelW, trackW, tint) {
+    return `${' '.repeat(labelW + 1)}${tint(buildRulerLine(totalMs, trackW), ANSI.dim)}`;
+}
+function renderLegend(tint) {
+    const entry = (status, text) => `${tint(FULL_BLOCK, ANSI[status])} ${text}`;
+    const entries = [
+        entry('completed', 'completed'),
+        entry('running', 'running'),
+        entry('failed', 'failed'),
+        entry('pending', 'pending')
+    ];
+    return tint(entries.join('   '), ANSI.dim);
+}
+// The bars only encode failure as a red lane; surface the reason underneath so a
+// failed run is actionable from the chart alone. `failureMessage` is only
+// populated when the history was fetched with payloads (the server strips it
+// otherwise), so spans without one are simply omitted here.
+function buildFailureLines(spans, labelFor, width, tint) {
+    const failed = spans.filter(span => span.status === 'failed' && span.failureMessage);
+    if (failed.length === 0) {
+        return [];
+    }
+    const lines = failed.map(span => {
+        const message = (span.failureMessage ?? '').replace(/\s+/g, ' ').trim();
+        return tint(truncate(`✗ ${labelFor(span)}: ${message}`, width), ANSI.failed);
+    });
+    return ['', tint('Failures', ANSI.dim), ...lines];
+}
+export default function renderWaterfall(spans, totalDurationMs, options) {
+    const { width, color, header, labels } = options;
+    if (spans.length === 0) {
+        return [header, 'No steps found for this run.'].filter(Boolean).join('\n\n');
+    }
+    const tint = (text, code) => (color ? `${code}${text}${ANSI.reset}` : text);
+    const labelFor = (span) => labels?.get(span.id) ?? span.name;
+    const durationFor = (span) => formatDurationLabel(Math.max(0, span.durationMs));
+    const longestLabel = Math.max(...spans.map(s => labelFor(s).length));
+    const labelW = clamp(longestLabel, LABEL_MIN, LABEL_MAX);
+    const durationW = Math.max(...spans.map(s => durationFor(s).length));
+    const trackW = Math.max(width - labelW - durationW - 2, MIN_TRACK);
+    const rows = spans.map(span => {
+        const label = padOrTruncate(labelFor(span), labelW);
+        const { startCol, barLen, instantaneous } = computeBar(span.startOffsetMs, span.endOffsetMs, totalDurationMs, trackW);
+        const glyph = instantaneous ? THIN_BLOCK : FULL_BLOCK;
+        const leading = ' '.repeat(startCol);
+        const trailing = ' '.repeat(Math.max(trackW - startCol - barLen, 0));
+        const track = `${leading}${tint(glyph.repeat(barLen), ANSI[span.status])}${trailing}`;
+        const duration = tint(durationFor(span).padStart(durationW), ANSI.dim);
+        return `${label} ${track} ${duration}`;
+    });
+    const headerLines = header ? [header, ''] : [];
+    const failureLines = buildFailureLines(spans, labelFor, width, tint);
+    const legendLines = color ? ['', renderLegend(tint)] : [];
+    return [
+        ...headerLines,
+        renderRuler(totalDurationMs, labelW, trackW, tint),
+        ...rows,
+        ...failureLines,
+        ...legendLines
+    ].join('\n');
+}

package/dist/utils/waterfall.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/waterfall.spec.js

@@ -0,0 +1,100 @@
+import { describe, it, expect } from 'vitest';
+import renderWaterfall, { pickTickStep, formatTickLabel, formatDurationLabel, computeBar } from './waterfall.js';
+const span = (id, name, status, startOffsetMs, durationMs) => ({
+    id,
+    name,
+    technicalName: name,
+    description: null,
+    status,
+    kind: 'activity',
+    attempt: 1,
+    startedAt: null,
+    scheduledAt: null,
+    completedAt: null,
+    startOffsetMs,
+    endOffsetMs: startOffsetMs + durationMs,
+    durationMs,
+    failureMessage: null
+});
+describe('pickTickStep', () => {
+    it('targets ~8 ticks by choosing the smallest sufficient step', () => {
+        expect(pickTickStep(0)).toBe(1_000);
+        expect(pickTickStep(8_000)).toBe(1_000);
+        expect(pickTickStep(80_000)).toBe(10_000);
+        expect(pickTickStep(160_000)).toBe(30_000);
+    });
+});
+describe('formatTickLabel', () => {
+    it('formats axis ticks like the UI', () => {
+        expect(formatTickLabel(0)).toBe('0');
+        expect(formatTickLabel(500)).toBe('500ms');
+        expect(formatTickLabel(27_000)).toBe('27s');
+        expect(formatTickLabel(60_000)).toBe('1m');
+        expect(formatTickLabel(72_000)).toBe('1m12s');
+        expect(formatTickLabel(3_600_000)).toBe('1h');
+        expect(formatTickLabel(3_660_000)).toBe('1h1m');
+    });
+});
+describe('formatDurationLabel', () => {
+    it('always shows a unit, including zero', () => {
+        expect(formatDurationLabel(0)).toBe('0ms');
+        expect(formatDurationLabel(999)).toBe('999ms');
+        expect(formatDurationLabel(1_000)).toBe('1s');
+        expect(formatDurationLabel(27_000)).toBe('27s');
+    });
+    it('carries a rounded-up remainder instead of rendering 60s/60m', () => {
+        expect(formatDurationLabel(59_500)).toBe('1m');
+        expect(formatDurationLabel(119_500)).toBe('2m');
+        expect(formatDurationLabel(3_599_500)).toBe('1h');
+    });
+});
+describe('computeBar', () => {
+    it('maps offsets to columns with a min width and lane clamp', () => {
+        expect(computeBar(0, 27_000, 100_000, 50)).toEqual({ startCol: 0, barLen: 14, instantaneous: false });
+        // Zero-duration step → a single thin marker
+        expect(computeBar(50_000, 50_000, 100_000, 50)).toEqual({ startCol: 25, barLen: 1, instantaneous: true });
+        // A short step at the very end is clamped so it stays inside the lane
+        expect(computeBar(99_000, 100_000, 100_000, 50)).toEqual({ startCol: 49, barLen: 1, instantaneous: false });
+    });
+    it('sizes the bar to span start→end without right-edge drift', () => {
+        // Full-span step fills the lane exactly.
+        expect(computeBar(0, 100_000, 100_000, 50)).toEqual({ startCol: 0, barLen: 50, instantaneous: false });
+        // End column is rounded from the true end offset (33), not start + a
+        // separately-rounded width (which used to overshoot to col 34).
+        expect(computeBar(33_000, 66_000, 100_000, 50)).toEqual({ startCol: 17, barLen: 16, instantaneous: false });
+    });
+});
+describe('renderWaterfall', () => {
+    const spans = [
+        span('a', 'Compress Text', 'completed', 0, 27_000),
+        span('b', 'Generate Brief', 'pending', 40_000, 0)
+    ];
+    it('renders labels, bars, durations and a header without color by default', () => {
+        const out = renderWaterfall(spans, 40_000, { width: 70, color: false, header: 'wf-1 · run abcd1234 · running · 40s' });
+        expect(out).toContain('Compress Text');
+        expect(out).toContain('Generate Brief');
+        expect(out).toContain('█');
+        expect(out).toContain('27s');
+        expect(out).toContain('wf-1 · run abcd1234');
+        expect(out).not.toContain('\x1b[');
+    });
+    it('emits ANSI color when enabled', () => {
+        const out = renderWaterfall(spans, 40_000, { width: 70, color: true });
+        expect(out).toContain('\x1b[');
+        expect(out).toContain('\x1b[92m'); // completed → green
+    });
+    it('shows a friendly message when there are no steps', () => {
+        const out = renderWaterfall([], 1, { width: 70, color: false, header: 'wf-1' });
+        expect(out).toContain('No steps found for this run.');
+    });
+    it('lists the reason under the chart for failed steps that carry a message', () => {
+        const failed = { ...span('c', 'Scrape Serp Page', 'failed', 10_000, 2_000), failureMessage: 'connection reset' };
+        const out = renderWaterfall([...spans, failed], 40_000, { width: 70, color: false });
+        expect(out).toContain('Failures');
+        expect(out).toContain('✗ Scrape Serp Page: connection reset');
+    });
+    it('omits the failures section when no failed step has a message', () => {
+        const out = renderWaterfall(spans, 40_000, { width: 70, color: false });
+        expect(out).not.toContain('Failures');
+    });
+});

package/dist/views/dev/dev_app.js

@@ -18,7 +18,8 @@ import { HELP_HINTS, HELP_SECTION_COUNT, HelpPanel } from '#views/dev/panels/hel
 import { RunModal } from '#views/dev/modals/run_modal.js';
 import { ExpandedJsonModal } from '#views/dev/modals/expanded_json_modal.js';
 import { StepsModal } from '#views/dev/modals/steps_modal.js';
-import { MIN_TERMINAL_COLUMNS, MIN_TERMINAL_ROWS } from '#views/dev/utils/constants.js';
+import { StepGraphModal } from '#views/dev/modals/step_graph_modal.js';
+import { MIN_TERMINAL_COLUMNS, MIN_TERMINAL_ROWS } from '#views/dev/utils/ui_constants.js';
 const TAB_NUMBER_KEYS = {
     1: 'workflows',
     2: 'runs',
@@ -65,7 +66,7 @@ const useGlobalInput = (opts) => {
                 .catch(err => exit(err instanceof Error ? err : new Error(String(err))));
             return;
         }
-        if (ui.search.open || ui.runModal.open || ui.expandedJson.open || opts.runDetailOpen) {
+        if (ui.search.open || ui.runModal.open || ui.expandedJson.open || ui.stepGraph.open || opts.runDetailOpen) {
             return;
         }
         // Esc on a list view drops an active filter. Skip when we're on
@@ -133,9 +134,14 @@ const footerFor = (opts) => {
     return { hints: HELP_HINTS, itemCount: HELP_SECTION_COUNT, itemLabel: 'sections' };
 };
 const overlayFor = (opts) => {
+    // expandedJson sits on top of everything — it's popped from another overlay
+    // (e.g. the step graph's `e`), so it must win when both are open.
     if (opts.ui.expandedJson.open) {
         return _jsx(ExpandedJsonModal, {});
     }
+    if (opts.ui.stepGraph.open && opts.stepGraphRun) {
+        return _jsx(StepGraphModal, { run: opts.stepGraphRun, height: opts.rows });
+    }
     if (opts.ui.runModal.open) {
         return _jsx(RunModal, { workflowName: opts.ui.runModal.workflowName, workflowPath: opts.ui.runModal.workflowPath });
     }
@@ -177,6 +183,14 @@ const Shell = ({ dockerComposePath, onCleanup }) => {
         runs.find(r => r.runId === ui.selection.runId && r.workflowId === ui.selection.workflowId) :
         undefined;
     const runDetailOpen = ui.runsView === 'detail' && detailRun !== undefined;
+    // Re-resolve the step-graph run from the polled list each render so its
+    // status/duration stay live; fall back to the snapshot captured at open.
+    const stepGraphRun = useMemo(() => {
+        const captured = ui.stepGraph.open ? ui.stepGraph.run : null;
+        return captured ?
+            (runs.find(r => r.runId === captured.runId && r.workflowId === captured.workflowId) ?? captured) :
+            undefined;
+    }, [ui.stepGraph.open, ui.stepGraph.run, runs]);
     useGlobalInput({ onCleanup, runDetailOpen });
     const failingServices = useMemo(() => services.filter(isServiceFailed).length, [services]);
     const serviceBadge = useMemo(() => {
@@ -210,7 +224,7 @@ const Shell = ({ dockerComposePath, onCleanup }) => {
         serviceCount: services.length,
         phase
     });
-    const overlay = overlayFor({ ui, detailRun, runDetailOpen, rows });
+    const overlay = overlayFor({ ui, detailRun, stepGraphRun, runDetailOpen, rows });
     if (terminalTooSmall) {
         return _jsx(TerminalTooSmall, { rows: rows, cols: cols });
     }

package/dist/views/dev/hooks/use_step_graph.d.ts

@@ -0,0 +1,22 @@
+import { type WorkflowMeta } from '#services/workflow_history.js';
+import type { Span } from '#services/workflow_history/correlator.js';
+export interface StepGraph {
+    spans: Span[];
+    totalDurationMs: number;
+    workflow: WorkflowMeta | null;
+    labels: Map<string, string>;
+    loading: boolean;
+    error: string | null;
+}
+/**
+ * Fetches a run's correlated step spans for the dev TUI's waterfall overlay,
+ * reusing the same `fetchWorkflowHistory` path as the `workflow history` CLI
+ * command. Driven by `usePoll`: while the run is still advancing it re-pulls
+ * every tick so newly scheduled / finished steps appear, then stops and caches
+ * once terminal. The modal ticks the time axis between polls so the right edge
+ * tracks elapsed time.
+ *
+ * A hard fetch failure surfaces as `error` only when nothing has loaded yet — a
+ * transient poll blip keeps the last good chart on screen.
+ */
+export declare const useStepGraph: (workflowId: string | undefined, runId: string | undefined, status?: string) => StepGraph;

package/dist/views/dev/hooks/use_step_graph.js

@@ -0,0 +1,76 @@
+import { useRef, useState } from 'react';
+import { fetchWorkflowHistory } from '#services/workflow_history.js';
+import buildSpanLabels from '#utils/span_labels.js';
+import { isTerminalRunStatus } from '#views/dev/hooks/use_run_detail.js';
+import { usePoll, POLL_INTERVAL_MS } from '#views/dev/hooks/use_poll.js';
+const EMPTY_GRAPH = {
+    spans: [],
+    totalDurationMs: 0,
+    workflow: null,
+    labels: new Map(),
+    loading: false,
+    error: null
+};
+const stepGraphCache = new Map();
+/**
+ * Fetches a run's correlated step spans for the dev TUI's waterfall overlay,
+ * reusing the same `fetchWorkflowHistory` path as the `workflow history` CLI
+ * command. Driven by `usePoll`: while the run is still advancing it re-pulls
+ * every tick so newly scheduled / finished steps appear, then stops and caches
+ * once terminal. The modal ticks the time axis between polls so the right edge
+ * tracks elapsed time.
+ *
+ * A hard fetch failure surfaces as `error` only when nothing has loaded yet — a
+ * transient poll blip keeps the last good chart on screen.
+ */
+export const useStepGraph = (workflowId, runId, status) => {
+    const [graph, setGraph] = useState(EMPTY_GRAPH);
+    const terminal = isTerminalRunStatus(status);
+    const requestKeyRef = useRef('');
+    usePoll(Boolean(workflowId), POLL_INTERVAL_MS, async () => {
+        if (!workflowId) {
+            return 'done';
+        }
+        const key = `${workflowId}:${runId ?? 'latest'}`;
+        requestKeyRef.current = key;
+        const cached = stepGraphCache.get(key);
+        if (cached) {
+            setGraph(cached);
+            return 'done';
+        }
+        setGraph(current => (current.spans.length === 0 ? { ...current, loading: true } : current));
+        try {
+            // Pull payloads so the detail pane can show each step's input/output and
+            // a failed step's reason.
+            const result = await fetchWorkflowHistory({ workflowId, runId, includePayloads: true });
+            if (requestKeyRef.current !== key) {
+                return 'done'; // a different run was selected mid-flight
+            }
+            const next = {
+                spans: result.spans,
+                totalDurationMs: result.totalDurationMs,
+                workflow: result.workflow,
+                labels: buildSpanLabels(result.spans),
+                loading: false,
+                error: null
+            };
+            // Cache only terminal runs — a running run's history is still growing.
+            if (terminal) {
+                stepGraphCache.set(key, next);
+            }
+            setGraph(next);
+        }
+        catch (err) {
+            if (requestKeyRef.current !== key) {
+                return 'done';
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            // Keep the last good chart if a poll blips; only surface a cold failure.
+            setGraph(current => (current.spans.length > 0 ?
+                { ...current, loading: false } :
+                { ...EMPTY_GRAPH, error: message }));
+        }
+        return terminal ? 'done' : 'continue';
+    });
+    return graph;
+};

package/dist/views/dev/modals/step_graph_modal.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+import type { WorkflowRun } from '#services/workflow_runs.js';
+export declare const StepGraphModal: React.FC<{
+    run: WorkflowRun;
+    height: number;
+}>;