@outputai/cli 0.8.2-next.edf06bb.0 → 0.9.1-dev.000c5f3.0

package/dist/services/workflow_history/correlator.spec.js

@@ -0,0 +1,116 @@
+import { describe, it, expect } from 'vitest';
+import { correlate } from './correlator.js';
+const T0 = Date.parse('2026-06-22T12:00:00.000Z');
+const at = (seconds) => new Date(T0 + (seconds * 1000)).toISOString();
+// Minimal Temporal-shaped event builders.
+const scheduled = (id, name, sec, input) => ({
+    eventId: id,
+    eventTypeName: 'ACTIVITY_TASK_SCHEDULED',
+    eventTime: at(sec),
+    activityTaskScheduledEventAttributes: { activityType: { name }, activityId: `act-${id}`, input }
+});
+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, result: { ok: true } }
+});
+const failed = (id, scheduledEventId, sec, message) => ({
+    eventId: id,
+    eventTypeName: 'ACTIVITY_TASK_FAILED',
+    eventTime: at(sec),
+    activityTaskFailedEventAttributes: { scheduledEventId, failure: { message } }
+});
+function buildEvents() {
+    return [
+        { eventId: '1', eventTypeName: 'WORKFLOW_EXECUTION_STARTED', eventTime: at(0), workflowExecutionStartedEventAttributes: {} },
+        // Sequential completed activity (0s → 27s)
+        scheduled('2', 'contentBrief#compressText', 0, { text: 'x' }),
+        started('3', '2', 0),
+        completed('4', '2', 27),
+        // Parallel fan-out of the same step: one completes (1s), one fails (8s)
+        scheduled('5', 'contentBrief#scrapeSerpPage', 30),
+        scheduled('6', 'contentBrief#scrapeSerpPage', 30),
+        started('7', '5', 30),
+        started('8', '6', 30),
+        completed('9', '5', 31),
+        failed('10', '6', 38, 'boom'),
+        // Noise steps — must be filtered out
+        scheduled('11', '$shared#callWebhook', 35),
+        started('11s', '11', 35),
+        scheduled('12', '__internal#resolveTrace', 35),
+        // Pending activity (scheduled, never started)
+        scheduled('13', 'contentBrief#generateBrief', 40),
+        // Child workflow (initiatedEventId arrives as a protobuf Long struct)
+        {
+            eventId: '20', eventTypeName: 'START_CHILD_WORKFLOW_EXECUTION_INITIATED', eventTime: at(50),
+            startChildWorkflowExecutionInitiatedEventAttributes: { workflowType: { name: 'subWorkflow' } }
+        },
+        {
+            eventId: '21', eventTypeName: 'CHILD_WORKFLOW_EXECUTION_STARTED', eventTime: at(50),
+            childWorkflowExecutionStartedEventAttributes: { initiatedEventId: { low: 20, high: 0, unsigned: false } }
+        },
+        {
+            eventId: '22', eventTypeName: 'CHILD_WORKFLOW_EXECUTION_COMPLETED', eventTime: at(60),
+            childWorkflowExecutionCompletedEventAttributes: { initiatedEventId: { low: 20, high: 0, unsigned: false }, result: { done: true } }
+        }
+    ];
+}
+describe('correlate', () => {
+    const spans = correlate(buildEvents(), T0);
+    const byId = (id) => spans.find(s => s.id === id);
+    it('filters framework noise steps', () => {
+        expect(spans.every(s => !s.technicalName.startsWith('__internal#'))).toBe(true);
+        expect(spans.some(s => s.technicalName === '$shared#callWebhook')).toBe(false);
+    });
+    it('produces one span per real activity plus the child workflow', () => {
+        expect(spans).toHaveLength(5);
+    });
+    it('returns spans sorted by start offset', () => {
+        const offsets = spans.map(s => s.startOffsetMs);
+        expect(offsets).toEqual([...offsets].sort((a, b) => a - b));
+    });
+    it('correlates a completed activity with humanized name, offset, and duration', () => {
+        const compress = byId('2');
+        expect(compress.name).toBe('Compress Text');
+        expect(compress.status).toBe('completed');
+        expect(compress.startOffsetMs).toBe(0);
+        expect(compress.durationMs).toBe(27_000);
+        expect(compress.attempt).toBe(1);
+        expect(compress.kind).toBe('activity');
+    });
+    it('distinguishes parallel instances of the same step', () => {
+        const ok = byId('5');
+        const bad = byId('6');
+        expect(ok.name).toBe('Scrape Serp Page');
+        expect(ok.status).toBe('completed');
+        expect(ok.startOffsetMs).toBe(30_000);
+        expect(ok.durationMs).toBe(1_000);
+        expect(bad.status).toBe('failed');
+        expect(bad.failureMessage).toBe('boom');
+        expect(bad.durationMs).toBe(8_000);
+    });
+    it('marks a scheduled-only activity pending with a zero-duration span at its scheduled offset', () => {
+        const pending = byId('13');
+        expect(pending.status).toBe('pending');
+        expect(pending.startOffsetMs).toBe(40_000);
+        expect(pending.durationMs).toBe(0);
+    });
+    it('correlates a child workflow via a Long-struct initiatedEventId', () => {
+        const child = byId('child-20');
+        expect(child.name).toBe('Sub Workflow');
+        expect(child.kind).toBe('child_workflow');
+        expect(child.status).toBe('completed');
+        expect(child.startOffsetMs).toBe(50_000);
+        expect(child.durationMs).toBe(10_000);
+    });
+    it('is robust to an empty event list', () => {
+        expect(correlate([], T0)).toEqual([]);
+    });
+});

package/dist/services/workflow_history.d.ts

@@ -0,0 +1,23 @@
+import { type HistoryEvent, type Span } from '#services/workflow_history/correlator.js';
+export interface WorkflowMeta {
+    workflowId?: string;
+    runId?: string;
+    status?: string;
+    startTime?: string;
+    closeTime?: string | null;
+    historyLength?: number;
+    taskQueue?: string;
+}
+export interface FetchWorkflowHistoryOptions {
+    workflowId: string;
+    runId?: string;
+    includePayloads?: boolean;
+}
+export interface WorkflowHistoryResult {
+    workflow: WorkflowMeta | null;
+    runId: string | null;
+    events: HistoryEvent[];
+    spans: Span[];
+    totalDurationMs: number;
+}
+export declare function fetchWorkflowHistory(options: FetchWorkflowHistoryOptions): Promise<WorkflowHistoryResult>;

package/dist/services/workflow_history.js

@@ -0,0 +1,79 @@
+/**
+ * Fetches a workflow run's full Temporal history from the API and correlates the
+ * flat event stream into spans (one per step) the CLI can render as a waterfall.
+ *
+ * Pages through `GET /workflow/{id}/history` (mirroring Atlas's
+ * OutputWorkflows::WorkflowHistory): the first page carries the workflow
+ * metadata and resolves the run ID; subsequent pages echo that run ID alongside
+ * the `nextPageToken` (the endpoint requires runId once a pageToken is used).
+ */
+import { getWorkflowIdHistory } from '#api/generated/api.js';
+import { correlate } from '#services/workflow_history/correlator.js';
+const PAGE_SIZE = 50;
+function toMs(value) {
+    if (!value) {
+        return null;
+    }
+    const ms = Date.parse(String(value));
+    return Number.isNaN(ms) ? null : ms;
+}
+function earliestEventMs(events) {
+    const times = events
+        .map(e => toMs(e.eventTime))
+        .filter((ms) => ms !== null);
+    return times.length > 0 ? Math.min(...times) : null;
+}
+// Timeline origin (0 offset): the workflow's start time, falling back to the
+// WORKFLOW_EXECUTION_STARTED event, then the earliest event seen.
+function workflowStartMs(meta, events) {
+    const fromMeta = toMs(meta?.startTime);
+    if (fromMeta !== null) {
+        return fromMeta;
+    }
+    const started = events.find(e => e.eventTypeName === 'WORKFLOW_EXECUTION_STARTED');
+    const fromStarted = toMs(started?.eventTime);
+    if (fromStarted !== null) {
+        return fromStarted;
+    }
+    return earliestEventMs(events);
+}
+function totalDuration(meta, spans, startMs) {
+    const closeMs = toMs(meta?.closeTime ?? undefined);
+    if (closeMs !== null && startMs !== null && (closeMs - startMs) > 0) {
+        return closeMs - startMs;
+    }
+    const maxEnd = spans.reduce((max, span) => Math.max(max, span.endOffsetMs), 0);
+    return Math.max(maxEnd, 1);
+}
+async function fetchAllPages(workflowId, includePayloads, runId, pageToken, acc) {
+    const response = await getWorkflowIdHistory(workflowId, { runId, pageSize: PAGE_SIZE, pageToken, includePayloads });
+    if (!response.data) {
+        throw new Error('API returned invalid response (missing data)');
+    }
+    const data = response.data;
+    // The generated `data.workflow` is an opaque `{ [key: string]: unknown }`, so
+    // narrow it to WorkflowMeta via `unknown` (its real fields are validated by
+    // the server, mirroring Atlas's metadata shape).
+    const meta = acc.meta ?? data.workflow ?? null;
+    const resolvedRunId = runId ?? data.runId ?? acc.runId;
+    const events = [...acc.events, ...(data.events ?? [])];
+    const nextToken = data.nextPageToken ?? undefined;
+    const nextAcc = { meta, runId: resolvedRunId, events };
+    if (nextToken) {
+        return fetchAllPages(workflowId, includePayloads, resolvedRunId, nextToken, nextAcc);
+    }
+    return nextAcc;
+}
+export async function fetchWorkflowHistory(options) {
+    const { workflowId, runId, includePayloads = false } = options;
+    const { meta, runId: resolvedRunId, events } = await fetchAllPages(workflowId, includePayloads, runId, undefined, { meta: null, runId, events: [] });
+    const startMs = workflowStartMs(meta, events);
+    const spans = correlate(events, startMs);
+    return {
+        workflow: meta,
+        runId: resolvedRunId ?? meta?.runId ?? null,
+        events,
+        spans,
+        totalDurationMs: totalDuration(meta, spans, startMs)
+    };
+}

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 {};