sequant 1.20.3 → 2.0.1

package/dist/src/lib/workflow/batch-executor.js

@@ -10,11 +10,63 @@
 import chalk from "chalk";
 import { spawnSync } from "child_process";
 import { createPhaseLogFromTiming } from "./log-writer.js";
+import { classifyError } from "./error-classifier.js";
 import { PhaseSpinner } from "../phase-spinner.js";
 import { getGitDiffStats, getCommitHash } from "./git-diff-utils.js";
 import { createCheckpointCommit, rebaseBeforePR, createPR, readCacheMetrics, filterResumedPhases, } from "./worktree-manager.js";
 import { executePhaseWithRetry } from "./phase-executor.js";
-import { detectPhasesFromLabels, parseRecommendedWorkflow, determinePhasesForIssue, BUG_LABELS, } from "./phase-mapper.js";
+import { detectPhasesFromLabels, parseRecommendedWorkflow, determinePhasesForIssue, BUG_LABELS, DOCS_LABELS, } from "./phase-mapper.js";
+/**
+ * Emit a structured progress line to stderr for MCP progress notifications.
+ * Only emits when running under an orchestrator (e.g., MCP server).
+ * The MCP handler parses these lines to send `notifications/progress`.
+ *
+ * @param issue - GitHub issue number
+ * @param phase - Phase name (e.g., "spec", "exec", "qa")
+ * @param event - Phase lifecycle event: "start", "complete", or "failed"
+ * @param extra - Optional fields: durationSeconds (on complete), error (on failed)
+ */
+/**
+ * Build enriched prompt context for the /loop phase from a failed phase result (#488).
+ * Passes QA verdict, failed ACs, and error directly so the /loop skill doesn't need
+ * to reconstruct context from GitHub comments (which fails in subprocess).
+ *
+ * @internal Exported for testing only
+ */
+export function buildLoopContext(failedResult) {
+    const parts = [`Previous phase "${failedResult.phase}" failed.`];
+    if (failedResult.verdict) {
+        parts.push(`QA Verdict: ${failedResult.verdict}`);
+    }
+    if (failedResult.summary?.gaps?.length) {
+        parts.push(`QA Gaps:\n${failedResult.summary.gaps.map((gap) => `- ${gap}`).join("\n")}`);
+    }
+    if (failedResult.summary?.suggestions?.length) {
+        parts.push(`Suggestions:\n${failedResult.summary.suggestions.map((s) => `- ${s}`).join("\n")}`);
+    }
+    if (failedResult.error) {
+        parts.push(`Error: ${failedResult.error}`);
+    }
+    // Include tail of output for additional context (truncated to avoid prompt bloat)
+    if (failedResult.output) {
+        const tail = failedResult.output.slice(-2000);
+        parts.push(`Last output:\n${tail}`);
+    }
+    return parts.join("\n\n");
+}
+export function emitProgressLine(issue, phase, event = "start", extra) {
+    if (!process.env.SEQUANT_ORCHESTRATOR)
+        return;
+    const payload = { issue, phase, event };
+    if (extra?.durationSeconds !== undefined) {
+        payload.durationSeconds = extra.durationSeconds;
+    }
+    if (extra?.error !== undefined) {
+        payload.error = extra.error;
+    }
+    const line = `SEQUANT_PROGRESS:${JSON.stringify(payload)}\n`;
+    process.stderr.write(line);
+}
 export async function getIssueInfo(issueNumber) {
     try {
         const result = spawnSync("gh", ["issue", "view", String(issueNumber), "--json", "title,labels"], { stdio: "pipe" });
@@ -95,8 +147,8 @@ export function sortByDependencies(issueNumbers) {
         }
     }
     // Note: inDegree counts how many issues depend on each issue
-    // We want to process issues that nothing depends on last
-    // So we sort by: issues nothing depends on first, then dependent issues
+    // We want to process issues that have no dependencies first,
+    // so dependent issues come after their prerequisites
     const sorted = [];
     const queue = [];
     // Start with issues that have no dependencies
@@ -163,7 +215,8 @@ export function getEnvConfig() {
     }
     return config;
 }
-export async function executeBatch(issueNumbers, config, logWriter, stateManager, options, issueInfoMap, worktreeMap, shutdownManager, packageManager, baseBranch) {
+export async function executeBatch(issueNumbers, batchCtx) {
+    const { config, options, issueInfoMap, worktreeMap, logWriter, stateManager, shutdownManager, packageManager, baseBranch, onProgress, } = batchCtx;
     const results = [];
     for (const issueNumber of issueNumbers) {
         // Check if shutdown was triggered
@@ -179,8 +232,21 @@ export async function executeBatch(issueNumbers, config, logWriter, stateManager
         if (logWriter) {
             logWriter.startIssue(issueNumber, issueInfo.title, issueInfo.labels);
         }
-        const result = await runIssueWithLogging(issueNumber, config, logWriter, stateManager, issueInfo.title, issueInfo.labels, options, worktreeInfo?.path, worktreeInfo?.branch, shutdownManager, false, // Batch mode doesn't support chain
-        packageManager, undefined, baseBranch);
+        const ctx = {
+            issueNumber,
+            title: issueInfo.title,
+            labels: issueInfo.labels,
+            config,
+            options,
+            services: { logWriter, stateManager, shutdownManager },
+            worktree: worktreeInfo
+                ? { path: worktreeInfo.path, branch: worktreeInfo.branch }
+                : undefined,
+            packageManager,
+            baseBranch,
+            onProgress,
+        };
+        const result = await runIssueWithLogging(ctx);
         results.push(result);
         // Record PR info in log before completing issue
         if (logWriter && result.prNumber && result.prUrl) {
@@ -193,14 +259,23 @@ export async function executeBatch(issueNumbers, config, logWriter, stateManager
     }
     return results;
 }
-export async function runIssueWithLogging(issueNumber, config, logWriter, stateManager, issueTitle, labels, options, worktreePath, branch, shutdownManager, chainMode, packageManager, isLastInChain, baseBranch) {
+export async function runIssueWithLogging(ctx) {
+    // Destructure context for use throughout the function
+    const { issueNumber, config, options, title: issueTitle, labels, services: { logWriter, stateManager, shutdownManager }, worktree, chain, packageManager, baseBranch, onProgress, } = ctx;
+    const worktreePath = worktree?.path;
+    const branch = worktree?.branch;
+    const chainMode = chain?.enabled;
+    const isLastInChain = chain?.isLast;
     const startTime = Date.now();
     const phaseResults = [];
     let loopTriggered = false;
     let sessionId;
-    console.log(chalk.blue(`\n  Issue #${issueNumber}`));
+    // In parallel mode, suppress per-issue terminal output to prevent interleaving.
+    // The caller (run.ts) handles progress display via updateProgress().
+    const log = config.parallel ? () => { } : console.log.bind(console);
+    log(chalk.blue(`\n  Issue #${issueNumber}`));
     if (worktreePath) {
-        console.log(chalk.gray(`    Worktree: ${worktreePath}`));
+        log(chalk.gray(`    Worktree: ${worktreePath}`));
     }
     // Initialize state tracking for this issue
     if (stateManager) {
@@ -224,7 +299,7 @@ export async function runIssueWithLogging(issueNumber, config, logWriter, stateM
         catch (error) {
             // State tracking errors shouldn't stop execution
             if (config.verbose) {
-                console.log(chalk.yellow(`    ⚠️  State tracking error: ${error}`));
+                log(chalk.yellow(`    ⚠️  State tracking error: ${error}`));
             }
         }
     }
@@ -235,23 +310,39 @@ export async function runIssueWithLogging(issueNumber, config, logWriter, stateM
     if (options.autoDetectPhases) {
         // Check if labels indicate a simple bug/fix (skip spec entirely)
         const lowerLabels = labels.map((l) => l.toLowerCase());
-        const isSimpleBugFix = lowerLabels.some((label) => BUG_LABELS.some((bugLabel) => label.includes(bugLabel)));
+        const isSimpleBugFix = lowerLabels.some((label) => BUG_LABELS.some((bugLabel) => label === bugLabel));
+        // Check if labels indicate documentation-only work (skip spec)
+        const isDocs = lowerLabels.some((label) => DOCS_LABELS.some((docsLabel) => label === docsLabel));
         if (isSimpleBugFix) {
             // Simple bug fix: skip spec, go straight to exec → qa
             phases = ["exec", "qa"];
-            console.log(chalk.gray(`    Bug fix detected: ${phases.join(" → ")}`));
+            log(chalk.gray(`    Bug fix detected: ${phases.join(" → ")}`));
+        }
+        else if (isDocs) {
+            // Documentation issue: skip spec, lighter pipeline
+            phases = ["exec", "qa"];
+            log(chalk.gray(`    Docs issue detected: ${phases.join(" → ")}`));
         }
         else {
             // Run spec first to get recommended workflow
-            console.log(chalk.gray(`    Running spec to determine workflow...`));
-            // Create spinner for spec phase (1 of estimated 3: spec, exec, qa)
-            const specSpinner = new PhaseSpinner({
-                phase: "spec",
-                phaseIndex: 1,
-                totalPhases: 3, // Estimate; will be refined after spec
-                shutdownManager,
-            });
-            specSpinner.start();
+            log(chalk.gray(`    Running spec to determine workflow...`));
+            // Create spinner for spec phase (suppressed in parallel mode to prevent interleaving)
+            const specSpinner = config.parallel
+                ? undefined
+                : new PhaseSpinner({
+                    phase: "spec",
+                    phaseIndex: 1,
+                    totalPhases: 3, // Estimate; will be refined after spec
+                    shutdownManager,
+                });
+            specSpinner?.start();
+            emitProgressLine(issueNumber, "spec", "start");
+            try {
+                onProgress?.(issueNumber, "spec", "start");
+            }
+            catch {
+                /* progress errors must not halt */
+            }
             // Track spec phase start in state
             if (stateManager) {
                 try {
@@ -280,14 +371,46 @@ export async function runIssueWithLogging(issueNumber, config, logWriter, stateM
             }
             phaseResults.push(specResult);
             specAlreadyRan = true;
+            // Emit completion/failure progress event (AC-8)
+            const specDurationSec = Math.round((specEndTime.getTime() - specStartTime.getTime()) / 1000);
+            if (specResult.success) {
+                const extra = { durationSeconds: specDurationSec };
+                emitProgressLine(issueNumber, "spec", "complete", extra);
+                try {
+                    onProgress?.(issueNumber, "spec", "complete", extra);
+                }
+                catch {
+                    /* progress errors must not halt */
+                }
+            }
+            else {
+                const extra = { error: specResult.error ?? "unknown" };
+                emitProgressLine(issueNumber, "spec", "failed", extra);
+                try {
+                    onProgress?.(issueNumber, "spec", "failed", extra);
+                }
+                catch {
+                    /* progress errors must not halt */
+                }
+            }
             // Log spec phase result
             // Note: Spec runs in main repo, not worktree, so no git diff stats
             if (logWriter) {
+                // Build errorContext from captured stderr/stdout tails (#447)
+                let specErrorContext;
+                if (!specResult.success && specResult.stderrTail) {
+                    specErrorContext = {
+                        stderrTail: specResult.stderrTail ?? [],
+                        stdoutTail: specResult.stdoutTail ?? [],
+                        exitCode: specResult.exitCode,
+                        category: classifyError(specResult.stderrTail ?? []),
+                    };
+                }
                 const phaseLog = createPhaseLogFromTiming("spec", issueNumber, specStartTime, specEndTime, specResult.success
                     ? "success"
                     : specResult.error?.includes("Timeout")
                         ? "timeout"
-                        : "failure", { error: specResult.error });
+                        : "failure", { error: specResult.error, errorContext: specErrorContext });
                 logWriter.logPhase(phaseLog);
             }
             // Track spec phase completion in state
@@ -303,7 +426,7 @@ export async function runIssueWithLogging(issueNumber, config, logWriter, stateM
                 }
             }
             if (!specResult.success) {
-                specSpinner.fail(specResult.error);
+                specSpinner?.fail(specResult.error);
                 const durationSeconds = (Date.now() - startTime) / 1000;
                 return {
                     issueNumber,
@@ -313,7 +436,7 @@ export async function runIssueWithLogging(issueNumber, config, logWriter, stateM
                     loopTriggered: false,
                 };
             }
-            specSpinner.succeed();
+            specSpinner?.succeed();
             // Parse recommended workflow from spec output
             const parsedWorkflow = specResult.output
                 ? parseRecommendedWorkflow(specResult.output)
@@ -322,15 +445,15 @@ export async function runIssueWithLogging(issueNumber, config, logWriter, stateM
                 // Remove spec from phases since we already ran it
                 phases = parsedWorkflow.phases.filter((p) => p !== "spec");
                 detectedQualityLoop = parsedWorkflow.qualityLoop;
-                console.log(chalk.gray(`    Spec recommends: ${phases.join(" → ")}${detectedQualityLoop ? " (quality loop)" : ""}`));
+                log(chalk.gray(`    Spec recommends: ${phases.join(" → ")}${detectedQualityLoop ? " (quality loop)" : ""}`));
             }
             else {
                 // Fall back to label-based detection
-                console.log(chalk.yellow(`    Could not parse spec recommendation, using label-based detection`));
+                log(chalk.yellow(`    Could not parse spec recommendation, using label-based detection`));
                 const detected = detectPhasesFromLabels(labels);
                 phases = detected.phases.filter((p) => p !== "spec");
                 detectedQualityLoop = detected.qualityLoop;
-                console.log(chalk.gray(`    Fallback: ${phases.join(" → ")}`));
+                log(chalk.gray(`    Fallback: ${phases.join(" → ")}`));
             }
         }
     }
@@ -338,21 +461,21 @@ export async function runIssueWithLogging(issueNumber, config, logWriter, stateM
         // Use explicit phases with adjustments
         phases = determinePhasesForIssue(config.phases, labels, options);
         if (phases.length !== config.phases.length) {
-            console.log(chalk.gray(`    Phases adjusted: ${phases.join(" → ")}`));
+            log(chalk.gray(`    Phases adjusted: ${phases.join(" → ")}`));
         }
     }
     // Resume: filter out completed phases if --resume flag is set
     if (options.resume) {
         const resumeResult = filterResumedPhases(issueNumber, phases, true);
         if (resumeResult.skipped.length > 0) {
-            console.log(chalk.gray(`    Resume: skipping completed phases: ${resumeResult.skipped.join(", ")}`));
+            log(chalk.gray(`    Resume: skipping completed phases: ${resumeResult.skipped.join(", ")}`));
             phases = resumeResult.phases;
         }
         // Also skip spec if it was auto-detected as completed
         if (specAlreadyRan &&
             resumeResult.skipped.length === 0 &&
             resumeResult.phases.length === 0) {
-            console.log(chalk.gray(`    Resume: all phases already completed`));
+            log(chalk.gray(`    Resume: all phases already completed`));
         }
     }
     // Add testgen phase if requested (and spec was in the phases)
@@ -370,6 +493,12 @@ export async function runIssueWithLogging(issueNumber, config, logWriter, stateM
             }
         }
     }
+    // Build per-issue config with issue type metadata for skill env propagation
+    const lowerLabelsForType = labels.map((l) => l.toLowerCase());
+    const issueIsDocs = lowerLabelsForType.some((label) => DOCS_LABELS.some((docsLabel) => label === docsLabel));
+    const issueConfig = issueIsDocs
+        ? { ...config, issueType: "docs" }
+        : config;
     let iteration = 0;
     const useQualityLoop = config.qualityLoop || detectedQualityLoop;
     const maxIterations = useQualityLoop ? config.maxIterations : 1;
@@ -377,7 +506,7 @@ export async function runIssueWithLogging(issueNumber, config, logWriter, stateM
     while (iteration < maxIterations) {
         iteration++;
         if (useQualityLoop && iteration > 1) {
-            console.log(chalk.yellow(`    Quality loop iteration ${iteration}/${maxIterations}`));
+            log(chalk.yellow(`    Quality loop iteration ${iteration}/${maxIterations}`));
             loopTriggered = true;
         }
         let phasesFailed = false;
@@ -388,15 +517,24 @@ export async function runIssueWithLogging(issueNumber, config, logWriter, stateM
         for (let phaseIdx = 0; phaseIdx < phases.length; phaseIdx++) {
             const phase = phases[phaseIdx];
             const phaseNumber = phaseIdx + 1 + phaseIndexOffset;
-            // Create spinner for this phase
-            const phaseSpinner = new PhaseSpinner({
-                phase,
-                phaseIndex: phaseNumber,
-                totalPhases,
-                shutdownManager,
-                iteration: useQualityLoop ? iteration : undefined,
-            });
-            phaseSpinner.start();
+            // Create spinner for this phase (suppressed in parallel mode)
+            const phaseSpinner = config.parallel
+                ? undefined
+                : new PhaseSpinner({
+                    phase,
+                    phaseIndex: phaseNumber,
+                    totalPhases,
+                    shutdownManager,
+                    iteration: useQualityLoop ? iteration : undefined,
+                });
+            phaseSpinner?.start();
+            emitProgressLine(issueNumber, phase, "start");
+            try {
+                onProgress?.(issueNumber, phase, "start");
+            }
+            catch {
+                /* progress errors must not halt */
+            }
             // Track phase start in state
             if (stateManager) {
                 try {
@@ -407,7 +545,7 @@ export async function runIssueWithLogging(issueNumber, config, logWriter, stateM
                 }
             }
             const phaseStartTime = new Date();
-            const result = await executePhaseWithRetry(issueNumber, phase, config, sessionId, worktreePath, shutdownManager, phaseSpinner);
+            const result = await executePhaseWithRetry(issueNumber, phase, issueConfig, sessionId, worktreePath, shutdownManager, phaseSpinner);
             const phaseEndTime = new Date();
             // Capture session ID for subsequent phases
             if (result.sessionId) {
@@ -423,6 +561,28 @@ export async function runIssueWithLogging(issueNumber, config, logWriter, stateM
                 }
             }
             phaseResults.push(result);
+            // Emit completion/failure progress event (AC-8)
+            const phaseDurationSec = Math.round((phaseEndTime.getTime() - phaseStartTime.getTime()) / 1000);
+            if (result.success) {
+                const extra = { durationSeconds: phaseDurationSec };
+                emitProgressLine(issueNumber, phase, "complete", extra);
+                try {
+                    onProgress?.(issueNumber, phase, "complete", extra);
+                }
+                catch {
+                    /* progress errors must not halt */
+                }
+            }
+            else {
+                const extra = { error: result.error ?? "unknown" };
+                emitProgressLine(issueNumber, phase, "failed", extra);
+                try {
+                    onProgress?.(issueNumber, phase, "failed", extra);
+                }
+                catch {
+                    /* progress errors must not halt */
+                }
+            }
             // Log phase result with observability data (AC-1, AC-2, AC-3, AC-7)
             if (logWriter) {
                 // Capture git diff stats for worktree phases (AC-1, AC-3)
@@ -435,6 +595,16 @@ export async function runIssueWithLogging(issueNumber, config, logWriter, stateM
                     : undefined;
                 // Read cache metrics for QA phase (AC-7)
                 const cacheMetrics = phase === "qa" ? readCacheMetrics(worktreePath) : undefined;
+                // Build errorContext from captured stderr/stdout tails (#447)
+                let errorContext;
+                if (!result.success && result.stderrTail) {
+                    errorContext = {
+                        stderrTail: result.stderrTail ?? [],
+                        stdoutTail: result.stdoutTail ?? [],
+                        exitCode: result.exitCode,
+                        category: classifyError(result.stderrTail ?? []),
+                    };
+                }
                 const phaseLog = createPhaseLogFromTiming(phase, issueNumber, phaseStartTime, phaseEndTime, result.success
                     ? "success"
                     : result.error?.includes("Timeout")
@@ -442,11 +612,13 @@ export async function runIssueWithLogging(issueNumber, config, logWriter, stateM
                         : "failure", {
                     error: result.error,
                     verdict: result.verdict,
+                    summary: result.summary,
                     // Observability fields (AC-1, AC-2, AC-3, AC-7)
                     filesModified: diffStats?.filesModified,
                     fileDiffStats: diffStats?.fileDiffStats,
                     commitHash,
                     cacheMetrics,
+                    errorContext,
                 });
                 logWriter.logPhase(phaseLog);
             }
@@ -465,34 +637,76 @@ export async function runIssueWithLogging(issueNumber, config, logWriter, stateM
                 }
             }
             if (result.success) {
-                phaseSpinner.succeed();
+                phaseSpinner?.succeed();
             }
             else {
-                phaseSpinner.fail(result.error);
+                phaseSpinner?.fail(result.error);
                 phasesFailed = true;
                 // If quality loop enabled, run loop phase to fix issues
                 if (useQualityLoop && iteration < maxIterations) {
-                    // Create spinner for loop phase
-                    const loopSpinner = new PhaseSpinner({
-                        phase: "loop",
-                        phaseIndex: phaseNumber,
-                        totalPhases,
-                        shutdownManager,
-                        iteration,
-                    });
-                    loopSpinner.start();
-                    const loopResult = await executePhaseWithRetry(issueNumber, "loop", config, sessionId, worktreePath, shutdownManager, loopSpinner);
+                    // Create spinner for loop phase (suppressed in parallel mode)
+                    const loopSpinner = config.parallel
+                        ? undefined
+                        : new PhaseSpinner({
+                            phase: "loop",
+                            phaseIndex: phaseNumber,
+                            totalPhases,
+                            shutdownManager,
+                            iteration,
+                        });
+                    loopSpinner?.start();
+                    emitProgressLine(issueNumber, "loop", "start");
+                    try {
+                        onProgress?.(issueNumber, "loop", "start");
+                    }
+                    catch {
+                        /* progress errors must not halt */
+                    }
+                    // Build enriched config for loop phase with QA context (#488).
+                    // Pass verdict, failed ACs, and error directly so the /loop skill
+                    // doesn't need to reconstruct context from GitHub comments.
+                    const loopConfig = {
+                        ...issueConfig,
+                        lastVerdict: result.verdict ?? undefined,
+                        failedAcs: result.summary?.gaps?.join("; ") ?? undefined,
+                        promptContext: buildLoopContext(result),
+                    };
+                    const loopStartTime = new Date();
+                    const loopResult = await executePhaseWithRetry(issueNumber, "loop", loopConfig, sessionId, worktreePath, shutdownManager, loopSpinner);
+                    const loopEndTime = new Date();
                     phaseResults.push(loopResult);
+                    // Emit loop completion/failure progress event (AC-8)
+                    const loopDurationSec = Math.round((loopEndTime.getTime() - loopStartTime.getTime()) / 1000);
+                    if (loopResult.success) {
+                        const extra = { durationSeconds: loopDurationSec };
+                        emitProgressLine(issueNumber, "loop", "complete", extra);
+                        try {
+                            onProgress?.(issueNumber, "loop", "complete", extra);
+                        }
+                        catch {
+                            /* progress errors must not halt */
+                        }
+                    }
+                    else {
+                        const extra = { error: loopResult.error ?? "unknown" };
+                        emitProgressLine(issueNumber, "loop", "failed", extra);
+                        try {
+                            onProgress?.(issueNumber, "loop", "failed", extra);
+                        }
+                        catch {
+                            /* progress errors must not halt */
+                        }
+                    }
                     if (loopResult.sessionId) {
                         sessionId = loopResult.sessionId;
                     }
                     if (loopResult.success) {
-                        loopSpinner.succeed();
+                        loopSpinner?.succeed();
                         // Continue to next iteration
                         break;
                     }
                     else {
-                        loopSpinner.fail(loopResult.error);
+                        loopSpinner?.fail(loopResult.error);
                     }
                 }
                 // Stop on first failure (if not in quality loop or loop failed)

package/dist/src/lib/workflow/drivers/agent-driver.d.ts

@@ -0,0 +1,56 @@
+/**
+ * AgentDriver interface — decouples workflow orchestration from agent execution.
+ *
+ * Claude Code is the default implementation; alternatives (Aider, Codex CLI,
+ * Continue.dev, Copilot SDK, Cursor API) can be added by implementing this
+ * interface without touching orchestration logic.
+ */
+/**
+ * Configuration passed to an agent for phase execution.
+ */
+export interface AgentExecutionConfig {
+    cwd: string;
+    env: Record<string, string>;
+    abortSignal?: AbortSignal;
+    phaseTimeout: number;
+    verbose: boolean;
+    mcp: boolean;
+    /** Resume a previous session (driver-specific; ignored if unsupported) */
+    sessionId?: string;
+    /** Callback for streaming output */
+    onOutput?: (text: string) => void;
+    /** Callback for stderr */
+    onStderr?: (text: string) => void;
+    /** Relevant files for the phase (used by file-oriented drivers like Aider) */
+    files?: string[];
+}
+/**
+ * Result returned by an agent after executing a phase.
+ */
+export interface AgentPhaseResult {
+    success: boolean;
+    output: string;
+    sessionId?: string;
+    error?: string;
+    /** Last N lines of stderr captured via RingBuffer (#447) */
+    stderrTail?: string[];
+    /** Last N lines of stdout captured via RingBuffer (#447) */
+    stdoutTail?: string[];
+    /** Process exit code (undefined for SDK-based drivers) (#447) */
+    exitCode?: number;
+}
+/**
+ * Interface that all agent backends must implement.
+ *
+ * The driver is responsible for executing a prompt and returning
+ * a structured result. Parsing (QA verdicts, etc.) stays in
+ * phase-executor.ts — the driver just captures text.
+ */
+export interface AgentDriver {
+    /** Human-readable name for logging */
+    name: string;
+    /** Execute a phase prompt and return structured result */
+    executePhase(prompt: string, config: AgentExecutionConfig): Promise<AgentPhaseResult>;
+    /** Check if this driver is available/configured */
+    isAvailable(): Promise<boolean>;
+}

package/dist/src/lib/workflow/drivers/agent-driver.js

@@ -0,0 +1,8 @@
+/**
+ * AgentDriver interface — decouples workflow orchestration from agent execution.
+ *
+ * Claude Code is the default implementation; alternatives (Aider, Codex CLI,
+ * Continue.dev, Copilot SDK, Cursor API) can be added by implementing this
+ * interface without touching orchestration logic.
+ */
+export {};

package/dist/src/lib/workflow/drivers/aider.d.ts

@@ -0,0 +1,18 @@
+/**
+ * AiderDriver — AgentDriver implementation wrapping the Aider CLI.
+ *
+ * Shells out to `aider --yes --no-auto-commits --message "<prompt>"`
+ * for fully non-interactive phase execution. Sequant manages git,
+ * not Aider.
+ */
+import type { AgentDriver, AgentExecutionConfig, AgentPhaseResult } from "./agent-driver.js";
+import type { AiderSettings } from "../../settings.js";
+export declare class AiderDriver implements AgentDriver {
+    name: string;
+    private settings?;
+    constructor(settings?: AiderSettings);
+    executePhase(prompt: string, config: AgentExecutionConfig): Promise<AgentPhaseResult>;
+    isAvailable(): Promise<boolean>;
+    /** Build the CLI argument list for aider. */
+    private buildArgs;
+}