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

package/dist/api/generated/api.d.ts

@@ -66,22 +66,29 @@ export interface Workflow {
     /** Alternative names that resolve to this workflow */
     aliases?: string[];
 }
+/**
+ * Legacy trace information containing nested destinations
+ * @nullable
+ */
+export type TraceInfoV1 = {
+    /** Available destinations for trace data */
+    destinations?: {
+        /** Absolute path to local trace file, omitted if not saved locally */
+        local?: string;
+        /** Remote trace location (e.g., S3 URI), omitted if not saved remotely */
+        remote?: string;
+    };
+} | null;
 /**
  * Available destinations for trace data
+ * @nullable
  */
-export type TraceInfoDestinations = {
+export type TraceInfoV2 = {
     /** Absolute path to local trace file, omitted if not saved locally */
     local?: string;
     /** Remote trace location (e.g., S3 URI), omitted if not saved remotely */
     remote?: string;
-};
-/**
- * An object with information about the trace generated by the execution
- */
-export interface TraceInfo {
-    /** Available destinations for trace data */
-    destinations?: TraceInfoDestinations;
-}
+} | null;
 /**
  * The workflow input
  */
@@ -148,7 +155,7 @@ export declare const WorkflowRunInfoStatus: {
     readonly running: "running";
     readonly completed: "completed";
     readonly failed: "failed";
-    readonly canceled: "canceled";
+    readonly cancelled: "cancelled";
     readonly terminated: "terminated";
     readonly timed_out: "timed_out";
     readonly continued_as_new: "continued_as_new";
@@ -180,7 +187,7 @@ export interface WorkflowRunsResponse {
  */
 export type WorkflowStatusResponseStatus = typeof WorkflowStatusResponseStatus[keyof typeof WorkflowStatusResponseStatus];
 export declare const WorkflowStatusResponseStatus: {
-    readonly canceled: "canceled";
+    readonly cancelled: "cancelled";
     readonly completed: "completed";
     readonly continued_as_new: "continued_as_new";
     readonly failed: "failed";
@@ -204,20 +211,33 @@ export interface WorkflowStatusResponse {
 /**
  * The workflow execution status
  */
-export type WorkflowResultResponseStatus = typeof WorkflowResultResponseStatus[keyof typeof WorkflowResultResponseStatus];
-export declare const WorkflowResultResponseStatus: {
+export type WorkflowResultStatus = typeof WorkflowResultStatus[keyof typeof WorkflowResultStatus];
+export declare const WorkflowResultStatus: {
     readonly completed: "completed";
     readonly failed: "failed";
-    readonly canceled: "canceled";
+    readonly cancelled: "cancelled";
     readonly terminated: "terminated";
     readonly timed_out: "timed_out";
     readonly continued_as_new: "continued_as_new";
 };
+/**
+ * Structured error details captured from the workflow or activity failure
+ * @nullable
+ */
+export type SerializedWorkflowError = {
+    /** Failing activity type, omitted when the failure did not originate in an activity */
+    activityType?: string;
+    /** Original error class name */
+    name?: string;
+    /** Original error message */
+    message?: string;
+    [key: string]: unknown;
+} | null;
 /**
  * Structured failure details if the workflow failed, null otherwise
  * @nullable
  */
-export type WorkflowResultResponseErrorDetails = {
+export type WorkflowResultV1ResponseErrorDetails = {
     /**
        * Friendly failure message (from the underlying application error)
        * @nullable
@@ -246,29 +266,64 @@ export type WorkflowResultResponseErrorDetails = {
         [key: string]: unknown;
     } | null;
 } | null | null;
-export interface WorkflowResultResponse {
+/**
+ * Legacy wrapped workflow result
+ * @deprecated
+ */
+export interface WorkflowResultV1Response {
     /** The workflow execution id */
-    workflowId?: string;
-    /** The specific run id for this execution */
-    runId?: string;
+    workflowId: string;
+    /**
+       * The specific run id for this execution
+       * @nullable
+       */
+    runId: string | null;
+    status: WorkflowResultStatus;
     /** The original input passed to the workflow, null if unavailable */
-    input?: unknown;
+    input: unknown | null;
     /** The result of workflow, null if workflow failed */
-    output?: unknown;
-    trace?: TraceInfo;
-    /** The workflow execution status */
-    status?: WorkflowResultResponseStatus;
+    output: unknown | null;
+    trace: TraceInfoV1 | null;
     /**
        * Error message if workflow failed, null otherwise
        * @nullable
        */
-    error?: string | null;
+    error: string | null;
     /**
        * Structured failure details if the workflow failed, null otherwise
        * @nullable
        */
-    errorDetails?: WorkflowResultResponseErrorDetails;
+    errorDetails: WorkflowResultV1ResponseErrorDetails;
+}
+/**
+ * Workflow result response version
+ */
+export type WorkflowResultV2ResponseV = typeof WorkflowResultV2ResponseV[keyof typeof WorkflowResultV2ResponseV];
+export declare const WorkflowResultV2ResponseV: {
+    readonly NUMBER_2: "2";
+};
+/**
+ * Current workflow result with direct output and memo-based trace information
+ */
+export interface WorkflowResultV2Response {
+    /** Workflow result response version */
+    v: WorkflowResultV2ResponseV;
+    /** The workflow execution id */
+    workflowId: string;
+    /**
+       * The specific run id for this execution
+       * @nullable
+       */
+    runId: string | null;
+    status: WorkflowResultStatus;
+    /** The original input passed to the workflow, null if unavailable */
+    input: unknown | null;
+    /** Direct workflow output, null if no output is available */
+    output: unknown | null;
+    trace: TraceInfoV2 | null;
+    error: (SerializedWorkflowError | null) | null;
 }
+export type WorkflowResultResponse = WorkflowResultV2Response | WorkflowResultV1Response;
 export interface WorkflowInputResponse {
     /** The workflow execution id */
     workflowId: string;

package/dist/api/generated/api.js

@@ -19,13 +19,13 @@ export const WorkflowRunInfoStatus = {
     running: 'running',
     completed: 'completed',
     failed: 'failed',
-    canceled: 'canceled',
+    cancelled: 'cancelled',
     terminated: 'terminated',
     timed_out: 'timed_out',
     continued_as_new: 'continued_as_new',
 };
 export const WorkflowStatusResponseStatus = {
-    canceled: 'canceled',
+    cancelled: 'cancelled',
     completed: 'completed',
     continued_as_new: 'continued_as_new',
     failed: 'failed',
@@ -34,14 +34,17 @@ export const WorkflowStatusResponseStatus = {
     timed_out: 'timed_out',
     unspecified: 'unspecified',
 };
-export const WorkflowResultResponseStatus = {
+export const WorkflowResultStatus = {
     completed: 'completed',
     failed: 'failed',
-    canceled: 'canceled',
+    cancelled: 'cancelled',
     terminated: 'terminated',
     timed_out: 'timed_out',
     continued_as_new: 'continued_as_new',
 };
+export const WorkflowResultV2ResponseV = {
+    NUMBER_2: '2',
+};
 ;
 export const getGetHealthUrl = () => {
     return `/health`;

package/dist/assets/docker/docker-compose-dev.yml

@@ -80,7 +80,7 @@ services:
         condition: service_healthy
       worker:
         condition: service_healthy
-    image: outputai/api:${OUTPUT_API_VERSION:-0.10.1-next.fc0a41f.0}
+    image: outputai/api:${OUTPUT_API_VERSION:-0.11.0}
     init: true
     networks:
       - main
@@ -118,7 +118,7 @@ services:
       - OUTPUT_CATALOG_ID=${OUTPUT_CATALOG_ID:-main}
       - OUTPUT_REDIS_URL=redis://redis:6379
       - OUTPUT_TRACE_LOCAL_ON=${OUTPUT_TRACE_LOCAL_ON:-true}
-      - OUTPUT_TRACE_HOST_PATH=${PWD}/logs
+      - OUTPUT_TRACE_HOST_PATH=${OUTPUT_TRACE_HOST_PATH:-${PWD}/logs}
       - OUTPUT_TRACE_HTTP_VERBOSE=${OUTPUT_TRACE_HTTP_VERBOSE:-true}
       - OUTPUT_ENABLE_ATTRIBUTE_SIGNAL_EMISSION=${OUTPUT_ENABLE_ATTRIBUTE_SIGNAL_EMISSION:-false}
       - TEMPORAL_ADDRESS=temporal:7233

package/dist/commands/workflow/monitor.d.ts

@@ -12,6 +12,9 @@ import { Command } from '@oclif/core';
  * can tail and parse the stream incrementally, which native `--json`'s
  * "one object at the end" model can't do. See docs/guides/packages/cli.mdx
  * ("output workflow monitor") for the same rationale written up for users.
+ *
+ * The polling loop itself lives in `#services/monitor_stream.js` so
+ * `workflow start --monitor` (OUT-537) streams through the same code path.
  */
 export default class WorkflowMonitor extends Command {
     static description: string;
@@ -20,30 +23,12 @@ export default class WorkflowMonitor extends Command {
         workflowId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     static flags: {
-        'run-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'include-payloads': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         interval: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         color: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'run-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
-    /**
-     * Wraps a single poll: a failure on the very first tick propagates (there's
-     * nothing to fall back on), but a transient blip (see `isTransientPollError`)
-     * after we've already been monitoring successfully just 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 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.
-     *
-     * 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.
-     */
-    private poll;
     catch(error: Error): Promise<void>;
 }

package/dist/commands/workflow/monitor.js

@@ -1,39 +1,8 @@
 import { Args, Command, Flags } from '@oclif/core';
-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 { ERROR_STATUSES, TERMINAL_STATUSES } from '#utils/format_workflow_result.js';
-import { handleApiError } from '#utils/error_handler.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 DEFAULT_INTERVAL_MS = 2500;
-const MAX_CONSECUTIVE_ERRORS = 5;
+import { commandStreamIo, monitorErrorOverrides, streamWorkflowUpdates } from '#services/monitor_stream.js';
+import { handleCommandError } from '#utils/error_handler.js';
+import { monitorStreamFlags } from '#utils/monitor_flags.js';
 const OUTPUT_FORMAT = { JSON: 'json', TEXT: 'text' };
-const SIGINT_EXIT_CODE = 130;
-const TRANSIENT_ERROR_CODES = new Set(['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'EAI_AGAIN', 'ENOTFOUND']);
-/**
- * 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)));
-}
 /**
  * Unlike `run`/`status`/`result` (migrated to oclif's native `--json` in
  * OUT-419, #281), this command deliberately keeps a custom `--format json`
@@ -47,6 +16,9 @@ function isTransientPollError(error) {
  * can tail and parse the stream incrementally, which native `--json`'s
  * "one object at the end" model can't do. See docs/guides/packages/cli.mdx
  * ("output workflow monitor") for the same rationale written up for users.
+ *
+ * The polling loop itself lives in `#services/monitor_stream.js` so
+ * `workflow start --monitor` (OUT-537) streams through the same code path.
  */
 export default class WorkflowMonitor extends Command {
     static description = 'Attach to a workflow run and stream status updates until it ends';
@@ -72,159 +44,25 @@ export default class WorkflowMonitor extends Command {
             options: [OUTPUT_FORMAT.TEXT, OUTPUT_FORMAT.JSON],
             default: OUTPUT_FORMAT.TEXT
         }),
-        'include-payloads': Flags.boolean({
-            description: 'Include decoded step input/output payloads',
-            default: false
-        }),
-        interval: Flags.integer({
-            description: 'Poll interval in milliseconds. Once a resumed poll is long-polling ' +
-                'server-side for new events, this also bounds how long that block may last (capped ' +
-                'at the server\'s configured max), so an idle workflow\'s update cadence is roughly ' +
-                'twice this value (the long-poll bound, then this sleep) rather than a much longer, ' +
-                'separate server default.',
-            default: DEFAULT_INTERVAL_MS,
-            min: 1
-        }),
-        color: Flags.boolean({
-            description: 'Colorize status output (use --no-color to disable)',
-            default: true,
-            allowNo: true
-        })
+        ...monitorStreamFlags()
     };
     async run() {
         const { args, flags } = await this.parse(WorkflowMonitor);
-        const color = shouldColorize(flags.color);
-        const json = flags.format === OUTPUT_FORMAT.JSON;
-        // Threaded via mutable properties (not `let` reassignment) so state
-        // persists across polls without local variable reassignment.
-        const state = {
+        await streamWorkflowUpdates({
+            workflowId: args.workflowId,
             runId: flags['run-id'],
-            consecutiveErrors: 0,
-            firstTick: true,
-            // 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) => {
-            this.log(json ?
-                JSON.stringify({ workflowId: args.workflowId, runId: state.runId, ...fields }) :
-                text);
-        };
-        emit({ monitoring: true }, `Monitoring ${args.workflowId}${state.runId ? ` (run ${state.runId})` : ''}... (Ctrl+C to detach)`);
-        const sigintHandler = () => {
-            emit({ detached: true }, '\nDetached (the workflow keeps running).');
-            process.exit(SIGINT_EXIT_CODE);
-        };
-        process.on('SIGINT', sigintHandler);
-        try {
-            while (true) {
-                const outcome = await this.poll(args.workflowId, flags, state);
-                if (outcome === null) {
-                    state.consecutiveErrors += 1;
-                    await sleep(flags.interval);
-                    continue;
-                }
-                state.consecutiveErrors = 0;
-                state.firstTick = false;
-                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) {
-                        this.error('Workflow continued as a new run, but the new run ID could not be determined.', { exit: 1 });
-                    }
-                    emit({ continuedAsNewRunId: result.continuedAsNewRunId }, formatContinuedAsNew(result.continuedAsNewRunId));
-                    state.runId = result.continuedAsNewRunId;
-                    state.cursor = undefined;
-                    seen.clear();
-                    labels.clear();
-                    await sleep(flags.interval);
-                    continue;
-                }
-                if (status && TERMINAL_STATUSES.has(status)) {
-                    const summary = `${status === 'completed' ? '✓' : '✗'} workflow ${status} · ${formatDurationLabel(result.totalDurationMs)}`;
-                    emit({ status }, summary);
-                    if (ERROR_STATUSES.has(status)) {
-                        process.exitCode = 1;
-                    }
-                    return;
-                }
-                await sleep(flags.interval);
-            }
-        }
-        finally {
-            process.removeListener('SIGINT', sigintHandler);
-        }
-    }
-    /**
-     * Wraps a single poll: a failure on the very first tick propagates (there's
-     * nothing to fall back on), but a transient blip (see `isTransientPollError`)
-     * after we've already been monitoring successfully just 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 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.
-     *
-     * 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 poll(workflowId, flags, state) {
-        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 options = { workflowId, runId: state.runId, includePayloads: flags['include-payloads'], longPollTimeoutMs: flags.interval };
-            if (!state.cursor) {
-                const result = await fetchWorkflowHistory(options);
-                return { result, cursor: result.cursor };
-            }
-            return await fetchWorkflowHistoryUpdates(options, state.cursor);
-        }
-        catch (error) {
-            if (state.firstTick || !isTransientPollError(error) || state.consecutiveErrors + 1 >= MAX_CONSECUTIVE_ERRORS) {
-                throw error;
-            }
-            this.warn(`Poll failed (${state.consecutiveErrors + 1}/${MAX_CONSECUTIVE_ERRORS}), retrying: ${getErrorMessage(error)}`);
-            return null;
-        }
+            includePayloads: flags['include-payloads'],
+            interval: flags.interval,
+            json: flags.format === OUTPUT_FORMAT.JSON,
+            color: flags.color
+        }, commandStreamIo(this));
     }
     async catch(error) {
-        // 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.
-        const response = error.response;
-        const isStaleCursor = response?.status === 400 && response.data?.error === 'InvalidPageTokenError';
-        const overrides = { 404: 'Workflow not found. Check the workflow ID.' };
-        if (isStaleCursor) {
-            overrides[400] = 'Resume cursor is no longer valid for this workflow; restart the monitor.';
-        }
-        return handleApiError(error, (...args) => this.error(...args), overrides);
+        return handleCommandError(error, (...args) => this.error(...args), {
+            ...monitorErrorOverrides(error),
+            // Owned by this command rather than the shared overrides: here the id is the
+            // argument the user typed, so pointing at it is actionable advice.
+            404: 'Workflow not found. Check the workflow ID.'
+        });
     }
 }

package/dist/commands/workflow/monitor.spec.js

@@ -39,9 +39,11 @@ const update = (status, overrides = {}) => ({
     cursor: { pageToken: 'token', lastEventId: 1, meta: null, runId: 'run-1', events: [] }
 });
 describe('workflow monitor command', () => {
-    beforeEach(() => {
+    beforeEach(async () => {
         vi.clearAllMocks();
         process.exitCode = undefined;
+        const { sleep } = await import('#utils/sleep.js');
+        vi.mocked(sleep).mockResolvedValue(undefined);
     });
     describe('command definition', () => {
         it('exports a valid OCLIF command with a required workflowId arg', async () => {
@@ -99,6 +101,14 @@ describe('workflow monitor command', () => {
             expect(cmd.log).toHaveBeenCalledWith(expect.stringContaining('workflow completed'));
             expect(process.exitCode).toBeUndefined();
         });
+        it('pins the fetch to an explicit run id instead of resolving the latest run', async () => {
+            const { cmd, fetchWorkflowHistory } = await createCommand({ 'run-id': 'run-9' });
+            fetchWorkflowHistory.mockResolvedValueOnce(history('completed', { runId: 'run-9' }));
+            await cmd.run();
+            // The whole point of `start --monitor` pinning the run it just started: the
+            // id has to survive options -> state -> the first fetch, not just be accepted.
+            expect(fetchWorkflowHistory).toHaveBeenCalledWith(expect.objectContaining({ runId: 'run-9' }));
+        });
         it('sets exit code 1 when the workflow ends in a failed status', async () => {
             const { cmd, fetchWorkflowHistory } = await createCommand();
             fetchWorkflowHistory.mockResolvedValueOnce(history('failed', {
@@ -170,12 +180,31 @@ describe('workflow monitor command', () => {
             fetchWorkflowHistory.mockResolvedValueOnce(history('continued_as_new'));
             await expect(cmd.run()).rejects.toThrow(/new run ID could not be determined/);
         });
-        it('propagates a failure on the very first poll', async () => {
+        it('propagates a non-transient failure on the very first poll', async () => {
             const { cmd, fetchWorkflowHistory } = await createCommand();
             fetchWorkflowHistory.mockRejectedValue(new Error('network down'));
             await expect(cmd.run()).rejects.toThrow('network down');
             expect(fetchWorkflowHistory).toHaveBeenCalledTimes(1);
         });
+        it('retries a transient failure on the very first poll instead of aborting', async () => {
+            const { cmd, fetchWorkflowHistory } = await createCommand();
+            // `start --monitor` polls milliseconds after the API accepted the start, so
+            // the first poll is the one most likely to catch a restart — giving up there
+            // would abandon a workflow that is already running.
+            fetchWorkflowHistory
+                .mockRejectedValueOnce(new HttpError('Service unavailable', { status: 503 }))
+                .mockResolvedValueOnce(history('completed', { totalDurationMs: 1000 }));
+            await cmd.run();
+            expect(fetchWorkflowHistory).toHaveBeenCalledTimes(2);
+            expect(cmd.warn).toHaveBeenCalledWith(expect.stringContaining('(1/5)'));
+            expect(process.exitCode).toBeUndefined();
+        });
+        it('gives up on the first poll once the retry budget is exhausted', async () => {
+            const { cmd, fetchWorkflowHistory } = await createCommand();
+            fetchWorkflowHistory.mockRejectedValue(new HttpError('Service unavailable', { status: 503 }));
+            await expect(cmd.run()).rejects.toThrow('Service unavailable');
+            expect(fetchWorkflowHistory).toHaveBeenCalledTimes(5);
+        });
         it('retries a transient network failure after the first successful poll instead of crashing', async () => {
             const { cmd, fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await createCommand();
             fetchWorkflowHistory.mockResolvedValueOnce(history('running'));
@@ -217,11 +246,61 @@ describe('workflow monitor command', () => {
             expect(sigintCall).toBeDefined();
             const handler = sigintCall[1];
             handler();
+            // The exit is deferred until stdout drains, so it can't truncate the
+            // workflow ID `start --monitor` printed moments earlier.
+            expect(exitSpy).not.toHaveBeenCalled();
+            await new Promise(resolve => setImmediate(resolve));
             expect(exitSpy).toHaveBeenCalledWith(130);
-            expect(cmd.log).toHaveBeenCalledWith(expect.stringContaining('Detached'));
+            // The detach message names the follow-up commands, since the workflow is
+            // still running and the user has nothing else on screen to act on.
+            const detached = cmd.log.mock.calls
+                .map(([line]) => line)
+                .find((line) => line.includes('Detached'));
+            expect(detached).toContain('workflow status wf-1');
+            expect(detached).toContain('workflow result wf-1');
             onSpy.mockRestore();
             exitSpy.mockRestore();
         });
+        it('records exit 130 on detach even when the command unwinds first', async () => {
+            const { cmd, fetchWorkflowHistory } = await createCommand();
+            const { sleep } = await import('#utils/sleep.js');
+            // Still running, so the loop sleeps — that's where Ctrl+C lands in practice.
+            fetchWorkflowHistory.mockResolvedValue(history('running'));
+            const onSpy = vi.spyOn(process, 'on');
+            const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined));
+            vi.mocked(sleep).mockImplementation(async () => {
+                const sigint = onSpy.mock.calls.find(([event]) => event === 'SIGINT');
+                sigint[1]();
+            });
+            await cmd.run();
+            // The deferred exit races the command returning normally; if the natural
+            // unwind wins, only the recorded code decides what the shell sees.
+            expect(process.exitCode).toBe(130);
+            // Let the deferred flush land while process.exit is still stubbed.
+            await new Promise(resolve => setImmediate(resolve));
+            expect(exitSpy).toHaveBeenCalledWith(130);
+            onSpy.mockRestore();
+            exitSpy.mockRestore();
+        });
+        it('blames the workflow id for a 404, which is the argument the user typed', async () => {
+            const { cmd } = await createCommand();
+            const notFound = Object.assign(new Error('not found'), {
+                response: { status: 404, data: { error: 'WorkflowNotFoundError', message: 'Workflow "wf-1" not found' } }
+            });
+            // The override lives on this command rather than in the shared
+            // `monitorErrorOverrides`: under `start --monitor` the id came back from the
+            // API, so the same advice would misdirect the user.
+            await expect(cmd.catch(notFound)).rejects.toThrow();
+            expect(cmd.error).toHaveBeenCalledWith('Workflow not found. Check the workflow ID.', expect.objectContaining({ exit: 1 }));
+        });
+        it('explains a stale resume cursor behind the API\'s generic 400', async () => {
+            const { cmd } = await createCommand();
+            const staleCursor = Object.assign(new Error('bad request'), {
+                response: { status: 400, data: { error: 'InvalidPageTokenError' } }
+            });
+            await expect(cmd.catch(staleCursor)).rejects.toThrow();
+            expect(cmd.error).toHaveBeenCalledWith(expect.stringContaining('Resume cursor is no longer valid'), expect.objectContaining({ exit: 1 }));
+        });
         it('emits NDJSON lines under --format json', async () => {
             const { cmd, fetchWorkflowHistory } = await createCommand({ format: 'json' });
             fetchWorkflowHistory.mockResolvedValueOnce(history('completed', { spans: [span('1', 'completed')], totalDurationMs: 1000 }));

package/dist/commands/workflow/result.js

@@ -1,6 +1,6 @@
 import { Args, Command } from '@oclif/core';
 import { getWorkflowIdResult } from '#api/generated/api.js';
-import { formatWorkflowResult, ERROR_STATUSES } from '#utils/format_workflow_result.js';
+import { formatWorkflowResult, isErrorStatus } from '#utils/format_workflow_result.js';
 import { handleApiError } from '#utils/error_handler.js';
 export default class WorkflowResult extends Command {
     static description = 'Get workflow execution result';
@@ -24,7 +24,7 @@ export default class WorkflowResult extends Command {
         }
         const data = response.data;
         this.log(`\n${formatWorkflowResult(data)}`);
-        if (ERROR_STATUSES.has(data.status)) {
+        if (isErrorStatus(data.status)) {
             process.exitCode = 1;
         }
         return data;