@supaku/agentfactory-cli 0.3.0 → 0.4.1

package/dist/src/lib/analyze-logs-runner.js

@@ -0,0 +1,216 @@
+/**
+ * Log Analyzer Runner -- Programmatic API for the log analyzer CLI.
+ *
+ * Extracts the core logic from the analyze-logs bin script so that it can be
+ * invoked programmatically (e.g. from a Next.js route handler or test) without
+ * process.exit / dotenv / argv coupling.
+ */
+import { execSync } from 'child_process';
+import { createLogAnalyzer } from '@supaku/agentfactory';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const DEFAULT_POLL_INTERVAL = 5000;
+/** Detect the git repository root. Falls back to cwd. */
+export function getGitRoot() {
+    try {
+        return execSync('git rev-parse --show-toplevel', {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        return process.cwd();
+    }
+}
+function formatTime() {
+    return new Date().toLocaleTimeString();
+}
+function emptyStats() {
+    return {
+        sessionsAnalyzed: 0,
+        totalErrors: 0,
+        totalPatterns: 0,
+        issuesCreated: 0,
+        issuesUpdated: 0,
+    };
+}
+async function analyzeAndPrintSession(analyzer, sessionId, options, stats) {
+    console.log(`\nAnalyzing session: ${sessionId}`);
+    console.log('-'.repeat(50));
+    const result = analyzer.analyzeSession(sessionId);
+    if (!result) {
+        console.log('  [SKIP] Session not found or incomplete');
+        return false;
+    }
+    console.log(`  Issue: ${result.metadata.issueIdentifier}`);
+    console.log(`  Work Type: ${result.metadata.workType}`);
+    console.log(`  Status: ${result.metadata.status}`);
+    console.log(`  Events: ${result.eventsAnalyzed}`);
+    console.log(`  Errors: ${result.errorsFound}`);
+    console.log(`  Patterns: ${result.patterns.length}`);
+    stats.sessionsAnalyzed++;
+    stats.totalErrors += result.errorsFound;
+    stats.totalPatterns += result.patterns.length;
+    if (options.verbose && result.patterns.length > 0) {
+        console.log('\n  Detected Patterns:');
+        for (const pattern of result.patterns) {
+            console.log(`    - [${pattern.severity}] ${pattern.title}`);
+            console.log(`      Type: ${pattern.type}, Occurrences: ${pattern.occurrences}`);
+            if (pattern.tool) {
+                console.log(`      Tool: ${pattern.tool}`);
+            }
+        }
+    }
+    if (result.suggestedIssues.length > 0) {
+        console.log(`\n  Suggested Issues: ${result.suggestedIssues.length}`);
+        if (options.verbose) {
+            for (const issue of result.suggestedIssues) {
+                console.log(`    - ${issue.title}`);
+                console.log(`      Signature: ${issue.signature}`);
+                console.log(`      Labels: ${issue.labels.join(', ')}`);
+            }
+        }
+        try {
+            const issueResults = await analyzer.createIssues(result.suggestedIssues, sessionId, options.dryRun);
+            for (const issueResult of issueResults) {
+                if (issueResult.created) {
+                    console.log(`  [${options.dryRun ? 'WOULD CREATE' : 'CREATED'}] ${issueResult.identifier}`);
+                    stats.issuesCreated++;
+                }
+                else {
+                    console.log(`  [${options.dryRun ? 'WOULD UPDATE' : 'UPDATED'}] ${issueResult.identifier}`);
+                    stats.issuesUpdated++;
+                }
+            }
+        }
+        catch (error) {
+            console.log(`  [ERROR] Failed to create issues: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (!options.dryRun) {
+        analyzer.markProcessed(sessionId, result);
+        console.log('  [PROCESSED]');
+    }
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Summary printer
+// ---------------------------------------------------------------------------
+export function printSummary(stats, dryRun) {
+    console.log('\n' + '='.repeat(50));
+    console.log('=== Summary ===\n');
+    console.log(`  Sessions analyzed: ${stats.sessionsAnalyzed}`);
+    console.log(`  Total errors found: ${stats.totalErrors}`);
+    console.log(`  Total patterns detected: ${stats.totalPatterns}`);
+    console.log(`  Issues created: ${stats.issuesCreated}${dryRun ? ' (dry run)' : ''}`);
+    console.log(`  Issues updated: ${stats.issuesUpdated}${dryRun ? ' (dry run)' : ''}`);
+    console.log('');
+}
+// ---------------------------------------------------------------------------
+// Follow mode (watch)
+// ---------------------------------------------------------------------------
+async function runFollowMode(analyzer, options, interval, signal) {
+    const stats = emptyStats();
+    const processedInSession = new Set();
+    console.log(`[${formatTime()}] Watching for new sessions (poll interval: ${interval}ms)`);
+    console.log(`[${formatTime()}] Press Ctrl+C to stop\n`);
+    const isAborted = () => signal?.aborted ?? false;
+    // Initial check for existing unprocessed sessions
+    const initialSessions = analyzer.getUnprocessedSessions();
+    if (initialSessions.length > 0) {
+        console.log(`[${formatTime()}] Found ${initialSessions.length} existing unprocessed session(s)`);
+        for (const sid of initialSessions) {
+            if (isAborted())
+                break;
+            await analyzeAndPrintSession(analyzer, sid, options, stats);
+            processedInSession.add(sid);
+        }
+    }
+    // Poll loop
+    while (!isAborted()) {
+        await new Promise((resolve) => {
+            const timer = setTimeout(resolve, interval);
+            // If an abort signal fires while waiting, resolve immediately
+            if (signal) {
+                const onAbort = () => {
+                    clearTimeout(timer);
+                    resolve();
+                };
+                signal.addEventListener('abort', onAbort, { once: true });
+            }
+        });
+        if (isAborted())
+            break;
+        const sessions = analyzer.getUnprocessedSessions();
+        const newSessions = sessions.filter((s) => !processedInSession.has(s));
+        if (newSessions.length > 0) {
+            console.log(`[${formatTime()}] Found ${newSessions.length} new session(s) ready for analysis`);
+            for (const sid of newSessions) {
+                if (isAborted())
+                    break;
+                const analyzed = await analyzeAndPrintSession(analyzer, sid, options, stats);
+                if (analyzed) {
+                    processedInSession.add(sid);
+                }
+            }
+        }
+    }
+    console.log(`\n[${formatTime()}] Stopping...`);
+    return stats;
+}
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+/**
+ * Run the log analyzer programmatically.
+ *
+ * For one-shot mode (default) the returned promise resolves with the analysis
+ * result once all sessions have been processed.
+ *
+ * For follow mode (`config.follow = true`) the analyzer keeps running until
+ * the optional `signal` is aborted.  When the signal fires the current poll
+ * cycle finishes and the accumulated stats are returned.
+ */
+export async function runLogAnalyzer(config = {}, signal) {
+    const gitRoot = config.gitRoot ?? getGitRoot();
+    const logsDir = config.logsDir ?? process.env.AGENT_LOGS_DIR ?? `${gitRoot}/.agent-logs`;
+    const dryRun = config.dryRun ?? false;
+    const verbose = config.verbose ?? false;
+    const interval = config.interval ?? DEFAULT_POLL_INTERVAL;
+    console.log('\n=== AgentFactory Log Analyzer ===\n');
+    if (dryRun) {
+        console.log('[DRY RUN MODE - No issues will be created]\n');
+    }
+    const analyzer = createLogAnalyzer({ logsDir });
+    // Cleanup mode
+    if (config.cleanup) {
+        console.log('Cleaning up old logs...\n');
+        const deleted = analyzer.cleanupOldLogs();
+        console.log(`Deleted ${deleted} old log entries.\n`);
+        return emptyStats();
+    }
+    // Follow (watch) mode
+    if (config.follow) {
+        return runFollowMode(analyzer, { dryRun, verbose }, interval, signal);
+    }
+    // Standard one-shot mode
+    const stats = emptyStats();
+    let sessionsToAnalyze;
+    if (config.sessionId) {
+        sessionsToAnalyze = [config.sessionId];
+        console.log(`Analyzing session: ${config.sessionId}\n`);
+    }
+    else {
+        sessionsToAnalyze = analyzer.getUnprocessedSessions();
+        console.log(`Found ${sessionsToAnalyze.length} unprocessed session(s)\n`);
+    }
+    if (sessionsToAnalyze.length === 0) {
+        console.log('No sessions to analyze.\n');
+        return stats;
+    }
+    for (const sid of sessionsToAnalyze) {
+        await analyzeAndPrintSession(analyzer, sid, { dryRun, verbose }, stats);
+    }
+    return stats;
+}

package/dist/src/lib/cleanup-runner.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Cleanup Runner -- Programmatic API for the worktree cleanup CLI.
+ *
+ * Exports `runCleanup()` so worktree cleanup can be invoked from code
+ * without going through process.argv / process.env / process.exit.
+ */
+export interface CleanupRunnerConfig {
+    /** Show what would be cleaned up without removing (default: false) */
+    dryRun?: boolean;
+    /** Force removal even if worktree appears active (default: false) */
+    force?: boolean;
+    /** Custom worktrees directory (default: {gitRoot}/.worktrees) */
+    worktreePath?: string;
+    /** Git root for default worktree path (default: auto-detect) */
+    gitRoot?: string;
+}
+export interface CleanupResult {
+    scanned: number;
+    orphaned: number;
+    cleaned: number;
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+}
+export declare function getGitRoot(): string;
+export declare function runCleanup(config?: CleanupRunnerConfig): CleanupResult;
+//# sourceMappingURL=cleanup-runner.d.ts.map

package/dist/src/lib/cleanup-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup-runner.d.ts","sourceRoot":"","sources":["../../../src/lib/cleanup-runner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,qEAAqE;IACrE,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC/C;AAuBD,wBAAgB,UAAU,IAAI,MAAM,CASnC;AAuND,wBAAgB,UAAU,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,aAAa,CAUtE"}

package/dist/src/lib/cleanup-runner.js

@@ -0,0 +1,224 @@
+/**
+ * Cleanup Runner -- Programmatic API for the worktree cleanup CLI.
+ *
+ * Exports `runCleanup()` so worktree cleanup can be invoked from code
+ * without going through process.argv / process.env / process.exit.
+ */
+import { execSync } from 'child_process';
+import { existsSync, readdirSync, statSync } from 'fs';
+import { resolve, basename } from 'path';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+export function getGitRoot() {
+    try {
+        return execSync('git rev-parse --show-toplevel', {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        return process.cwd();
+    }
+}
+/**
+ * Get list of git worktrees from 'git worktree list'
+ */
+function getGitWorktrees() {
+    const worktrees = new Map();
+    try {
+        const output = execSync('git worktree list --porcelain', {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let currentPath = '';
+        for (const line of output.split('\n')) {
+            if (line.startsWith('worktree ')) {
+                currentPath = line.substring(9);
+            }
+            else if (line.startsWith('branch ')) {
+                const branch = line.substring(7).replace('refs/heads/', '');
+                worktrees.set(currentPath, branch);
+            }
+        }
+    }
+    catch (error) {
+        console.error('Failed to list git worktrees:', error);
+    }
+    return worktrees;
+}
+/**
+ * Check if a git branch exists
+ */
+function branchExists(branchName) {
+    try {
+        execSync(`git show-ref --verify --quiet refs/heads/${branchName}`, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Scan the worktrees directory and identify orphaned worktrees
+ */
+function scanWorktrees(options) {
+    const worktreesDir = resolve(options.worktreePath);
+    const result = [];
+    if (!existsSync(worktreesDir)) {
+        console.log(`Worktrees directory not found: ${worktreesDir}`);
+        return result;
+    }
+    const gitWorktrees = getGitWorktrees();
+    const entries = readdirSync(worktreesDir);
+    for (const entry of entries) {
+        const entryPath = resolve(worktreesDir, entry);
+        try {
+            if (!statSync(entryPath).isDirectory()) {
+                continue;
+            }
+        }
+        catch {
+            continue;
+        }
+        const info = {
+            path: entryPath,
+            branch: entry,
+            isOrphaned: false,
+        };
+        const isKnownWorktree = gitWorktrees.has(entryPath);
+        const branchName = isKnownWorktree ? gitWorktrees.get(entryPath) : entry;
+        if (options.force) {
+            info.isOrphaned = true;
+            info.reason = 'force cleanup requested';
+        }
+        else if (!isKnownWorktree) {
+            info.isOrphaned = true;
+            info.reason = 'not registered with git worktree';
+        }
+        else if (!branchExists(branchName)) {
+            info.isOrphaned = true;
+            info.reason = `branch '${branchName}' no longer exists`;
+        }
+        result.push(info);
+    }
+    return result;
+}
+/**
+ * Remove a single worktree
+ */
+function removeWorktree(worktreePath) {
+    try {
+        execSync(`git worktree remove "${worktreePath}" --force`, {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return { success: true };
+    }
+    catch {
+        try {
+            execSync(`rm -rf "${worktreePath}"`, {
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            execSync('git worktree prune', {
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            return { success: true };
+        }
+        catch (rmError) {
+            return {
+                success: false,
+                error: rmError instanceof Error ? rmError.message : String(rmError),
+            };
+        }
+    }
+}
+/**
+ * Core cleanup logic
+ */
+function cleanup(options) {
+    const result = {
+        scanned: 0,
+        orphaned: 0,
+        cleaned: 0,
+        errors: [],
+    };
+    console.log('Scanning worktrees...\n');
+    try {
+        execSync('git worktree prune', {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch {
+        console.log('Note: Could not prune git worktree metadata');
+    }
+    const worktrees = scanWorktrees(options);
+    result.scanned = worktrees.length;
+    if (worktrees.length === 0) {
+        console.log('No worktrees found.\n');
+        return result;
+    }
+    console.log(`Found ${worktrees.length} worktree(s) in ${options.worktreePath}/\n`);
+    for (const wt of worktrees) {
+        const status = wt.isOrphaned ? '  orphaned' : '    active';
+        const reason = wt.reason ? ` (${wt.reason})` : '';
+        console.log(`  ${status}: ${basename(wt.path)}${reason}`);
+    }
+    console.log('');
+    const orphaned = worktrees.filter((wt) => wt.isOrphaned);
+    result.orphaned = orphaned.length;
+    if (orphaned.length === 0) {
+        console.log('No orphaned worktrees to clean up.\n');
+        return result;
+    }
+    if (options.dryRun) {
+        console.log(`[DRY RUN] Would clean up ${orphaned.length} orphaned worktree(s):\n`);
+        for (const wt of orphaned) {
+            console.log(`  Would remove: ${wt.path}`);
+        }
+        console.log('');
+        return result;
+    }
+    console.log(`Cleaning up ${orphaned.length} orphaned worktree(s)...\n`);
+    for (const wt of orphaned) {
+        process.stdout.write(`  Removing ${basename(wt.path)}... `);
+        const removal = removeWorktree(wt.path);
+        if (removal.success) {
+            console.log('done');
+            result.cleaned++;
+        }
+        else {
+            console.log(`FAILED: ${removal.error}`);
+            result.errors.push({ path: wt.path, error: removal.error || 'Unknown error' });
+        }
+    }
+    console.log('');
+    try {
+        execSync('git worktree prune', {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        console.log('Pruned git worktree metadata.\n');
+    }
+    catch {
+        // Ignore prune errors
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Runner
+// ---------------------------------------------------------------------------
+export function runCleanup(config) {
+    const gitRoot = config?.gitRoot ?? getGitRoot();
+    const options = {
+        dryRun: config?.dryRun ?? false,
+        force: config?.force ?? false,
+        worktreePath: config?.worktreePath ?? resolve(gitRoot, '.worktrees'),
+    };
+    return cleanup(options);
+}

package/dist/src/lib/orchestrator-runner.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Orchestrator Runner -- Programmatic API for the orchestrator CLI.
+ *
+ * Exports `runOrchestrator()` so the orchestrator can be invoked from code
+ * (e.g. Next.js route handlers, tests, or custom scripts) without going
+ * through process.argv / process.env / process.exit.
+ */
+import { type AgentProcess, type OrchestratorIssue } from '@supaku/agentfactory';
+export interface OrchestratorRunnerConfig {
+    /** Linear API key for authentication */
+    linearApiKey: string;
+    /** Filter issues by project name */
+    project?: string;
+    /** Maximum concurrent agents (default: 3) */
+    max?: number;
+    /** Process a single issue by ID */
+    single?: string;
+    /** Wait for agents to complete (default: true) */
+    wait?: boolean;
+    /** Show what would be done without executing (default: false) */
+    dryRun?: boolean;
+    /** Git repository root (default: auto-detect) */
+    gitRoot?: string;
+    /** Callbacks for agent lifecycle events */
+    callbacks?: OrchestratorCallbacks;
+}
+export interface OrchestratorCallbacks {
+    onIssueSelected?: (issue: OrchestratorIssue) => void;
+    onAgentStart?: (agent: AgentProcess) => void;
+    onAgentComplete?: (agent: AgentProcess) => void;
+    onAgentError?: (agent: AgentProcess, error: Error) => void;
+    onAgentIncomplete?: (agent: AgentProcess) => void;
+}
+export interface OrchestratorRunnerResult {
+    agentsSpawned: number;
+    errors: Array<{
+        issueId: string;
+        error: Error;
+    }>;
+    completed: AgentProcess[];
+}
+export declare function getGitRoot(): string;
+export declare function formatDuration(ms: number): string;
+export declare function runOrchestrator(config: OrchestratorRunnerConfig): Promise<OrchestratorRunnerResult>;
+//# sourceMappingURL=orchestrator-runner.d.ts.map

package/dist/src/lib/orchestrator-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-runner.d.ts","sourceRoot":"","sources":["../../../src/lib/orchestrator-runner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAA;AAM7B,MAAM,WAAW,wBAAwB;IACvC,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAA;IACpB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,kDAAkD;IAClD,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,qBAAqB,CAAA;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAA;IACpD,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;IAC5C,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;IAC/C,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IAC1D,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;CAClD;AAED,MAAM,WAAW,wBAAwB;IACvC,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC,CAAA;IAChD,SAAS,EAAE,YAAY,EAAE,CAAA;CAC1B;AAMD,wBAAgB,UAAU,IAAI,MAAM,CASnC;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAYjD;AA0CD,wBAAsB,eAAe,CACnC,MAAM,EAAE,wBAAwB,GAC/B,OAAO,CAAC,wBAAwB,CAAC,CAqFnC"}

package/dist/src/lib/orchestrator-runner.js

@@ -0,0 +1,144 @@
+/**
+ * Orchestrator Runner -- Programmatic API for the orchestrator CLI.
+ *
+ * Exports `runOrchestrator()` so the orchestrator can be invoked from code
+ * (e.g. Next.js route handlers, tests, or custom scripts) without going
+ * through process.argv / process.env / process.exit.
+ */
+import path from 'path';
+import { execSync } from 'child_process';
+import { createOrchestrator, } from '@supaku/agentfactory';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+export function getGitRoot() {
+    try {
+        return execSync('git rev-parse --show-toplevel', {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        return process.cwd();
+    }
+}
+export function formatDuration(ms) {
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    if (hours > 0) {
+        return `${hours}h ${minutes % 60}m ${seconds % 60}s`;
+    }
+    if (minutes > 0) {
+        return `${minutes}m ${seconds % 60}s`;
+    }
+    return `${seconds}s`;
+}
+// ---------------------------------------------------------------------------
+// Default callbacks (console.log-based, matching the original CLI output)
+// ---------------------------------------------------------------------------
+function defaultCallbacks() {
+    return {
+        onIssueSelected: (issue) => {
+            console.log(`Selected: ${issue.identifier} - ${issue.title}`);
+            console.log(`  URL: ${issue.url}`);
+            console.log(`  Labels: ${issue.labels.join(', ') || 'none'}`);
+        },
+        onAgentStart: (agent) => {
+            console.log(`Agent started: ${agent.identifier} (PID: ${agent.pid})`);
+            console.log(`  Worktree: ${agent.worktreePath}`);
+        },
+        onAgentComplete: (agent) => {
+            const duration = agent.completedAt
+                ? formatDuration(agent.completedAt.getTime() - agent.startedAt.getTime())
+                : 'unknown';
+            console.log(`Agent completed: ${agent.identifier} (${duration})`);
+        },
+        onAgentError: (_agent, error) => {
+            console.error(`Agent failed: ${_agent.identifier}`);
+            console.error(`  Error: ${error.message}`);
+        },
+        onAgentIncomplete: (agent) => {
+            const duration = agent.completedAt
+                ? formatDuration(agent.completedAt.getTime() - agent.startedAt.getTime())
+                : 'unknown';
+            console.warn(`Agent incomplete: ${agent.identifier} (${duration})`);
+            console.warn(`  Reason: ${agent.incompleteReason ?? 'unknown'}`);
+            console.warn(`  Worktree preserved: ${agent.worktreePath}`);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Runner
+// ---------------------------------------------------------------------------
+export async function runOrchestrator(config) {
+    const maxConcurrent = config.max ?? 3;
+    const wait = config.wait ?? true;
+    const dryRun = config.dryRun ?? false;
+    const gitRoot = config.gitRoot ?? getGitRoot();
+    const cb = config.callbacks ?? defaultCallbacks();
+    const orchestrator = createOrchestrator({
+        project: config.project,
+        maxConcurrent,
+        worktreePath: path.resolve(gitRoot, '.worktrees'),
+        linearApiKey: config.linearApiKey,
+    }, {
+        onIssueSelected: cb.onIssueSelected,
+        onAgentStart: cb.onAgentStart,
+        onAgentComplete: cb.onAgentComplete,
+        onAgentError: cb.onAgentError,
+        onAgentIncomplete: cb.onAgentIncomplete,
+    });
+    const result = {
+        agentsSpawned: 0,
+        errors: [],
+        completed: [],
+    };
+    // --single mode ----------------------------------------------------------
+    if (config.single) {
+        if (dryRun) {
+            return result;
+        }
+        await orchestrator.spawnAgentForIssue(config.single);
+        result.agentsSpawned = 1;
+        if (wait) {
+            // Wire up SIGINT so callers running from a terminal can stop agents
+            const sigintHandler = () => {
+                orchestrator.stopAll();
+            };
+            process.on('SIGINT', sigintHandler);
+            try {
+                const completed = await orchestrator.waitForAll();
+                result.completed = completed;
+            }
+            finally {
+                process.removeListener('SIGINT', sigintHandler);
+            }
+        }
+        return result;
+    }
+    // --dry-run mode ---------------------------------------------------------
+    if (dryRun) {
+        await orchestrator.getBacklogIssues();
+        // Nothing to spawn in dry-run; caller can inspect issues via callbacks
+        return result;
+    }
+    // Normal run -------------------------------------------------------------
+    const runResult = await orchestrator.run();
+    result.agentsSpawned = runResult.agents.length;
+    result.errors = runResult.errors;
+    if (wait && runResult.agents.length > 0) {
+        const sigintHandler = () => {
+            orchestrator.stopAll();
+        };
+        process.on('SIGINT', sigintHandler);
+        try {
+            const completed = await orchestrator.waitForAll();
+            result.completed = completed;
+        }
+        finally {
+            process.removeListener('SIGINT', sigintHandler);
+        }
+    }
+    return result;
+}