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

package/dist/utils/env_loader.js

@@ -5,7 +5,6 @@
  */
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-import * as dotenv from 'dotenv';
 import debugFactory from 'debug';
 const debug = debugFactory('output-cli:env-loader');
 export function loadEnvironment() {
@@ -17,5 +16,10 @@ export function loadEnvironment() {
         return;
     }
     debug(`Loading env from: ${envPath}`);
-    dotenv.config({ path: envPath, quiet: true });
+    try {
+        process.loadEnvFile(envPath);
+    }
+    catch (err) {
+        debug(`Warning: Failed to load env file ${envPath}: ${err}`);
+    }
 }

package/dist/utils/env_loader.spec.js

@@ -1,43 +1,72 @@
-/**
- * Tests for the env loader utility
- */
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
-import * as dotenv from 'dotenv';
-vi.mock('node:fs');
-vi.mock('dotenv');
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { loadEnvironment } from './env_loader.js';
 describe('loadEnvironment', () => {
-    const originalEnv = { ...process.env };
-    const mockCwd = '/mock/project';
+    const mockCwd = mkdtempSync(join(tmpdir(), 'output-env-loader-'));
     beforeEach(() => {
-        vi.resetModules();
-        vi.clearAllMocks();
+        for (const name of readdirSync(mockCwd)) {
+            rmSync(join(mockCwd, name), { recursive: true, force: true });
+        }
         vi.spyOn(process, 'cwd').mockReturnValue(mockCwd);
-        vi.spyOn(console, 'log').mockImplementation(() => { });
-        vi.spyOn(console, 'warn').mockImplementation(() => { });
+        vi.stubEnv('OUTPUT_CLI_ENV', undefined);
+        vi.stubEnv('OUTPUT_API_URL', undefined);
+        vi.stubEnv('OUTPUT_API_TOKEN', undefined);
     });
     afterEach(() => {
-        process.env = { ...originalEnv };
         vi.restoreAllMocks();
+        vi.unstubAllEnvs();
     });
-    it('should load from OUTPUT_CLI_ENV when set and file exists', async () => {
-        process.env.OUTPUT_CLI_ENV = '.env.prod';
-        const expectedPath = resolve(mockCwd, '.env.prod');
-        vi.mocked(existsSync).mockReturnValue(true);
-        vi.mocked(dotenv.config).mockReturnValue({ parsed: { OUTPUT_API_URL: 'https://prod.api.com' } });
-        const { loadEnvironment } = await import('./env_loader.js');
+    afterAll(() => {
+        rmSync(mockCwd, { recursive: true, force: true });
+    });
+    it('loads variables from OUTPUT_CLI_ENV', () => {
+        writeFileSync(join(mockCwd, '.env'), [
+            'OUTPUT_API_URL=https://default.api.com',
+            'OUTPUT_API_TOKEN=default-token'
+        ].join('\n'));
+        writeFileSync(join(mockCwd, '.env.mock'), [
+            'OUTPUT_API_URL=https://mock.api.com',
+            'OUTPUT_API_TOKEN=mock-token'
+        ].join('\n'));
+        process.env.OUTPUT_CLI_ENV = '.env.mock';
+        loadEnvironment();
+        expect(process.env.OUTPUT_API_URL).toBe('https://mock.api.com');
+        expect(process.env.OUTPUT_API_TOKEN).toBe('mock-token');
+    });
+    it('loads variables from .env by default', () => {
+        writeFileSync(join(mockCwd, '.env'), [
+            'OUTPUT_API_URL=https://default.api.com',
+            'OUTPUT_API_TOKEN=default-token'
+        ].join('\n'));
+        writeFileSync(join(mockCwd, '.env.mock'), [
+            'OUTPUT_API_URL=https://mock.api.com',
+            'OUTPUT_API_TOKEN=mock-token'
+        ].join('\n'));
         loadEnvironment();
-        expect(dotenv.config).toHaveBeenCalledWith({ path: expectedPath, quiet: true });
-    });
-    it('should load .env by default and log', async () => {
-        delete process.env.OUTPUT_CLI_ENV;
-        const envPath = resolve(mockCwd, '.env');
-        vi.mocked(existsSync).mockImplementation(p => p === envPath);
-        vi.mocked(dotenv.config).mockReturnValue({ parsed: {} });
-        const { loadEnvironment } = await import('./env_loader.js');
+        expect(process.env.OUTPUT_API_URL).toBe('https://default.api.com');
+        expect(process.env.OUTPUT_API_TOKEN).toBe('default-token');
+    });
+    it('does nothing when the env file is missing', () => {
+        expect(() => loadEnvironment()).not.toThrow();
+        expect(process.env.OUTPUT_API_URL).toBeUndefined();
+        expect(process.env.OUTPUT_API_TOKEN).toBeUndefined();
+    });
+    it('does not throw when the env path is not a readable file', () => {
+        mkdirSync(join(mockCwd, 'not-a-file.env'));
+        process.env.OUTPUT_CLI_ENV = 'not-a-file.env';
+        expect(() => loadEnvironment()).not.toThrow();
+        expect(process.env.OUTPUT_API_URL).toBeUndefined();
+    });
+    it('does not overwrite already-set process.env values', () => {
+        vi.stubEnv('OUTPUT_API_URL', 'https://ambient.api.com');
+        writeFileSync(join(mockCwd, '.env'), [
+            'OUTPUT_API_URL=https://file.api.com',
+            'OUTPUT_API_TOKEN=file-token'
+        ].join('\n'));
         loadEnvironment();
-        expect(dotenv.config).toHaveBeenCalledTimes(1);
-        expect(dotenv.config).toHaveBeenCalledWith({ path: envPath, quiet: true });
+        expect(process.env.OUTPUT_API_URL).toBe('https://ambient.api.com');
+        expect(process.env.OUTPUT_API_TOKEN).toBe('file-token');
     });
 });

package/dist/utils/error_handler.d.ts

@@ -5,4 +5,14 @@ type ErrorOverrides = {
 export declare function handleApiError(error: unknown, errorFn: (...args: [message: string, options: {
     exit: number;
 }]) => never, overrides?: ErrorOverrides): never;
+/**
+ * `catch()` handling for a command that raises oclif errors of its own. Flag
+ * relationship failures and every `this.error( ..., { exit } )` already carry an
+ * exit code and formatted output, and `handleApiError` would flatten all of it
+ * to a bare exit 1 — so pass those straight through and only map what actually
+ * came back from the API.
+ */
+export declare function handleCommandError(error: Error, errorFn: (...args: [message: string, options: {
+    exit: number;
+}]) => never, overrides?: ErrorOverrides): never;
 export {};

package/dist/utils/error_handler.js

@@ -1,3 +1,4 @@
+import { CLIError } from '@oclif/core/errors';
 import { config } from '#config.js';
 function getDefaultMessages() {
     return {
@@ -79,3 +80,16 @@ export function handleApiError(error, errorFn, overrides = {}) {
     const detailedMessage = getDetailedErrorMessage(error);
     errorFn(detailedMessage, { exit: 1 });
 }
+/**
+ * `catch()` handling for a command that raises oclif errors of its own. Flag
+ * relationship failures and every `this.error( ..., { exit } )` already carry an
+ * exit code and formatted output, and `handleApiError` would flatten all of it
+ * to a bare exit 1 — so pass those straight through and only map what actually
+ * came back from the API.
+ */
+export function handleCommandError(error, errorFn, overrides = {}) {
+    if (error instanceof CLIError) {
+        throw error;
+    }
+    return handleApiError(error, errorFn, overrides);
+}

package/dist/utils/error_handler.spec.d.ts

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

package/dist/utils/error_handler.spec.js

@@ -0,0 +1,62 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { describe, it, expect, vi } from 'vitest';
+import { CLIError } from '@oclif/core/errors';
+import { handleApiError, handleCommandError } from './error_handler.js';
+const errorFn = () => vi.fn((message) => {
+    throw new Error(message);
+});
+const apiError = (status, data) => Object.assign(new Error('request failed'), { response: { status, data } });
+describe('handleApiError()', () => {
+    it('prefers a caller override over the server body for the same status', () => {
+        const fn = errorFn();
+        expect(() => handleApiError(apiError(404, { error: 'WorkflowNotFoundError', message: 'Workflow "wf-1" not found' }), fn, { 404: 'Workflow not found. Check the workflow ID.' })).toThrow('Workflow not found. Check the workflow ID.');
+    });
+    it('surfaces the server body when no override covers the status', () => {
+        const fn = errorFn();
+        // What `start --monitor` relies on now that it passes no 404 override: the
+        // API's own words, rather than advice about an id the user never typed.
+        expect(() => handleApiError(apiError(404, { error: 'WorkflowNotFoundError', message: 'Workflow "wf-1" not found' }), fn)).toThrow('WorkflowNotFoundError: Workflow "wf-1" not found.');
+    });
+    it('appends a root cause to the server message when the API reports one', () => {
+        const fn = errorFn();
+        expect(() => handleApiError(apiError(500, { error: 'StepFailure', message: 'Step failed', rootCause: { error: 'TypeError', message: 'x is not a function' } }), fn)).toThrow(/TypeError: x is not a function/);
+    });
+    it('falls back to the status default when the body carries no detail', () => {
+        const fn = errorFn();
+        expect(() => handleApiError(apiError(401), fn)).toThrow(/OUTPUT_API_AUTH_TOKEN/);
+    });
+    it.each([
+        ['a top-level code', Object.assign(new Error('connect'), { code: 'ECONNREFUSED' })],
+        ['a nested cause', Object.assign(new Error('fetch failed'), { cause: { code: 'ECONNREFUSED' } })]
+    ])('reports a refused connection from %s before looking at any status', (_label, error) => {
+        const fn = errorFn();
+        expect(() => handleApiError(error, fn)).toThrow(/Is the API server running\?/);
+    });
+    it('assembles a detailed message when there is no response at all', () => {
+        const fn = errorFn();
+        const error = Object.assign(new Error('fetch failed'), {
+            cause: Object.assign(new Error('getaddrinfo EAI_AGAIN api'), { code: 'EAI_AGAIN', hostname: 'api', port: 3001 })
+        });
+        expect(() => handleApiError(error, fn)).toThrow(/fetch failed \| Cause: getaddrinfo EAI_AGAIN api \| Code: EAI_AGAIN \| Host: api:3001/);
+    });
+    it('always exits 1, leaving a command\'s own exit codes to the command', () => {
+        const fn = errorFn();
+        expect(() => handleApiError(apiError(500), fn)).toThrow();
+        expect(fn).toHaveBeenCalledWith(expect.any(String), { exit: 1 });
+    });
+});
+describe('handleCommandError()', () => {
+    it('rethrows an oclif error untouched so its exit code and formatting survive', () => {
+        const fn = errorFn();
+        // `workflow start --monitor` raises exit 2 (bad flag combination) and exit 3
+        // (started but unmonitorable); flattening those to exit 1 would let a CI job
+        // retrying on a failed workflow re-submit one that is already running.
+        const cliError = new CLIError('Cannot combine --monitor with --json', { exit: 2 });
+        expect(() => handleCommandError(cliError, fn)).toThrow(cliError);
+        expect(fn).not.toHaveBeenCalled();
+    });
+    it('maps anything that came back from the API the same way handleApiError does', () => {
+        const fn = errorFn();
+        expect(() => handleCommandError(apiError(404), fn, { 404: 'Workflow not found. Check the workflow name.' })).toThrow('Workflow not found. Check the workflow name.');
+    });
+});

package/dist/utils/format_workflow_result.d.ts

@@ -1,6 +1,18 @@
-import type { WorkflowResultResponse, WorkflowResultResponseStatus } from '../api/generated/api.js';
+import type { WorkflowResultResponse } from '../api/generated/api.js';
 type WorkflowResult = Pick<WorkflowResultResponse, 'workflowId' | 'output' | 'status' | 'error'>;
-export declare const ERROR_STATUSES: ReadonlySet<WorkflowResultResponseStatus | undefined>;
-export declare const TERMINAL_STATUSES: ReadonlySet<string>;
+declare const ERROR_STATUS_VALUES: readonly ["failed", "cancelled", "terminated", "timed_out"];
+export type ErrorStatus = typeof ERROR_STATUS_VALUES[number];
+export type TerminalStatus = 'completed' | ErrorStatus;
+/**
+ * Maps a raw status to a canonical error status, or `undefined` if it is not one.
+ * Legacy spellings (`canceled`) are normalized so callers only ever see the
+ * current API vocabulary — until `normalizeWorkflowStatus` is removed.
+ */
+export declare function isErrorStatus(status: string | null | undefined): ErrorStatus | undefined;
+/**
+ * Maps a raw status to a canonical terminal status, or `undefined` if it is not
+ * one. Same normalization contract as `isErrorStatus`.
+ */
+export declare function isTerminalStatus(status: string | null | undefined): TerminalStatus | undefined;
 export declare function formatWorkflowResult(result: WorkflowResult): string;
 export {};

package/dist/utils/format_workflow_result.js

@@ -1,9 +1,39 @@
 import { normalizeWorkflowStatus } from './normalize_workflow_status.js';
-export const ERROR_STATUSES = new Set(['failed', 'canceled', 'terminated', 'timed_out']);
-// Every error status plus the one success status — derived so the two sets can't
-// silently drift apart as error statuses evolve. Shared by `workflow monitor` and
-// the dev TUI's `useRunDetail`/`useStepGraph` so both agree on what "done" means.
-export const TERMINAL_STATUSES = new Set(['completed', ...ERROR_STATUSES]);
+// `satisfies` rather than a plain annotation: it pins these to the generated API
+// union without widening them, so regenerating the API with a renamed status
+// breaks the build instead of silently making that status non-terminal.
+const ERROR_STATUS_VALUES = [
+    'failed', 'cancelled', 'terminated', 'timed_out'
+];
+const ERROR_STATUSES = new Set(ERROR_STATUS_VALUES);
+const TERMINAL_STATUSES = new Set(['completed', ...ERROR_STATUS_VALUES]);
+/**
+ * Maps a raw status to a canonical error status, or `undefined` if it is not one.
+ * Legacy spellings (`canceled`) are normalized so callers only ever see the
+ * current API vocabulary — until `normalizeWorkflowStatus` is removed.
+ */
+/* eslint-disable consistent-return -- returns ErrorStatus | undefined via early exit */
+export function isErrorStatus(status) {
+    if (typeof status !== 'string') {
+        return undefined;
+    }
+    const normalized = normalizeWorkflowStatus(status);
+    return ERROR_STATUSES.has(normalized) ? normalized : undefined;
+}
+/* eslint-enable consistent-return */
+/**
+ * Maps a raw status to a canonical terminal status, or `undefined` if it is not
+ * one. Same normalization contract as `isErrorStatus`.
+ */
+/* eslint-disable consistent-return -- returns TerminalStatus | undefined via early exit */
+export function isTerminalStatus(status) {
+    if (typeof status !== 'string') {
+        return undefined;
+    }
+    const normalized = normalizeWorkflowStatus(status);
+    return TERMINAL_STATUSES.has(normalized) ? normalized : undefined;
+}
+/* eslint-enable consistent-return */
 export function formatWorkflowResult(result) {
     const status = normalizeWorkflowStatus(result.status);
     const lines = [
@@ -17,7 +47,10 @@ export function formatWorkflowResult(result) {
     else {
         lines.push(`Status: ${status || 'unknown'}`);
         if (result.error) {
-            lines.push(`Error: ${result.error}`);
+            const error = typeof result.error === 'string' ?
+                result.error :
+                result.error.message ?? JSON.stringify(result.error, null, 2);
+            lines.push(`Error: ${error}`);
         }
     }
     return lines.join('\n');

package/dist/utils/format_workflow_result.spec.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { formatWorkflowResult } from './format_workflow_result.js';
+import { formatWorkflowResult, isErrorStatus } from './format_workflow_result.js';
 describe('formatWorkflowResult', () => {
     it('should display output for completed workflows', () => {
         const result = formatWorkflowResult({
@@ -13,7 +13,7 @@ describe('formatWorkflowResult', () => {
         expect(result).toContain('"values"');
         expect(result).not.toContain('Status:');
     });
-    it('should display error details for failed workflows', () => {
+    it('should display legacy string errors for failed workflows', () => {
         const result = formatWorkflowResult({
             workflowId: 'wf-456',
             status: 'failed',
@@ -25,6 +25,29 @@ describe('formatWorkflowResult', () => {
         expect(result).toContain('Error: Activity task failed');
         expect(result).not.toContain('Output:');
     });
+    it('should display the message from structured errors', () => {
+        const result = formatWorkflowResult({
+            workflowId: 'wf-v2',
+            status: 'failed',
+            output: null,
+            error: {
+                name: 'ValidationError',
+                message: 'Input is invalid',
+                code: 'INVALID_INPUT'
+            }
+        });
+        expect(result).toContain('Error: Input is invalid');
+        expect(result).not.toContain('[object Object]');
+    });
+    it('should serialize structured errors without a message', () => {
+        const result = formatWorkflowResult({
+            workflowId: 'wf-v2',
+            status: 'failed',
+            output: null,
+            error: { code: 'UNKNOWN' }
+        });
+        expect(result).toContain('"code": "UNKNOWN"');
+    });
     it('should display status for terminated workflows', () => {
         const result = formatWorkflowResult({
             workflowId: 'wf-term',
@@ -35,15 +58,25 @@ describe('formatWorkflowResult', () => {
         expect(result).toContain('Status: terminated');
         expect(result).toContain('Error: Workflow terminated by user');
     });
-    it('should display status for canceled workflows', () => {
+    it('should display status for cancelled workflows', () => {
         const result = formatWorkflowResult({
+            workflowId: 'wf-cancel',
+            status: 'cancelled',
+            output: null,
+            error: 'Workflow was cancelled'
+        });
+        expect(result).toContain('Status: cancelled');
+        expect(result).toContain('Error: Workflow was cancelled');
+    });
+    it('normalizes canceled responses without changing the current status type', () => {
+        const legacyResult = {
             workflowId: 'wf-cancel',
             status: 'canceled',
             output: null,
             error: 'Workflow was canceled'
-        });
-        expect(result).toContain('Status: canceled');
-        expect(result).toContain('Error: Workflow was canceled');
+        };
+        expect(formatWorkflowResult(legacyResult)).toContain('Status: cancelled');
+        expect(isErrorStatus('canceled')).toBe('cancelled');
     });
     it('should display status without error line for continued_as_new workflows', () => {
         const result = formatWorkflowResult({

package/dist/utils/monitor_flags.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The stream's defaults when the tuning flags are not given. Caller-side, not a
+ * property of the loop: `streamWorkflowUpdates` takes all three as required
+ * options and never falls back. Single-sourced because only `workflow monitor`
+ * can hand them to oclif — `workflow start --monitor` has to apply them itself
+ * (see `gatedMonitorStreamFlags`), and a literal repeated on that side would
+ * drift the moment one of these changes.
+ */
+export declare const MONITOR_DEFAULTS: {
+    readonly interval: 2500;
+    readonly color: true;
+    readonly includePayloads: false;
+};
+/** For a command that always monitors, where oclif can apply the defaults itself. */
+export declare function monitorStreamFlags(): {
+    '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>;
+};
+/**
+ * For a command where monitoring is opt-in (`workflow start --monitor`).
+ *
+ * These carry no oclif `default` on purpose: a defaulted flag counts as present
+ * (`validateFlags` runs a relationship check whenever the parsed value is not
+ * `undefined`, and `validateDependsOn` has no `setFromDefault` exemption the way
+ * `validateExclusive` does), which triggers its own `dependsOn` check and fails
+ * every invocation that omits `--monitor` — including a plain `workflow start`.
+ * The caller applies the defaults in `run()`, so the interval's default is
+ * spelled out in the help text rather than rendered by oclif.
+ */
+export declare function gatedMonitorStreamFlags(gatedBy: string): {
+    'include-payloads': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    interval: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    color: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+};

package/dist/utils/monitor_flags.js

@@ -0,0 +1,76 @@
+import { Flags } from '@oclif/core';
+/**
+ * The stream's defaults when the tuning flags are not given. Caller-side, not a
+ * property of the loop: `streamWorkflowUpdates` takes all three as required
+ * options and never falls back. Single-sourced because only `workflow monitor`
+ * can hand them to oclif — `workflow start --monitor` has to apply them itself
+ * (see `gatedMonitorStreamFlags`), and a literal repeated on that side would
+ * drift the moment one of these changes.
+ */
+export const MONITOR_DEFAULTS = {
+    interval: 2500,
+    color: true,
+    includePayloads: false
+};
+/**
+ * Descriptions and constraints for the three flags that tune
+ * `streamWorkflowUpdates`, single-sourced so `workflow monitor` and
+ * `workflow start --monitor` can't drift apart on help text — the interval
+ * caveat in particular is easy to lose in a copy-paste.
+ */
+const PAYLOADS_DESCRIPTION = 'Include decoded step input/output payloads';
+const COLOR_DESCRIPTION = 'Colorize status output (use --no-color to disable)';
+const INTERVAL_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.';
+/** For a command that always monitors, where oclif can apply the defaults itself. */
+export function monitorStreamFlags() {
+    return {
+        'include-payloads': Flags.boolean({
+            description: PAYLOADS_DESCRIPTION,
+            default: MONITOR_DEFAULTS.includePayloads
+        }),
+        interval: Flags.integer({
+            description: INTERVAL_DESCRIPTION,
+            default: MONITOR_DEFAULTS.interval,
+            min: 1
+        }),
+        color: Flags.boolean({
+            description: COLOR_DESCRIPTION,
+            default: MONITOR_DEFAULTS.color,
+            allowNo: true
+        })
+    };
+}
+/**
+ * For a command where monitoring is opt-in (`workflow start --monitor`).
+ *
+ * These carry no oclif `default` on purpose: a defaulted flag counts as present
+ * (`validateFlags` runs a relationship check whenever the parsed value is not
+ * `undefined`, and `validateDependsOn` has no `setFromDefault` exemption the way
+ * `validateExclusive` does), which triggers its own `dependsOn` check and fails
+ * every invocation that omits `--monitor` — including a plain `workflow start`.
+ * The caller applies the defaults in `run()`, so the interval's default is
+ * spelled out in the help text rather than rendered by oclif.
+ */
+export function gatedMonitorStreamFlags(gatedBy) {
+    const gate = { dependsOn: [gatedBy], helpGroup: 'MONITOR' };
+    const requires = ` (requires --${gatedBy})`;
+    return {
+        'include-payloads': Flags.boolean({
+            description: `${PAYLOADS_DESCRIPTION}${requires}`,
+            ...gate
+        }),
+        interval: Flags.integer({
+            description: `${INTERVAL_DESCRIPTION}${requires} [default: ${MONITOR_DEFAULTS.interval}]`,
+            min: 1,
+            ...gate
+        }),
+        color: Flags.boolean({
+            description: `${COLOR_DESCRIPTION}${requires}`,
+            allowNo: true,
+            ...gate
+        })
+    };
+}

package/dist/utils/normalize_workflow_status.d.ts

@@ -1,8 +1,9 @@
 /**
- * Temporary compatibility for API responses produced before CONTINUED_AS_NEW
- * was exposed as `continued_as_new`.
+ * Normalizes statuses from earlier API contracts.
+ *
+ * This can be removed after Aug, 2026
  *
  * @param status - Workflow status from the API
  * @returns Normalized workflow status
  */
-export declare const normalizeWorkflowStatus: <T extends string | null | undefined>(status: T) => T | "continued_as_new";
+export declare const normalizeWorkflowStatus: <T extends string | null | undefined>(status: T) => T | "continued_as_new" | "cancelled";

package/dist/utils/normalize_workflow_status.js

@@ -1,8 +1,17 @@
 /**
- * Temporary compatibility for API responses produced before CONTINUED_AS_NEW
- * was exposed as `continued_as_new`.
+ * Normalizes statuses from earlier API contracts.
+ *
+ * This can be removed after Aug, 2026
  *
  * @param status - Workflow status from the API
  * @returns Normalized workflow status
  */
-export const normalizeWorkflowStatus = (status) => status === 'continued' ? 'continued_as_new' : status;
+export const normalizeWorkflowStatus = (status) => {
+    if (status === 'continued') {
+        return 'continued_as_new';
+    }
+    if (status === 'canceled') {
+        return 'cancelled';
+    }
+    return status;
+};

package/dist/utils/normalize_workflow_status.spec.js

@@ -4,6 +4,9 @@ describe('normalizeWorkflowStatus', () => {
     it('temporarily maps continued to continued_as_new', () => {
         expect(normalizeWorkflowStatus('continued')).toBe('continued_as_new');
     });
+    it('maps the previous canceled spelling to cancelled', () => {
+        expect(normalizeWorkflowStatus('canceled')).toBe('cancelled');
+    });
     it('leaves other statuses and nullish values unchanged', () => {
         expect(normalizeWorkflowStatus('completed')).toBe('completed');
         expect(normalizeWorkflowStatus('continued_as_new')).toBe('continued_as_new');

package/dist/utils/port_collision.d.ts

@@ -3,14 +3,21 @@
  * an actionable hint that names the conflicting port and the env var to
  * override.
  *
- * Docker compose surfaces port collisions through two common error shapes:
- *   - "Bind for 0.0.0.0:3001 failed: port is already allocated"
- *   - "failed to bind host port for 0.0.0.0:7233:.../tcp: address already in use"
+ * Docker wraps the same failure differently across versions and platforms —
+ * Docker 29 on macOS nests it three deep:
  *
- * We match both, extract the host port, then map it back to the env var that
- * sets it. The map prefers a runtime lookup of resolved ports (so a user who
- * already set OUTPUT_API_HOST_PORT=3050 sees that var named when 3050
- * collides) and falls back to a default-port table for the unresolved case.
+ *   Error response from daemon: failed to set up container networking: driver
+ *   failed programming external connectivity on endpoint out-api-1 (a1b2…):
+ *   Bind for 0.0.0.0:3001 failed: port is already allocated
+ *
+ * Matching whole message shapes means a new wrapper silently drops the hint, so
+ * we anchor on the terminal phrase instead and take the host port nearest to it.
+ * That survives wrappers we haven't seen.
+ *
+ * The port is then mapped back to the env var that sets it. The map prefers a
+ * runtime lookup of resolved ports (so a user who already set
+ * OUTPUT_API_HOST_PORT=3050 sees that var named when 3050 collides) and falls
+ * back to a default-port table for the unresolved case.
  */
 /**
  * Find the first host port mentioned in a docker compose bind failure.
@@ -24,6 +31,14 @@ export declare function extractCollidedPort(stderr: string): number | null;
  * that overrides it; otherwise it suggests freeing the port.
  */
 export declare function formatPortCollisionHint(stderr: string, resolvedPorts: Record<string, number>): string | null;
+/**
+ * Compose a docker-failure message from a caller-supplied core sentence and the
+ * process's recent output: an actionable port-collision hint (when one is
+ * detected) is prepended, and the raw recent output is appended. Shared by the
+ * foreground exit handler and the detached/reconcile path so both surface the
+ * same failure shape.
+ */
+export declare function formatComposeFailure(reason: string, output: string, resolvedPorts: Record<string, number>): string;
 /**
  * Build a hint from a known list of colliding ports. For a single collision
  * the output matches `formatPortCollisionHint` exactly so callers stay