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

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/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

package/dist/utils/port_collision.js

@@ -3,20 +3,25 @@
  * 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.
  */
-const PORT_BIND_PATTERNS = [
-    /Bind for [^:\s]+:(\d+) failed: port is already allocated/,
-    /failed to bind host port for [^:\s]+:(\d+)[^]*?address already in use/,
-    /listen tcp [^:\s]+:(\d+):\s*bind: address already in use/
-];
+const COLLISION_PHRASES = ['port is already allocated', 'address already in use'];
+/** Trailing `:<port>` in a fragment — the host port a bind failure names. */
+const TRAILING_PORT = /:(\d+)(?!.*:\d)/s;
 const DEFAULT_PORT_TO_ENV_VAR = {
     3001: 'OUTPUT_API_HOST_PORT',
     8080: 'OUTPUT_TEMPORAL_UI_HOST_PORT',
@@ -35,8 +40,15 @@ export function extractCollidedPort(stderr) {
     if (!stderr) {
         return null;
     }
-    for (const pattern of PORT_BIND_PATTERNS) {
-        const match = stderr.match(pattern);
+    for (const phrase of COLLISION_PHRASES) {
+        const phraseIndex = stderr.indexOf(phrase);
+        if (phraseIndex === -1) {
+            continue;
+        }
+        // The host port is the last one named before the phrase — every shape puts
+        // it there ("Bind for 0.0.0.0:3001 failed: port is already allocated",
+        // "listen tcp 0.0.0.0:3001: bind: address already in use").
+        const match = stderr.slice(0, phraseIndex).match(TRAILING_PORT);
         if (match) {
             return parseInt(match[1], 10);
         }
@@ -87,6 +99,19 @@ export function formatPortCollisionHint(stderr, resolvedPorts) {
     }
     return formatSingleCollision(port, resolvedPorts);
 }
+/**
+ * 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 function formatComposeFailure(reason, output, resolvedPorts) {
+    const hint = formatPortCollisionHint(output, resolvedPorts);
+    const prefix = hint ? `${hint}\n\n` : '';
+    const detail = output ? `\n\nRecent Docker output:\n${output}` : '';
+    return `${prefix}${reason}${detail}`;
+}
 /**
  * Build a hint from a known list of colliding ports. For a single collision
  * the output matches `formatPortCollisionHint` exactly so callers stay

package/dist/utils/port_collision.spec.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { extractCollidedPort, formatPortCollisionHint, formatPortCollisionsHint } from './port_collision.js';
+import { extractCollidedPort, formatPortCollisionHint, formatPortCollisionsHint, formatComposeFailure } from './port_collision.js';
 const DEFAULT_PORTS = { api: 3001, temporalUi: 8080, temporal: 7233 };
 describe('extractCollidedPort', () => {
     it('matches the "Bind for ... port is already allocated" shape', () => {
@@ -22,6 +22,24 @@ describe('extractCollidedPort', () => {
     it('returns null when no bind failure is present', () => {
         expect(extractCollidedPort('some unrelated stderr line')).toBeNull();
     });
+    // Captured verbatim from Docker 29.4.0 on macOS. The bind failure is nested
+    // three wrappers deep; matching whole message shapes missed it.
+    it('extracts the port from Docker 29\'s nested container-networking wrapper', () => {
+        const stderr = 'Error response from daemon: failed to set up container networking: ' +
+            'driver failed programming external connectivity on endpoint out-api-1 ' +
+            '(e72baf85643fb5dc19000acf62c1ad0d11bffc653cabe1fc8861387ec1ebd629): ' +
+            'Bind for 0.0.0.0:3001 failed: port is already allocated';
+        expect(extractCollidedPort(stderr)).toBe(3001);
+    });
+    it('extracts the port from the "ports are not available" wrapper', () => {
+        const stderr = 'Error: ports are not available: exposing port TCP 0.0.0.0:3001 -> 0.0.0.0:0: ' +
+            'listen tcp 0.0.0.0:3001: bind: address already in use';
+        expect(extractCollidedPort(stderr)).toBe(3001);
+    });
+    it('ignores an IP-like prefix and takes the port nearest the failure phrase', () => {
+        const stderr = 'container 172.17.0.2:5432 started\nBind for 0.0.0.0:8080 failed: port is already allocated';
+        expect(extractCollidedPort(stderr)).toBe(8080);
+    });
     it('returns null for empty input', () => {
         expect(extractCollidedPort('')).toBeNull();
     });
@@ -80,3 +98,24 @@ describe('formatPortCollisionsHint', () => {
         expect(hint).toContain('• Port 5432 — stop the process holding it');
     });
 });
+describe('formatComposeFailure', () => {
+    const reason = 'Docker compose failed to start services (exit code 1).';
+    it('prepends the actionable hint when the output names a collision', () => {
+        const message = formatComposeFailure(reason, 'Bind for 0.0.0.0:3001 failed: port is already allocated', DEFAULT_PORTS);
+        expect(message.startsWith('Port 3001 is already in use.')).toBe(true);
+        expect(message).toContain('OUTPUT_API_HOST_PORT=<other port>');
+        expect(message).toContain(reason);
+        expect(message).toContain('Recent Docker output:');
+    });
+    it('omits the output section entirely when nothing was captured', () => {
+        const message = formatComposeFailure(reason, '', DEFAULT_PORTS);
+        expect(message).toBe(reason);
+        expect(message).not.toContain('Recent Docker output:');
+    });
+    it('returns reason plus raw output, with no hint, for an unrecognized failure', () => {
+        const message = formatComposeFailure(reason, 'no such image: outputai/api:dev', DEFAULT_PORTS);
+        expect(message.startsWith(reason)).toBe(true);
+        expect(message).toContain('Recent Docker output:\nno such image');
+        expect(message).not.toContain('is already in use');
+    });
+});

package/dist/views/dev/chrome/footer.d.ts

@@ -8,5 +8,7 @@ export interface FooterState {
     hints?: CommandHint[];
     itemCount?: number;
     itemLabel?: string;
+    /** Attached to a pre-existing stack — quitting leaves services running. */
+    attached?: boolean;
 }
 export declare const Footer: React.FC<FooterState>;

package/dist/views/dev/chrome/footer.js

@@ -5,16 +5,16 @@ import packageJson from '../../../../package.json' with { type: 'json' };
 const GLOBAL_HINT_ROWS = 1;
 const LOCAL_HINT_ROWS = 1;
 export const getHeight = () => GLOBAL_HINT_ROWS + LOCAL_HINT_ROWS;
-const GLOBAL_HINTS = [
+const globalHints = (attached) => [
     { key: 'tab', label: 'next tab' },
     { key: 'shift-tab', label: 'prev tab' },
     { key: '1-4', label: 'tabs' },
     { key: '/', label: 'search' },
     { key: '?', label: 'help' },
-    { key: 'ctrl+c', label: 'quit' }
+    { key: 'ctrl+c', label: attached ? 'detach (keeps running)' : 'quit' }
 ];
 const VERSION = packageJson.version;
 const HintRow = ({ hints }) => (_jsx(Box, { flexDirection: "row", children: hints.length === 0 ? (_jsx(Text, { children: " " })) : hints.map((hint, i) => (_jsxs(React.Fragment, { children: [i > 0 && _jsx(Text, { dimColor: true, children: '  ' }), _jsx(Text, { bold: true, children: hint.key }), _jsx(Text, { dimColor: true, children: ` ${hint.label}` })] }, hint.key))) }));
-export const Footer = ({ hints = [], itemCount, itemLabel }) => {
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", justifyContent: "space-between", children: [_jsx(HintRow, { hints: GLOBAL_HINTS }), typeof itemCount === 'number' && itemLabel && (_jsx(Box, { children: _jsxs(Text, { dimColor: true, children: [itemCount, " ", itemLabel] }) }))] }), _jsxs(Box, { flexDirection: "row", justifyContent: "space-between", children: [_jsx(HintRow, { hints: hints }), _jsxs(Text, { color: "blackBright", children: ["v", VERSION] })] })] }));
+export const Footer = ({ hints = [], itemCount, itemLabel, attached = false }) => {
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", justifyContent: "space-between", children: [_jsx(HintRow, { hints: globalHints(attached) }), typeof itemCount === 'number' && itemLabel && (_jsx(Box, { children: _jsxs(Text, { dimColor: true, children: [itemCount, " ", itemLabel] }) }))] }), _jsxs(Box, { flexDirection: "row", justifyContent: "space-between", children: [_jsx(HintRow, { hints: hints }), _jsxs(Text, { color: "blackBright", children: ["v", VERSION] })] })] }));
 };

package/dist/views/dev/dev_app.d.ts

@@ -3,4 +3,5 @@ export type Phase = 'waiting' | 'running' | 'failed';
 export declare const DevApp: React.FC<{
     dockerComposePath: string;
     onCleanup: () => Promise<void>;
+    attached?: boolean;
 }>;

package/dist/views/dev/dev_app.js

@@ -150,7 +150,7 @@ const overlayFor = (opts) => {
     }
     return null;
 };
-const Shell = ({ dockerComposePath, onCleanup }) => {
+const Shell = ({ dockerComposePath, onCleanup, attached }) => {
     const { exit } = useApp();
     const ui = useUiState();
     const [phase, setPhase] = useState('waiting');
@@ -160,7 +160,16 @@ const Shell = ({ dockerComposePath, onCleanup }) => {
         onServices: setServices,
         onAllHealthy: () => setPhase('running'),
         onFailure: () => setPhase('failed'),
-        onTimeout: () => exit(new Error('Timeout waiting for services to become healthy'))
+        // An attach/reconcile session monitors a stack it doesn't own, so a slow
+        // health check must not be fatal — drop into the dashboard and keep
+        // polling status. Only an owned fresh start treats the timeout as an error.
+        onTimeout: () => {
+            if (attached) {
+                setPhase('running');
+                return;
+            }
+            exit(new Error('Timeout waiting for services to become healthy'));
+        }
     });
     useStatusRefresh(dockerComposePath, phase !== 'waiting', setServices);
     useWorkflowRunsPolling(phase !== 'waiting', setRuns);
@@ -231,6 +240,6 @@ const Shell = ({ dockerComposePath, onCleanup }) => {
     if (overlay) {
         return (_jsx(Box, { flexDirection: "column", height: rows, paddingX: 1, children: overlay }));
     }
-    return (_jsxs(Box, { flexDirection: "column", height: rows, paddingX: 1, children: [_jsx(Header, { counters: counters }), _jsx(TabBar, { active: ui.tab, borderColor: RULE_PURPLE }), _jsx(SearchBar, { active: ui.search.open }), _jsxs(Box, { flexDirection: "column", flexGrow: 1, height: contentRows, overflow: "hidden", children: [ui.tab === 'workflows' && _jsx(WorkflowsPanel, { workflows: workflows, runs: runs }), ui.tab === 'runs' && _jsx(RunsPanel, { runs: runs, height: contentRows }), ui.tab === 'services' && (_jsx(ServicesPanel, { height: contentRows, phase: phase, services: services, dockerComposePath: dockerComposePath })), ui.tab === 'help' && _jsx(HelpPanel, {})] }), _jsx(Toasts, {}), _jsx(Footer, { hints: footer.hints, itemCount: footer.itemCount, itemLabel: footer.itemLabel })] }));
+    return (_jsxs(Box, { flexDirection: "column", height: rows, paddingX: 1, children: [_jsx(Header, { counters: counters }), _jsx(TabBar, { active: ui.tab, borderColor: RULE_PURPLE }), _jsx(SearchBar, { active: ui.search.open }), _jsxs(Box, { flexDirection: "column", flexGrow: 1, height: contentRows, overflow: "hidden", children: [ui.tab === 'workflows' && _jsx(WorkflowsPanel, { workflows: workflows, runs: runs }), ui.tab === 'runs' && _jsx(RunsPanel, { runs: runs, height: contentRows }), ui.tab === 'services' && (_jsx(ServicesPanel, { height: contentRows, phase: phase, services: services, dockerComposePath: dockerComposePath })), ui.tab === 'help' && _jsx(HelpPanel, {})] }), _jsx(Toasts, {}), _jsx(Footer, { hints: footer.hints, itemCount: footer.itemCount, itemLabel: footer.itemLabel, attached: attached })] }));
 };
-export const DevApp = ({ dockerComposePath, onCleanup }) => (_jsx(UiStateProvider, { children: _jsx(Shell, { dockerComposePath: dockerComposePath, onCleanup: onCleanup }) }));
+export const DevApp = ({ dockerComposePath, onCleanup, attached = false }) => (_jsx(UiStateProvider, { children: _jsx(Shell, { dockerComposePath: dockerComposePath, onCleanup: onCleanup, attached: attached }) }));

package/dist/views/dev/hooks/use_run_detail.js

@@ -3,13 +3,15 @@ import { readFile } from 'node:fs/promises';
 import { getWorkflowIdResult, getWorkflowIdRunsRidResult, getWorkflowIdTraceLog, getWorkflowIdRunsRidTraceLog } from '#api/generated/api.js';
 import { normalizeWorkflowStatus } from '#utils/normalize_workflow_status.js';
 import { TERMINAL_STATUSES } from '#utils/format_workflow_result.js';
+import { createBoundedCache } from '#views/dev/utils/bounded_cache.js';
 const EMPTY_DETAIL = {
     result: null,
     trace: null,
     steps: [],
     loading: false
 };
-const runDetailCache = new Map();
+const RUN_DETAIL_CACHE_MAX = 50;
+const runDetailCache = createBoundedCache(RUN_DETAIL_CACHE_MAX);
 const stepNameOf = (node) => {
     if (node.name) {
         return node.name;