@supaku/agentfactory-cli 0.3.0 → 0.4.0

package/dist/src/lib/queue-admin-runner.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Queue Admin Runner -- Programmatic API for the queue admin CLI.
+ *
+ * Extracts ALL command handlers from the queue-admin bin script so they can be
+ * invoked programmatically (e.g. from a Next.js route handler or test) without
+ * process.exit / dotenv / argv coupling.
+ */
+export type QueueAdminCommand = 'list' | 'sessions' | 'workers' | 'clear-claims' | 'clear-queue' | 'clear-all' | 'reset' | 'remove';
+export interface QueueAdminRunnerConfig {
+    /** Command to execute */
+    command: QueueAdminCommand;
+    /** Session ID for 'remove' command (partial match) */
+    sessionId?: string;
+}
+export declare const C: {
+    readonly reset: "\u001B[0m";
+    readonly red: "\u001B[31m";
+    readonly green: "\u001B[32m";
+    readonly yellow: "\u001B[33m";
+    readonly cyan: "\u001B[36m";
+    readonly gray: "\u001B[90m";
+};
+/**
+ * Run a queue admin command programmatically.
+ *
+ * Throws if REDIS_URL is not set or if the 'remove' command is called without
+ * a sessionId.
+ */
+export declare function runQueueAdmin(config: QueueAdminRunnerConfig): Promise<void>;
+//# sourceMappingURL=queue-admin-runner.d.ts.map

package/dist/src/lib/queue-admin-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-admin-runner.d.ts","sourceRoot":"","sources":["../../../src/lib/queue-admin-runner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkBH,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,UAAU,GACV,SAAS,GACT,cAAc,GACd,aAAa,GACb,WAAW,GACX,OAAO,GACP,QAAQ,CAAA;AAEZ,MAAM,WAAW,sBAAsB;IACrC,yBAAyB;IACzB,OAAO,EAAE,iBAAiB,CAAA;IAC1B,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAgBD,eAAO,MAAM,CAAC;;;;;;;CAOJ,CAAA;AAgZV;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BjF"}

package/dist/src/lib/queue-admin-runner.js

@@ -0,0 +1,378 @@
+/**
+ * Queue Admin Runner -- Programmatic API for the queue admin CLI.
+ *
+ * Extracts ALL command handlers from the queue-admin bin script so they can be
+ * invoked programmatically (e.g. from a Next.js route handler or test) without
+ * process.exit / dotenv / argv coupling.
+ */
+import { getRedisClient, redisKeys, redisDel, redisGet, redisSet, redisZRangeByScore, redisZRem, redisHGetAll, disconnectRedis, } from '@supaku/agentfactory-server';
+// ---------------------------------------------------------------------------
+// Redis key constants
+// ---------------------------------------------------------------------------
+const WORK_QUEUE_KEY = 'work:queue';
+const WORK_ITEMS_KEY = 'work:items';
+const WORK_CLAIM_PREFIX = 'work:claim:';
+const SESSION_KEY_PREFIX = 'agent:session:';
+const WORKER_PREFIX = 'work:worker:';
+// ---------------------------------------------------------------------------
+// ANSI colors
+// ---------------------------------------------------------------------------
+export const C = {
+    reset: '\x1b[0m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    cyan: '\x1b[36m',
+    gray: '\x1b[90m',
+};
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function ensureRedis() {
+    if (!process.env.REDIS_URL) {
+        throw new Error('REDIS_URL environment variable is not set');
+    }
+    // Initialize the Redis client
+    getRedisClient();
+}
+// ---------------------------------------------------------------------------
+// Command handlers
+// ---------------------------------------------------------------------------
+async function listQueue() {
+    ensureRedis();
+    // Get items from sorted set (current queue format)
+    const queuedSessionIds = await redisZRangeByScore(WORK_QUEUE_KEY, '-inf', '+inf');
+    const workItems = await redisHGetAll(WORK_ITEMS_KEY);
+    const workItemCount = Object.keys(workItems).length;
+    console.log(`\n${C.cyan}Work Queue${C.reset} (${Math.max(queuedSessionIds.length, workItemCount)} items):`);
+    console.log('='.repeat(60));
+    if (workItemCount === 0 && queuedSessionIds.length === 0) {
+        console.log('(empty)');
+    }
+    else {
+        for (const [sessionId, itemJson] of Object.entries(workItems)) {
+            try {
+                const work = JSON.parse(itemJson);
+                console.log(`- ${work.issueIdentifier ?? sessionId.slice(0, 8)} (session: ${sessionId.slice(0, 8)}...)`);
+                console.log(`  Priority: ${work.priority ?? 'none'}, WorkType: ${work.workType ?? 'development'}`);
+                if (work.queuedAt) {
+                    console.log(`  Queued: ${new Date(work.queuedAt).toISOString()}`);
+                }
+                if (work.claudeSessionId) {
+                    console.log(`  ${C.yellow}Has claudeSessionId: ${work.claudeSessionId.substring(0, 12)}${C.reset}`);
+                }
+                if (work.prompt) {
+                    console.log(`  Prompt: "${work.prompt.slice(0, 50)}..."`);
+                }
+            }
+            catch {
+                console.log(`- [invalid JSON]: ${sessionId}`);
+            }
+        }
+    }
+    await disconnectRedis();
+}
+async function listSessions() {
+    ensureRedis();
+    const keys = await redisKeys(`${SESSION_KEY_PREFIX}*`);
+    console.log(`\n${C.cyan}Sessions${C.reset} (${keys.length} total):`);
+    console.log('='.repeat(60));
+    if (keys.length === 0) {
+        console.log('(none)');
+    }
+    else {
+        for (const key of keys) {
+            const session = await redisGet(key);
+            if (session) {
+                const statusColors = {
+                    pending: C.yellow,
+                    claimed: C.cyan,
+                    running: C.cyan,
+                    completed: C.green,
+                    failed: C.red,
+                    stopped: C.yellow,
+                };
+                const statusColor = statusColors[session.status] || '';
+                console.log(`- ${session.issueIdentifier || session.issueId.slice(0, 8)} [${statusColor}${session.status}${C.reset}]`);
+                console.log(`  Session: ${session.linearSessionId.slice(0, 12)}...`);
+                if (session.workType) {
+                    console.log(`  WorkType: ${session.workType}`);
+                }
+                console.log(`  Updated: ${new Date(session.updatedAt * 1000).toISOString()}`);
+                if (session.workerId) {
+                    console.log(`  Worker: ${session.workerId}`);
+                }
+            }
+        }
+    }
+    await disconnectRedis();
+}
+async function listWorkersFn() {
+    ensureRedis();
+    const keys = await redisKeys(`${WORKER_PREFIX}*`);
+    console.log(`\n${C.cyan}Workers${C.reset} (${keys.length} total):`);
+    console.log('='.repeat(60));
+    if (keys.length === 0) {
+        console.log('(none)');
+    }
+    else {
+        for (const key of keys) {
+            const worker = await redisGet(key);
+            if (worker) {
+                const statusColor = worker.status === 'active' ? C.green : C.yellow;
+                console.log(`- ${worker.id.slice(0, 12)} [${statusColor}${worker.status}${C.reset}]`);
+                if (worker.hostname) {
+                    console.log(`  Hostname: ${worker.hostname}`);
+                }
+                console.log(`  Capacity: ${worker.activeCount ?? 0}/${worker.capacity ?? '?'}`);
+                if (worker.lastHeartbeat) {
+                    const ago = Math.round((Date.now() - worker.lastHeartbeat) / 1000);
+                    console.log(`  Last heartbeat: ${ago}s ago`);
+                }
+            }
+        }
+    }
+    await disconnectRedis();
+}
+async function clearClaims() {
+    ensureRedis();
+    console.log('Clearing work claims...');
+    const claimKeys = await redisKeys(`${WORK_CLAIM_PREFIX}*`);
+    console.log(`Found ${claimKeys.length} claim(s)`);
+    if (claimKeys.length === 0) {
+        console.log('No claims to clear');
+        await disconnectRedis();
+        return;
+    }
+    let deleted = 0;
+    for (const key of claimKeys) {
+        const result = await redisDel(key);
+        if (result > 0) {
+            console.log(`  Deleted: ${key}`);
+            deleted++;
+        }
+    }
+    console.log(`\nCleared ${deleted} claim(s)`);
+    await disconnectRedis();
+}
+async function clearQueue() {
+    ensureRedis();
+    console.log('Clearing work queue...');
+    const queuedSessionIds = await redisZRangeByScore(WORK_QUEUE_KEY, '-inf', '+inf');
+    console.log(`Found ${queuedSessionIds.length} item(s) in queue sorted set`);
+    const workItems = await redisHGetAll(WORK_ITEMS_KEY);
+    const workItemCount = Object.keys(workItems).length;
+    console.log(`Found ${workItemCount} item(s) in work items hash`);
+    // Show what we're clearing
+    for (const [sessionId, itemJson] of Object.entries(workItems)) {
+        try {
+            const work = JSON.parse(itemJson);
+            console.log(`  - ${work.issueIdentifier ?? sessionId.slice(0, 8)} (workType: ${work.workType || 'development'})`);
+            if (work.claudeSessionId) {
+                console.log(`    ${C.yellow}Has claudeSessionId: ${work.claudeSessionId.substring(0, 12)}${C.reset}`);
+            }
+        }
+        catch {
+            console.log(`  - [invalid JSON]: ${sessionId}`);
+        }
+    }
+    let cleared = 0;
+    if (queuedSessionIds.length > 0) {
+        await redisDel(WORK_QUEUE_KEY);
+        cleared++;
+    }
+    if (workItemCount > 0) {
+        await redisDel(WORK_ITEMS_KEY);
+        cleared++;
+    }
+    const totalItems = Math.max(queuedSessionIds.length, workItemCount);
+    if (cleared > 0) {
+        console.log(`\nCleared ${totalItems} item(s) from work queue`);
+    }
+    else {
+        console.log('\nQueue was already empty');
+    }
+    await disconnectRedis();
+}
+async function clearAll() {
+    ensureRedis();
+    console.log('Clearing ALL state...\n');
+    // Clear work queue
+    const queuedSessionIds = await redisZRangeByScore(WORK_QUEUE_KEY, '-inf', '+inf');
+    const workItems = await redisHGetAll(WORK_ITEMS_KEY);
+    if (queuedSessionIds.length > 0)
+        await redisDel(WORK_QUEUE_KEY);
+    if (Object.keys(workItems).length > 0)
+        await redisDel(WORK_ITEMS_KEY);
+    console.log(`Cleared ${Math.max(queuedSessionIds.length, Object.keys(workItems).length)} queue items`);
+    // Clear all sessions
+    const sessionKeys = await redisKeys(`${SESSION_KEY_PREFIX}*`);
+    for (const key of sessionKeys) {
+        await redisDel(key);
+    }
+    console.log(`Cleared ${sessionKeys.length} sessions`);
+    // Clear all claims
+    const claimKeys = await redisKeys(`${WORK_CLAIM_PREFIX}*`);
+    for (const key of claimKeys) {
+        await redisDel(key);
+    }
+    console.log(`Cleared ${claimKeys.length} claims`);
+    // Clear all workers
+    const workerKeys = await redisKeys(`${WORKER_PREFIX}*`);
+    for (const key of workerKeys) {
+        await redisDel(key);
+    }
+    console.log(`Cleared ${workerKeys.length} worker registrations`);
+    console.log('\nAll cleared!');
+    await disconnectRedis();
+}
+async function resetWorkState() {
+    ensureRedis();
+    console.log('Resetting work state...');
+    console.log('-'.repeat(60));
+    let totalCleared = 0;
+    // 1. Clear work claims
+    console.log('\nClearing work claims...');
+    const claimKeys = await redisKeys(`${WORK_CLAIM_PREFIX}*`);
+    console.log(`  Found ${claimKeys.length} claim(s)`);
+    for (const key of claimKeys) {
+        const result = await redisDel(key);
+        if (result > 0) {
+            console.log(`  Deleted: ${key}`);
+            totalCleared++;
+        }
+    }
+    // 2. Clear work queue
+    console.log('\nClearing work queue...');
+    const queuedSessionIds = await redisZRangeByScore(WORK_QUEUE_KEY, '-inf', '+inf');
+    console.log(`  Found ${queuedSessionIds.length} queued item(s) in sorted set`);
+    const workItems = await redisHGetAll(WORK_ITEMS_KEY);
+    const workItemCount = Object.keys(workItems).length;
+    console.log(`  Found ${workItemCount} item(s) in work items hash`);
+    for (const [sessionId, itemJson] of Object.entries(workItems)) {
+        try {
+            const work = JSON.parse(itemJson);
+            console.log(`  - ${work.issueIdentifier ?? sessionId.slice(0, 8)} (workType: ${work.workType || 'development'})`);
+        }
+        catch {
+            console.log(`  - [invalid item: ${sessionId}]`);
+        }
+    }
+    if (queuedSessionIds.length > 0 || workItemCount > 0) {
+        await redisDel(WORK_QUEUE_KEY);
+        await redisDel(WORK_ITEMS_KEY);
+        totalCleared += Math.max(queuedSessionIds.length, workItemCount);
+        console.log(`  Cleared queue and items hash`);
+    }
+    // 3. Reset stuck sessions
+    console.log('\nResetting stuck sessions...');
+    const sessionKeys = await redisKeys(`${SESSION_KEY_PREFIX}*`);
+    console.log(`  Found ${sessionKeys.length} session(s)`);
+    let sessionsReset = 0;
+    for (const key of sessionKeys) {
+        const session = await redisGet(key);
+        if (!session)
+            continue;
+        if (session.status === 'running' || session.status === 'claimed') {
+            console.log(`  Resetting: ${session.issueIdentifier || session.linearSessionId}`);
+            console.log(`    Status: ${session.status}, WorkerId: ${session.workerId || 'none'}`);
+            const updated = {
+                ...session,
+                status: 'pending',
+                workerId: undefined,
+                claimedAt: undefined,
+                claudeSessionId: undefined,
+                updatedAt: Math.floor(Date.now() / 1000),
+            };
+            await redisSet(key, updated, 24 * 60 * 60);
+            sessionsReset++;
+            console.log(`    Reset to pending`);
+        }
+    }
+    console.log('\n' + '-'.repeat(60));
+    console.log(`\nReset complete:`);
+    console.log(`   - Claims cleared: ${claimKeys.length}`);
+    console.log(`   - Queue items cleared: ${Math.max(queuedSessionIds.length, workItemCount)}`);
+    console.log(`   - Sessions reset: ${sessionsReset}`);
+    await disconnectRedis();
+}
+async function removeSession(sessionId) {
+    ensureRedis();
+    let found = false;
+    // Find session by partial ID match
+    const keys = await redisKeys(`${SESSION_KEY_PREFIX}*`);
+    for (const key of keys) {
+        if (key.includes(sessionId)) {
+            await redisDel(key);
+            console.log(`Removed session: ${key.replace(SESSION_KEY_PREFIX, '')}`);
+            found = true;
+        }
+    }
+    // Also remove from queue if present
+    const workItems = await redisHGetAll(WORK_ITEMS_KEY);
+    for (const [sid, itemJson] of Object.entries(workItems)) {
+        if (sid.includes(sessionId)) {
+            // Remove from hash via direct Redis command
+            const redis = getRedisClient();
+            await redis.hdel(WORK_ITEMS_KEY, sid);
+            // Remove from sorted set
+            await redisZRem(WORK_QUEUE_KEY, sid);
+            const work = JSON.parse(itemJson);
+            console.log(`Removed from queue: ${work.issueIdentifier ?? sid.slice(0, 8)}`);
+            found = true;
+        }
+    }
+    // Remove claim if present
+    const claimKeys = await redisKeys(`${WORK_CLAIM_PREFIX}*`);
+    for (const key of claimKeys) {
+        if (key.includes(sessionId)) {
+            await redisDel(key);
+            console.log(`Removed claim: ${key}`);
+            found = true;
+        }
+    }
+    if (!found) {
+        console.log(`No session found matching: ${sessionId}`);
+    }
+    await disconnectRedis();
+}
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+/**
+ * Run a queue admin command programmatically.
+ *
+ * Throws if REDIS_URL is not set or if the 'remove' command is called without
+ * a sessionId.
+ */
+export async function runQueueAdmin(config) {
+    switch (config.command) {
+        case 'list':
+            await listQueue();
+            break;
+        case 'sessions':
+            await listSessions();
+            break;
+        case 'workers':
+            await listWorkersFn();
+            break;
+        case 'clear-claims':
+            await clearClaims();
+            break;
+        case 'clear-queue':
+            await clearQueue();
+            break;
+        case 'clear-all':
+            await clearAll();
+            break;
+        case 'reset':
+            await resetWorkState();
+            break;
+        case 'remove':
+            if (!config.sessionId) {
+                throw new Error('remove command requires a sessionId');
+            }
+            await removeSession(config.sessionId);
+            break;
+    }
+}

package/dist/src/lib/worker-fleet-runner.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Worker Fleet Runner — Programmatic API for the worker fleet manager CLI.
+ *
+ * Spawns and manages multiple worker processes for parallel agent execution.
+ * Each worker runs as a separate OS process with its own resources.
+ */
+export interface FleetRunnerConfig {
+    /** Number of worker processes (default: CPU cores / 2) */
+    workers?: number;
+    /** Agents per worker (default: 3) */
+    capacity?: number;
+    /** Show configuration without starting workers (default: false) */
+    dryRun?: boolean;
+    /** Coordinator API URL (required) */
+    apiUrl: string;
+    /** API key for authentication (required) */
+    apiKey: string;
+    /** Path to the worker script/binary (default: auto-detect from this package) */
+    workerScript?: string;
+}
+/**
+ * Run a fleet of worker processes.
+ *
+ * The caller can cancel via the optional {@link AbortSignal}. The function
+ * returns once all workers have been stopped.
+ */
+export declare function runWorkerFleet(config: FleetRunnerConfig, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=worker-fleet-runner.d.ts.map

package/dist/src/lib/worker-fleet-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-fleet-runner.d.ts","sourceRoot":"","sources":["../../../src/lib/worker-fleet-runner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,mEAAmE;IACnE,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAA;IACd,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAA;IACd,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAqSD;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,iBAAiB,EACzB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAmBf"}

package/dist/src/lib/worker-fleet-runner.js

@@ -0,0 +1,224 @@
+/**
+ * Worker Fleet Runner — Programmatic API for the worker fleet manager CLI.
+ *
+ * Spawns and manages multiple worker processes for parallel agent execution.
+ * Each worker runs as a separate OS process with its own resources.
+ */
+import { spawn } from 'child_process';
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+// ---------------------------------------------------------------------------
+// ANSI colors
+// ---------------------------------------------------------------------------
+const colors = {
+    reset: '\x1b[0m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    magenta: '\x1b[35m',
+    cyan: '\x1b[36m',
+    gray: '\x1b[90m',
+};
+const workerColors = [
+    colors.cyan,
+    colors.magenta,
+    colors.yellow,
+    colors.green,
+    colors.blue,
+];
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function timestamp() {
+    return new Date().toLocaleTimeString('en-US', { hour12: false });
+}
+function fleetLog(workerId, color, level, message) {
+    const prefix = workerId !== null
+        ? `[W${workerId.toString().padStart(2, '0')}]`
+        : '[FLEET]';
+    const levelColor = level === 'ERR' ? colors.red : level === 'WRN' ? colors.yellow : colors.gray;
+    console.log(`${colors.gray}${timestamp()}${colors.reset} ${color}${prefix}${colors.reset} ${levelColor}${level}${colors.reset} ${message}`);
+}
+function getDefaultWorkerScript() {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
+    // Runner lives in lib/, worker.js is one level up
+    return path.resolve(__dirname, '..', 'worker.js');
+}
+// ---------------------------------------------------------------------------
+// WorkerFleet class (internal)
+// ---------------------------------------------------------------------------
+class WorkerFleet {
+    workers = new Map();
+    fleetConfig;
+    shuttingDown = false;
+    workerScript;
+    resolveRunning = null;
+    constructor(fleetConfig, workerScript) {
+        this.fleetConfig = fleetConfig;
+        this.workerScript = workerScript;
+    }
+    async start(signal) {
+        const { workers, capacity, dryRun } = this.fleetConfig;
+        const totalCapacity = workers * capacity;
+        console.log(`
+${colors.cyan}================================================================${colors.reset}
+${colors.cyan}  AgentFactory Worker Fleet Manager${colors.reset}
+${colors.cyan}================================================================${colors.reset}
+  Workers:         ${colors.green}${workers}${colors.reset}
+  Capacity/Worker: ${colors.green}${capacity}${colors.reset}
+  Total Capacity:  ${colors.green}${totalCapacity}${colors.reset} concurrent agents
+
+  System:
+    CPU Cores:    ${os.cpus().length}
+    Total RAM:    ${Math.round(os.totalmem() / 1024 / 1024 / 1024)} GB
+    Free RAM:     ${Math.round(os.freemem() / 1024 / 1024 / 1024)} GB
+${colors.cyan}================================================================${colors.reset}
+`);
+        if (dryRun) {
+            console.log(`${colors.yellow}Dry run mode - not starting workers${colors.reset}`);
+            return;
+        }
+        // Wire up AbortSignal for graceful shutdown
+        const onAbort = () => this.shutdown('AbortSignal');
+        signal?.addEventListener('abort', onAbort, { once: true });
+        try {
+            // Spawn workers with staggered start to avoid thundering herd
+            for (let i = 0; i < workers; i++) {
+                if (signal?.aborted)
+                    break;
+                await this.spawnWorker(i);
+                if (i < workers - 1) {
+                    await new Promise((resolve) => setTimeout(resolve, 1000));
+                }
+            }
+            if (signal?.aborted)
+                return;
+            fleetLog(null, colors.green, 'INF', `All ${workers} workers started`);
+            // Keep the fleet manager running until shutdown
+            await new Promise((resolve) => {
+                this.resolveRunning = resolve;
+            });
+        }
+        finally {
+            signal?.removeEventListener('abort', onAbort);
+        }
+    }
+    async spawnWorker(id) {
+        const color = workerColors[id % workerColors.length];
+        const existingWorker = this.workers.get(id);
+        const restartCount = existingWorker?.restartCount ?? 0;
+        fleetLog(id, color, 'INF', `Starting worker (capacity: ${this.fleetConfig.capacity})${restartCount > 0 ? ` [restart #${restartCount}]` : ''}`);
+        const workerProcess = spawn('node', [
+            this.workerScript,
+            '--capacity',
+            String(this.fleetConfig.capacity),
+            '--api-url',
+            this.fleetConfig.apiUrl,
+            '--api-key',
+            this.fleetConfig.apiKey,
+        ], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: {
+                ...process.env,
+                WORKER_FLEET_ID: String(id),
+            },
+            cwd: process.cwd(),
+        });
+        const workerInfo = {
+            id,
+            process: workerProcess,
+            color,
+            startedAt: new Date(),
+            restartCount,
+        };
+        this.workers.set(id, workerInfo);
+        // Handle stdout — prefix with worker ID
+        workerProcess.stdout?.on('data', (data) => {
+            const lines = data.toString().trim().split('\n');
+            for (const line of lines) {
+                if (line.trim()) {
+                    console.log(`${color}[W${id.toString().padStart(2, '0')}]${colors.reset} ${line}`);
+                }
+            }
+        });
+        // Handle stderr
+        workerProcess.stderr?.on('data', (data) => {
+            const lines = data.toString().trim().split('\n');
+            for (const line of lines) {
+                if (line.trim()) {
+                    console.log(`${color}[W${id.toString().padStart(2, '0')}]${colors.reset} ${colors.red}${line}${colors.reset}`);
+                }
+            }
+        });
+        // Handle worker exit
+        workerProcess.on('exit', (code, sig) => {
+            if (this.shuttingDown) {
+                fleetLog(id, color, 'INF', `Worker stopped (code: ${code}, signal: ${sig})`);
+                return;
+            }
+            fleetLog(id, color, 'WRN', `Worker exited unexpectedly (code: ${code}, signal: ${sig}) - restarting in 5s`);
+            const worker = this.workers.get(id);
+            if (worker) {
+                worker.restartCount++;
+            }
+            setTimeout(() => {
+                if (!this.shuttingDown) {
+                    this.spawnWorker(id);
+                }
+            }, 5000);
+        });
+        workerProcess.on('error', (err) => {
+            fleetLog(id, color, 'ERR', `Worker error: ${err.message}`);
+        });
+    }
+    async shutdown(reason) {
+        if (this.shuttingDown)
+            return;
+        this.shuttingDown = true;
+        console.log(`\n${colors.yellow}Received ${reason} - shutting down fleet...${colors.reset}`);
+        for (const [id, worker] of this.workers) {
+            fleetLog(id, worker.color, 'INF', 'Stopping worker...');
+            worker.process.kill('SIGTERM');
+        }
+        // Wait for workers to exit (max 30 seconds)
+        const forceKillTimeout = setTimeout(() => {
+            console.log(`${colors.red}Timeout waiting for workers - force killing${colors.reset}`);
+            for (const worker of this.workers.values()) {
+                worker.process.kill('SIGKILL');
+            }
+        }, 30000);
+        await Promise.all(Array.from(this.workers.values()).map((worker) => new Promise((resolve) => {
+            worker.process.on('exit', () => resolve());
+        })));
+        clearTimeout(forceKillTimeout);
+        console.log(`${colors.green}All workers stopped${colors.reset}`);
+        // Resolve the running promise so start() returns
+        this.resolveRunning?.();
+    }
+}
+// ---------------------------------------------------------------------------
+// Runner
+// ---------------------------------------------------------------------------
+/**
+ * Run a fleet of worker processes.
+ *
+ * The caller can cancel via the optional {@link AbortSignal}. The function
+ * returns once all workers have been stopped.
+ */
+export async function runWorkerFleet(config, signal) {
+    const workers = config.workers ?? Math.max(1, Math.floor(os.cpus().length / 2));
+    const capacity = config.capacity ?? 3;
+    const dryRun = config.dryRun ?? false;
+    const workerScript = config.workerScript ?? getDefaultWorkerScript();
+    const fleet = new WorkerFleet({
+        workers,
+        capacity,
+        dryRun,
+        apiUrl: config.apiUrl,
+        apiKey: config.apiKey,
+    }, workerScript);
+    await fleet.start(signal);
+}