@outputai/cli 0.10.1-next.f6a7c1a.0 → 0.11.0

package/dist/services/monitor_stream.js

@@ -0,0 +1,285 @@
+import { fetchWorkflowHistory, fetchWorkflowHistoryUpdates } from '#services/workflow_history.js';
+import buildSpanLabels from '#utils/span_labels.js';
+import { formatDurationLabel } from '#utils/waterfall.js';
+import { diffSpanUpdates, formatContinuedAsNew, formatSpanUpdate } from '#utils/monitor_log.js';
+import { isErrorStatus, isTerminalStatus } from '#utils/format_workflow_result.js';
+import { getErrorMessage } from '#utils/error_utils.js';
+import { sleep } from '#utils/sleep.js';
+import { shouldColorize } from '#utils/color.js';
+import { HttpError } from '#api/http_client.js';
+const MAX_CONSECUTIVE_ERRORS = 5;
+/**
+ * Retry sleep ceiling while no poll has succeeded yet. The retry budget covers
+ * the first poll for `start --monitor`'s sake (see `poll`), but `workflow
+ * monitor wf-x` against a server that was never reachable pays for that too —
+ * and with a large `--interval` it would sit through the whole budget before
+ * reporting a connection it could never make. Capping only the pre-first-success
+ * sleep keeps the retry useful without making "the API is down" take minutes to
+ * surface; once a poll has succeeded, the user's `--interval` is honored.
+ */
+const UNESTABLISHED_RETRY_MS = 1000;
+const SIGINT_EXIT_CODE = 130;
+const FLUSH_TIMEOUT_MS = 2000;
+const TRANSIENT_ERROR_CODES = new Set(['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'EAI_AGAIN', 'ENOTFOUND']);
+/**
+ * Adapts an oclif command to the above. Late-bound arrows rather than
+ * `command.log.bind( command )`: oclif (and the unit tests) replace these as own
+ * properties on the instance, so they must resolve at call time. Structurally
+ * typed so a test double satisfies it without a real oclif `Config`.
+ */
+export function commandStreamIo(command) {
+    return {
+        log: message => command.log(message),
+        warn: message => {
+            command.warn(message);
+        },
+        error: message => command.error(message, { exit: 1 })
+    };
+}
+/**
+ * Distinguishes blips worth retrying from errors that will fail identically on
+ * every attempt: network hiccups, a client-side request timeout, and 5xx/408/429
+ * responses are transient. Everything else — a 4xx like a stale/invalid resume
+ * cursor (`InvalidPageTokenError`, surfaced as 400), or a bug in correlate()/
+ * buildResult() re-throwing the same exception — can't self-resolve by waiting,
+ * so it should surface immediately instead of burning the retry budget.
+ */
+function isTransientPollError(error) {
+    if (error instanceof HttpError) {
+        const status = error.response.status;
+        return status >= 500 || status === 408 || status === 429;
+    }
+    const err = error;
+    if (err.name === 'TimeoutError') {
+        return true;
+    }
+    return Boolean((err.code && TRANSIENT_ERROR_CODES.has(err.code)) ||
+        (err.cause?.code && TRANSIENT_ERROR_CODES.has(err.cause.code)));
+}
+/**
+ * Wraps a single poll: a transient blip (see `isTransientPollError`) returns
+ * `null` so the loop can retry — matching the dev TUI's `useStepGraph` behavior
+ * of keeping the last good state on a poll hiccup. A non-transient error (e.g. a
+ * 404 for a mistyped workflow id, a stale resume cursor, or a bug in the parsing
+ * pipeline) rethrows immediately since retrying it cannot succeed.
+ * `MAX_CONSECUTIVE_ERRORS` bounds how long we'll retry transient failures before
+ * giving up.
+ *
+ * The retry budget deliberately covers the *first* poll too. `workflow start
+ * --monitor` issues it milliseconds after the API accepted the start request, so
+ * the first poll is the one most likely to catch a rolling restart or a single
+ * 503 — and aborting there abandons a workflow that is already running. The
+ * sleep between those pre-first-success retries is capped so `workflow monitor`
+ * against an unreachable server doesn't pay the full budget at `--interval`
+ * (see `UNESTABLISHED_RETRY_MS`).
+ *
+ * Fetch strategy is driven by `state.cursor`, not tick count: no cursor yet
+ * (the very first poll, or the first poll of a run chained via continue-as-new)
+ * uses `fetchWorkflowHistory` (fast, no long-poll) so that render isn't delayed;
+ * once a cursor exists, every poll resumes via `fetchWorkflowHistoryUpdates`
+ * instead of re-paging the whole history — see `plan_workflow_monitor_history.md`
+ * for why a full re-fetch every tick is expensive for long-running workflows.
+ */
+async function poll(options, state, io) {
+    try {
+        // Keeps the resumed long-poll's server-side block roughly aligned with `--interval`
+        // instead of always blocking for the server's full configured deadline regardless of
+        // it (see `plan_workflow_monitor_history.md`'s "Known tradeoff" note). Only takes
+        // effect once resuming (i.e. from the second tick onward); `fetchWorkflowHistory`
+        // ignores it on the initial full walk.
+        const fetchOptions = {
+            workflowId: options.workflowId,
+            runId: state.runId,
+            includePayloads: options.includePayloads,
+            longPollTimeoutMs: options.interval
+        };
+        if (!state.cursor) {
+            const result = await fetchWorkflowHistory(fetchOptions);
+            return { result, cursor: result.cursor };
+        }
+        return await fetchWorkflowHistoryUpdates(fetchOptions, state.cursor);
+    }
+    catch (error) {
+        // Whatever this poll was doing stopped mattering the moment the user
+        // detached: reporting a retry would contradict the "Detached" line already
+        // printed, and rethrowing would unwind past the loop's own detach guards
+        // into the caller's "monitoring stopped" handling, racing exit 3 against the
+        // 130 the detach already recorded. The loop breaks on `detached` right after
+        // this returns, so `null` here is not a retry.
+        if (state.detached) {
+            return null;
+        }
+        if (!isTransientPollError(error) || state.consecutiveErrors + 1 >= MAX_CONSECUTIVE_ERRORS) {
+            throw error;
+        }
+        io.warn(`Poll failed (${state.consecutiveErrors + 1}/${MAX_CONSECUTIVE_ERRORS}), retrying: ${getErrorMessage(error)}`);
+        return null;
+    }
+}
+/**
+ * `process.exit` discards whatever is still queued on an asynchronous stdout —
+ * a pipe on macOS, where writes are buffered rather than synchronous (TTY and
+ * file writes are synchronous on POSIX and are not truncated). Detaching from
+ * `workflow start --monitor` that way can drop the `Workflow ID:` line the
+ * command printed moments earlier, leaving the user with no way to reattach to a
+ * workflow that is still running. So queue an empty write behind the pending
+ * output and exit once it drains, with a ceiling in case the reader has stalled.
+ */
+function exitAfterFlush(code) {
+    const state = { exited: false };
+    const exit = () => {
+        if (state.exited) {
+            return;
+        }
+        state.exited = true;
+        process.exit(code);
+    };
+    const timer = setTimeout(exit, FLUSH_TIMEOUT_MS);
+    process.stdout.write('', () => {
+        clearTimeout(timer);
+        exit();
+    });
+}
+/**
+ * Polls a workflow run and emits status updates until it reaches a terminal
+ * state, following continue-as-new chains. Shared by `workflow monitor` and
+ * `workflow start --monitor` so both behave identically; see `MonitorStreamIo`
+ * for why output is injected rather than taken from a `Command`.
+ *
+ * Sets `process.exitCode = 1` on a terminal error status rather than throwing,
+ * so the caller's own output (e.g. `start`'s "Workflow started successfully")
+ * is still the command's primary result. Returns the terminal status it stopped
+ * on — `undefined` if it stopped because the user detached — so a caller can
+ * tailor its own follow-up (`workflow result` vs `workflow debug`).
+ */
+export async function streamWorkflowUpdates(options, io) {
+    const color = shouldColorize(options.color);
+    // Threaded via mutable properties (not `let` reassignment) so state
+    // persists across polls without local variable reassignment.
+    const state = {
+        runId: options.runId,
+        consecutiveErrors: 0,
+        // Set by the SIGINT handler so an in-flight poll can't print another update
+        // on top of "Detached" while stdout drains (see `exitAfterFlush`).
+        detached: false,
+        terminalStatus: undefined,
+        // Undefined until a resumable cursor is established (see `poll` and
+        // `fetchWorkflowHistoryUpdates`); reset on continue-as-new since a new run's
+        // cursor position is meaningless carried over from the old one.
+        cursor: undefined
+    };
+    const seen = new Map();
+    // Assigned once per span id and never overwritten: `buildSpanLabels` numbers
+    // same-named spans by how many are in the array *at call time*, so recomputing
+    // it fresh every poll could retroactively change a label already printed to
+    // the user (e.g. an unnumbered "Scrape Page" becoming "Scrape Page #1" once a
+    // second instance appears). Freezing on first sight keeps printed labels stable.
+    const labels = new Map();
+    // One emit point for both output formats: json mode wraps `fields` (plus
+    // the ambient workflow/run id) as a line of NDJSON, text mode prints `text`.
+    const emit = (fields, text) => {
+        io.log(options.json ?
+            JSON.stringify({ workflowId: options.workflowId, runId: state.runId, ...fields }) :
+            text);
+    };
+    emit({ monitoring: true }, `Monitoring ${options.workflowId}${state.runId ? ` (run ${state.runId})` : ''}... (Ctrl+C to detach)`);
+    const sigintHandler = () => {
+        // The listener stays registered until the loop unwinds through `finally`, and
+        // the exit is deferred behind a stdout flush — so an impatient second Ctrl+C
+        // lands here again and would print a second "Detached" line and schedule a
+        // second exit.
+        if (state.detached) {
+            return;
+        }
+        state.detached = true;
+        // Recorded as well as exited with: deferring the exit for a stdout flush
+        // lets the loop unwind and the command return normally in the meantime, and
+        // whichever of the two finishes first has to land on 130.
+        process.exitCode = SIGINT_EXIT_CODE;
+        emit({ detached: true }, `\nDetached (the workflow keeps running). Use "workflow status ${options.workflowId}" to check on it, ` +
+            `or "workflow result ${options.workflowId}" once it finishes.`);
+        exitAfterFlush(SIGINT_EXIT_CODE);
+    };
+    process.on('SIGINT', sigintHandler);
+    try {
+        while (true) {
+            if (state.detached) {
+                break;
+            }
+            const outcome = await poll(options, state, io);
+            if (state.detached) {
+                break;
+            }
+            if (outcome === null) {
+                state.consecutiveErrors += 1;
+                await sleep(state.cursor ? options.interval : Math.min(options.interval, UNESTABLISHED_RETRY_MS));
+                continue;
+            }
+            state.consecutiveErrors = 0;
+            state.cursor = outcome.cursor;
+            const result = outcome.result;
+            state.runId = result.runId ?? state.runId;
+            for (const [id, label] of buildSpanLabels(result.spans)) {
+                if (!labels.has(id)) {
+                    labels.set(id, label);
+                }
+            }
+            for (const update of diffSpanUpdates(result.spans, labels, seen)) {
+                emit({ span: update.span }, formatSpanUpdate(update, color));
+            }
+            const status = result.workflow?.status;
+            if (status === 'continued_as_new') {
+                if (!result.continuedAsNewRunId) {
+                    io.error('Workflow continued as a new run, but the new run ID could not be determined.');
+                    // `io.error` is typed `never`, but nothing enforces that at runtime.
+                    // Without this, an `io` whose `error` returns would fall through to
+                    // re-poll the latest run with the cursor cleared — replaying the whole
+                    // span history every interval, forever, with a zero exit code.
+                    break;
+                }
+                emit({ continuedAsNewRunId: result.continuedAsNewRunId }, formatContinuedAsNew(result.continuedAsNewRunId));
+                state.runId = result.continuedAsNewRunId;
+                state.cursor = undefined;
+                seen.clear();
+                labels.clear();
+                await sleep(options.interval);
+                continue;
+            }
+            const terminalStatus = isTerminalStatus(status);
+            if (terminalStatus) {
+                const failed = isErrorStatus(terminalStatus);
+                emit({ status: terminalStatus }, `${failed ? '✗' : '✓'} workflow ${terminalStatus} · ${formatDurationLabel(result.totalDurationMs)}`);
+                if (failed) {
+                    process.exitCode = 1;
+                }
+                state.terminalStatus = terminalStatus;
+                break;
+            }
+            await sleep(options.interval);
+        }
+    }
+    finally {
+        process.removeListener('SIGINT', sigintHandler);
+    }
+    return state.terminalStatus;
+}
+/**
+ * Shared `catch` handling for both entry points. A 400 is the generic status for
+ * several distinct causes (invalid pageToken, a missing runId, an out-of-range
+ * longPollTimeoutMs) — only override it with the stale-cursor message when the
+ * server actually identifies that specific cause; otherwise let the real
+ * validation error surface instead of misdiagnosing an unrelated 400.
+ *
+ * Deliberately no 404 here: "check the workflow ID" only reads correctly where
+ * the user typed the id, so `workflow monitor` adds it and `start --monitor`
+ * doesn't — there the id came back from `postWorkflowStart`, and the server's own
+ * message is left to surface inside the "started, but monitoring stopped" wrapper
+ * instead of advising a fix that isn't the user's to make.
+ */
+export function monitorErrorOverrides(error) {
+    const response = error.response;
+    const isStaleCursor = response?.status === 400 && response.data?.error === 'InvalidPageTokenError';
+    return isStaleCursor ?
+        { 400: 'Resume cursor is no longer valid for this workflow; restart the monitor.' } :
+        {};
+}

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

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

package/dist/services/monitor_stream.spec.js

@@ -0,0 +1,285 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { HttpError } from '#api/http_client.js';
+import { commandStreamIo, monitorErrorOverrides, streamWorkflowUpdates } from './monitor_stream.js';
+vi.mock('#services/workflow_history.js', () => ({ fetchWorkflowHistory: vi.fn(), fetchWorkflowHistoryUpdates: vi.fn() }));
+vi.mock('#utils/sleep.js', () => ({ sleep: vi.fn().mockResolvedValue(undefined) }));
+/**
+ * Direct coverage of the loop now that two commands share it. `monitor.spec.ts`
+ * exercises it end-to-end through `workflow monitor`, and `start.spec.ts` stubs
+ * it out entirely — so what's here is the behavior neither reaches: the return
+ * value both callers branch on, the pre-cursor retry cap, the detach guards, and
+ * the error classification at its edges.
+ */
+const cursor = { pageToken: 'token', lastEventId: 1, meta: null, runId: 'run-1', events: [] };
+const history = (status, overrides = {}) => ({
+    workflow: { status },
+    runId: 'run-1',
+    events: [],
+    spans: [],
+    totalDurationMs: 0,
+    continuedAsNewRunId: null,
+    cursor,
+    ...overrides
+});
+const update = (status, overrides = {}) => ({ result: history(status, overrides), cursor });
+const createIo = (errorReturns = false) => ({
+    log: vi.fn(),
+    warn: vi.fn(),
+    // Typed `never` in the interface but nothing enforces that at runtime, which is
+    // exactly what the continue-as-new guard defends against — so both shapes are
+    // constructible here.
+    error: (errorReturns ?
+        vi.fn() :
+        vi.fn((message) => {
+            throw new Error(message);
+        }))
+});
+const options = (overrides = {}) => ({
+    workflowId: 'wf-1',
+    runId: undefined,
+    includePayloads: false,
+    interval: 5000,
+    json: false,
+    color: false,
+    ...overrides
+});
+const flush = () => new Promise(resolve => setImmediate(resolve));
+describe('monitor_stream service', () => {
+    beforeEach(async () => {
+        vi.clearAllMocks();
+        process.exitCode = undefined;
+        const { sleep } = await import('#utils/sleep.js');
+        vi.mocked(sleep).mockResolvedValue(undefined);
+    });
+    afterEach(() => {
+        process.exitCode = undefined;
+    });
+    const histories = async () => {
+        const { fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await import('#services/workflow_history.js');
+        return {
+            fetchWorkflowHistory: vi.mocked(fetchWorkflowHistory),
+            fetchWorkflowHistoryUpdates: vi.mocked(fetchWorkflowHistoryUpdates)
+        };
+    };
+    describe('streamWorkflowUpdates() return value', () => {
+        it('returns the terminal status it stopped on so the caller can name a follow-up', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('completed'));
+            // `start --monitor` branches on this to print "workflow result" vs
+            // "workflow debug"; a boolean or a throw wouldn't carry enough.
+            expect(await streamWorkflowUpdates(options(), createIo())).toBe('completed');
+            expect(process.exitCode).toBeUndefined();
+        });
+        it('returns a failed status and records exit 1 without throwing', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('failed'));
+            // Not thrown: the caller's own output stays the command's primary result.
+            expect(await streamWorkflowUpdates(options(), createIo())).toBe('failed');
+            expect(process.exitCode).toBe(1);
+        });
+        it('returns undefined when the user detached, so no follow-up is printed', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            const { sleep } = await import('#utils/sleep.js');
+            fetchWorkflowHistory.mockResolvedValue(history('running'));
+            const onSpy = vi.spyOn(process, 'on');
+            const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined));
+            vi.mocked(sleep).mockImplementation(async () => {
+                onSpy.mock.calls.find(([event]) => event === 'SIGINT')[1]();
+            });
+            expect(await streamWorkflowUpdates(options(), createIo())).toBeUndefined();
+            await flush();
+            onSpy.mockRestore();
+            exitSpy.mockRestore();
+        });
+    });
+    describe('retry pacing', () => {
+        it('caps the retry sleep while no cursor is established, ignoring a long --interval', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            const { sleep } = await import('#utils/sleep.js');
+            fetchWorkflowHistory
+                .mockRejectedValueOnce(new HttpError('Service unavailable', { status: 503 }))
+                .mockResolvedValueOnce(history('completed'));
+            await streamWorkflowUpdates(options({ interval: 5000 }), createIo());
+            // Otherwise "the API is down" takes interval x budget to surface — minutes,
+            // for a `workflow monitor` against a server that was never reachable.
+            expect(vi.mocked(sleep)).toHaveBeenCalledWith(1000);
+        });
+        it('honors an --interval shorter than the cap rather than slowing the retry down', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            const { sleep } = await import('#utils/sleep.js');
+            fetchWorkflowHistory
+                .mockRejectedValueOnce(new HttpError('Service unavailable', { status: 503 }))
+                .mockResolvedValueOnce(history('completed'));
+            await streamWorkflowUpdates(options({ interval: 250 }), createIo());
+            expect(vi.mocked(sleep)).toHaveBeenCalledWith(250);
+        });
+        it('sleeps the full --interval on a retry once a cursor exists', async () => {
+            const { fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await histories();
+            const { sleep } = await import('#utils/sleep.js');
+            fetchWorkflowHistory.mockResolvedValueOnce(history('running'));
+            fetchWorkflowHistoryUpdates
+                .mockRejectedValueOnce(new HttpError('Service unavailable', { status: 503 }))
+                .mockResolvedValueOnce(update('completed'));
+            await streamWorkflowUpdates(options({ interval: 5000 }), createIo());
+            expect(vi.mocked(sleep)).not.toHaveBeenCalledWith(1000);
+            expect(vi.mocked(sleep)).toHaveBeenCalledWith(5000);
+        });
+    });
+    describe('transient error classification', () => {
+        const retried = async (error) => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockRejectedValueOnce(error).mockResolvedValueOnce(history('completed'));
+            const io = createIo();
+            await streamWorkflowUpdates(options(), io);
+            return { calls: fetchWorkflowHistory.mock.calls.length, io };
+        };
+        it.each([
+            ['a 503', new HttpError('Service unavailable', { status: 503 })],
+            ['a 429 rate limit', new HttpError('Too many requests', { status: 429 })],
+            ['a 408 request timeout', new HttpError('Request timeout', { status: 408 })],
+            ['a client-side TimeoutError', Object.assign(new Error('timed out'), { name: 'TimeoutError' })],
+            ['a nested ECONNREFUSED cause', Object.assign(new Error('fetch failed'), { cause: { code: 'ECONNREFUSED' } })],
+            ['a top-level EAI_AGAIN', Object.assign(new Error('dns'), { code: 'EAI_AGAIN' })]
+        ])('retries %s', async (_label, error) => {
+            const { calls, io } = await retried(error);
+            expect(calls).toBe(2);
+            expect(io.warn).toHaveBeenCalledWith(expect.stringContaining('(1/5)'));
+        });
+        it.each([
+            ['a 404 for a mistyped workflow id', new HttpError('Not found', { status: 404 })],
+            ['a 400 stale resume cursor', new HttpError('Invalid page token', { status: 400 })],
+            ['a bug in the parsing pipeline', new TypeError('spans is not iterable')]
+        ])('surfaces %s immediately instead of burning the retry budget', async (_label, error) => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockRejectedValue(error);
+            const io = createIo();
+            await expect(streamWorkflowUpdates(options(), io)).rejects.toThrow();
+            expect(fetchWorkflowHistory).toHaveBeenCalledTimes(1);
+            expect(io.warn).not.toHaveBeenCalled();
+        });
+    });
+    describe('detaching', () => {
+        const detachDuring = async () => {
+            const onSpy = vi.spyOn(process, 'on');
+            const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined));
+            const sigint = () => onSpy.mock.calls.find(([event]) => event === 'SIGINT')[1]();
+            return { onSpy, exitSpy, sigint };
+        };
+        it('swallows a poll failure raised after the user detached instead of racing the exit code', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            const { onSpy, exitSpy, sigint } = await detachDuring();
+            // The in-flight poll dies because the process is on its way out. Rethrowing
+            // would unwind into `start`'s "monitoring stopped" handler and race exit 3
+            // against the 130 the detach already recorded.
+            fetchWorkflowHistory.mockImplementation(async () => {
+                sigint();
+                throw new Error('socket hang up');
+            });
+            const io = createIo();
+            expect(await streamWorkflowUpdates(options(), io)).toBeUndefined();
+            expect(process.exitCode).toBe(130);
+            expect(io.warn).not.toHaveBeenCalled();
+            expect(fetchWorkflowHistory).toHaveBeenCalledTimes(1);
+            await flush();
+            onSpy.mockRestore();
+            exitSpy.mockRestore();
+        });
+        it('ignores a second Ctrl+C while the first is still draining stdout', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('completed'));
+            const { onSpy, exitSpy, sigint } = await detachDuring();
+            const io = createIo();
+            await streamWorkflowUpdates(options(), io);
+            sigint();
+            // The exit is deferred behind a flush and the listener is still registered,
+            // so an impatient user lands here again before the process is gone.
+            sigint();
+            await flush();
+            const detached = io.log.mock.calls.filter((call) => String(call[0]).includes('Detached'));
+            expect(detached).toHaveLength(1);
+            expect(exitSpy).toHaveBeenCalledTimes(1);
+            onSpy.mockRestore();
+            exitSpy.mockRestore();
+        });
+        it('removes its SIGINT listener once the loop ends', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('completed'));
+            const before = process.listenerCount('SIGINT');
+            await streamWorkflowUpdates(options(), createIo());
+            expect(process.listenerCount('SIGINT')).toBe(before);
+        });
+        it('removes its SIGINT listener even when the loop unwinds on an error', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockRejectedValue(new HttpError('Not found', { status: 404 }));
+            const before = process.listenerCount('SIGINT');
+            await expect(streamWorkflowUpdates(options(), createIo())).rejects.toThrow();
+            expect(process.listenerCount('SIGINT')).toBe(before);
+        });
+    });
+    describe('continue-as-new', () => {
+        it('breaks instead of re-polling forever when the new run id is missing and io.error returns', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockResolvedValue(history('continued_as_new'));
+            // `io.error` is typed `never`, but an io whose error returns would otherwise
+            // fall through and replay the whole history every interval, forever, with a
+            // zero exit code.
+            const io = createIo(true);
+            expect(await streamWorkflowUpdates(options(), io)).toBeUndefined();
+            expect(io.error).toHaveBeenCalledWith(expect.stringContaining('new run ID could not be determined'));
+            expect(fetchWorkflowHistory).toHaveBeenCalledTimes(1);
+        });
+        it('reports the chained run under the new run id in json mode', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory
+                .mockResolvedValueOnce(history('continued_as_new', { continuedAsNewRunId: 'run-2' }))
+                .mockResolvedValueOnce(history('completed', { runId: 'run-2' }));
+            const io = createIo();
+            await streamWorkflowUpdates(options({ json: true }), io);
+            const lines = io.log.mock.calls.map((call) => JSON.parse(call[0]));
+            expect(lines.some((line) => line.continuedAsNewRunId === 'run-2')).toBe(true);
+            // Every subsequent line carries the run actually being polled, not the one
+            // the stream attached to.
+            expect(lines.at(-1)).toMatchObject({ workflowId: 'wf-1', runId: 'run-2', status: 'completed' });
+        });
+    });
+    describe('commandStreamIo()', () => {
+        it('resolves log/warn at call time so a replaced command method still receives output', async () => {
+            const command = { log: vi.fn(), warn: vi.fn(), error: vi.fn() };
+            const io = commandStreamIo(command);
+            // oclif (and the command specs) swap these in as own properties after the
+            // adapter exists, which a `.bind()` at construction time would miss.
+            const replacement = vi.fn();
+            command.log = replacement;
+            io.log('hello');
+            expect(replacement).toHaveBeenCalledWith('hello');
+        });
+        it('raises command errors with an explicit exit 1', () => {
+            const command = { log: vi.fn(), warn: vi.fn(), error: vi.fn() };
+            commandStreamIo(command).error('boom');
+            expect(command.error).toHaveBeenCalledWith('boom', { exit: 1 });
+        });
+    });
+    describe('monitorErrorOverrides()', () => {
+        const withResponse = (status, data) => Object.assign(new Error('failed'), { response: { status, data } });
+        it('overrides a 400 the server identifies as a stale resume cursor', () => {
+            expect(monitorErrorOverrides(withResponse(400, { error: 'InvalidPageTokenError' }))).toEqual({
+                400: expect.stringContaining('Resume cursor is no longer valid')
+            });
+        });
+        it('leaves an unrelated 400 alone rather than misdiagnosing it as a stale cursor', () => {
+            // 400 also covers a missing runId and an out-of-range longPollTimeoutMs, whose
+            // real validation messages are more useful than a cursor guess.
+            expect(monitorErrorOverrides(withResponse(400, { error: 'ValidationError' }))).toEqual({});
+            expect(monitorErrorOverrides(withResponse(400))).toEqual({});
+        });
+        it('does not override a 404, which only reads correctly where the user typed the id', () => {
+            // `workflow monitor` adds its own; under `start --monitor` the id came back
+            // from the API, so "check the workflow ID" would misdirect the user.
+            expect(monitorErrorOverrides(withResponse(404))).toEqual({});
+        });
+        it('tolerates an error with no response at all', () => {
+            expect(monitorErrorOverrides(new Error('fetch failed'))).toEqual({});
+        });
+    });
+});

package/dist/services/workflow_history.js

@@ -10,13 +10,13 @@
 import { getWorkflowIdHistory } from '#api/generated/api.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';
+import { isTerminalStatus } 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));
+    return status === 'continued_as_new' || isTerminalStatus(status) !== undefined;
 }
 function numericEventId(event) {
     const id = Number(event.eventId);

package/dist/templates/agent_instructions/CLAUDE.md.template

@@ -17,10 +17,12 @@ claude plugin install outputai@outputai --scope project
 npm run output:dev           # Start dev environment (worker + Temporal)
 npm run output:worker:build  # Build TypeScript to dist/
 npm run output:worker:check  # Optional: bundle-check workflows for bad imports (node: built-ins)
-npm run output:worker:watch  # Build + restart on file changes
-npm run output:worker        # Install, build, and start worker
+npm run output:worker:watch  # Build + restart on src/ file changes
+npm run output:worker        # Build and start worker
 ```
 
+Hot-reload watches `src/` only. After changing dependencies (`package.json` / lockfile), run `npm install`, then `npx output dev down` and `npm run output:dev` again so the worker container reinstalls. A hot-reload alone is not enough; if the stack is still running, `npx output dev down` is required.
+
 ## Project Structure
 
 ```
@@ -44,7 +46,7 @@ config/
 ## Key Conventions
 
 - **Workflows are deterministic**: No I/O, no `Date.now()`, no `Math.random()` in `workflow.ts`. All side effects go in steps or evaluators.
-- **HTTP clients**: Always use `httpClient` from `@outputai/http` -- never raw `fetch` or `axios`. This enables automatic tracing and cost tracking.
+- **HTTP clients**: Use `outputFetch` or `createKyClient` from `@outputai/http` instead of raw `fetch` or `axios`. Requests are automatically traced; use `addRequestCost` when cost tracking is needed.
 - **LLM calls**: Use `generateText` from `@outputai/llm` with `.prompt` files. Never call LLM APIs directly.
 
 ---

package/dist/templates/project/README.md.template

@@ -79,7 +79,9 @@ This starts:
 - Temporal server and UI (http://localhost:8080)
 - PostgreSQL and Redis databases
 - Output.ai API server (http://localhost:3001)
-- Worker process for executing workflows
+- Worker process for executing workflows (auto-reloads on `src/` changes)
+
+Dependency changes (`package.json` / lockfile) are not picked up by hot-reload. Run `npm install`, then `npx output dev down` and `npm run output:dev` again so the worker container reinstalls. A hot-reload alone is not enough; if the stack is still running, `npx output dev down` is required.
 
 ### 4. Run a workflow
 

package/dist/templates/project/package.json.template

@@ -9,8 +9,8 @@
     "output:worker:build": "rm -rf dist/* && tsc -p ./ && output-copy-assets",
     "output:worker:start": "output-worker",
     "output:worker:check": "output-worker --check",
-    "output:worker": "npm run output:worker:install && npm run output:worker:build && npm run output:worker:start",
-    "output:worker:watch": "npx nodemon --watch src --watch package.json --ext ts,js,json,prompt,md --ignore 'dist/**' --ignore '**/*.spec.*' --ignore '**/*.test.*' --exec 'npm run output:worker'",
+    "output:worker": "npm run output:worker:build && npm run output:worker:start",
+    "output:worker:watch": "npx nodemon --watch src --ext ts,js,json,prompt,md --ignore 'dist/**' --ignore '**/*.spec.*' --ignore '**/*.test.*' --exec 'npm run output:worker'",
     "output:dev": "output dev"
   },
   "dependencies": {

package/dist/templates/project/src/clients/jina.ts.template

@@ -1,4 +1,4 @@
-import { httpClient } from '@outputai/http';
+import { createKyClient } from '@outputai/http';
 
 export interface JinaReaderResponse {
   code: number;
@@ -12,13 +12,13 @@ export interface JinaReaderResponse {
   };
 }
 
-const jinaClient = httpClient( {
-  prefixUrl: 'https://r.jina.ai',
+const client = createKyClient( {
+  prefix: 'https://r.jina.ai',
   timeout: 30000
 } );
 
 export async function fetchBlogContent( url: string ): Promise<JinaReaderResponse> {
-  const response = await jinaClient.post( '', {
+  const response = await client.post( '', {
     json: { url },
     headers: {
       'Accept': 'application/json',