@outputai/cli 0.10.1-next.09ed166.0 → 0.10.1-next.1070949.0

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/templates/agent_instructions/CLAUDE.md.template

@@ -17,10 +17,12 @@ claude plugin install outputai@outputai --scope project
 npm run output:dev           # Start dev environment (worker + Temporal)
 npm run output:worker:build  # Build TypeScript to dist/
 npm run output:worker:check  # Optional: bundle-check workflows for bad imports (node: built-ins)
-npm run output:worker:watch  # Build + restart on file changes
-npm run output:worker        # Install, build, and start worker
+npm run output:worker:watch  # Build + restart on src/ file changes
+npm run output:worker        # Build and start worker
 ```
 
+Hot-reload watches `src/` only. After changing dependencies (`package.json` / lockfile), run `npm install`, then `npx output dev down` and `npm run output:dev` again so the worker container reinstalls. A hot-reload alone is not enough; if the stack is still running, `npx output dev down` is required.
+
 ## Project Structure
 
 ```
@@ -44,7 +46,7 @@ config/
 ## Key Conventions
 
 - **Workflows are deterministic**: No I/O, no `Date.now()`, no `Math.random()` in `workflow.ts`. All side effects go in steps or evaluators.
-- **HTTP clients**: Always use `httpClient` from `@outputai/http` -- never raw `fetch` or `axios`. This enables automatic tracing and cost tracking.
+- **HTTP clients**: Use `outputFetch` or `createKyClient` from `@outputai/http` instead of raw `fetch` or `axios`. Requests are automatically traced; use `addRequestCost` when cost tracking is needed.
 - **LLM calls**: Use `generateText` from `@outputai/llm` with `.prompt` files. Never call LLM APIs directly.
 
 ---

package/dist/templates/project/README.md.template

@@ -79,7 +79,9 @@ This starts:
 - Temporal server and UI (http://localhost:8080)
 - PostgreSQL and Redis databases
 - Output.ai API server (http://localhost:3001)
-- Worker process for executing workflows
+- Worker process for executing workflows (auto-reloads on `src/` changes)
+
+Dependency changes (`package.json` / lockfile) are not picked up by hot-reload. Run `npm install`, then `npx output dev down` and `npm run output:dev` again so the worker container reinstalls. A hot-reload alone is not enough; if the stack is still running, `npx output dev down` is required.
 
 ### 4. Run a workflow
 

package/dist/templates/project/package.json.template

@@ -9,8 +9,8 @@
     "output:worker:build": "rm -rf dist/* && tsc -p ./ && output-copy-assets",
     "output:worker:start": "output-worker",
     "output:worker:check": "output-worker --check",
-    "output:worker": "npm run output:worker:install && npm run output:worker:build && npm run output:worker:start",
-    "output:worker:watch": "npx nodemon --watch src --watch package.json --ext ts,js,json,prompt,md --ignore 'dist/**' --ignore '**/*.spec.*' --ignore '**/*.test.*' --exec 'npm run output:worker'",
+    "output:worker": "npm run output:worker:build && npm run output:worker:start",
+    "output:worker:watch": "npx nodemon --watch src --ext ts,js,json,prompt,md --ignore 'dist/**' --ignore '**/*.spec.*' --ignore '**/*.test.*' --exec 'npm run output:worker'",
     "output:dev": "output dev"
   },
   "dependencies": {

package/dist/templates/project/src/clients/jina.ts.template

@@ -1,4 +1,4 @@
-import { httpClient } from '@outputai/http';
+import { createKyClient } from '@outputai/http';
 
 export interface JinaReaderResponse {
   code: number;
@@ -12,13 +12,13 @@ export interface JinaReaderResponse {
   };
 }
 
-const jinaClient = httpClient( {
-  prefixUrl: 'https://r.jina.ai',
+const client = createKyClient( {
+  prefix: 'https://r.jina.ai',
   timeout: 30000
 } );
 
 export async function fetchBlogContent( url: string ): Promise<JinaReaderResponse> {
-  const response = await jinaClient.post( '', {
+  const response = await client.post( '', {
     json: { url },
     headers: {
       'Accept': 'application/json',

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/format_workflow_result.d.ts

@@ -1,6 +1,7 @@
-import type { WorkflowResultResponse, WorkflowResultResponseStatus } from '../api/generated/api.js';
+import type { WorkflowResultResponse, WorkflowResultStatus } from '../api/generated/api.js';
 type WorkflowResult = Pick<WorkflowResultResponse, 'workflowId' | 'output' | 'status' | 'error'>;
-export declare const ERROR_STATUSES: ReadonlySet<WorkflowResultResponseStatus | undefined>;
+export declare const ERROR_STATUSES: ReadonlySet<WorkflowResultStatus>;
+export declare const isErrorWorkflowStatus: (status: string | null | undefined) => boolean;
 export declare const TERMINAL_STATUSES: ReadonlySet<string>;
 export declare function formatWorkflowResult(result: WorkflowResult): string;
 export {};

package/dist/utils/format_workflow_result.js

@@ -1,5 +1,6 @@
 import { normalizeWorkflowStatus } from './normalize_workflow_status.js';
-export const ERROR_STATUSES = new Set(['failed', 'canceled', 'terminated', 'timed_out']);
+export const ERROR_STATUSES = new Set(['failed', 'cancelled', 'terminated', 'timed_out']);
+export const isErrorWorkflowStatus = (status) => ERROR_STATUSES.has(normalizeWorkflowStatus(status));
 // 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.
@@ -17,7 +18,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, isErrorWorkflowStatus } 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(isErrorWorkflowStatus('canceled')).toBe(true);
     });
     it('should display status without error line for continued_as_new workflows', () => {
         const result = formatWorkflowResult({

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