@outputai/cli 0.10.1-next.37650c5.0 → 0.10.1-next.52bedcf.0

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

@@ -393,6 +393,12 @@ export type GetWorkflowIdHistoryParams = {
      * Include decoded input/output payloads in events
      */
     includePayloads?: boolean;
+    /**
+     * When set, long-poll for a new event once caught up to the end of history instead of returning immediately, bounding the block by this many milliseconds. Clamped to the server's configured maximum — a caller can shorten the wait but never exceed it. Omit for an immediate response; on timeout returns the same page's cursor unchanged with an empty events array so the caller can retry. Lets a poller keep the block roughly aligned with its own tick interval.
+    
+     * @minimum 1
+     */
+    longPollTimeoutMs?: number;
 };
 /**
  * Workflow metadata (null on subsequent pages)
@@ -431,6 +437,12 @@ export type GetWorkflowIdRunsRidHistoryParams = {
      * Include decoded input/output payloads in events
      */
     includePayloads?: boolean;
+    /**
+     * When set, long-poll for a new event once caught up to the end of history instead of returning immediately, bounding the block by this many milliseconds. Clamped to the server's configured maximum — a caller can shorten the wait but never exceed it. Omit for an immediate response; on timeout returns the same page's cursor unchanged with an empty events array so the caller can retry. Lets a poller keep the block roughly aligned with its own tick interval.
+    
+     * @minimum 1
+     */
+    longPollTimeoutMs?: number;
 };
 /**
  * Workflow metadata (null on subsequent pages)

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.37650c5.0}
+    image: outputai/api:${OUTPUT_API_VERSION:-0.10.1-next.52bedcf.0}
     init: true
     networks:
       - main

package/dist/commands/dev/index.js

@@ -110,7 +110,28 @@ export default class Dev extends Command {
         // `instance` ref is filled in once `render()` returns; until then,
         // signal handlers just stop docker and exit.
         const instanceRef = { current: null };
-        process.on('exit', exitAltScreenOnce);
+        // Single terminal-restore sequence shared by every exit path: stop Ink
+        // (frees raw mode) then leave the alt-screen. The `finally` guarantees
+        // the alt-screen is left even if `unmount()` throws — otherwise a crash
+        // could strand the user in the blank alt buffer. This is the one place
+        // the unmount → leave-alt-screen order lives, so the paths can't drift.
+        const restoreTerminal = () => {
+            try {
+                instanceRef.current?.unmount();
+            }
+            finally {
+                exitAltScreenOnce();
+            }
+        };
+        // Collect a disposer for every process listener so registration and
+        // teardown can't drift: a handler added through `on` is always removed by
+        // the `finally` below, with no separate removeListener list to keep in sync.
+        const disposers = [];
+        const on = (event, handler) => {
+            process.on(event, handler);
+            disposers.push(() => process.removeListener(event, handler));
+        };
+        on('exit', exitAltScreenOnce);
         // `process.on` doesn't await the handler, so the cleanup promise would
         // float and any rejection would surface as an unhandled rejection.
         // Wrap the async work in a sync registration that explicitly logs
@@ -124,10 +145,35 @@ export default class Dev extends Command {
                 exitAltScreenOnce();
                 console.error('Cleanup failed:', getErrorMessage(err));
             })
-                .finally(() => instanceRef.current?.unmount());
+                .finally(restoreTerminal);
         };
-        process.on('SIGINT', handleSignal);
-        process.on('SIGTERM', handleSignal);
+        on('SIGINT', handleSignal);
+        on('SIGTERM', handleSignal);
+        // A fatal crash (uncaught exception / unhandled rejection) skips both the
+        // clean-exit path and the signal handlers. Tear docker down via cleanup()
+        // FIRST, then restore the terminal and print the crash: unmounting Ink
+        // resolves the awaited waitUntilExit(), which resumes run() and strips the
+        // signal listeners — so unmounting before cleanup would drop them
+        // mid-teardown and let a Ctrl+C orphan the stack. Print the raw error so
+        // Node's stack trace survives, then re-exit non-zero. Fire-once: a second
+        // catchable crash during teardown is a no-op. A hard V8 abort() (SIGABRT)
+        // is uncatchable and not covered here.
+        const fatalState = { handled: false };
+        const handleFatalError = (err) => {
+            if (fatalState.handled) {
+                return;
+            }
+            fatalState.handled = true;
+            cleanup()
+                .catch(cleanupErr => console.error('Cleanup failed:', getErrorMessage(cleanupErr)))
+                .finally(() => {
+                restoreTerminal();
+                console.error(err);
+                process.exit(1);
+            });
+        };
+        on('uncaughtException', handleFatalError);
+        on('unhandledRejection', handleFatalError);
         try {
             enterAltScreen();
             const instance = render(React.createElement(DevApp, { dockerComposePath, onCleanup: cleanup }), { exitOnCtrlC: false });
@@ -158,9 +204,14 @@ export default class Dev extends Command {
             exitAltScreenOnce();
         }
         catch (error) {
-            instanceRef.current?.unmount();
-            exitAltScreenOnce();
+            restoreTerminal();
             this.error(getErrorMessage(error), { exit: 1 });
         }
+        finally {
+            // Remove every process-global listener registered above; otherwise each
+            // run() (test invocations included) leaks a live handler that force-
+            // exits the process on the next stray signal or rejection.
+            disposers.forEach(dispose => dispose());
+        }
     }
 }

package/dist/commands/dev/index.spec.js

@@ -328,6 +328,61 @@ describe('dev command', () => {
             expect(cmd.error).not.toHaveBeenCalled();
         });
     });
+    describe('fatal error handling', () => {
+        it('restores the terminal and exits non-zero on an uncaught exception', async () => {
+            const inkInstance = createControllableInkInstance();
+            vi.mocked(render).mockReturnValue(inkInstance);
+            // Capture the registered handlers instead of letting them attach to the
+            // real process, and neutralize process.exit so firing one doesn't kill
+            // the test runner.
+            const handlers = {};
+            const onSpy = vi.spyOn(process, 'on').mockImplementation(((event, handler) => {
+                handlers[event] = handler;
+                return process;
+            }));
+            const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined));
+            const stdoutSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+            const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+            const cmd = new Dev([], {});
+            cmd.log = vi.fn();
+            cmd.error = vi.fn();
+            Object.defineProperty(cmd, 'parse', {
+                value: vi.fn().mockResolvedValue({ flags: { 'compose-file': undefined, 'image-pull-policy': 'always' }, args: {} }),
+                configurable: true
+            });
+            const runPromise = cmd.run();
+            await new Promise(resolve => setImmediate(resolve));
+            expect(handlers.uncaughtException).toBeInstanceOf(Function);
+            expect(handlers.unhandledRejection).toBeInstanceOf(Function);
+            const crash = new Error('boom');
+            handlers.uncaughtException(crash);
+            // Terminal restore, the crash print, and exit all run after docker
+            // teardown settles, so they land a tick later.
+            await new Promise(resolve => setImmediate(resolve));
+            // Docker is torn down before exit, so a crash doesn't orphan the
+            // compose stack.
+            expect(dockerService.stopDockerCompose).toHaveBeenCalled();
+            expect(inkInstance.unmount).toHaveBeenCalled();
+            expect(stdoutSpy).toHaveBeenCalledWith('\x1b[?1049l');
+            expect(errorSpy).toHaveBeenCalledWith(crash);
+            expect(exitSpy).toHaveBeenCalledWith(1);
+            // Discriminating order: docker must be fully torn down BEFORE Ink
+            // unmounts. Unmounting resolves waitUntilExit() and resumes run(),
+            // which strips the signal listeners — so an unmount-first ordering
+            // would drop the SIGINT handler mid-teardown and risk orphaning the
+            // stack on a Ctrl+C.
+            expect(vi.mocked(dockerService.stopDockerCompose).mock.invocationCallOrder[0])
+                .toBeLessThan(inkInstance.unmount.mock.invocationCallOrder[0]);
+            // Within the restore, Ink unmounts before the alt-screen is left, and
+            // the crash prints only after — otherwise console.error paints into a
+            // buffer the user never sees.
+            const leaveAltScreenCall = stdoutSpy.mock.invocationCallOrder[stdoutSpy.mock.calls.findIndex(([seq]) => seq === '\x1b[?1049l')];
+            expect(inkInstance.unmount.mock.invocationCallOrder[0]).toBeLessThan(leaveAltScreenCall);
+            expect(leaveAltScreenCall).toBeLessThan(errorSpy.mock.invocationCallOrder[0]);
+            onSpy.mockRestore();
+            runPromise.catch(() => { });
+        });
+    });
     describe('image pull policy', () => {
         it('should pass pull policy to startDockerCompose', async () => {
             const cmd = new Dev([], {});

package/dist/commands/workflow/history.js

@@ -3,6 +3,7 @@ import { fetchWorkflowHistory } from '#services/workflow_history.js';
 import buildSpanLabels from '#utils/span_labels.js';
 import renderWaterfall, { formatDurationLabel } from '#utils/waterfall.js';
 import { handleApiError } from '#utils/error_handler.js';
+import { shouldColorize } from '#utils/color.js';
 const DEFAULT_WIDTH = 80;
 const OUTPUT_FORMAT = { JSON: 'json', TEXT: 'text' };
 export default class WorkflowHistory extends Command {
@@ -56,7 +57,7 @@ export default class WorkflowHistory extends Command {
         });
         if (flags.raw) {
             this.log(JSON.stringify({
-                workflow: result.workflow,
+                workflow: result.rawWorkflow,
                 runId: result.runId,
                 events: result.events
             }, null, 2));
@@ -73,8 +74,7 @@ export default class WorkflowHistory extends Command {
         }
         const labels = buildSpanLabels(result.spans);
         const width = flags.width ?? process.stdout.columns ?? DEFAULT_WIDTH;
-        const color = flags.color && !process.env.NO_COLOR &&
-            (!!process.env.FORCE_COLOR || process.stdout.isTTY === true);
+        const color = shouldColorize(flags.color);
         this.log(renderWaterfall(result.spans, result.totalDurationMs, {
             width,
             color,

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

@@ -1,6 +1,9 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
 import { describe, it, expect, vi } from 'vitest';
-// Isolate the command module from the API/service layer at import time.
-vi.mock('../../services/workflow_history.js', () => ({
+// Isolate the command module from the API/service layer at import time. Must use the
+// `#`-aliased specifier — history.ts imports via that alias, and a relative specifier here
+// resolves to a different module id, so the mock silently never intercepts the real import.
+vi.mock('#services/workflow_history.js', () => ({
     fetchWorkflowHistory: vi.fn()
 }));
 describe('workflow history command', () => {
@@ -23,4 +26,30 @@ describe('workflow history command', () => {
         expect(flags.format.default).toBe('text');
         expect(flags.raw.default).toBe(false);
     });
+    describe('run() --raw', () => {
+        it('prints the server\'s literal status, not the client-normalized one', async () => {
+            const WorkflowHistory = (await import('./history.js')).default;
+            const { fetchWorkflowHistory } = await import('#services/workflow_history.js');
+            // `workflow` carries the normalized status (what monitor/waterfall consume);
+            // `rawWorkflow` is the untouched server value — `--raw` must use the latter.
+            vi.mocked(fetchWorkflowHistory).mockResolvedValueOnce({
+                workflow: { workflowId: 'wf-1', runId: 'run-1', status: 'continued_as_new' },
+                rawWorkflow: { workflowId: 'wf-1', runId: 'run-1', status: 'continued' },
+                runId: 'run-1',
+                events: [],
+                spans: [],
+                totalDurationMs: 0,
+                continuedAsNewRunId: null
+            });
+            const cmd = new WorkflowHistory(['wf-1', '--raw'], {});
+            cmd.log = vi.fn();
+            cmd.parse = vi.fn().mockResolvedValue({
+                args: { workflowId: 'wf-1' },
+                flags: { 'run-id': undefined, format: 'text', raw: true, 'include-payloads': false, width: undefined, color: false }
+            });
+            await cmd.run();
+            const printed = JSON.parse(cmd.log.mock.calls[0][0]);
+            expect(printed.workflow.status).toBe('continued');
+        });
+    });
 });

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

@@ -0,0 +1,49 @@
+import { Command } from '@oclif/core';
+/**
+ * Unlike `run`/`status`/`result` (migrated to oclif's native `--json` in
+ * OUT-419, #281), this command deliberately keeps a custom `--format json`
+ * instead of `enableJsonFlag`. Native `--json` suppresses all `this.log()`
+ * calls and prints exactly one JSON object — the command's return value —
+ * after `run()` resolves. `monitor` has no single "return value": it emits a
+ * live stream of discrete events (span status changes, a continue-as-new
+ * notice, a final summary) while the workflow is still in progress, and
+ * `--format json` prints each as its own NDJSON line as it happens. That's
+ * the point — a caller (often another automated/agent process, not a human)
+ * 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.
+ */
+export default class WorkflowMonitor extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        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(): 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

@@ -0,0 +1,230 @@
+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;
+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`
+ * instead of `enableJsonFlag`. Native `--json` suppresses all `this.log()`
+ * calls and prints exactly one JSON object — the command's return value —
+ * after `run()` resolves. `monitor` has no single "return value": it emits a
+ * live stream of discrete events (span status changes, a continue-as-new
+ * notice, a final summary) while the workflow is still in progress, and
+ * `--format json` prints each as its own NDJSON line as it happens. That's
+ * the point — a caller (often another automated/agent process, not a human)
+ * 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.
+ */
+export default class WorkflowMonitor extends Command {
+    static description = 'Attach to a workflow run and stream status updates until it ends';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> wf-12345',
+        '<%= config.bin %> <%= command.id %> wf-12345 --run-id 2fe0b36b-...',
+        '<%= config.bin %> <%= command.id %> wf-12345 --format json'
+    ];
+    static args = {
+        workflowId: Args.string({
+            description: 'The workflow ID to monitor',
+            required: true
+        })
+    };
+    static flags = {
+        'run-id': Flags.string({
+            char: 'r',
+            description: 'Monitor a specific run (defaults to the latest run; continue-as-new chains are followed regardless)'
+        }),
+        format: Flags.string({
+            char: 'f',
+            description: 'Output format',
+            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
+        })
+    };
+    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 = {
+            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;
+        }
+    }
+    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);
+    }
+}

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

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