@outputai/cli 0.10.1-dev.b7b2fbe.0 → 0.10.1-next.2cbd0a2.0

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

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

@@ -0,0 +1,243 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { HttpError } from '#api/http_client.js';
+vi.mock('#services/workflow_history.js', () => ({ fetchWorkflowHistory: vi.fn(), fetchWorkflowHistoryUpdates: vi.fn() }));
+vi.mock('#utils/sleep.js', () => ({ sleep: vi.fn().mockResolvedValue(undefined) }));
+const span = (id, status, overrides = {}) => ({
+    id,
+    name: `Step ${id}`,
+    technicalName: `wf#step${id}`,
+    description: null,
+    status,
+    kind: 'activity',
+    attempt: 1,
+    startedAt: null,
+    scheduledAt: null,
+    completedAt: null,
+    startOffsetMs: 0,
+    endOffsetMs: 0,
+    durationMs: 1000,
+    failureMessage: null,
+    ...overrides
+});
+const history = (status, overrides = {}) => ({
+    workflow: { status },
+    runId: 'run-1',
+    events: [],
+    spans: [],
+    totalDurationMs: 0,
+    continuedAsNewRunId: null,
+    // Every result carries a cursor now (see workflow_history.ts) — `poll()` uses its
+    // presence to decide fetchWorkflowHistory vs. fetchWorkflowHistoryUpdates on the next tick.
+    cursor: { pageToken: 'token', lastEventId: 1, meta: null, runId: 'run-1', events: [] },
+    ...overrides
+});
+// `fetchWorkflowHistoryUpdates` (used from the second poll onward) wraps the same result
+// shape with a resume cursor; tests don't care about cursor contents, only that it's threaded.
+const update = (status, overrides = {}) => ({
+    result: history(status, overrides),
+    cursor: { pageToken: 'token', lastEventId: 1, meta: null, runId: 'run-1', events: [] }
+});
+describe('workflow monitor command', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        process.exitCode = undefined;
+    });
+    describe('command definition', () => {
+        it('exports a valid OCLIF command with a required workflowId arg', async () => {
+            const WorkflowMonitor = (await import('./monitor.js')).default;
+            expect(WorkflowMonitor).toBeDefined();
+            expect(WorkflowMonitor.args).toHaveProperty('workflowId');
+            expect(WorkflowMonitor.args.workflowId.required).toBe(true);
+        });
+        it('declares the expected flags and defaults', async () => {
+            const WorkflowMonitor = (await import('./monitor.js')).default;
+            const flags = WorkflowMonitor.flags;
+            expect(flags).toHaveProperty('run-id');
+            expect(flags).toHaveProperty('include-payloads');
+            expect(flags).toHaveProperty('interval');
+            expect(flags).toHaveProperty('color');
+            expect(flags.format.options).toEqual(['text', 'json']);
+            expect(flags.format.default).toBe('text');
+            expect(flags.interval.default).toBe(2500);
+            expect(flags.color.default).toBe(true);
+        });
+    });
+    describe('run()', () => {
+        const createCommand = async (flagOverrides = {}) => {
+            const WorkflowMonitor = (await import('./monitor.js')).default;
+            const { fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await import('#services/workflow_history.js');
+            const cmd = new WorkflowMonitor(['wf-1'], {});
+            cmd.log = vi.fn();
+            cmd.warn = vi.fn();
+            cmd.error = vi.fn((message) => {
+                throw new Error(message);
+            });
+            cmd.parse = vi.fn().mockResolvedValue({
+                args: { workflowId: 'wf-1' },
+                flags: {
+                    'run-id': undefined,
+                    format: 'text',
+                    'include-payloads': false,
+                    interval: 1,
+                    color: false,
+                    ...flagOverrides
+                }
+            });
+            return {
+                cmd,
+                fetchWorkflowHistory: vi.mocked(fetchWorkflowHistory),
+                fetchWorkflowHistoryUpdates: vi.mocked(fetchWorkflowHistoryUpdates)
+            };
+        };
+        it('prints span updates and exits cleanly when the workflow is already completed on the first poll', async () => {
+            const { cmd, fetchWorkflowHistory } = await createCommand();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('completed', { spans: [span('1', 'completed')], totalDurationMs: 5000 }));
+            await cmd.run();
+            expect(fetchWorkflowHistory).toHaveBeenCalledTimes(1);
+            expect(cmd.log).toHaveBeenCalledWith(expect.stringContaining('Step 1'));
+            expect(cmd.log).toHaveBeenCalledWith(expect.stringContaining('workflow completed'));
+            expect(process.exitCode).toBeUndefined();
+        });
+        it('sets exit code 1 when the workflow ends in a failed status', async () => {
+            const { cmd, fetchWorkflowHistory } = await createCommand();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('failed', {
+                spans: [span('1', 'failed', { failureMessage: 'boom' })], totalDurationMs: 1000
+            }));
+            await cmd.run();
+            expect(process.exitCode).toBe(1);
+        });
+        it('polls again while the workflow is running, then stops once it completes', async () => {
+            const { cmd, fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await createCommand();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('running', { spans: [span('1', 'running')] }));
+            fetchWorkflowHistoryUpdates.mockResolvedValueOnce(update('completed', {
+                spans: [span('1', 'completed')], totalDurationMs: 2000
+            }));
+            await cmd.run();
+            expect(fetchWorkflowHistory).toHaveBeenCalledTimes(1);
+            expect(fetchWorkflowHistoryUpdates).toHaveBeenCalledTimes(1);
+            expect(cmd.log).toHaveBeenCalledWith(expect.stringContaining('running'));
+            expect(cmd.log).toHaveBeenCalledWith(expect.stringContaining('1s'));
+            expect(process.exitCode).toBeUndefined();
+        });
+        it('keeps a span label stable once printed, even when a same-named span appears on a later poll', async () => {
+            const { cmd, fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await createCommand();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('running', { spans: [span('1', 'running', { name: 'Scrape Page' })] }));
+            // Span 2 shares span 1's name, only showing up on the second poll — buildSpanLabels
+            // would number both "#1"/"#2" if recomputed fresh, retroactively relabeling span 1's
+            // already-printed "running" line.
+            fetchWorkflowHistoryUpdates.mockResolvedValueOnce(update('completed', {
+                spans: [
+                    span('1', 'completed', { name: 'Scrape Page' }),
+                    span('2', 'completed', { name: 'Scrape Page' })
+                ]
+            }));
+            await cmd.run();
+            const lines = cmd.log.mock.calls.map(([line]) => line);
+            expect(lines.some((line) => line.includes('Scrape Page running'))).toBe(true);
+            // Span 1's completion line keeps its original unnumbered label...
+            expect(lines.some((line) => line.includes('Scrape Page  '))).toBe(true);
+            expect(lines.some((line) => line.includes('Scrape Page #1'))).toBe(false);
+            // ...while span 2, new this tick, is free to be numbered.
+            expect(lines.some((line) => line.includes('Scrape Page #2'))).toBe(true);
+        });
+        it('does not re-print a span whose status has not changed between polls', async () => {
+            const { cmd, fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await createCommand();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('running', { spans: [span('1', 'running')] }));
+            fetchWorkflowHistoryUpdates.mockResolvedValueOnce(update('completed', {
+                spans: [span('1', 'running'), span('2', 'completed')], totalDurationMs: 1000
+            }));
+            await cmd.run();
+            const runningLines = cmd.log.mock.calls.filter(([line]) => line.includes('Step 1'));
+            expect(runningLines).toHaveLength(1); // span 1 only reported once, not again on the second poll
+        });
+        it('follows a continue-as-new chain by re-polling with the new run id', async () => {
+            const { cmd, fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await createCommand();
+            fetchWorkflowHistory
+                .mockResolvedValueOnce(history('continued_as_new', { continuedAsNewRunId: 'run-2' }))
+                // The new run's cursor was reset, so its first poll takes the same fast,
+                // non-waiting path as the very first poll of the command — not a resumed one.
+                .mockResolvedValueOnce(history('completed', { runId: 'run-2', totalDurationMs: 500 }));
+            await cmd.run();
+            expect(fetchWorkflowHistory).toHaveBeenCalledTimes(2);
+            expect(fetchWorkflowHistory).toHaveBeenNthCalledWith(2, expect.objectContaining({ runId: 'run-2' }));
+            expect(fetchWorkflowHistoryUpdates).not.toHaveBeenCalled();
+            expect(cmd.log).toHaveBeenCalledWith(expect.stringContaining('continued as new run run-2'));
+            expect(process.exitCode).toBeUndefined();
+        });
+        it('errors when the workflow continues as new but no new run id can be determined', async () => {
+            const { cmd, fetchWorkflowHistory } = await createCommand();
+            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 () => {
+            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 network failure after the first successful poll instead of crashing', async () => {
+            const { cmd, fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await createCommand();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('running'));
+            fetchWorkflowHistoryUpdates
+                .mockRejectedValueOnce(Object.assign(new Error('blip'), { code: 'ECONNRESET' }))
+                .mockResolvedValueOnce(update('completed', { totalDurationMs: 1000 }));
+            await cmd.run();
+            expect(fetchWorkflowHistory).toHaveBeenCalledTimes(1);
+            expect(fetchWorkflowHistoryUpdates).toHaveBeenCalledTimes(2);
+            expect(cmd.warn).toHaveBeenCalledWith(expect.stringContaining('(1/5)'));
+            expect(process.exitCode).toBeUndefined();
+        });
+        it('retries a transient 503 HttpError after the first successful poll', async () => {
+            const { cmd, fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await createCommand();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('running'));
+            fetchWorkflowHistoryUpdates
+                .mockRejectedValueOnce(new HttpError('Service unavailable', { status: 503 }))
+                .mockResolvedValueOnce(update('completed', { totalDurationMs: 1000 }));
+            await cmd.run();
+            expect(fetchWorkflowHistoryUpdates).toHaveBeenCalledTimes(2);
+            expect(cmd.warn).toHaveBeenCalledWith(expect.stringContaining('(1/5)'));
+            expect(process.exitCode).toBeUndefined();
+        });
+        it('immediately rethrows a non-transient error (e.g. a stale resume cursor) without retrying', async () => {
+            const { cmd, fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await createCommand();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('running'));
+            fetchWorkflowHistoryUpdates.mockRejectedValueOnce(new HttpError('Invalid page token', { status: 400 }));
+            await expect(cmd.run()).rejects.toThrow('Invalid page token');
+            expect(fetchWorkflowHistoryUpdates).toHaveBeenCalledTimes(1);
+            expect(cmd.warn).not.toHaveBeenCalled();
+        });
+        it('registers a SIGINT handler that detaches and exits 130 without affecting the workflow', async () => {
+            const { cmd, fetchWorkflowHistory } = await createCommand();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('completed'));
+            const onSpy = vi.spyOn(process, 'on');
+            const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined));
+            await cmd.run();
+            const sigintCall = onSpy.mock.calls.find(([event]) => event === 'SIGINT');
+            expect(sigintCall).toBeDefined();
+            const handler = sigintCall[1];
+            handler();
+            expect(exitSpy).toHaveBeenCalledWith(130);
+            expect(cmd.log).toHaveBeenCalledWith(expect.stringContaining('Detached'));
+            onSpy.mockRestore();
+            exitSpy.mockRestore();
+        });
+        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 }));
+            await cmd.run();
+            const lines = cmd.log.mock.calls.map(([line]) => line);
+            expect(lines.every((line) => {
+                try {
+                    JSON.parse(line);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            })).toBe(true);
+            expect(lines.some((line) => JSON.parse(line).span?.id === '1')).toBe(true);
+            expect(lines.some((line) => JSON.parse(line).monitoring === true)).toBe(true);
+        });
+    });
+});

package/dist/generated/framework_version.json

@@ -1,3 +1,3 @@
 {
-    "framework": "0.10.1-dev.b7b2fbe.0"
+    "framework": "0.10.1-next.2cbd0a2.0"
 }

package/dist/services/docker.d.ts

@@ -24,10 +24,32 @@ export declare class DockerComposeConfigNotFoundError extends Error {
 declare const isDockerInstalled: () => boolean;
 export declare function validateDockerEnvironment(): void;
 export declare function getDefaultDockerComposePath(): string;
+export declare function resolveDockerComposePath(customPath?: string): Promise<string>;
 export declare function parseServiceStatus(jsonOutput: string): ServiceStatus[];
 export declare function getServiceStatus(dockerComposePath: string): Promise<ServiceStatus[]>;
 export declare function isServiceHealthy(service: ServiceStatus): boolean;
 export declare function isServiceFailed(service: ServiceStatus): boolean;
+export declare const STACK_STATE: {
+    /** Nothing live for this project — a fresh start we own. */
+    readonly NONE: "none";
+    /** Every container found is running and healthy (or has no healthcheck). */
+    readonly RUNNING: "running";
+    /** Something is live but not everything is healthy — reconcile. */
+    readonly PARTIAL: "partial";
+};
+export type StackState = typeof STACK_STATE[keyof typeof STACK_STATE];
+/**
+ * Classify the current state of a project's stack from `docker compose ps`.
+ *
+ * This is the detection signal `output dev` branches on: nothing live means a
+ * fresh start; an all-healthy result means we can attach and monitor without
+ * touching the stack; anything in between is reconciled with `up -d`.
+ *
+ * Scoped to the shared `output-sdk` compose project, which distinguishes our
+ * containers from unrelated processes — but not one Output checkout from
+ * another, since the project name defaults to a machine-global constant.
+ */
+export declare function classifyStackState(services: ServiceStatus[]): StackState;
 export declare function waitForServicesHealthy(dockerComposePath: string, timeoutMs?: number, pollIntervalMs?: number): Promise<void>;
 export interface DockerComposeHandlers {
     onError?: (error: Error, output: string) => void;
@@ -39,6 +61,11 @@ export interface StartDockerComposeOptions extends DockerComposeHandlers {
     pullPolicy?: PullPolicy;
 }
 export declare function startDockerCompose({ dockerComposePath, pullPolicy, onError, onExit }: StartDockerComposeOptions): Promise<ChildProcess>;
-export declare function startDockerComposeDetached(dockerComposePath: string, pullPolicy?: PullPolicy): void;
+export interface DetachedUpResult {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    output: string;
+}
+export declare function runDockerComposeUpDetached(dockerComposePath: string, pullPolicy?: PullPolicy): Promise<DetachedUpResult>;
 export declare function stopDockerCompose(dockerComposePath: string): Promise<void>;
 export { isDockerInstalled, DockerValidationError };