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

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

@@ -1,7 +1,6 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import React from 'react';
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import fs from 'node:fs/promises';
 import { render } from 'ink';
 import * as dockerService from '#services/docker.js';
 import * as codingAgentsService from '#services/coding_agents.js';
@@ -13,34 +12,23 @@ vi.mock('#services/coding_agents.js', () => ({
 vi.mock('#utils/port_availability.js', () => ({
     findUnavailablePorts: vi.fn().mockResolvedValue([])
 }));
-vi.mock('#services/docker.js', () => ({
-    validateDockerEnvironment: vi.fn(),
-    startDockerCompose: vi.fn(),
-    stopDockerCompose: vi.fn().mockResolvedValue(undefined),
-    getServiceStatus: vi.fn().mockResolvedValue([
-        { name: 'redis', state: 'running', health: 'healthy', ports: ['6379:6379'] },
-        { name: 'temporal', state: 'running', health: 'healthy', ports: ['7233:7233'] }
-    ]),
-    isServiceFailed: vi.fn((s) => s.state === 'exited' || s.health === 'unhealthy'),
-    DockerComposeConfigNotFoundError: Error,
-    DockerValidationError: Error,
-    getDefaultDockerComposePath: vi.fn(() => '/path/to/docker-compose-dev.yml'),
-    SERVICE_HEALTH: {
-        HEALTHY: 'healthy',
-        UNHEALTHY: 'unhealthy',
-        STARTING: 'starting',
-        NONE: 'none'
-    },
-    SERVICE_STATE: {
-        RUNNING: 'running',
-        EXITED: 'exited'
-    }
-}));
-vi.mock('node:fs/promises', () => ({
-    default: {
-        access: vi.fn()
-    }
-}));
+vi.mock('#services/docker.js', async (importActual) => {
+    const actual = await importActual();
+    return {
+        ...actual,
+        // Override only the IO surface. Pure helpers (classifyStackState,
+        // isServiceHealthy, STACK_STATE, error classes) come from the real module,
+        // so branch selection here exercises the same logic production runs.
+        validateDockerEnvironment: vi.fn(),
+        startDockerCompose: vi.fn(),
+        runDockerComposeUpDetached: vi.fn().mockResolvedValue({ code: 0, signal: null, output: '' }),
+        stopDockerCompose: vi.fn().mockResolvedValue(undefined),
+        // Default: nothing running — a fresh start. Individual tests opt into an
+        // existing stack by overriding this to drive attach / reconcile branches.
+        getServiceStatus: vi.fn().mockResolvedValue([]),
+        resolveDockerComposePath: vi.fn().mockResolvedValue('/path/to/docker-compose-dev.yml')
+    };
+});
 vi.mock('ink', () => ({
     render: vi.fn().mockReturnValue({
         waitUntilExit: vi.fn().mockResolvedValue(undefined),
@@ -88,12 +76,22 @@ describe('dev command', () => {
         vi.mocked(dockerService.validateDockerEnvironment).mockResolvedValue(undefined);
         // By default, no host port is taken — individual tests opt in.
         vi.mocked(portAvailability.findUnavailablePorts).mockResolvedValue([]);
+        // By default, no stack is running — a fresh start. Tests opt into the
+        // attach / reconcile branches by overriding getServiceStatus.
+        vi.mocked(dockerService.getServiceStatus).mockResolvedValue([]);
+        vi.mocked(dockerService.runDockerComposeUpDetached).mockResolvedValue({ code: 0, signal: null, output: '' });
         // By default, startDockerCompose returns a mock process
         vi.mocked(dockerService.startDockerCompose).mockResolvedValue(createMockDockerProcess());
-        // By default, fs.access succeeds (file exists)
-        vi.mocked(fs).access.mockResolvedValue(undefined);
+        // By default, the compose file resolves and exists.
+        vi.mocked(dockerService.resolveDockerComposePath).mockResolvedValue('/path/to/docker-compose-dev.yml');
         // By default, ensureClaudePlugin succeeds
         vi.mocked(codingAgentsService.ensureClaudePlugin).mockResolvedValue(undefined);
+        // By default, render returns an instance that exits immediately. Tests
+        // needing a controllable lifecycle override this.
+        vi.mocked(render).mockReturnValue({
+            waitUntilExit: vi.fn().mockResolvedValue(undefined),
+            unmount: vi.fn()
+        });
     });
     afterEach(() => {
         vi.restoreAllMocks();
@@ -154,19 +152,19 @@ describe('dev command', () => {
             });
             await expect(cmd.run()).rejects.toThrow('Docker is not installed');
         });
-        it('should call validateDockerEnvironment', async () => {
+        it('should call validateDockerEnvironment before doing any work', async () => {
             const cmd = new Dev([], {});
             cmd.log = vi.fn();
             cmd.error = vi.fn();
-            // Mock the subprocess spawn to prevent actual execution
-            vi.doMock('node:child_process', () => ({
-                spawn: vi.fn().mockReturnValue({
-                    on: vi.fn(),
-                    kill: vi.fn()
-                })
-            }));
-            // This test just verifies the function is called
-            expect(vi.mocked(dockerService.validateDockerEnvironment)).toBeDefined();
+            Object.defineProperty(cmd, 'parse', {
+                value: vi.fn().mockResolvedValue({
+                    flags: { 'compose-file': undefined, 'image-pull-policy': 'always', detached: true },
+                    args: {}
+                }),
+                configurable: true
+            });
+            await cmd.run();
+            expect(dockerService.validateDockerEnvironment).toHaveBeenCalled();
         });
     });
     describe('Claude plugin update', () => {
@@ -223,7 +221,7 @@ describe('dev command', () => {
             runPromise.catch(() => { });
         });
         it('should handle docker compose configuration not found', async () => {
-            vi.mocked(fs).access.mockRejectedValue(new Error('File not found'));
+            vi.mocked(dockerService.resolveDockerComposePath).mockRejectedValue(new dockerService.DockerComposeConfigNotFoundError('/path/to/docker-compose-dev.yml'));
             const cmd = new Dev([], {});
             cmd.log = vi.fn();
             cmd.error = vi.fn();
@@ -327,6 +325,356 @@ describe('dev command', () => {
             expect(inkInstance.unmount).not.toHaveBeenCalledWith(expect.any(Error));
             expect(cmd.error).not.toHaveBeenCalled();
         });
+        // Without this, mutating teardownIfOwned to return unconditionally leaves
+        // every test green while each session leaks containers holding ports.
+        it('stops compose and kills the foreground process when it owns the stack', async () => {
+            const dockerProcess = createMockDockerProcess();
+            vi.mocked(dockerService.startDockerCompose).mockResolvedValue(dockerProcess);
+            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', detached: false },
+                    args: {}
+                }),
+                configurable: true
+            });
+            const runPromise = cmd.run();
+            await new Promise(resolve => setImmediate(resolve));
+            const appElement = vi.mocked(render).mock.calls.at(-1)?.[0];
+            if (!React.isValidElement(appElement)) {
+                throw new Error('Expected render to receive a React element');
+            }
+            await appElement.props.onCleanup();
+            expect(dockerService.stopDockerCompose).toHaveBeenCalledWith('/path/to/docker-compose-dev.yml');
+            expect(dockerProcess.kill).toHaveBeenCalledWith('SIGTERM');
+            runPromise.catch(() => { });
+        });
+        // The abnormal-exit route (health timeout, compose crash) resolves outside
+        // the signal path and has its own teardown call.
+        it('tears down an owned stack when the TUI exits abnormally', async () => {
+            const dockerProcess = createMockDockerProcess();
+            vi.mocked(dockerService.startDockerCompose).mockResolvedValue(dockerProcess);
+            const inkInstance = createControllableInkInstance();
+            vi.mocked(render).mockReturnValue(inkInstance);
+            const cmd = new Dev([], {});
+            cmd.log = vi.fn();
+            cmd.error = vi.fn(() => {
+                throw new Error('aborted');
+            });
+            Object.defineProperty(cmd, 'parse', {
+                value: vi.fn().mockResolvedValue({
+                    flags: { 'compose-file': undefined, 'image-pull-policy': 'always', detached: false },
+                    args: {}
+                }),
+                configurable: true
+            });
+            const runPromise = cmd.run();
+            await new Promise(resolve => setImmediate(resolve));
+            inkInstance.unmount(new Error('Timeout waiting for services to become healthy'));
+            await expect(runPromise).rejects.toThrow('aborted');
+            expect(dockerService.stopDockerCompose).toHaveBeenCalledWith('/path/to/docker-compose-dev.yml');
+        });
+    });
+    describe('attach and reconcile behavior', () => {
+        const runningStack = [
+            { name: 'redis', state: 'running', health: 'healthy', ports: [] },
+            { name: 'temporal', state: 'running', health: 'healthy', ports: ['7233:7233'] },
+            { name: 'api', state: 'running', health: 'none', ports: ['3001:3001'] }
+        ];
+        const makeCmd = () => {
+            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', detached: false },
+                    args: {}
+                }),
+                configurable: true
+            });
+            return cmd;
+        };
+        const lastRenderedProps = () => {
+            const appElement = vi.mocked(render).mock.calls.at(-1)?.[0];
+            if (!React.isValidElement(appElement)) {
+                throw new Error('Expected render to receive a React element');
+            }
+            return appElement.props;
+        };
+        it('attaches to a healthy running stack without a foreground up or port probe', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue(runningStack);
+            const cmd = makeCmd();
+            await cmd.run();
+            expect(portAvailability.findUnavailablePorts).not.toHaveBeenCalled();
+            expect(dockerService.startDockerCompose).not.toHaveBeenCalled();
+            expect(dockerService.runDockerComposeUpDetached).not.toHaveBeenCalled();
+            expect(cmd.error).not.toHaveBeenCalled();
+            expect(lastRenderedProps().attached).toBe(true);
+        });
+        it('leaves an attached stack running on cleanup (no teardown)', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue(runningStack);
+            const cmd = makeCmd();
+            await cmd.run();
+            await lastRenderedProps().onCleanup();
+            expect(dockerService.stopDockerCompose).not.toHaveBeenCalled();
+        });
+        it('does not port-probe or error when our own stack already holds the ports', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue(runningStack);
+            vi.mocked(portAvailability.findUnavailablePorts).mockResolvedValue([3001]);
+            const cmd = makeCmd();
+            await cmd.run();
+            expect(portAvailability.findUnavailablePorts).not.toHaveBeenCalled();
+            expect(cmd.error).not.toHaveBeenCalled();
+        });
+        it('reconciles a partially-failed stack with a detached up, then monitors', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue([
+                { name: 'temporal', state: 'running', health: 'healthy', ports: ['7233:7233'] },
+                { name: 'worker', state: 'exited', health: 'none', ports: [] }
+            ]);
+            const cmd = makeCmd();
+            await cmd.run();
+            expect(dockerService.runDockerComposeUpDetached).toHaveBeenCalledWith('/path/to/docker-compose-dev.yml', 'always');
+            // Reconcile monitors via ps polling, not a foreground up.
+            expect(dockerService.startDockerCompose).not.toHaveBeenCalled();
+            expect(portAvailability.findUnavailablePorts).not.toHaveBeenCalled();
+            expect(cmd.error).not.toHaveBeenCalled();
+            expect(lastRenderedProps().attached).toBe(true);
+        });
+        it('aborts with a port-collision hint when the reconcile up fails to bind', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue([
+                { name: 'temporal', state: 'running', health: 'healthy', ports: ['7233:7233'] },
+                { name: 'worker', state: 'exited', health: 'none', ports: [] }
+            ]);
+            vi.mocked(dockerService.runDockerComposeUpDetached).mockResolvedValue({
+                code: 1,
+                signal: null,
+                output: 'Error response from daemon: failed to set up container networking: driver failed ' +
+                    'programming external connectivity on endpoint out-api-1 (a1b2c3): ' +
+                    'Bind for 0.0.0.0:3001 failed: port is already allocated'
+            });
+            const cmd = makeCmd();
+            // this.error throws in oclif; emulate so the flow stops at the abort.
+            const errorMock = vi.fn((_message) => {
+                throw new Error('aborted');
+            });
+            cmd.error = errorMock;
+            await expect(cmd.run()).rejects.toThrow('aborted');
+            const message = errorMock.mock.calls.at(-1)?.[0];
+            expect(message).toContain('Port 3001 is already in use.');
+            expect(message).toContain('OUTPUT_API_HOST_PORT=');
+            expect(render).not.toHaveBeenCalled();
+        });
+        it('falls back to a fresh foreground start when no stack is running', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue([]);
+            const cmd = makeCmd();
+            const runPromise = cmd.run();
+            await new Promise(resolve => setImmediate(resolve));
+            expect(portAvailability.findUnavailablePorts).toHaveBeenCalled();
+            expect(dockerService.startDockerCompose).toHaveBeenCalled();
+            expect(dockerService.runDockerComposeUpDetached).not.toHaveBeenCalled();
+            expect(lastRenderedProps().attached).toBe(false);
+            runPromise.catch(() => { });
+        });
+        // A stopped stack (reboot, `docker compose stop`, failed teardown) leaves
+        // exited rows in `ps --all`. Before the classifier keyed on "is anything
+        // live", these reconciled and then disowned themselves: a plain `output dev`
+        // started every container and left them running on quit.
+        it('treats an all-exited stack as an owned fresh start, not an attach', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue([
+                { name: 'temporal', state: 'exited', health: 'none', ports: [] },
+                { name: 'worker', state: 'exited', health: 'none', ports: [] }
+            ]);
+            const cmd = makeCmd();
+            const runPromise = cmd.run();
+            await new Promise(resolve => setImmediate(resolve));
+            expect(portAvailability.findUnavailablePorts).toHaveBeenCalled();
+            expect(dockerService.startDockerCompose).toHaveBeenCalled();
+            expect(dockerService.runDockerComposeUpDetached).not.toHaveBeenCalled();
+            expect(lastRenderedProps().attached).toBe(false);
+            runPromise.catch(() => { });
+        });
+        it('tears down an all-exited stack it restarted, since it owns it', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue([
+                { name: 'temporal', state: 'exited', health: 'none', ports: [] }
+            ]);
+            const cmd = makeCmd();
+            const runPromise = cmd.run();
+            await new Promise(resolve => setImmediate(resolve));
+            await lastRenderedProps().onCleanup();
+            expect(dockerService.stopDockerCompose).toHaveBeenCalledWith('/path/to/docker-compose-dev.yml');
+            runPromise.catch(() => { });
+        });
+        // The `ps` query absorbs a broken compose file, a dead daemon, EACCES on the
+        // socket, and any JSON.parse throw. Falling back to a fresh start is right;
+        // doing it silently is what reported a port collision with the wrong remedy.
+        it('falls back to a fresh start and warns when the state query fails', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockRejectedValue(new Error('no configuration file provided: not found'));
+            const cmd = makeCmd();
+            cmd.warn = vi.fn();
+            const runPromise = cmd.run();
+            await new Promise(resolve => setImmediate(resolve));
+            expect(portAvailability.findUnavailablePorts).toHaveBeenCalled();
+            expect(dockerService.startDockerCompose).toHaveBeenCalled();
+            expect(lastRenderedProps().attached).toBe(false);
+            const warned = vi.mocked(cmd.warn).mock.calls.map(c => String(c[0])).join('\n');
+            expect(warned).toContain('no configuration file provided: not found');
+            expect(warned).toContain('output dev down');
+            runPromise.catch(() => { });
+        });
+        it('warns that quitting leaves the stack up when attaching', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue(runningStack);
+            const cmd = makeCmd();
+            await cmd.run();
+            const logged = vi.mocked(cmd.log).mock.calls.map(c => c[0]).join('\n');
+            expect(logged).toContain('Quitting leaves these services running');
+            expect(logged).toContain('output dev down');
+        });
+        it('does not claim the stack survives quitting on an owned fresh start', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue([]);
+            const cmd = makeCmd();
+            const runPromise = cmd.run();
+            await new Promise(resolve => setImmediate(resolve));
+            const logged = vi.mocked(cmd.log).mock.calls.map(c => c[0]).join('\n');
+            expect(logged).not.toContain('Quitting leaves these services running');
+            runPromise.catch(() => { });
+        });
+    });
+    describe('detached flag', () => {
+        const makeDetachedCmd = () => {
+            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', detached: true },
+                    args: {}
+                }),
+                configurable: true
+            });
+            return cmd;
+        };
+        it('brings the stack up detached and exits without mounting the TUI', async () => {
+            const cmd = makeDetachedCmd();
+            await cmd.run();
+            expect(dockerService.runDockerComposeUpDetached).toHaveBeenCalledWith('/path/to/docker-compose-dev.yml', 'always');
+            expect(render).not.toHaveBeenCalled();
+            expect(cmd.error).not.toHaveBeenCalled();
+        });
+        // The -d path lost its probe when the state check moved inside the NONE
+        // branch. It matters more than it looks: a non-container process holding a
+        // published port does NOT fail `compose up -d` on Docker Desktop — the
+        // container starts and the port keeps answering the other process.
+        it('probes host ports before starting a fresh detached stack', async () => {
+            const cmd = makeDetachedCmd();
+            await cmd.run();
+            expect(portAvailability.findUnavailablePorts).toHaveBeenCalled();
+            expect(dockerService.runDockerComposeUpDetached).toHaveBeenCalled();
+        });
+        it('aborts before compose when a foreign process holds a port', async () => {
+            vi.mocked(portAvailability.findUnavailablePorts).mockResolvedValue([3001]);
+            const cmd = makeDetachedCmd();
+            const errorMock = vi.fn((_message) => {
+                throw new Error('aborted');
+            });
+            cmd.error = errorMock;
+            await expect(cmd.run()).rejects.toThrow('aborted');
+            expect(errorMock.mock.calls.at(-1)?.[0]).toContain('Port 3001 is already in use.');
+            expect(dockerService.runDockerComposeUpDetached).not.toHaveBeenCalled();
+        });
+        it('warns rather than silently assuming a fresh start when the query fails', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockRejectedValue(new Error('daemon not running'));
+            const cmd = makeDetachedCmd();
+            cmd.warn = vi.fn();
+            await cmd.run();
+            const warned = vi.mocked(cmd.warn).mock.calls.map(c => String(c[0])).join('\n');
+            expect(warned).toContain('daemon not running');
+            expect(portAvailability.findUnavailablePorts).toHaveBeenCalled();
+        });
+        it('does not probe when our own stack is already running', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue([
+                { name: 'api', state: 'running', health: 'healthy', ports: ['3001:3001'] }
+            ]);
+            vi.mocked(portAvailability.findUnavailablePorts).mockResolvedValue([3001]);
+            const cmd = makeDetachedCmd();
+            await cmd.run();
+            expect(portAvailability.findUnavailablePorts).not.toHaveBeenCalled();
+            expect(cmd.error).not.toHaveBeenCalled();
+        });
+        it('aborts with a port-collision hint when the detached up fails to bind', async () => {
+            vi.mocked(dockerService.runDockerComposeUpDetached).mockResolvedValue({
+                code: 1,
+                signal: null,
+                output: 'Error response from daemon: failed to set up container networking: driver failed ' +
+                    'programming external connectivity on endpoint out-temporal-1 (d4e5f6): ' +
+                    'Bind for 0.0.0.0:7233 failed: port is already allocated'
+            });
+            const cmd = makeDetachedCmd();
+            const errorMock = vi.fn((_message) => {
+                throw new Error('aborted');
+            });
+            cmd.error = errorMock;
+            await expect(cmd.run()).rejects.toThrow('aborted');
+            const message = errorMock.mock.calls.at(-1)?.[0];
+            expect(message).toContain('Port 7233 is already in use.');
+            expect(message).toContain('OUTPUT_TEMPORAL_HOST_PORT=');
+        });
+    });
+    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 () => {

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