sequant 1.20.2 → 2.0.0

package/dist/src/commands/run.js

@@ -9,7 +9,9 @@
  */
 import chalk from "chalk";
 import { spawnSync } from "child_process";
+import pLimit from "p-limit";
 import { getManifest } from "../lib/manifest.js";
+import { formatElapsedTime } from "../lib/phase-spinner.js";
 import { getSettings } from "../lib/settings.js";
 import { LogWriter } from "../lib/workflow/log-writer.js";
 import { StateManager } from "../lib/workflow/state-manager.js";
@@ -23,6 +25,13 @@ import { getCommitHash } from "../lib/workflow/git-diff-utils.js";
 import { getTokenUsageForRun } from "../lib/workflow/token-utils.js";
 import { reconcileStateAtStartup } from "../lib/workflow/state-utils.js";
 import { analyzeRun, formatReflection } from "../lib/workflow/run-reflect.js";
+/** @internal Log a non-fatal warning: one-line summary always, detail in verbose. */
+export function logNonFatalWarning(message, error, verbose) {
+    console.log(chalk.yellow(message));
+    if (verbose) {
+        console.log(chalk.gray(`    ${error}`));
+    }
+}
 // Extracted modules
 import { detectDefaultBranch, ensureWorktrees, ensureWorktreesChain, getWorktreeDiffStats, } from "../lib/workflow/worktree-manager.js";
 import { formatDuration } from "../lib/workflow/phase-executor.js";
@@ -32,6 +41,64 @@ export { parseQaVerdict, formatDuration, executePhaseWithRetry, } from "../lib/w
 export { detectDefaultBranch, checkWorktreeFreshness, removeStaleWorktree, listWorktrees, getWorktreeChangedFiles, getWorktreeDiffStats, readCacheMetrics, filterResumedPhases, ensureWorktree, createCheckpointCommit, reinstallIfLockfileChanged, rebaseBeforePR, createPR, } from "../lib/workflow/worktree-manager.js";
 export { detectPhasesFromLabels, parseRecommendedWorkflow, determinePhasesForIssue, } from "../lib/workflow/phase-mapper.js";
 export { getIssueInfo, sortByDependencies, parseBatches, getEnvConfig, executeBatch, runIssueWithLogging, } from "../lib/workflow/batch-executor.js";
+/**
+ * Normalize Commander.js --no-X flags into typed RunOptions fields.
+ * Replaces the `as any` cast (#402 AC-4).
+ */
+export function normalizeCommanderOptions(options) {
+    const raw = options;
+    return {
+        ...options,
+        ...(raw.log === false && { noLog: true }),
+        ...(raw.smartTests === false && { noSmartTests: true }),
+        ...(raw.mcp === false && { noMcp: true }),
+        ...(raw.retry === false && { noRetry: true }),
+        ...(raw.rebase === false && { noRebase: true }),
+        ...(raw.pr === false && { noPr: true }),
+    };
+}
+/**
+ * Execute a single issue with log bookkeeping (start/complete/PR info).
+ * Replaces the duplicated per-issue wrapper in sequential and parallel loops (#402 AC-1).
+ */
+async function executeOneIssue(args) {
+    const { issueNumber, batchCtx, chain, parallelIssueNumber } = args;
+    const { config, options, issueInfoMap, worktreeMap, logWriter, stateManager, shutdownManager, packageManager, baseBranch, onProgress, } = batchCtx;
+    const issueInfo = issueInfoMap.get(issueNumber) ?? {
+        title: `Issue #${issueNumber}`,
+        labels: [],
+    };
+    const worktreeInfo = worktreeMap.get(issueNumber);
+    // Start issue logging
+    if (logWriter) {
+        logWriter.startIssue(issueNumber, issueInfo.title, issueInfo.labels);
+    }
+    const ctx = {
+        issueNumber,
+        title: issueInfo.title,
+        labels: issueInfo.labels,
+        config,
+        options,
+        services: { logWriter, stateManager, shutdownManager },
+        worktree: worktreeInfo
+            ? { path: worktreeInfo.path, branch: worktreeInfo.branch }
+            : undefined,
+        chain,
+        packageManager,
+        baseBranch,
+        onProgress,
+    };
+    const result = await runIssueWithLogging(ctx);
+    // Record PR info in log before completing issue
+    if (logWriter && result.prNumber && result.prUrl) {
+        logWriter.setPRInfo(result.prNumber, result.prUrl, parallelIssueNumber);
+    }
+    // Complete issue logging
+    if (logWriter) {
+        logWriter.completeIssue(parallelIssueNumber);
+    }
+    return result;
+}
 /**
  * Main run command
  */
@@ -61,22 +128,11 @@ export async function runCommand(issues, options) {
     const envConfig = getEnvConfig();
     // Settings provide defaults, env overrides settings, CLI overrides all
     // Note: phases are auto-detected per-issue unless --phases is explicitly set
-    // Commander.js converts --no-X to { X: false }, not { noX: true }.
-    // Normalize these so RunOptions fields (noLog, noMcp, etc.) work correctly.
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const cliOpts = options;
-    const normalizedOptions = {
-        ...options,
-        ...(cliOpts.log === false && { noLog: true }),
-        ...(cliOpts.smartTests === false && { noSmartTests: true }),
-        ...(cliOpts.mcp === false && { noMcp: true }),
-        ...(cliOpts.retry === false && { noRetry: true }),
-        ...(cliOpts.rebase === false && { noRebase: true }),
-        ...(cliOpts.pr === false && { noPr: true }),
-    };
+    const normalizedOptions = normalizeCommanderOptions(options);
     const mergedOptions = {
         // Settings defaults (phases removed - now auto-detected)
         sequential: normalizedOptions.sequential ?? settings.run.sequential,
+        concurrency: normalizedOptions.concurrency ?? settings.run.concurrency,
         timeout: normalizedOptions.timeout ?? settings.run.timeout,
         logPath: normalizedOptions.logPath ?? settings.run.logPath,
         qualityLoop: normalizedOptions.qualityLoop ?? settings.run.qualityLoop,
@@ -132,6 +188,13 @@ export async function runCommand(issues, options) {
             console.log("");
         }
     }
+    // Validate concurrency value
+    if (mergedOptions.concurrency !== undefined &&
+        (mergedOptions.concurrency < 1 ||
+            !Number.isInteger(mergedOptions.concurrency))) {
+        console.log(chalk.red(`❌ Invalid --concurrency value: ${mergedOptions.concurrency}. Must be a positive integer.`));
+        return;
+    }
     // Validate QA gate requirements
     if (mergedOptions.qaGate && !mergedOptions.chain) {
         console.log(chalk.red("❌ --qa-gate requires --chain flag"));
@@ -161,10 +224,14 @@ export async function runCommand(issues, options) {
     const retryEnabled = mergedOptions.noRetry
         ? false
         : (settings.run.retry ?? true);
+    const isSequential = mergedOptions.sequential ?? false;
+    const isParallel = !isSequential && issueNumbers.length > 1;
     const config = {
         ...DEFAULT_CONFIG,
         phases: explicitPhases ?? DEFAULT_PHASES,
-        sequential: mergedOptions.sequential ?? false,
+        sequential: isSequential,
+        concurrency: mergedOptions.concurrency ?? DEFAULT_CONFIG.concurrency,
+        parallel: isParallel,
         dryRun: mergedOptions.dryRun ?? false,
         verbose: mergedOptions.verbose ?? false,
         phaseTimeout: mergedOptions.timeout ?? DEFAULT_CONFIG.phaseTimeout,
@@ -173,6 +240,8 @@ export async function runCommand(issues, options) {
         noSmartTests: mergedOptions.noSmartTests ?? false,
         mcp: mcpEnabled,
         retry: retryEnabled,
+        agent: mergedOptions.agent ?? settings.run.agent,
+        aiderSettings: settings.run.aider,
     };
     // Propagate verbose mode to UI config so spinners use text-only mode.
     // This prevents animated spinner control characters from colliding with
@@ -234,7 +303,7 @@ export async function runCommand(issues, options) {
     else {
         console.log(chalk.gray(`  Phases: ${config.phases.join(" → ")}`));
     }
-    console.log(chalk.gray(`  Mode: ${config.sequential ? "stop-on-failure" : "continue-on-failure"}`));
+    console.log(chalk.gray(`  Mode: ${config.sequential ? "sequential (stop-on-failure)" : `parallel (concurrency: ${config.concurrency})`}`));
     if (config.qualityLoop) {
         console.log(chalk.gray(`  Quality loop: enabled (max ${config.maxIterations} iterations)`));
     }
@@ -270,11 +339,9 @@ export async function runCommand(issues, options) {
                 console.log(chalk.gray(`  State reconciled: ${reconcileResult.advanced.map((n) => `#${n}`).join(", ")} → merged`));
             }
         }
-        catch {
+        catch (error) {
             // AC-8: Graceful degradation - don't block execution on reconciliation failure
-            if (config.verbose) {
-                console.log(chalk.yellow(`  ⚠️  State reconciliation failed, continuing...`));
-            }
+            logNonFatalWarning(`  ⚠️  State reconciliation failed, continuing...`, error, config.verbose);
         }
     }
     // AC-1 & AC-2: Pre-flight state guard - skip completed issues unless --force
@@ -294,8 +361,9 @@ export async function runCommand(issues, options) {
                     activeIssues.push(issueNumber);
                 }
             }
-            catch {
+            catch (error) {
                 // AC-8: Graceful degradation - if state check fails, include the issue
+                logNonFatalWarning(`  ⚠️  State lookup failed for #${issueNumber}, including anyway...`, error, config.verbose);
                 activeIssues.push(issueNumber);
             }
         }
@@ -357,6 +425,18 @@ export async function runCommand(issues, options) {
             }
         }
     }
+    // Shared context for all execution paths
+    const batchCtx = {
+        config,
+        options: mergedOptions,
+        issueInfoMap,
+        worktreeMap,
+        logWriter,
+        stateManager,
+        shutdownManager: shutdown,
+        packageManager: manifest.packageManager,
+        baseBranch: resolvedBaseBranch,
+    };
     // Execute with graceful shutdown handling
     const results = [];
     let exitCode = 0;
@@ -366,7 +446,7 @@ export async function runCommand(issues, options) {
             for (let batchIdx = 0; batchIdx < batches.length; batchIdx++) {
                 const batch = batches[batchIdx];
                 console.log(chalk.blue(`\n  Batch ${batchIdx + 1}/${batches.length}: Issues ${batch.map((n) => `#${n}`).join(", ")}`));
-                const batchResults = await executeBatch(batch, config, logWriter, stateManager, mergedOptions, issueInfoMap, worktreeMap, shutdown, manifest.packageManager, resolvedBaseBranch);
+                const batchResults = await executeBatch(batch, batchCtx);
                 results.push(...batchResults);
                 // Check if batch failed and we should stop
                 const batchFailed = batchResults.some((r) => !r.success);
@@ -380,28 +460,14 @@ export async function runCommand(issues, options) {
             // Sequential execution
             for (let i = 0; i < issueNumbers.length; i++) {
                 const issueNumber = issueNumbers[i];
-                const issueInfo = issueInfoMap.get(issueNumber) ?? {
-                    title: `Issue #${issueNumber}`,
-                    labels: [],
-                };
-                const worktreeInfo = worktreeMap.get(issueNumber);
-                // Start issue logging
-                if (logWriter) {
-                    logWriter.startIssue(issueNumber, issueInfo.title, issueInfo.labels);
-                }
-                const result = await runIssueWithLogging(issueNumber, config, logWriter, stateManager, issueInfo.title, issueInfo.labels, mergedOptions, worktreeInfo?.path, worktreeInfo?.branch, shutdown, mergedOptions.chain, // Enable checkpoint commits in chain mode
-                manifest.packageManager, 
-                // In chain mode, only the last issue should trigger pre-PR rebase
-                mergedOptions.chain ? i === issueNumbers.length - 1 : undefined, resolvedBaseBranch);
+                const result = await executeOneIssue({
+                    issueNumber,
+                    batchCtx,
+                    chain: mergedOptions.chain
+                        ? { enabled: true, isLast: i === issueNumbers.length - 1 }
+                        : undefined,
+                });
                 results.push(result);
-                // Record PR info in log before completing issue
-                if (logWriter && result.prNumber && result.prUrl) {
-                    logWriter.setPRInfo(result.prNumber, result.prUrl);
-                }
-                // Complete issue logging
-                if (logWriter) {
-                    logWriter.completeIssue();
-                }
                 // Check if shutdown was triggered
                 if (shutdown.shuttingDown) {
                     break;
@@ -435,32 +501,135 @@ export async function runCommand(issues, options) {
             }
         }
         else {
-            // Default mode: run issues serially but continue on failure (don't stop)
-            // TODO: Add proper parallel execution with listr2
-            for (const issueNumber of issueNumbers) {
-                // Check if shutdown was triggered
-                if (shutdown.shuttingDown) {
-                    break;
+            // Default mode: run issues concurrently with configurable concurrency limit
+            const limit = pLimit(config.concurrency);
+            // Track progress for concurrent issues
+            const issueStatus = new Map();
+            for (const num of issueNumbers) {
+                issueStatus.set(num, { state: "running" });
+            }
+            const renderProgressLine = () => {
+                const parts = issueNumbers.map((num) => {
+                    const info = issueStatus.get(num);
+                    if (info.state === "done")
+                        return colors.success(`#${num} ✓`);
+                    if (info.state === "failed")
+                        return colors.error(`#${num} ✗`);
+                    return colors.warning(`#${num} ⏳`);
+                });
+                return `  Progress: ${parts.join("  ")}`;
+            };
+            const updateProgress = (completedIssue) => {
+                if (mergedOptions.quiet)
+                    return;
+                if (process.stdout.isTTY) {
+                    // TTY: overwrite the progress line in place
+                    process.stdout.write(`\r${renderProgressLine()}`);
                 }
-                const issueInfo = issueInfoMap.get(issueNumber) ?? {
-                    title: `Issue #${issueNumber}`,
-                    labels: [],
-                };
-                const worktreeInfo = worktreeMap.get(issueNumber);
-                // Start issue logging
-                if (logWriter) {
-                    logWriter.startIssue(issueNumber, issueInfo.title, issueInfo.labels);
+                // Print a per-issue completion summary (works on both TTY and non-TTY)
+                if (completedIssue != null) {
+                    const info = issueStatus.get(completedIssue);
+                    const duration = info.durationSeconds != null
+                        ? ` (${formatElapsedTime(info.durationSeconds)})`
+                        : "";
+                    if (info.state === "done") {
+                        const line = `  ${colors.success("✓")} Issue #${completedIssue} completed${duration}`;
+                        if (process.stdout.isTTY) {
+                            // Move to a new line before printing the summary, then re-render progress
+                            process.stdout.write(`\n${line}\n${renderProgressLine()}`);
+                        }
+                        else {
+                            console.log(line);
+                        }
+                    }
+                    else {
+                        const errorSuffix = info.error ? `: ${info.error}` : "";
+                        const line = `  ${colors.error("✗")} Issue #${completedIssue} failed${duration}${errorSuffix}`;
+                        if (process.stdout.isTTY) {
+                            process.stdout.write(`\n${line}\n${renderProgressLine()}`);
+                        }
+                        else {
+                            console.log(line);
+                        }
+                    }
                 }
-                const result = await runIssueWithLogging(issueNumber, config, logWriter, stateManager, issueInfo.title, issueInfo.labels, mergedOptions, worktreeInfo?.path, worktreeInfo?.branch, shutdown, false, // Parallel mode doesn't support chain
-                manifest.packageManager, undefined, resolvedBaseBranch);
-                results.push(result);
-                // Record PR info in log before completing issue
-                if (logWriter && result.prNumber && result.prUrl) {
-                    logWriter.setPRInfo(result.prNumber, result.prUrl);
+            };
+            // Per-phase progress callback for parallel mode (AC-1, AC-3)
+            const parallelStartTime = Date.now();
+            const onPhaseProgress = (issue, phase, event, extra) => {
+                if (mergedOptions.quiet)
+                    return;
+                let line;
+                if (event === "start") {
+                    line = `  ${colors.warning("●")} #${issue}: ${phase} started`;
                 }
-                // Complete issue logging
-                if (logWriter) {
-                    logWriter.completeIssue();
+                else if (event === "complete") {
+                    const dur = extra?.durationSeconds != null
+                        ? ` (${formatElapsedTime(extra.durationSeconds)})`
+                        : "";
+                    line = `  ${colors.success("●")} #${issue}: ${phase} ✓${dur}`;
+                }
+                else {
+                    line = `  ${colors.error("●")} #${issue}: ${phase} ✗`;
+                }
+                console.log(line);
+            };
+            // 60-second heartbeat timer so the terminal never appears frozen (AC-2)
+            const HEARTBEAT_INTERVAL_MS = 60_000;
+            const heartbeatTimer = setInterval(() => {
+                if (mergedOptions.quiet)
+                    return;
+                const elapsedSec = Math.round((Date.now() - parallelStartTime) / 1000);
+                console.log(`  ${colors.warning("⏳")} Still running... (${formatElapsedTime(elapsedSec)} elapsed)`);
+            }, HEARTBEAT_INTERVAL_MS);
+            updateProgress();
+            const settledResults = await Promise.allSettled(issueNumbers.map((issueNumber) => limit(async () => {
+                // Check if shutdown was triggered before starting
+                if (shutdown.shuttingDown) {
+                    return {
+                        issueNumber,
+                        success: false,
+                        phaseResults: [],
+                        durationSeconds: 0,
+                        loopTriggered: false,
+                    };
+                }
+                const result = await executeOneIssue({
+                    issueNumber,
+                    batchCtx: { ...batchCtx, onProgress: onPhaseProgress },
+                    parallelIssueNumber: issueNumber,
+                });
+                // Update progress with completion details
+                issueStatus.set(issueNumber, {
+                    state: result.success ? "done" : "failed",
+                    durationSeconds: result.durationSeconds,
+                    error: result.phaseResults.find((p) => !p.success)?.error,
+                });
+                updateProgress(issueNumber);
+                return result;
+            })));
+            // Clean up heartbeat timer
+            clearInterval(heartbeatTimer);
+            // Clear the progress line
+            if (process.stdout.isTTY && !mergedOptions.quiet) {
+                process.stdout.write("\n");
+            }
+            // Collect results from settled promises
+            for (let i = 0; i < settledResults.length; i++) {
+                const settled = settledResults[i];
+                if (settled.status === "fulfilled") {
+                    results.push(settled.value);
+                }
+                else {
+                    // Defensive fallback — runIssueWithLogging catches errors internally,
+                    // so this path is unreachable in normal operation.
+                    results.push({
+                        issueNumber: issueNumbers[i],
+                        success: false,
+                        phaseResults: [],
+                        durationSeconds: 0,
+                        loopTriggered: false,
+                    });
                 }
             }
         }
@@ -555,9 +724,7 @@ export async function runCommand(issues, options) {
             }
             catch (metricsError) {
                 // Metrics recording errors shouldn't stop execution
-                if (config.verbose) {
-                    console.log(chalk.yellow(`  ⚠️  Metrics recording error: ${metricsError}`));
-                }
+                logNonFatalWarning(`  ⚠️  Metrics recording failed, continuing...`, metricsError, config.verbose);
             }
         }
         // Summary

package/dist/src/commands/serve.d.ts

@@ -0,0 +1,13 @@
+/**
+ * sequant serve - Start MCP server
+ *
+ * Exposes Sequant workflow orchestration as tools and resources
+ * over the Model Context Protocol (MCP).
+ *
+ * Supports stdio (default) and SSE transports.
+ */
+export interface ServeOptions {
+    transport?: "stdio" | "sse";
+    port?: number;
+}
+export declare function serveCommand(options: ServeOptions): Promise<void>;

package/dist/src/commands/serve.js

@@ -0,0 +1,131 @@
+/**
+ * sequant serve - Start MCP server
+ *
+ * Exposes Sequant workflow orchestration as tools and resources
+ * over the Model Context Protocol (MCP).
+ *
+ * Supports stdio (default) and SSE transports.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { createServer as createHttpServer, } from "http";
+import { createServer } from "../mcp/server.js";
+import { getVersion } from "../lib/version.js";
+export async function serveCommand(options) {
+    const version = getVersion();
+    const server = createServer(version);
+    const transportType = options.transport || "stdio";
+    if (transportType === "sse") {
+        await startSSE(server, options.port || 3100);
+    }
+    else {
+        await startStdio(server);
+    }
+}
+async function startStdio(server) {
+    const transport = new StdioServerTransport();
+    // Handle graceful shutdown
+    let shuttingDown = false;
+    const shutdown = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        try {
+            await server.close();
+        }
+        catch {
+            /* best-effort */
+        }
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    await server.connect(transport);
+    // Write startup info to stderr (stdout is for MCP protocol)
+    process.stderr.write(`Sequant MCP server started (stdio)\n`);
+}
+async function startSSE(server, port) {
+    let sseTransport = null;
+    let clientConnected = false;
+    const httpServer = createHttpServer(async (req, res) => {
+        const url = new URL(req.url || "/", `http://localhost:${port}`);
+        if (url.pathname === "/sse" && req.method === "GET") {
+            // Reject if a client is already connected
+            if (clientConnected) {
+                res.writeHead(409, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    error: "conflict",
+                    message: "Another SSE client is already connected",
+                }));
+                return;
+            }
+            // SSE endpoint - create transport and connect
+            sseTransport = new SSEServerTransport("/messages", res);
+            clientConnected = true;
+            // Clean up on client disconnect
+            res.on("close", () => {
+                clientConnected = false;
+                sseTransport = null;
+            });
+            try {
+                await server.connect(sseTransport);
+            }
+            catch {
+                clientConnected = false;
+                sseTransport = null;
+                if (!res.headersSent) {
+                    res.writeHead(500, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({
+                        error: "connection_failed",
+                        message: "Failed to establish MCP transport connection",
+                    }));
+                }
+            }
+        }
+        else if (url.pathname === "/messages" &&
+            req.method === "POST" &&
+            sseTransport) {
+            // Message endpoint for client-to-server communication
+            await sseTransport.handlePostMessage(req, res);
+        }
+        else if (url.pathname === "/health" && req.method === "GET") {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                status: "ok",
+                transport: "sse",
+                connected: clientConnected,
+            }));
+        }
+        else {
+            res.writeHead(404);
+            res.end("Not found");
+        }
+    });
+    // Handle graceful shutdown
+    let shuttingDown = false;
+    const shutdown = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        try {
+            await server.close();
+        }
+        catch {
+            /* best-effort */
+        }
+        try {
+            await new Promise((resolve) => httpServer.close(() => resolve()));
+        }
+        catch {
+            /* best-effort */
+        }
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    httpServer.listen(port, "127.0.0.1", () => {
+        console.log(`Sequant MCP server started (SSE) on 127.0.0.1:${port}`);
+        console.log(`  SSE endpoint: http://127.0.0.1:${port}/sse`);
+        console.log(`  Health check: http://127.0.0.1:${port}/health`);
+    });
+}

package/dist/src/commands/stats.d.ts

@@ -8,6 +8,7 @@ interface StatsOptions {
     path?: string;
     csv?: boolean;
     json?: boolean;
+    detailed?: boolean;
 }
 /**
  * Main stats command