sequant 2.1.0 → 2.1.2

package/dist/src/lib/workflow/config-resolver.js

@@ -0,0 +1,167 @@
+/**
+ * ConfigResolver — 4-layer configuration merge for sequant run.
+ *
+ * Priority: defaults < settings < env < explicit (CLI flags).
+ * Handles Commander.js --no-X boolean negation at the CLI boundary.
+ *
+ * @module
+ */
+import { DEFAULT_CONFIG, DEFAULT_PHASES, } from "./types.js";
+import { getEnvConfig } from "./batch-executor.js";
+/**
+ * Coerce an env-var string to the type of the default value.
+ * Returns the string as-is if no default exists for type inference.
+ */
+function coerceEnvValue(value, defaultValue) {
+    if (typeof value !== "string")
+        return value;
+    if (typeof defaultValue === "number") {
+        const n = Number(value);
+        return isNaN(n) ? value : n;
+    }
+    if (typeof defaultValue === "boolean") {
+        return value === "true";
+    }
+    return value;
+}
+/**
+ * Generic 4-layer priority merge.
+ * For each key across all layers: explicit > env > settings > defaults.
+ * Env strings are coerced to match the type of the default value.
+ */
+export class ConfigResolver {
+    layers;
+    constructor(layers) {
+        this.layers = layers;
+    }
+    /**
+     * Resolve all layers into a single merged config object.
+     * Priority: explicit > env > settings > defaults.
+     */
+    resolve() {
+        const { defaults, settings, env, explicit } = this.layers;
+        // Collect all keys across layers
+        const allKeys = new Set([
+            ...Object.keys(defaults),
+            ...Object.keys(settings),
+            ...Object.keys(env),
+            ...Object.keys(explicit),
+        ]);
+        const result = {};
+        for (const key of allKeys) {
+            // Check each layer in reverse priority (lowest first)
+            const layers = [
+                { value: defaults[key] },
+                { value: settings[key] },
+                { value: env[key] },
+                { value: explicit[key] },
+            ];
+            // Walk from highest to lowest priority, take first defined value
+            let resolved = undefined;
+            const defaultVal = defaults[key];
+            for (const layer of layers) {
+                if (layer.value !== undefined) {
+                    resolved = layer.value;
+                }
+            }
+            // Coerce env values if the winning value came from env layer
+            if (resolved !== undefined &&
+                explicit[key] === undefined &&
+                env[key] !== undefined &&
+                settings[key] === undefined) {
+                // Only env contributed — coerce
+                resolved = coerceEnvValue(resolved, defaultVal);
+            }
+            else if (resolved !== undefined &&
+                explicit[key] === undefined &&
+                env[key] !== undefined) {
+                // env is present and wins over settings — coerce the env value
+                resolved = coerceEnvValue(env[key], defaultVal);
+            }
+            result[key] = resolved;
+        }
+        return result;
+    }
+}
+/**
+ * Normalize Commander.js --no-X flags into RunOptions negation fields.
+ * This is a thin adapter at the CLI boundary — not used by programmatic callers.
+ */
+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 }),
+    };
+}
+/**
+ * Resolve RunOptions + settings + env into a fully merged RunOptions.
+ * This replaces the inline merging logic previously in run.ts.
+ */
+export function resolveRunOptions(cliOptions, settings) {
+    const normalized = normalizeCommanderOptions(cliOptions);
+    const envConfig = getEnvConfig();
+    // Strip undefined keys so programmatic callers don't clobber env/settings values
+    const defined = Object.fromEntries(Object.entries(normalized).filter(([, v]) => v !== undefined));
+    const merged = {
+        // Settings defaults
+        sequential: defined.sequential ?? settings.run.sequential,
+        concurrency: defined.concurrency ?? settings.run.concurrency,
+        timeout: defined.timeout ?? settings.run.timeout,
+        logPath: defined.logPath ?? settings.run.logPath,
+        qualityLoop: defined.qualityLoop ?? settings.run.qualityLoop,
+        maxIterations: defined.maxIterations ?? settings.run.maxIterations,
+        noSmartTests: defined.noSmartTests ?? !settings.run.smartTests,
+        // Agent settings
+        isolateParallel: defined.isolateParallel ?? settings.agents.isolateParallel,
+        // Env overrides
+        ...envConfig,
+        // CLI explicit options override all
+        ...defined,
+    };
+    // Auto-detect phases from labels unless --phases explicitly set
+    const autoDetectPhases = !cliOptions.phases && settings.run.autoDetectPhases;
+    merged.autoDetectPhases = autoDetectPhases;
+    return merged;
+}
+/**
+ * Build an ExecutionConfig from merged RunOptions and settings.
+ * Extracts the phase-timeout, MCP, retry, and mode resolution logic
+ * that was previously inline in run.ts.
+ */
+export function buildExecutionConfig(mergedOptions, settings, issueCount) {
+    const explicitPhases = mergedOptions.phases
+        ? mergedOptions.phases.split(",").map((p) => p.trim())
+        : null;
+    const mcpEnabled = mergedOptions.noMcp
+        ? false
+        : (settings.run.mcp ?? DEFAULT_CONFIG.mcp);
+    const retryEnabled = mergedOptions.noRetry
+        ? false
+        : (settings.run.retry ?? true);
+    const isSequential = mergedOptions.sequential ?? false;
+    const isParallel = !isSequential && issueCount > 1;
+    return {
+        ...DEFAULT_CONFIG,
+        phases: explicitPhases ?? DEFAULT_PHASES,
+        sequential: isSequential,
+        concurrency: mergedOptions.concurrency ?? DEFAULT_CONFIG.concurrency,
+        parallel: isParallel,
+        dryRun: mergedOptions.dryRun ?? false,
+        verbose: mergedOptions.verbose ?? false,
+        phaseTimeout: mergedOptions.timeout ?? DEFAULT_CONFIG.phaseTimeout,
+        qualityLoop: mergedOptions.qualityLoop ?? false,
+        maxIterations: mergedOptions.maxIterations ?? DEFAULT_CONFIG.maxIterations,
+        noSmartTests: mergedOptions.noSmartTests ?? false,
+        mcp: mcpEnabled,
+        retry: retryEnabled,
+        agent: mergedOptions.agent ?? settings.run.agent,
+        aiderSettings: settings.run.aider,
+        isolateParallel: mergedOptions.isolateParallel,
+    };
+}

package/dist/src/lib/workflow/error-classifier.d.ts

@@ -1,16 +1,26 @@
 /**
  * Error classifier — categorizes phase failures from stderr content.
  *
- * Pattern-matches stderr lines against known error signatures to produce
- * a structured category for analytics and debugging.
+ * Refactored (AC-7): Returns typed SequantError instances instead of string
+ * categories. Exit codes are the primary signal; stderr patterns are secondary.
  */
-/** All recognized error categories (AC-7: defined as constants). */
+import { SequantError } from "../errors.js";
+/** All recognized error categories (kept for backwards compatibility). */
 export declare const ERROR_CATEGORIES: readonly ["context_overflow", "api_error", "hook_failure", "build_error", "timeout", "unknown"];
 export type ErrorCategory = (typeof ERROR_CATEGORIES)[number];
 /**
- * Classify stderr lines into an error category.
+ * Map from error type name to legacy category string.
+ * Used for backwards-compatible log storage (AC-8).
+ */
+export declare function errorTypeToCategory(error: SequantError): ErrorCategory;
+/**
+ * Classify stderr lines into a typed SequantError instance (AC-7).
+ *
+ * Exit codes are the primary signal; stderr patterns are secondary.
+ * Returns a typed error instance with structured metadata.
  *
- * Scans lines in order; the first classifier whose pattern matches any line wins.
- * Returns "unknown" if no patterns match.
+ * @param stderrLines - Lines from stderr
+ * @param exitCode - Process exit code (primary signal)
+ * @returns Typed SequantError subclass instance
  */
-export declare function classifyError(stderrLines: string[]): ErrorCategory;
+export declare function classifyError(stderrLines: string[], exitCode?: number): SequantError;

package/dist/src/lib/workflow/error-classifier.js

@@ -1,10 +1,11 @@
 /**
  * Error classifier — categorizes phase failures from stderr content.
  *
- * Pattern-matches stderr lines against known error signatures to produce
- * a structured category for analytics and debugging.
+ * Refactored (AC-7): Returns typed SequantError instances instead of string
+ * categories. Exit codes are the primary signal; stderr patterns are secondary.
  */
-/** All recognized error categories (AC-7: defined as constants). */
+import { ContextOverflowError, ApiError, HookFailureError, BuildError, TimeoutError, SubprocessError, } from "../errors.js";
+/** All recognized error categories (kept for backwards compatibility). */
 export const ERROR_CATEGORIES = [
     "context_overflow",
     "api_error",
@@ -13,6 +14,26 @@ export const ERROR_CATEGORIES = [
     "timeout",
     "unknown",
 ];
+/**
+ * Map from error type name to legacy category string.
+ * Used for backwards-compatible log storage (AC-8).
+ */
+export function errorTypeToCategory(error) {
+    switch (error.name) {
+        case "ContextOverflowError":
+            return "context_overflow";
+        case "ApiError":
+            return "api_error";
+        case "HookFailureError":
+            return "hook_failure";
+        case "BuildError":
+            return "build_error";
+        case "TimeoutError":
+            return "timeout";
+        default:
+            return "unknown";
+    }
+}
 /**
  * Ordered list of classifiers. First match wins (highest priority first).
  */
@@ -30,6 +51,16 @@ const CLASSIFIERS = [
     {
         category: "timeout",
         patterns: [/timeout/i, /timed?\s*out/i, /SIGTERM/, /deadline exceeded/i],
+        extract: (line) => {
+            const match = line.match(/(\d+)\s*(?:s|ms|seconds?|milliseconds?)/i);
+            if (match) {
+                const value = parseInt(match[1], 10);
+                // If the unit looks like seconds (or no unit after number), convert to ms
+                const isMs = /ms|milliseconds?/i.test(match[0]);
+                return { timeoutMs: isMs ? value : value * 1000 };
+            }
+            return {};
+        },
     },
     {
         category: "api_error",
@@ -43,6 +74,10 @@ const CLASSIFIERS = [
             /\b502\b/,
             /overloaded/i,
         ],
+        extract: (line) => {
+            const statusMatch = line.match(/\b(429|502|503|401|403)\b/);
+            return statusMatch ? { statusCode: parseInt(statusMatch[1], 10) } : {};
+        },
     },
     {
         category: "hook_failure",
@@ -52,6 +87,10 @@ const CLASSIFIERS = [
             /HOOK_BLOCKED/i,
             /blocked by hook/i,
         ],
+        extract: (line) => {
+            const hookMatch = line.match(/(?:hook|pre-?commit|HOOK_BLOCKED)[:\s]*(.{0,50})/i);
+            return hookMatch ? { hook: hookMatch[1]?.trim() || "unknown" } : {};
+        },
     },
     {
         category: "build_error",
@@ -65,26 +104,85 @@ const CLASSIFIERS = [
             /eslint/i,
             /npm ERR!/,
         ],
+        extract: (line) => {
+            if (/TS\d{4,5}:/.test(line)) {
+                const codeMatch = line.match(/(TS\d{4,5}):/);
+                return { toolchain: "tsc", errorCode: codeMatch?.[1] };
+            }
+            if (/eslint/i.test(line))
+                return { toolchain: "eslint" };
+            if (/npm ERR!/.test(line))
+                return { toolchain: "npm" };
+            return { toolchain: "unknown" };
+        },
     },
 ];
 /**
- * Classify stderr lines into an error category.
+ * Classify stderr lines into a typed SequantError instance (AC-7).
  *
- * Scans lines in order; the first classifier whose pattern matches any line wins.
- * Returns "unknown" if no patterns match.
+ * Exit codes are the primary signal; stderr patterns are secondary.
+ * Returns a typed error instance with structured metadata.
+ *
+ * @param stderrLines - Lines from stderr
+ * @param exitCode - Process exit code (primary signal)
+ * @returns Typed SequantError subclass instance
  */
-export function classifyError(stderrLines) {
-    if (!stderrLines || stderrLines.length === 0) {
-        return "unknown";
+export function classifyError(stderrLines, exitCode) {
+    const combinedStderr = stderrLines?.join(" ") ?? "";
+    // Primary signal: exit code (AC-7)
+    if (exitCode !== undefined) {
+        // 143 = SIGTERM, often timeout
+        if (exitCode === 143 || exitCode === 137) {
+            return new TimeoutError(`Process killed with signal (exit code ${exitCode})`, { timeoutMs: undefined, phase: undefined });
+        }
     }
-    for (const { category, patterns } of CLASSIFIERS) {
-        for (const line of stderrLines) {
-            for (const pattern of patterns) {
-                if (pattern.test(line)) {
-                    return category;
+    // Secondary signal: stderr pattern matching
+    if (stderrLines && stderrLines.length > 0) {
+        for (const { category, patterns, extract } of CLASSIFIERS) {
+            for (const line of stderrLines) {
+                for (const pattern of patterns) {
+                    if (pattern.test(line)) {
+                        const metadata = extract?.(line) ?? {};
+                        return createErrorForCategory(category, line, metadata, exitCode);
+                    }
                 }
             }
         }
     }
-    return "unknown";
+    // Fallback: SubprocessError with exit code
+    return new SubprocessError(combinedStderr || "Unknown error", {
+        exitCode,
+        command: undefined,
+        stderr: combinedStderr || undefined,
+    });
+}
+/**
+ * Create a typed error instance from a legacy category string.
+ */
+function createErrorForCategory(category, message, metadata, exitCode) {
+    switch (category) {
+        case "context_overflow":
+            return new ContextOverflowError(message, metadata);
+        case "api_error":
+            return new ApiError(message, {
+                statusCode: metadata.statusCode,
+                endpoint: metadata.endpoint,
+            });
+        case "hook_failure":
+            return new HookFailureError(message, {
+                hook: metadata.hook,
+                reason: metadata.reason,
+            });
+        case "build_error":
+            return new BuildError(message, {
+                toolchain: metadata.toolchain,
+                errorCode: metadata.errorCode,
+            });
+        case "timeout":
+            return new TimeoutError(message, {
+                timeoutMs: metadata.timeoutMs,
+            });
+        default:
+            return new SubprocessError(message, { exitCode });
+    }
 }

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

@@ -11,6 +11,8 @@ import chalk from "chalk";
 import { execSync } from "child_process";
 import { readAgentsMd } from "../agents-md.js";
 import { getDriver } from "./drivers/index.js";
+import { classifyError } from "./error-classifier.js";
+import { ApiError } from "../errors.js";
 /**
  * Natural language prompts for each phase.
  * Claude Code invokes the corresponding skills via natural language.
@@ -490,9 +492,19 @@ delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
                 return lastResult;
             }
             // Genuine failure (took long enough to be real work) → skip cold-start retries.
-            // For spec phase, break to allow Phase 3 (spec-specific retry) to run.
-            // For other phases, return immediately — no further retries.
+            // Use error classification (AC-9): if the error is retryable (e.g., API
+            // rate limit, transient 503), allow one more attempt even for genuine failures.
             if (duration >= COLD_START_THRESHOLD_SECONDS) {
+                const typedError = classifyError(lastResult.stderrTail ?? [], lastResult.exitCode);
+                if (typedError.isRetryable && attempt < COLD_START_MAX_RETRIES) {
+                    if (config.verbose) {
+                        const label = typedError instanceof ApiError
+                            ? `API error (status ${typedError.metadata.statusCode ?? "unknown"})`
+                            : typedError.name;
+                        console.log(chalk.yellow(`\n    ⟳ Retryable error: ${label}, retrying... (attempt ${attempt + 2}/${COLD_START_MAX_RETRIES + 1})`));
+                    }
+                    continue;
+                }
                 if (phase === "spec") {
                     break;
                 }

package/dist/src/lib/workflow/run-log-schema.d.ts

@@ -90,6 +90,9 @@ export declare const ErrorContextSchema: z.ZodObject<{
         hook_failure: "hook_failure";
         build_error: "build_error";
     }>;
+    errorType: z.ZodOptional<z.ZodString>;
+    errorMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    isRetryable: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type ErrorContext = z.infer<typeof ErrorContextSchema>;
 /**
@@ -177,6 +180,9 @@ export declare const PhaseLogSchema: z.ZodObject<{
             hook_failure: "hook_failure";
             build_error: "build_error";
         }>;
+        errorType: z.ZodOptional<z.ZodString>;
+        errorMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        isRetryable: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type PhaseLog = z.infer<typeof PhaseLogSchema>;
@@ -260,6 +266,9 @@ export declare const IssueLogSchema: z.ZodObject<{
                 hook_failure: "hook_failure";
                 build_error: "build_error";
             }>;
+            errorType: z.ZodOptional<z.ZodString>;
+            errorMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            isRetryable: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
     totalDurationSeconds: z.ZodNumber;
@@ -404,6 +413,9 @@ export declare const RunLogSchema: z.ZodObject<{
                     hook_failure: "hook_failure";
                     build_error: "build_error";
                 }>;
+                errorType: z.ZodOptional<z.ZodString>;
+                errorMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                isRetryable: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
         totalDurationSeconds: z.ZodNumber;

package/dist/src/lib/workflow/run-log-schema.js

@@ -79,7 +79,7 @@ export const ErrorContextSchema = z.object({
     stdoutTail: z.array(z.string()),
     /** Process exit code */
     exitCode: z.number().int().optional(),
-    /** Classified error category */
+    /** Classified error category (legacy, kept for backwards compatibility) */
     category: z.enum([
         "context_overflow",
         "api_error",
@@ -88,6 +88,12 @@ export const ErrorContextSchema = z.object({
         "timeout",
         "unknown",
     ]),
+    /** Typed error class name (AC-8), e.g. "ApiError", "BuildError" */
+    errorType: z.string().optional(),
+    /** Structured error metadata (AC-8) */
+    errorMetadata: z.record(z.string(), z.unknown()).optional(),
+    /** Whether this error type is retryable (AC-9) */
+    isRetryable: z.boolean().optional(),
 });
 /**
  * Condensed QA verdict summary for structured log output (#434).

package/dist/src/lib/workflow/run-orchestrator.d.ts

@@ -0,0 +1,124 @@
+/**
+ * RunOrchestrator — CLI-free execution engine for sequant workflows.
+ *
+ * Owns the full lifecycle: config → issue discovery → dispatch → results.
+ * Importable and usable without Commander.js or CLI context.
+ *
+ * @module
+ */
+import type { ExecutionConfig, IssueResult, RunOptions, ProgressCallback } from "./types.js";
+import type { WorktreeInfo } from "./worktree-manager.js";
+import { LogWriter } from "./log-writer.js";
+import { StateManager } from "./state-manager.js";
+import { ShutdownManager } from "../shutdown.js";
+import type { SequantSettings } from "../settings.js";
+/**
+ * Injectable services for RunOrchestrator.
+ * All optional — orchestrator degrades gracefully when services are absent.
+ */
+export interface OrchestratorServices {
+    logWriter?: LogWriter | null;
+    stateManager?: StateManager | null;
+    shutdownManager?: ShutdownManager;
+}
+/**
+ * CLI-free configuration for RunOrchestrator.
+ * No Commander.js types leak into this interface.
+ */
+export interface OrchestratorConfig {
+    /** Execution settings (phases, timeouts, mode flags) */
+    config: ExecutionConfig;
+    /** Merged run options (post-resolution, no raw CLI types) */
+    options: RunOptions;
+    /** Issue metadata keyed by issue number */
+    issueInfoMap: Map<number, {
+        title: string;
+        labels: string[];
+    }>;
+    /** Worktree paths keyed by issue number */
+    worktreeMap: Map<number, WorktreeInfo>;
+    /** Injectable services */
+    services: OrchestratorServices;
+    /** Package manager name (e.g. "npm", "pnpm") */
+    packageManager?: string;
+    /** Base branch for rebase/PR targets */
+    baseBranch?: string;
+    /** Per-phase progress callback (parallel mode) */
+    onProgress?: ProgressCallback;
+}
+/**
+ * High-level init config for full lifecycle execution.
+ * Used by RunOrchestrator.run() — the entry point for programmatic callers.
+ */
+export interface RunInit {
+    /** Raw CLI options (pre-merge) */
+    options: RunOptions;
+    /** Resolved settings */
+    settings: SequantSettings;
+    /** Manifest metadata */
+    manifest: {
+        stack: string;
+        packageManager: string;
+    };
+    /** Explicit base branch override */
+    baseBranch?: string;
+    /** Per-phase progress callback */
+    onProgress?: ProgressCallback;
+}
+/**
+ * Structured result of a full orchestrator run.
+ */
+export interface RunResult {
+    /** Per-issue results */
+    results: IssueResult[];
+    /** Log file path (if logging enabled) */
+    logPath: string | null;
+    /** Non-zero if any issue failed */
+    exitCode: number;
+    /** Worktree map (for summary display) */
+    worktreeMap: Map<number, WorktreeInfo>;
+    /** Issue info map (for summary display) */
+    issueInfoMap: Map<number, {
+        title: string;
+        labels: string[];
+    }>;
+    /** Resolved execution config */
+    config: ExecutionConfig;
+    /** Resolved merged options */
+    mergedOptions: RunOptions;
+    /** Log writer (for reflection access) */
+    logWriter: LogWriter | null;
+}
+/**
+ * CLI-free workflow execution engine.
+ *
+ * Two usage modes:
+ * 1. Full lifecycle: `RunOrchestrator.run(init, issueNumbers)` — handles
+ *    services, worktrees, state guard, execution, and metrics.
+ * 2. Low-level: `new RunOrchestrator(config).execute(issueNumbers)` — caller
+ *    manages setup/teardown.
+ */
+export declare class RunOrchestrator {
+    private readonly cfg;
+    constructor(config: OrchestratorConfig);
+    /**
+     * Full lifecycle execution — the primary entry point for programmatic use.
+     *
+     * Handles: config resolution → services setup → state guard →
+     * issue discovery → worktree creation → execution → metrics → cleanup.
+     */
+    static run(init: RunInit, issueArgs: string[], batches?: number[][] | null): Promise<RunResult>;
+    /**
+     * Execute workflow for the given issue numbers.
+     * Returns one IssueResult per issue.
+     */
+    execute(issueNumbers: number[]): Promise<IssueResult[]>;
+    private validate;
+    private buildBatchContext;
+    private executeSequential;
+    private executeParallel;
+    private executeOneIssue;
+    private static recordMetrics;
+}
+/** Log a non-fatal warning: one-line summary always, detail in verbose. */
+export declare function logNonFatalWarning(message: string, error: unknown, verbose: boolean): void;