@outputai/cli 0.10.1-dev.b7b2fbe.0 → 0.10.1-next.2caa4a1.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 };

package/dist/services/docker.js

@@ -1,9 +1,12 @@
 import { execFileSync, execSync, spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ux } from '@oclif/core';
 import semver from 'semver';
 import { config } from '#config.js';
+import { getErrorMessage } from '#utils/error_utils.js';
+import { formatComposeFailure } from '#utils/port_collision.js';
 const DEFAULT_COMPOSE_PATH = '../assets/docker/docker-compose-dev.yml';
 export const SERVICE_HEALTH = {
     HEALTHY: 'healthy',
@@ -83,6 +86,22 @@ export function validateDockerEnvironment() {
 export function getDefaultDockerComposePath() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), DEFAULT_COMPOSE_PATH);
 }
+// Resolve the compose file a `dev` command should act on — a caller-supplied
+// path (relative to cwd) or the bundled default — and verify it exists. Shared
+// by `dev` and `dev down` so the resolution rule and not-found error stay in
+// one place.
+export async function resolveDockerComposePath(customPath) {
+    const dockerComposePath = customPath ?
+        path.resolve(process.cwd(), customPath) :
+        getDefaultDockerComposePath();
+    try {
+        await fs.access(dockerComposePath);
+    }
+    catch {
+        throw new DockerComposeConfigNotFoundError(dockerComposePath);
+    }
+    return dockerComposePath;
+}
 export function parseServiceStatus(jsonOutput) {
     if (!jsonOutput.trim()) {
         return [];
@@ -118,6 +137,37 @@ export function isServiceHealthy(service) {
 export function isServiceFailed(service) {
     return service.state === SERVICE_STATE.EXITED || service.health === SERVICE_HEALTH.UNHEALTHY;
 }
+export const STACK_STATE = {
+    /** Nothing live for this project — a fresh start we own. */
+    NONE: 'none',
+    /** Every container found is running and healthy (or has no healthcheck). */
+    RUNNING: 'running',
+    /** Something is live but not everything is healthy — reconcile. */
+    PARTIAL: 'partial'
+};
+/**
+ * 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 function classifyStackState(services) {
+    // No container is live. `ps --all` also reports exited ones, so a stack left
+    // behind by a reboot, a `docker compose stop`, or a failed teardown lands
+    // here — that's an owned fresh start, not something to attach to.
+    if (!services.some(service => service.state === SERVICE_STATE.RUNNING)) {
+        return STACK_STATE.NONE;
+    }
+    if (services.every(isServiceHealthy)) {
+        return STACK_STATE.RUNNING;
+    }
+    return STACK_STATE.PARTIAL;
+}
 export async function waitForServicesHealthy(dockerComposePath, timeoutMs = 120000, pollIntervalMs = 2000) {
     const startTime = Date.now();
     while (Date.now() - startTime < timeoutMs) {
@@ -129,6 +179,18 @@ export async function waitForServicesHealthy(dockerComposePath, timeoutMs = 1200
     }
     throw new Error('Timeout waiting for services to become healthy');
 }
+// A rolling buffer that retains the last ~20k chars of a spawned process's
+// combined output, so a startup failure can surface recent Docker logs without
+// holding the whole stream. Shared by the two compose spawn sites.
+function createOutputBuffer() {
+    const buffer = { value: '' };
+    return {
+        append: (chunk) => {
+            buffer.value = `${buffer.value}${chunk.toString()}`.slice(-20000).trimStart();
+        },
+        read: () => buffer.value.trimEnd()
+    };
+}
 export async function startDockerCompose({ dockerComposePath, pullPolicy, onError, onExit }) {
     const args = [
         'compose',
@@ -140,29 +202,34 @@ export async function startDockerCompose({ dockerComposePath, pullPolicy, onErro
     if (pullPolicy) {
         args.push('--pull', pullPolicy);
     }
-    const output = {
-        value: ''
-    };
-    const appendOutput = (chunk) => {
-        output.value = `${output.value}${chunk.toString()}`.slice(-20000).trimStart();
-    };
+    const output = createOutputBuffer();
     const dockerProcess = spawn('docker', args, {
         cwd: process.cwd(),
         // The Ink dev UI owns the terminal. Drain compose output so Docker cannot
         // block on a full pipe, while keeping recent output for startup failures.
         stdio: ['ignore', 'pipe', 'pipe']
     });
-    dockerProcess.stdout?.on('data', appendOutput);
-    dockerProcess.stderr?.on('data', appendOutput);
+    dockerProcess.stdout?.on('data', output.append);
+    dockerProcess.stderr?.on('data', output.append);
     if (onError) {
-        dockerProcess.on('error', error => onError(error, output.value.trimEnd()));
+        dockerProcess.on('error', error => onError(error, output.read()));
     }
     if (onExit) {
-        dockerProcess.on('exit', (code, signal) => onExit(code, signal, output.value.trimEnd()));
+        // `close` rather than `exit` so stdio has drained — the buffered output is
+        // what formatComposeFailure greps for a bind failure.
+        dockerProcess.on('close', (code, signal) => onExit(code, signal, output.read()));
     }
     return dockerProcess;
 }
-export function startDockerComposeDetached(dockerComposePath, pullPolicy) {
+// Run `docker compose up -d` to completion, teeing Docker's progress to the
+// user's terminal while retaining recent output. The predecessor used
+// execFileSync with inherited stdio, which threw a raw compose error the caller
+// couldn't inspect; returning the exit code and output lets it surface a
+// port-collision hint instead. Async so image pulls don't block the event loop.
+//
+// Trade-off: piping means Docker sees a non-TTY and drops its redrawing
+// progress bars for plain scrolling lines.
+export function runDockerComposeUpDetached(dockerComposePath, pullPolicy) {
     const args = [
         'compose',
         '-f', dockerComposePath,
@@ -173,7 +240,34 @@ export function startDockerComposeDetached(dockerComposePath, pullPolicy) {
     if (pullPolicy) {
         args.push('--pull', pullPolicy);
     }
-    execFileSync('docker', args, { stdio: 'inherit', cwd: process.cwd() });
+    const output = createOutputBuffer();
+    return new Promise((resolve, reject) => {
+        // Pipe rather than inherit so we can both echo Docker's progress and keep
+        // recent output for a startup-failure hint.
+        const child = spawn('docker', args, {
+            cwd: process.cwd(),
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        child.stdout?.on('data', (chunk) => {
+            process.stdout.write(chunk);
+            output.append(chunk);
+        });
+        child.stderr?.on('data', (chunk) => {
+            process.stderr.write(chunk);
+            output.append(chunk);
+        });
+        // `error` fires when the spawn itself failed (docker missing, EACCES).
+        // Reject with the buffered output attached so the caller keeps the context
+        // rather than surfacing a bare `spawn docker ENOENT`.
+        child.on('error', error => {
+            reject(new Error(formatComposeFailure(getErrorMessage(error), output.read(), config.ports)));
+        });
+        // `close`, not `exit`: exit fires while stdio may still be draining, and on
+        // a fast-failing `up -d` — exactly the bind-collision case — the stderr
+        // chunk carrying the bind error can land after it. Resolving early makes
+        // the port-collision hint disappear intermittently.
+        child.on('close', (code, signal) => resolve({ code, signal, output: output.read() }));
+    });
 }
 export async function stopDockerCompose(dockerComposePath) {
     ux.stdout('⏹️  Stopping services...\n');

package/dist/services/docker.spec.js

@@ -1,11 +1,16 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { execFileSync, spawn } from 'node:child_process';
-import { parseServiceStatus, getServiceStatus, startDockerCompose, startDockerComposeDetached, stopDockerCompose, waitForServicesHealthy, isServiceHealthy, isServiceFailed } from './docker.js';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { parseServiceStatus, getServiceStatus, startDockerCompose, runDockerComposeUpDetached, stopDockerCompose, waitForServicesHealthy, isServiceHealthy, isServiceFailed, classifyStackState, STACK_STATE, resolveDockerComposePath, getDefaultDockerComposePath, DockerComposeConfigNotFoundError } from './docker.js';
 vi.mock('node:child_process', () => ({
     execSync: vi.fn(),
     execFileSync: vi.fn(),
     spawn: vi.fn()
 }));
+vi.mock('node:fs/promises', () => ({
+    default: { access: vi.fn() }
+}));
 const mockChildProcess = (process) => process;
 vi.mock('log-update', () => {
     const fn = vi.fn();
@@ -155,7 +160,7 @@ describe('docker service', () => {
                 onExit
             });
             expect(dockerProcess.on).toHaveBeenCalledWith('error', expect.any(Function));
-            expect(dockerProcess.on).toHaveBeenCalledWith('exit', expect.any(Function));
+            expect(dockerProcess.on).toHaveBeenCalledWith('close', expect.any(Function));
             streamHandlers.stdout?.(Buffer.from('starting services\n'));
             streamHandlers.stderr?.(Buffer.from('compose failed\n'));
             const error = new Error('Docker failed');
@@ -165,26 +170,99 @@ describe('docker service', () => {
             expect(onExit).toHaveBeenCalledWith(1, null, 'starting services\ncompose failed');
         });
     });
-    describe('startDockerComposeDetached', () => {
-        it('should pass --project-name and -d to docker compose up', () => {
-            vi.mocked(execFileSync).mockReturnValue('');
-            startDockerComposeDetached('/path/to/docker-compose.yml');
-            expect(execFileSync).toHaveBeenCalledWith('docker', [
+    describe('runDockerComposeUpDetached', () => {
+        const makeProcess = () => {
+            const handlers = {};
+            const proc = {
+                on: vi.fn((event, handler) => {
+                    if (event === 'error') {
+                        handlers.error = handler;
+                    }
+                    else {
+                        handlers.exit = handler;
+                    }
+                    return proc;
+                }),
+                stdout: {
+                    on: vi.fn((event, handler) => {
+                        handlers.stdout = handler;
+                        return proc.stdout;
+                    })
+                },
+                stderr: {
+                    on: vi.fn((event, handler) => {
+                        handlers.stderr = handler;
+                        return proc.stderr;
+                    })
+                }
+            };
+            return { proc, handlers };
+        };
+        it('passes --project-name and -d, tees output, and resolves with the exit code', async () => {
+            const { proc, handlers } = makeProcess();
+            vi.mocked(spawn).mockReturnValue(mockChildProcess(proc));
+            const stdoutSpy = vi.spyOn(process.stdout, 'write').mockReturnValue(true);
+            const promise = runDockerComposeUpDetached('/path/to/docker-compose.yml');
+            expect(spawn).toHaveBeenCalledWith('docker', [
                 'compose', '-f', '/path/to/docker-compose.yml',
                 '--project-directory', process.cwd(),
                 '--project-name', 'output-sdk',
                 'up', '-d'
-            ], expect.objectContaining({ stdio: 'inherit', cwd: process.cwd() }));
-        });
-        it('should append --pull when pullPolicy is provided', () => {
-            vi.mocked(execFileSync).mockReturnValue('');
-            startDockerComposeDetached('/path/to/docker-compose.yml', 'missing');
-            expect(execFileSync).toHaveBeenCalledWith('docker', [
+            ], expect.objectContaining({ cwd: process.cwd(), stdio: ['ignore', 'pipe', 'pipe'] }));
+            handlers.stdout?.(Buffer.from('pulling images\n'));
+            handlers.exit?.(0);
+            expect(await promise).toEqual({ code: 0, output: 'pulling images' });
+            expect(stdoutSpy).toHaveBeenCalledWith(Buffer.from('pulling images\n'));
+            stdoutSpy.mockRestore();
+        });
+        it('appends --pull when pullPolicy is provided', async () => {
+            const { proc, handlers } = makeProcess();
+            vi.mocked(spawn).mockReturnValue(mockChildProcess(proc));
+            vi.spyOn(process.stdout, 'write').mockReturnValue(true);
+            const promise = runDockerComposeUpDetached('/path/to/docker-compose.yml', 'missing');
+            handlers.exit?.(0);
+            await promise;
+            expect(spawn).toHaveBeenCalledWith('docker', [
                 'compose', '-f', '/path/to/docker-compose.yml',
                 '--project-directory', process.cwd(),
                 '--project-name', 'output-sdk',
                 'up', '-d', '--pull', 'missing'
-            ], expect.objectContaining({ stdio: 'inherit', cwd: process.cwd() }));
+            ], expect.objectContaining({ cwd: process.cwd() }));
+        });
+        it('resolves with a non-zero code and captured stderr so the caller can hint the collision', async () => {
+            const { proc, handlers } = makeProcess();
+            vi.mocked(spawn).mockReturnValue(mockChildProcess(proc));
+            vi.spyOn(process.stderr, 'write').mockReturnValue(true);
+            const promise = runDockerComposeUpDetached('/path/to/docker-compose.yml');
+            handlers.stderr?.(Buffer.from('Error: address already in use\n'));
+            handlers.exit?.(1);
+            expect(await promise).toEqual({ code: 1, output: 'Error: address already in use' });
+        });
+        it('rejects when the docker process fails to spawn', async () => {
+            const { proc, handlers } = makeProcess();
+            vi.mocked(spawn).mockReturnValue(mockChildProcess(proc));
+            const promise = runDockerComposeUpDetached('/path/to/docker-compose.yml');
+            handlers.error?.(new Error('spawn ENOENT'));
+            await expect(promise).rejects.toThrow('spawn ENOENT');
+        });
+    });
+    describe('resolveDockerComposePath', () => {
+        it('resolves a custom path against cwd and returns it when it exists', async () => {
+            vi.mocked(fs.access).mockResolvedValue(undefined);
+            const result = await resolveDockerComposePath('custom/compose.yml');
+            const expected = path.resolve(process.cwd(), 'custom/compose.yml');
+            expect(result).toBe(expected);
+            expect(fs.access).toHaveBeenCalledWith(expected);
+        });
+        it('throws DockerComposeConfigNotFoundError when the path does not exist', async () => {
+            vi.mocked(fs.access).mockRejectedValue(new Error('ENOENT'));
+            await expect(resolveDockerComposePath('missing.yml'))
+                .rejects.toBeInstanceOf(DockerComposeConfigNotFoundError);
+        });
+        it('falls back to the bundled default when no custom path is given', async () => {
+            vi.mocked(fs.access).mockResolvedValue(undefined);
+            const result = await resolveDockerComposePath();
+            expect(result).toBe(getDefaultDockerComposePath());
         });
     });
     describe('DOCKER_SERVICE_NAME wiring', () => {
@@ -259,6 +337,58 @@ describe('docker service', () => {
             expect(isServiceFailed({ name: 'temporal', state: 'running', health: 'starting', ports: [] })).toBe(false);
         });
     });
+    describe('classifyStackState', () => {
+        const svc = (state, health) => ({ name: 's', state, health, ports: [] });
+        it('returns NONE for an empty stack (fresh start)', () => {
+            expect(classifyStackState([])).toBe(STACK_STATE.NONE);
+        });
+        it('returns RUNNING when every service is up and healthy', () => {
+            expect(classifyStackState([
+                svc('running', 'healthy'),
+                svc('running', 'none')
+            ])).toBe(STACK_STATE.RUNNING);
+        });
+        it('returns PARTIAL when any service has failed (orphaned stack)', () => {
+            expect(classifyStackState([
+                svc('running', 'healthy'),
+                svc('exited', 'none')
+            ])).toBe(STACK_STATE.PARTIAL);
+        });
+        it('returns PARTIAL when services exist but some are still coming up', () => {
+            expect(classifyStackState([
+                svc('running', 'healthy'),
+                svc('created', 'none')
+            ])).toBe(STACK_STATE.PARTIAL);
+        });
+        it('treats an unhealthy service as PARTIAL, not RUNNING', () => {
+            expect(classifyStackState([
+                svc('running', 'healthy'),
+                svc('running', 'unhealthy')
+            ])).toBe(STACK_STATE.PARTIAL);
+        });
+        // `ps --all` reports exited containers, so a stack stopped by a reboot, a
+        // `docker compose stop`, or a failed teardown still has rows. Nothing is
+        // live, so this invocation would be the one starting it — that makes it an
+        // owned fresh start, not an attach.
+        it('returns NONE when every service is exited — an owned fresh start, not an attach', () => {
+            expect(classifyStackState([
+                svc('exited', 'none'),
+                svc('exited', 'none')
+            ])).toBe(STACK_STATE.NONE);
+        });
+        it('returns NONE when containers are created but none have started', () => {
+            expect(classifyStackState([
+                svc('created', 'none'),
+                svc('created', 'none')
+            ])).toBe(STACK_STATE.NONE);
+        });
+        it('still returns PARTIAL when at least one service is live', () => {
+            expect(classifyStackState([
+                svc('running', 'healthy'),
+                svc('exited', 'none')
+            ])).toBe(STACK_STATE.PARTIAL);
+        });
+    });
     describe('waitForServicesHealthy', () => {
         it('should resolve when all services are healthy', async () => {
             const mockOutput = `{"Service":"redis","State":"running","Health":"healthy","Publishers":[]}

package/dist/services/workflow_history/correlator.d.ts

@@ -19,6 +19,8 @@ export interface Span {
     output?: unknown;
 }
 export type HistoryEvent = Record<string, unknown>;
+export declare function eventTypeName(event: HistoryEvent): string;
+export declare function eventAttributes(event?: HistoryEvent): Record<string, unknown> | undefined;
 /**
  * @param events - flat Temporal history events, in chronological order
  * @param workflowStartTimeMs - epoch ms used as the timeline origin (0 offset)

package/dist/services/workflow_history/correlator.js

@@ -24,13 +24,13 @@ const CHILD_TERMINAL_TYPES = [
     'CHILD_WORKFLOW_EXECUTION_TIMED_OUT', 'CHILD_WORKFLOW_EXECUTION_CANCELED',
     'CHILD_WORKFLOW_EXECUTION_TERMINATED', 'START_CHILD_WORKFLOW_EXECUTION_FAILED'
 ];
-function eventTypeName(event) {
+export function eventTypeName(event) {
     return event.eventTypeName ?? '';
 }
 function eventId(event) {
     return String(event.eventId);
 }
-function eventAttributes(event) {
+export function eventAttributes(event) {
     const key = event && Object.keys(event).find(k => k.endsWith('EventAttributes'));
     return key ? event[key] : undefined;
 }

package/dist/services/workflow_history.d.ts

@@ -12,12 +12,40 @@ export interface FetchWorkflowHistoryOptions {
     workflowId: string;
     runId?: string;
     includePayloads?: boolean;
+    longPollTimeoutMs?: number;
 }
 export interface WorkflowHistoryResult {
     workflow: WorkflowMeta | null;
+    rawWorkflow: WorkflowMeta | null;
     runId: string | null;
     events: HistoryEvent[];
     spans: Span[];
     totalDurationMs: number;
+    continuedAsNewRunId: string | null;
+    cursor: WorkflowHistoryCursor;
+}
+/**
+ * Resume state for `fetchWorkflowHistoryUpdates`: the accumulated events (so spans/duration
+ * are always computed over the full history, not just the latest delta), `lastEventId` for
+ * de-duping a replayed page, and `pageToken` — the position that fetched the *current* end of
+ * history, which is itself always a valid resume point (see `fetchPages`) even though the
+ * server's own `nextPageToken` for that position is empty.
+ */
+export interface WorkflowHistoryCursor {
+    pageToken: string | undefined;
+    lastEventId: number;
+    meta: WorkflowMeta | null;
+    runId: string | undefined;
+    events: HistoryEvent[];
 }
 export declare function fetchWorkflowHistory(options: FetchWorkflowHistoryOptions): Promise<WorkflowHistoryResult>;
+/**
+ * Incremental counterpart to `fetchWorkflowHistory`, for a poller (`workflow monitor`) that
+ * calls repeatedly while a workflow is still running. Pass the previous call's `cursor`
+ * (from either function's result) to resume from where it left off instead of re-paging the
+ * whole history; omit it only to start a completely fresh walk.
+ */
+export declare function fetchWorkflowHistoryUpdates(options: FetchWorkflowHistoryOptions, cursor?: WorkflowHistoryCursor): Promise<{
+    result: WorkflowHistoryResult;
+    cursor: WorkflowHistoryCursor;
+}>;

package/dist/services/workflow_history.js

@@ -8,8 +8,20 @@
  * the `nextPageToken` (the endpoint requires runId once a pageToken is used).
  */
 import { getWorkflowIdHistory } from '#api/generated/api.js';
-import { correlate } from '#services/workflow_history/correlator.js';
+import { correlate, eventAttributes, eventTypeName } from '#services/workflow_history/correlator.js';
+import { normalizeWorkflowStatus } from '#utils/normalize_workflow_status.js';
+import { TERMINAL_STATUSES } from '#utils/format_workflow_result.js';
 const PAGE_SIZE = 50;
+// The status here comes from the request's own describe (fresh whenever `wait` is
+// set), so it can report the run closed before the closing event has been paged in.
+function isRunClosed(meta) {
+    const status = normalizeWorkflowStatus(meta?.status);
+    return status === 'continued_as_new' || (status !== undefined && TERMINAL_STATUSES.has(status));
+}
+function numericEventId(event) {
+    const id = Number(event.eventId);
+    return Number.isFinite(id) ? id : 0;
+}
 function toMs(value) {
     if (!value) {
         return null;
@@ -37,6 +49,13 @@ function workflowStartMs(meta, events) {
     }
     return earliestEventMs(events);
 }
+// The paginated history endpoint doesn't surface a resolved `newRunId` the way
+// the SSE stream endpoint does (see `stream_history.js`'s `doneChunk`), so pull
+// it directly off the WORKFLOW_EXECUTION_CONTINUED_AS_NEW event when present.
+function continuedAsNewRunId(events) {
+    const terminal = events.find(e => eventTypeName(e) === 'WORKFLOW_EXECUTION_CONTINUED_AS_NEW');
+    return eventAttributes(terminal)?.newExecutionRunId ?? null;
+}
 function totalDuration(meta, spans, startMs) {
     const closeMs = toMs(meta?.closeTime ?? undefined);
     if (closeMs !== null && startMs !== null && (closeMs - startMs) > 0) {
@@ -45,35 +64,99 @@ function totalDuration(meta, spans, startMs) {
     const maxEnd = spans.reduce((max, span) => Math.max(max, span.endOffsetMs), 0);
     return Math.max(maxEnd, 1);
 }
-async function fetchAllPages(workflowId, includePayloads, runId, pageToken, acc) {
-    const response = await getWorkflowIdHistory(workflowId, { runId, pageSize: PAGE_SIZE, pageToken, includePayloads });
+/**
+ * Pages through history starting from `acc` (its `pageToken`/`lastEventId`/`events` carry
+ * the resume position — pass a zeroed cursor for a fresh walk). When `longPollTimeoutMs` is
+ * set, every request asks the server to long-poll (`waitNewEvent`) rather than return
+ * immediately, so the final hop blocks — up to that many milliseconds (clamped to the server's
+ * ceiling) — until either a new event exists or the deadline elapses. `lastEventId` de-dupes:
+ * resuming from a previously-seen page token replays that page's events, which are filtered out
+ * here rather than appended twice.
+ */
+async function fetchPages(workflowId, includePayloads, acc, longPollTimeoutMs) {
+    const wait = longPollTimeoutMs !== undefined && longPollTimeoutMs > 0;
+    const { pageToken, runId } = acc;
+    const response = await getWorkflowIdHistory(workflowId, {
+        runId, pageSize: PAGE_SIZE, pageToken, includePayloads,
+        ...(wait ? { longPollTimeoutMs } : {})
+    });
     if (!response.data) {
         throw new Error('API returned invalid response (missing data)');
     }
     const data = response.data;
     // The generated `data.workflow` is an opaque `{ [key: string]: unknown }`, so
     // narrow it to WorkflowMeta via `unknown` (its real fields are validated by
-    // the server, mirroring Atlas's metadata shape).
-    const meta = acc.meta ?? data.workflow ?? null;
+    // the server, mirroring Atlas's metadata shape). Prefer the *fresh* value when the
+    // server sent one — it re-describes on every `wait` call specifically so status
+    // updates (e.g. running -> completed) are seen; falling back to `acc.meta` only
+    // covers the pages within a walk where the server didn't re-describe.
+    const meta = data.workflow ?? acc.meta;
     const resolvedRunId = runId ?? data.runId ?? acc.runId;
-    const events = [...acc.events, ...(data.events ?? [])];
+    const pageEvents = data.events ?? [];
+    const newEvents = pageEvents.filter(event => numericEventId(event) > acc.lastEventId);
+    const events = [...acc.events, ...newEvents];
+    // Events arrive in increasing eventId order, so the last new one is the max — no scan needed.
+    const lastEventId = newEvents.length > 0 ? numericEventId(newEvents[newEvents.length - 1]) : acc.lastEventId;
     const nextToken = data.nextPageToken ?? undefined;
-    const nextAcc = { meta, runId: resolvedRunId, events };
+    const nextAcc = { meta, runId: resolvedRunId, events, lastEventId, pageToken: nextToken ?? pageToken };
+    // While long-polling an open run, stop and hand back the first batch of new events
+    // instead of draining further pages — a poller needs each transition rendered as it
+    // arrives, and the buffered remainder will surface on subsequent ticks. Once the run
+    // is closed, though, no further ticks are coming: the poller acts on the closed
+    // status immediately, so stopping early would strand the trailing pages — including
+    // the terminal or CONTINUED_AS_NEW event — unfetched. Drain to the tip instead.
+    if (wait && newEvents.length > 0 && !isRunClosed(meta)) {
+        return nextAcc;
+    }
+    // The server echoes `pageToken` back unchanged (see `get_history.js`) when a waitNewEvent
+    // call's deadline elapses with nothing new — that's the tip, stop for this tick.
+    const timedOut = wait && nextToken === pageToken;
+    if (timedOut) {
+        return nextAcc;
+    }
     if (nextToken) {
-        return fetchAllPages(workflowId, includePayloads, resolvedRunId, nextToken, nextAcc);
+        return fetchPages(workflowId, includePayloads, nextAcc, longPollTimeoutMs);
     }
+    // Drained: the server has nothing more buffered (`nextToken` is empty), but unlike
+    // `nextToken`, `pageToken` — the position that fetched this now-empty page — is still a
+    // valid resume point: a future waitNewEvent call from here replays this page (de-duped by
+    // `lastEventId`) and then genuinely waits at the tip, instead of restarting from page 1.
     return nextAcc;
 }
-export async function fetchWorkflowHistory(options) {
-    const { workflowId, runId, includePayloads = false } = options;
-    const { meta, runId: resolvedRunId, events } = await fetchAllPages(workflowId, includePayloads, runId, undefined, { meta: null, runId, events: [] });
+function buildResult(pages) {
+    const { meta: rawMeta, runId: resolvedRunId, events } = pages;
+    // Normalize once here so every consumer (monitor, history, etc.) sees the
+    // same status vocabulary, matching status.ts/workflow_runs.ts/etc.
+    const status = normalizeWorkflowStatus(rawMeta?.status);
+    const meta = rawMeta ? { ...rawMeta, status } : rawMeta;
     const startMs = workflowStartMs(meta, events);
     const spans = correlate(events, startMs);
     return {
         workflow: meta,
+        rawWorkflow: rawMeta,
         runId: resolvedRunId ?? meta?.runId ?? null,
         events,
         spans,
-        totalDurationMs: totalDuration(meta, spans, startMs)
+        totalDurationMs: totalDuration(meta, spans, startMs),
+        continuedAsNewRunId: continuedAsNewRunId(events),
+        cursor: pages
     };
 }
+export async function fetchWorkflowHistory(options) {
+    const { workflowId, runId, includePayloads = false } = options;
+    const pages = await fetchPages(workflowId, includePayloads, { meta: null, runId, events: [], lastEventId: 0, pageToken: undefined });
+    return buildResult(pages);
+}
+/**
+ * Incremental counterpart to `fetchWorkflowHistory`, for a poller (`workflow monitor`) that
+ * calls repeatedly while a workflow is still running. Pass the previous call's `cursor`
+ * (from either function's result) to resume from where it left off instead of re-paging the
+ * whole history; omit it only to start a completely fresh walk.
+ */
+export async function fetchWorkflowHistoryUpdates(options, cursor) {
+    const { workflowId, includePayloads = false, longPollTimeoutMs } = options;
+    const seed = cursor ??
+        { meta: null, runId: options.runId, events: [], lastEventId: 0, pageToken: undefined };
+    const pages = await fetchPages(workflowId, includePayloads, seed, longPollTimeoutMs);
+    return { result: buildResult(pages), cursor: pages };
+}