@outputai/cli 0.10.0 → 0.10.1-next.09ed166.0

package/dist/services/workflow_history/correlator.js

@@ -24,13 +24,13 @@ const CHILD_TERMINAL_TYPES = [
     'CHILD_WORKFLOW_EXECUTION_TIMED_OUT', 'CHILD_WORKFLOW_EXECUTION_CANCELED',
     'CHILD_WORKFLOW_EXECUTION_TERMINATED', 'START_CHILD_WORKFLOW_EXECUTION_FAILED'
 ];
-function eventTypeName(event) {
+export function eventTypeName(event) {
     return event.eventTypeName ?? '';
 }
 function eventId(event) {
     return String(event.eventId);
 }
-function eventAttributes(event) {
+export function eventAttributes(event) {
     const key = event && Object.keys(event).find(k => k.endsWith('EventAttributes'));
     return key ? event[key] : undefined;
 }

package/dist/services/workflow_history.d.ts

@@ -12,12 +12,40 @@ export interface FetchWorkflowHistoryOptions {
     workflowId: string;
     runId?: string;
     includePayloads?: boolean;
+    longPollTimeoutMs?: number;
 }
 export interface WorkflowHistoryResult {
     workflow: WorkflowMeta | null;
+    rawWorkflow: WorkflowMeta | null;
     runId: string | null;
     events: HistoryEvent[];
     spans: Span[];
     totalDurationMs: number;
+    continuedAsNewRunId: string | null;
+    cursor: WorkflowHistoryCursor;
+}
+/**
+ * Resume state for `fetchWorkflowHistoryUpdates`: the accumulated events (so spans/duration
+ * are always computed over the full history, not just the latest delta), `lastEventId` for
+ * de-duping a replayed page, and `pageToken` — the position that fetched the *current* end of
+ * history, which is itself always a valid resume point (see `fetchPages`) even though the
+ * server's own `nextPageToken` for that position is empty.
+ */
+export interface WorkflowHistoryCursor {
+    pageToken: string | undefined;
+    lastEventId: number;
+    meta: WorkflowMeta | null;
+    runId: string | undefined;
+    events: HistoryEvent[];
 }
 export declare function fetchWorkflowHistory(options: FetchWorkflowHistoryOptions): Promise<WorkflowHistoryResult>;
+/**
+ * Incremental counterpart to `fetchWorkflowHistory`, for a poller (`workflow monitor`) that
+ * calls repeatedly while a workflow is still running. Pass the previous call's `cursor`
+ * (from either function's result) to resume from where it left off instead of re-paging the
+ * whole history; omit it only to start a completely fresh walk.
+ */
+export declare function fetchWorkflowHistoryUpdates(options: FetchWorkflowHistoryOptions, cursor?: WorkflowHistoryCursor): Promise<{
+    result: WorkflowHistoryResult;
+    cursor: WorkflowHistoryCursor;
+}>;

package/dist/services/workflow_history.js

@@ -8,8 +8,20 @@
  * 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';
+import { correlate, eventAttributes, eventTypeName } from '#services/workflow_history/correlator.js';
+import { normalizeWorkflowStatus } from '#utils/normalize_workflow_status.js';
+import { TERMINAL_STATUSES } from '#utils/format_workflow_result.js';
 const PAGE_SIZE = 50;
+// The status here comes from the request's own describe (fresh whenever `wait` is
+// set), so it can report the run closed before the closing event has been paged in.
+function isRunClosed(meta) {
+    const status = normalizeWorkflowStatus(meta?.status);
+    return status === 'continued_as_new' || (status !== undefined && TERMINAL_STATUSES.has(status));
+}
+function numericEventId(event) {
+    const id = Number(event.eventId);
+    return Number.isFinite(id) ? id : 0;
+}
 function toMs(value) {
     if (!value) {
         return null;
@@ -37,6 +49,13 @@ function workflowStartMs(meta, events) {
     }
     return earliestEventMs(events);
 }
+// The paginated history endpoint doesn't surface a resolved `newRunId` the way
+// the SSE stream endpoint does (see `stream_history.js`'s `doneChunk`), so pull
+// it directly off the WORKFLOW_EXECUTION_CONTINUED_AS_NEW event when present.
+function continuedAsNewRunId(events) {
+    const terminal = events.find(e => eventTypeName(e) === 'WORKFLOW_EXECUTION_CONTINUED_AS_NEW');
+    return eventAttributes(terminal)?.newExecutionRunId ?? null;
+}
 function totalDuration(meta, spans, startMs) {
     const closeMs = toMs(meta?.closeTime ?? undefined);
     if (closeMs !== null && startMs !== null && (closeMs - startMs) > 0) {
@@ -45,35 +64,99 @@ function totalDuration(meta, spans, 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 });
+/**
+ * Pages through history starting from `acc` (its `pageToken`/`lastEventId`/`events` carry
+ * the resume position — pass a zeroed cursor for a fresh walk). When `longPollTimeoutMs` is
+ * set, every request asks the server to long-poll (`waitNewEvent`) rather than return
+ * immediately, so the final hop blocks — up to that many milliseconds (clamped to the server's
+ * ceiling) — until either a new event exists or the deadline elapses. `lastEventId` de-dupes:
+ * resuming from a previously-seen page token replays that page's events, which are filtered out
+ * here rather than appended twice.
+ */
+async function fetchPages(workflowId, includePayloads, acc, longPollTimeoutMs) {
+    const wait = longPollTimeoutMs !== undefined && longPollTimeoutMs > 0;
+    const { pageToken, runId } = acc;
+    const response = await getWorkflowIdHistory(workflowId, {
+        runId, pageSize: PAGE_SIZE, pageToken, includePayloads,
+        ...(wait ? { longPollTimeoutMs } : {})
+    });
     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;
+    // the server, mirroring Atlas's metadata shape). Prefer the *fresh* value when the
+    // server sent one — it re-describes on every `wait` call specifically so status
+    // updates (e.g. running -> completed) are seen; falling back to `acc.meta` only
+    // covers the pages within a walk where the server didn't re-describe.
+    const meta = data.workflow ?? acc.meta;
     const resolvedRunId = runId ?? data.runId ?? acc.runId;
-    const events = [...acc.events, ...(data.events ?? [])];
+    const pageEvents = data.events ?? [];
+    const newEvents = pageEvents.filter(event => numericEventId(event) > acc.lastEventId);
+    const events = [...acc.events, ...newEvents];
+    // Events arrive in increasing eventId order, so the last new one is the max — no scan needed.
+    const lastEventId = newEvents.length > 0 ? numericEventId(newEvents[newEvents.length - 1]) : acc.lastEventId;
     const nextToken = data.nextPageToken ?? undefined;
-    const nextAcc = { meta, runId: resolvedRunId, events };
+    const nextAcc = { meta, runId: resolvedRunId, events, lastEventId, pageToken: nextToken ?? pageToken };
+    // While long-polling an open run, stop and hand back the first batch of new events
+    // instead of draining further pages — a poller needs each transition rendered as it
+    // arrives, and the buffered remainder will surface on subsequent ticks. Once the run
+    // is closed, though, no further ticks are coming: the poller acts on the closed
+    // status immediately, so stopping early would strand the trailing pages — including
+    // the terminal or CONTINUED_AS_NEW event — unfetched. Drain to the tip instead.
+    if (wait && newEvents.length > 0 && !isRunClosed(meta)) {
+        return nextAcc;
+    }
+    // The server echoes `pageToken` back unchanged (see `get_history.js`) when a waitNewEvent
+    // call's deadline elapses with nothing new — that's the tip, stop for this tick.
+    const timedOut = wait && nextToken === pageToken;
+    if (timedOut) {
+        return nextAcc;
+    }
     if (nextToken) {
-        return fetchAllPages(workflowId, includePayloads, resolvedRunId, nextToken, nextAcc);
+        return fetchPages(workflowId, includePayloads, nextAcc, longPollTimeoutMs);
     }
+    // Drained: the server has nothing more buffered (`nextToken` is empty), but unlike
+    // `nextToken`, `pageToken` — the position that fetched this now-empty page — is still a
+    // valid resume point: a future waitNewEvent call from here replays this page (de-duped by
+    // `lastEventId`) and then genuinely waits at the tip, instead of restarting from page 1.
     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: [] });
+function buildResult(pages) {
+    const { meta: rawMeta, runId: resolvedRunId, events } = pages;
+    // Normalize once here so every consumer (monitor, history, etc.) sees the
+    // same status vocabulary, matching status.ts/workflow_runs.ts/etc.
+    const status = normalizeWorkflowStatus(rawMeta?.status);
+    const meta = rawMeta ? { ...rawMeta, status } : rawMeta;
     const startMs = workflowStartMs(meta, events);
     const spans = correlate(events, startMs);
     return {
         workflow: meta,
+        rawWorkflow: rawMeta,
         runId: resolvedRunId ?? meta?.runId ?? null,
         events,
         spans,
-        totalDurationMs: totalDuration(meta, spans, startMs)
+        totalDurationMs: totalDuration(meta, spans, startMs),
+        continuedAsNewRunId: continuedAsNewRunId(events),
+        cursor: pages
     };
 }
+export async function fetchWorkflowHistory(options) {
+    const { workflowId, runId, includePayloads = false } = options;
+    const pages = await fetchPages(workflowId, includePayloads, { meta: null, runId, events: [], lastEventId: 0, pageToken: undefined });
+    return buildResult(pages);
+}
+/**
+ * Incremental counterpart to `fetchWorkflowHistory`, for a poller (`workflow monitor`) that
+ * calls repeatedly while a workflow is still running. Pass the previous call's `cursor`
+ * (from either function's result) to resume from where it left off instead of re-paging the
+ * whole history; omit it only to start a completely fresh walk.
+ */
+export async function fetchWorkflowHistoryUpdates(options, cursor) {
+    const { workflowId, includePayloads = false, longPollTimeoutMs } = options;
+    const seed = cursor ??
+        { meta: null, runId: options.runId, events: [], lastEventId: 0, pageToken: undefined };
+    const pages = await fetchPages(workflowId, includePayloads, seed, longPollTimeoutMs);
+    return { result: buildResult(pages), cursor: pages };
+}

package/dist/services/workflow_history.spec.js

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { getWorkflowIdHistory } from '#api/generated/api.js';
-import { fetchWorkflowHistory } from '#services/workflow_history.js';
+import { fetchWorkflowHistory, fetchWorkflowHistoryUpdates } 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.
@@ -48,6 +48,39 @@ describe('fetchWorkflowHistory', () => {
         expect(result.totalDurationMs).toBe(300_000); // closeTime - startTime
         expect(result.spans).toHaveLength(1);
         expect(result.spans[0].durationMs).toBe(27_000);
+        // Even though the server's own nextPageToken for the final page is empty (nothing more
+        // buffered), the cursor keeps the *request* token that reached it — a genuinely resumable
+        // position for a follow-up fetchWorkflowHistoryUpdates call. See fetchPages.
+        expect(result.cursor.pageToken).toBe('token-2');
+    });
+    it('a follow-up fetchWorkflowHistoryUpdates call resumes from fetchWorkflowHistory\'s cursor instead of re-paging from page 1', async () => {
+        mockGet
+            .mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-123', runId: 'run-456', status: 'running', startTime: at(0) },
+            runId: 'run-456',
+            events: [workflowStarted(0), scheduled('2', 'wf#step', 0)],
+            nextPageToken: 'token-2'
+        }))
+            .mockResolvedValueOnce(page({
+            workflow: null,
+            runId: 'run-456',
+            events: [started('3', '2', 0)],
+            nextPageToken: null
+        }));
+        const first = await fetchWorkflowHistory({ workflowId: 'wf-123' });
+        expect(mockGet).toHaveBeenCalledTimes(2);
+        // The next tick replays the last page (deduped) then finds nothing new and times out —
+        // one call, not a full re-walk from page 1 through both prior pages again.
+        mockGet.mockResolvedValueOnce(page({
+            workflow: null, runId: 'run-456', events: [], nextPageToken: 'token-2'
+        }));
+        const { result, cursor } = await fetchWorkflowHistoryUpdates({ workflowId: 'wf-123', runId: 'run-456', longPollTimeoutMs: 2500 }, first.cursor);
+        expect(mockGet).toHaveBeenCalledTimes(3);
+        expect(mockGet).toHaveBeenNthCalledWith(3, 'wf-123', {
+            runId: 'run-456', pageSize: 50, pageToken: 'token-2', includePayloads: false, longPollTimeoutMs: 2500
+        });
+        expect(result.events).toHaveLength(3);
+        expect(cursor.pageToken).toBe('token-2');
     });
     it('forwards an explicit runId and includePayloads, stopping after a single page', async () => {
         mockGet.mockResolvedValueOnce(page({
@@ -84,4 +117,153 @@ describe('fetchWorkflowHistory', () => {
         mockGet.mockResolvedValueOnce({ status: 200 });
         await expect(fetchWorkflowHistory({ workflowId: 'wf-x' })).rejects.toThrow(/invalid response/);
     });
+    it('extracts the chained run id from a WORKFLOW_EXECUTION_CONTINUED_AS_NEW event', async () => {
+        mockGet.mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-4', runId: 'run-4', status: 'continued_as_new', startTime: at(0) },
+            runId: 'run-4',
+            events: [
+                workflowStarted(0),
+                {
+                    eventId: '9', eventTypeName: 'WORKFLOW_EXECUTION_CONTINUED_AS_NEW', eventTime: at(60),
+                    workflowExecutionContinuedAsNewEventAttributes: { newExecutionRunId: 'run-5' }
+                }
+            ],
+            nextPageToken: null
+        }));
+        const result = await fetchWorkflowHistory({ workflowId: 'wf-4' });
+        expect(result.continuedAsNewRunId).toBe('run-5');
+    });
+    it('returns null continuedAsNewRunId when there is no continue-as-new event', async () => {
+        mockGet.mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-5', runId: 'run-5', status: 'completed', startTime: at(0), closeTime: at(1) },
+            runId: 'run-5', events: [workflowStarted(0)], nextPageToken: null
+        }));
+        const result = await fetchWorkflowHistory({ workflowId: 'wf-5' });
+        expect(result.continuedAsNewRunId).toBeNull();
+    });
+});
+describe('fetchWorkflowHistoryUpdates', () => {
+    it('stops as soon as the first hop finds new events, without draining further buffered pages', async () => {
+        // Two pages already exist beyond the resume point; the old behavior kept paging until a
+        // timeout, which could silently merge several transitions (even a terminal one) into a
+        // single delayed render. A poller needs each batch back as soon as it has something new.
+        mockGet.mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-7', runId: 'run-7', status: 'running', startTime: at(0) },
+            runId: 'run-7',
+            events: [workflowStarted(0)],
+            nextPageToken: 'page-2'
+        }));
+        const { result, cursor } = await fetchWorkflowHistoryUpdates({ workflowId: 'wf-7', runId: 'run-7', longPollTimeoutMs: 2500 });
+        expect(mockGet).toHaveBeenCalledTimes(1);
+        expect(mockGet).toHaveBeenCalledWith('wf-7', {
+            runId: 'run-7', pageSize: 50, pageToken: undefined, includePayloads: false, longPollTimeoutMs: 2500
+        });
+        expect(result.events).toHaveLength(1);
+        expect(result.workflow?.status).toBe('running');
+        // Resumes from the still-unfetched page 2 next time, not from the start.
+        expect(cursor.pageToken).toBe('page-2');
+        expect(cursor.lastEventId).toBe(1);
+    });
+    it('drains buffered pages when the describe already reports the run closed, so the terminal events are not stranded', async () => {
+        // >1 page of events accumulated between polls, then the run completed: the fresh
+        // describe says 'completed' before the closing events have been paged in. Stopping
+        // after the first batch would make the poller act on the terminal status with the
+        // final steps' events unfetched.
+        mockGet
+            .mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-8', runId: 'run-8', status: 'completed', startTime: at(0), closeTime: at(30) },
+            runId: 'run-8',
+            events: [workflowStarted(0), scheduled('2', 'wf#step', 0)],
+            nextPageToken: 'page-2'
+        }))
+            .mockResolvedValueOnce(page({
+            workflow: null,
+            runId: 'run-8',
+            events: [started('3', '2', 1), completed('4', '2', 30)],
+            nextPageToken: null
+        }));
+        const { result } = await fetchWorkflowHistoryUpdates({ workflowId: 'wf-8', runId: 'run-8' });
+        expect(mockGet).toHaveBeenCalledTimes(2);
+        expect(result.events).toHaveLength(4);
+        expect(result.spans).toHaveLength(1);
+        expect(result.spans[0].status).toBe('completed');
+    });
+    it('drains to the CONTINUED_AS_NEW event on a later page when the describe already reports continued_as_new', async () => {
+        mockGet
+            .mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-9', runId: 'run-9', status: 'continued_as_new', startTime: at(0) },
+            runId: 'run-9',
+            events: [workflowStarted(0)],
+            nextPageToken: 'page-2'
+        }))
+            .mockResolvedValueOnce(page({
+            workflow: null,
+            runId: 'run-9',
+            events: [{
+                    eventId: '2', eventTypeName: 'WORKFLOW_EXECUTION_CONTINUED_AS_NEW', eventTime: at(60),
+                    workflowExecutionContinuedAsNewEventAttributes: { newExecutionRunId: 'run-10' }
+                }],
+            nextPageToken: null
+        }));
+        const { result } = await fetchWorkflowHistoryUpdates({ workflowId: 'wf-9', runId: 'run-9' });
+        expect(mockGet).toHaveBeenCalledTimes(2);
+        expect(result.continuedAsNewRunId).toBe('run-10');
+    });
+    it('forwards longPollTimeoutMs to the API on a resumed poll', async () => {
+        mockGet.mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-7', runId: 'run-7', status: 'running', startTime: at(0) },
+            runId: 'run-7', events: [], nextPageToken: null
+        }));
+        await fetchWorkflowHistoryUpdates({ workflowId: 'wf-7', runId: 'run-7', longPollTimeoutMs: 2500 });
+        expect(mockGet).toHaveBeenCalledWith('wf-7', {
+            runId: 'run-7', pageSize: 50, pageToken: undefined, includePayloads: false, longPollTimeoutMs: 2500
+        });
+    });
+    it('sends no long-poll param when longPollTimeoutMs is not provided', async () => {
+        mockGet.mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-7', runId: 'run-7', status: 'running', startTime: at(0) },
+            runId: 'run-7', events: [], nextPageToken: null
+        }));
+        await fetchWorkflowHistoryUpdates({ workflowId: 'wf-7', runId: 'run-7' });
+        expect(mockGet).toHaveBeenCalledWith('wf-7', expect.not.objectContaining({ longPollTimeoutMs: expect.anything() }));
+    });
+    it('times out with the sent token echoed back when there is genuinely nothing new', async () => {
+        mockGet.mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-7', runId: 'run-7', status: 'running', startTime: at(0) },
+            runId: 'run-7',
+            events: [],
+            nextPageToken: null
+        }));
+        const { result, cursor } = await fetchWorkflowHistoryUpdates({ workflowId: 'wf-7', runId: 'run-7' });
+        expect(mockGet).toHaveBeenCalledTimes(1);
+        expect(result.events).toHaveLength(0);
+        expect(cursor.pageToken).toBeUndefined();
+    });
+    it('resumes from a prior cursor and picks up the workflow status finishing, not the status frozen on the cursor', async () => {
+        const cursor = {
+            pageToken: 'token-2',
+            lastEventId: 2,
+            meta: { workflowId: 'wf-6', runId: 'run-6', status: 'running', startTime: at(0) },
+            runId: 'run-6',
+            events: [workflowStarted(0), scheduled('2', 'wf#step', 0)]
+        };
+        mockGet.mockResolvedValueOnce(page({
+            // The server re-describes on every `wait` call specifically so a resumed poll can see
+            // status changes — this must win over the (now-stale) status carried on the cursor.
+            workflow: { workflowId: 'wf-6', runId: 'run-6', status: 'completed', startTime: at(0), closeTime: at(5) },
+            runId: 'run-6',
+            events: [started('3', '2', 1), completed('4', '2', 5)],
+            nextPageToken: null
+        }));
+        const { result, cursor: nextCursor } = await fetchWorkflowHistoryUpdates({ workflowId: 'wf-6', runId: 'run-6', longPollTimeoutMs: 2500 }, cursor);
+        expect(mockGet).toHaveBeenCalledTimes(1);
+        expect(mockGet).toHaveBeenCalledWith('wf-6', {
+            runId: 'run-6', pageSize: 50, pageToken: 'token-2', includePayloads: false, longPollTimeoutMs: 2500
+        });
+        expect(result.workflow?.status).toBe('completed');
+        // The events already carried on the cursor (2) plus the genuinely new ones (2).
+        expect(result.events).toHaveLength(4);
+        expect(nextCursor.pageToken).toBe('token-2');
+        expect(nextCursor.lastEventId).toBe(4);
+    });
 });

package/dist/utils/color.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Standard TTY/env precedence for whether a command should colorize its
+ * output: the command's own --color/--no-color flag wins first, then
+ * NO_COLOR opts out, then FORCE_COLOR opts in even off a TTY, then finally
+ * fall back to whether stdout is an interactive terminal.
+ */
+export declare function shouldColorize(flag: boolean): boolean;

package/dist/utils/color.js

@@ -0,0 +1,12 @@
+/**
+ * Standard TTY/env precedence for whether a command should colorize its
+ * output: the command's own --color/--no-color flag wins first, then
+ * NO_COLOR opts out, then FORCE_COLOR opts in even off a TTY, then finally
+ * fall back to whether stdout is an interactive terminal.
+ */
+export function shouldColorize(flag) {
+    // Per the NO_COLOR convention (https://no-color.org/), presence disables color
+    // regardless of value — `NO_COLOR=` must opt out just like `NO_COLOR=1`.
+    return flag && process.env.NO_COLOR === undefined &&
+        (!!process.env.FORCE_COLOR || process.stdout.isTTY === true);
+}

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

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

package/dist/utils/color.spec.js

@@ -0,0 +1,43 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { shouldColorize } from '#utils/color.js';
+describe('shouldColorize', () => {
+    const originalEnv = { ...process.env };
+    const originalTTY = process.stdout.isTTY;
+    beforeEach(() => {
+        delete process.env.NO_COLOR;
+        delete process.env.FORCE_COLOR;
+        Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true });
+    });
+    afterEach(() => {
+        process.env = { ...originalEnv };
+        Object.defineProperty(process.stdout, 'isTTY', { value: originalTTY, configurable: true });
+    });
+    it('returns false when the flag itself is false', () => {
+        expect(shouldColorize(false)).toBe(false);
+    });
+    it('returns true on a TTY with no overrides', () => {
+        expect(shouldColorize(true)).toBe(true);
+    });
+    it('disables color when NO_COLOR is set to a non-empty value', () => {
+        process.env.NO_COLOR = '1';
+        expect(shouldColorize(true)).toBe(false);
+    });
+    it('disables color when NO_COLOR is present but empty, per the NO_COLOR convention', () => {
+        process.env.NO_COLOR = '';
+        expect(shouldColorize(true)).toBe(false);
+    });
+    it('enables color off a TTY when FORCE_COLOR is set', () => {
+        Object.defineProperty(process.stdout, 'isTTY', { value: false, configurable: true });
+        process.env.FORCE_COLOR = '1';
+        expect(shouldColorize(true)).toBe(true);
+    });
+    it('disables color off a TTY with no FORCE_COLOR', () => {
+        Object.defineProperty(process.stdout, 'isTTY', { value: false, configurable: true });
+        expect(shouldColorize(true)).toBe(false);
+    });
+    it('NO_COLOR wins even when FORCE_COLOR is also set', () => {
+        process.env.FORCE_COLOR = '1';
+        process.env.NO_COLOR = '1';
+        expect(shouldColorize(true)).toBe(false);
+    });
+});

package/dist/utils/format_workflow_result.d.ts

@@ -1,5 +1,6 @@
 import type { WorkflowResultResponse, WorkflowResultResponseStatus } from '../api/generated/api.js';
 type WorkflowResult = Pick<WorkflowResultResponse, 'workflowId' | 'output' | 'status' | 'error'>;
 export declare const ERROR_STATUSES: ReadonlySet<WorkflowResultResponseStatus | undefined>;
+export declare const TERMINAL_STATUSES: ReadonlySet<string>;
 export declare function formatWorkflowResult(result: WorkflowResult): string;
 export {};

package/dist/utils/format_workflow_result.js

@@ -1,5 +1,9 @@
 import { normalizeWorkflowStatus } from './normalize_workflow_status.js';
 export const ERROR_STATUSES = new Set(['failed', 'canceled', 'terminated', 'timed_out']);
+// Every error status plus the one success status — derived so the two sets can't
+// silently drift apart as error statuses evolve. Shared by `workflow monitor` and
+// the dev TUI's `useRunDetail`/`useStepGraph` so both agree on what "done" means.
+export const TERMINAL_STATUSES = new Set(['completed', ...ERROR_STATUSES]);
 export function formatWorkflowResult(result) {
     const status = normalizeWorkflowStatus(result.status);
     const lines = [

package/dist/utils/monitor_log.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Turns newly-correlated spans into append-only status lines for `workflow
+ * monitor`. Unlike the waterfall (which needs the full span set up front to
+ * lay out a time axis), a live monitor just reports each span's status
+ * transitions as they're observed on each poll.
+ */
+import type { Span, SpanStatus } from '#services/workflow_history/correlator.js';
+export interface SpanUpdate {
+    span: Span;
+    label: string;
+}
+/**
+ * Returns spans whose status changed since the last call. `seen` is mutated
+ * in place so callers can carry it across polls. Pending spans are skipped —
+ * nothing worth reporting until a step starts.
+ */
+export declare function diffSpanUpdates(spans: Span[], labels: Map<string, string>, seen: Map<string, SpanStatus>): SpanUpdate[];
+/** Formats the continue-as-new transition line, keeping its glyph in the formatting layer. */
+export declare function formatContinuedAsNew(runId: string): string;
+export declare function formatSpanUpdate(update: SpanUpdate, color: boolean): string;

package/dist/utils/monitor_log.js

@@ -0,0 +1,48 @@
+import { ANSI, formatDurationLabel, makeTint } from '#utils/waterfall.js';
+const GLYPH = {
+    pending: '·',
+    running: '●',
+    completed: '✓',
+    failed: '✗'
+};
+// Continue-as-new is a workflow-level transition, not a span status, so it gets its own glyph
+// here in the formatting layer rather than being concatenated into the message at the call site.
+const CONTINUED_AS_NEW_GLYPH = '↻';
+/**
+ * Returns spans whose status changed since the last call. `seen` is mutated
+ * in place so callers can carry it across polls. Pending spans are skipped —
+ * nothing worth reporting until a step starts.
+ */
+export function diffSpanUpdates(spans, labels, seen) {
+    const updates = [];
+    for (const span of spans) {
+        if (span.status === 'pending' || seen.get(span.id) === span.status) {
+            continue;
+        }
+        seen.set(span.id, span.status);
+        updates.push({ span, label: labels.get(span.id) ?? span.name });
+    }
+    return updates;
+}
+/** Formats the continue-as-new transition line, keeping its glyph in the formatting layer. */
+export function formatContinuedAsNew(runId) {
+    return `${CONTINUED_AS_NEW_GLYPH} continued as new run ${runId}`;
+}
+export function formatSpanUpdate(update, color) {
+    const { span, label } = update;
+    const glyph = GLYPH[span.status];
+    const tint = makeTint(color);
+    const tintStatus = (text) => tint(text, ANSI[span.status]);
+    switch (span.status) {
+        case 'running':
+            return `${tintStatus(glyph)} ${label} running…`;
+        case 'completed':
+            return `${tintStatus(glyph)} ${label}  ${formatDurationLabel(Math.max(0, span.durationMs))}`;
+        case 'failed': {
+            const reason = span.failureMessage ? `: ${span.failureMessage}` : '';
+            return `${tintStatus(glyph)} ${label} failed${reason}`;
+        }
+        default:
+            return `${glyph} ${label} ${span.status}`;
+    }
+}

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

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

package/dist/utils/monitor_log.spec.js

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest';
+import { diffSpanUpdates, formatSpanUpdate } from '#utils/monitor_log.js';
+const span = (overrides) => ({
+    name: 'Step',
+    technicalName: 'wf#step',
+    description: null,
+    kind: 'activity',
+    attempt: 1,
+    startedAt: null,
+    scheduledAt: null,
+    completedAt: null,
+    startOffsetMs: 0,
+    endOffsetMs: 0,
+    durationMs: 0,
+    failureMessage: null,
+    ...overrides
+});
+describe('diffSpanUpdates', () => {
+    it('skips pending spans', () => {
+        const seen = new Map();
+        const updates = diffSpanUpdates([span({ id: '1', status: 'pending' })], new Map(), seen);
+        expect(updates).toHaveLength(0);
+        expect(seen.size).toBe(0);
+    });
+    it('reports a span the first time it is seen in a non-pending status', () => {
+        const seen = new Map();
+        const updates = diffSpanUpdates([span({ id: '1', status: 'running' })], new Map([['1', 'Fetch page']]), seen);
+        expect(updates).toHaveLength(1);
+        expect(updates[0].label).toBe('Fetch page');
+        expect(seen.get('1')).toBe('running');
+    });
+    it('does not re-report a span whose status is unchanged since the last call', () => {
+        const seen = new Map([['1', 'running']]);
+        const updates = diffSpanUpdates([span({ id: '1', status: 'running' })], new Map(), seen);
+        expect(updates).toHaveLength(0);
+    });
+    it('reports a span again once its status transitions (running -> completed)', () => {
+        const seen = new Map([['1', 'running']]);
+        const updates = diffSpanUpdates([span({ id: '1', status: 'completed' })], new Map(), seen);
+        expect(updates).toHaveLength(1);
+        expect(seen.get('1')).toBe('completed');
+    });
+    it('falls back to the span name when no label is provided', () => {
+        const seen = new Map();
+        const updates = diffSpanUpdates([span({ id: '1', status: 'running', name: 'Unlabeled' })], new Map(), seen);
+        expect(updates[0].label).toBe('Unlabeled');
+    });
+});
+describe('formatSpanUpdate', () => {
+    it('formats a running span', () => {
+        const line = formatSpanUpdate({ span: span({ id: '1', status: 'running' }), label: 'Fetch page' }, false);
+        expect(line).toBe('● Fetch page running…');
+    });
+    it('formats a completed span with its duration', () => {
+        const line = formatSpanUpdate({ span: span({ id: '1', status: 'completed', durationMs: 1234 }), label: 'Fetch page' }, false);
+        expect(line).toBe('✓ Fetch page  1s');
+    });
+    it('formats a failed span with its failure message', () => {
+        const line = formatSpanUpdate({ span: span({ id: '1', status: 'failed', failureMessage: 'boom' }), label: 'Fetch page' }, false);
+        expect(line).toBe('✗ Fetch page failed: boom');
+    });
+    it('formats a failed span without a failure message', () => {
+        const line = formatSpanUpdate({ span: span({ id: '1', status: 'failed' }), label: 'Fetch page' }, false);
+        expect(line).toBe('✗ Fetch page failed');
+    });
+    it('wraps the glyph in ANSI codes when color is enabled', () => {
+        const line = formatSpanUpdate({ span: span({ id: '1', status: 'running' }), label: 'Fetch page' }, true);
+        expect(line).toContain('●');
+        expect(line).not.toBe('● Fetch page running…'); // color codes present
+    });
+});