sequant 2.1.1 → 2.2.0

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

@@ -10,7 +10,7 @@
 import chalk from "chalk";
 import { spawnSync } from "child_process";
 import { createPhaseLogFromTiming } from "./log-writer.js";
-import { classifyError } from "./error-classifier.js";
+import { classifyError, errorTypeToCategory } 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";
@@ -399,11 +399,15 @@ export async function runIssueWithLogging(ctx) {
                 // Build errorContext from captured stderr/stdout tails (#447)
                 let specErrorContext;
                 if (!specResult.success && specResult.stderrTail) {
+                    const specError = classifyError(specResult.stderrTail ?? [], specResult.exitCode);
                     specErrorContext = {
                         stderrTail: specResult.stderrTail ?? [],
                         stdoutTail: specResult.stdoutTail ?? [],
                         exitCode: specResult.exitCode,
-                        category: classifyError(specResult.stderrTail ?? []),
+                        category: errorTypeToCategory(specError),
+                        errorType: specError.name,
+                        errorMetadata: specError.metadata,
+                        isRetryable: specError.isRetryable,
                     };
                 }
                 const phaseLog = createPhaseLogFromTiming("spec", issueNumber, specStartTime, specEndTime, specResult.success
@@ -595,14 +599,18 @@ export async function runIssueWithLogging(ctx) {
                     : undefined;
                 // Read cache metrics for QA phase (AC-7)
                 const cacheMetrics = phase === "qa" ? readCacheMetrics(worktreePath) : undefined;
-                // Build errorContext from captured stderr/stdout tails (#447)
+                // Build errorContext from captured stderr/stdout tails (#447, AC-7/AC-8)
                 let errorContext;
                 if (!result.success && result.stderrTail) {
+                    const typedError = classifyError(result.stderrTail ?? [], result.exitCode);
                     errorContext = {
                         stderrTail: result.stderrTail ?? [],
                         stdoutTail: result.stdoutTail ?? [],
                         exitCode: result.exitCode,
-                        category: classifyError(result.stderrTail ?? []),
+                        category: errorTypeToCategory(typedError),
+                        errorType: typedError.name,
+                        errorMetadata: typedError.metadata,
+                        isRetryable: typedError.isRetryable,
                     };
                 }
                 const phaseLog = createPhaseLogFromTiming(phase, issueNumber, phaseStartTime, phaseEndTime, result.success
@@ -739,7 +747,7 @@ export async function runIssueWithLogging(ctx) {
     }
     // Create checkpoint commit in chain mode after QA passes
     if (success && chainMode && worktreePath) {
-        createCheckpointCommit(worktreePath, issueNumber, config.verbose);
+        createCheckpointCommit(worktreePath, issueNumber, config.verbose, baseBranch);
     }
     // Rebase onto the base branch before PR creation (unless --no-rebase)
     // This ensures the branch is up-to-date and prevents lockfile drift

package/dist/src/lib/workflow/config-resolver.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 { type ExecutionConfig, type RunOptions } from "./types.js";
+import type { SequantSettings } from "../settings.js";
+/**
+ * Layers for config resolution.
+ * Each field is optional — only defined values participate in merging.
+ */
+export interface ConfigLayers {
+    defaults: Record<string, unknown>;
+    settings: Record<string, unknown>;
+    env: Record<string, unknown>;
+    explicit: Record<string, unknown>;
+}
+/**
+ * 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 declare class ConfigResolver {
+    private layers;
+    constructor(layers: ConfigLayers);
+    /**
+     * Resolve all layers into a single merged config object.
+     * Priority: explicit > env > settings > defaults.
+     */
+    resolve(): Record<string, unknown>;
+}
+/**
+ * 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 declare function normalizeCommanderOptions(options: RunOptions): RunOptions;
+/**
+ * Resolve RunOptions + settings + env into a fully merged RunOptions.
+ * This replaces the inline merging logic previously in run.ts.
+ */
+export declare function resolveRunOptions(cliOptions: RunOptions, settings: SequantSettings): RunOptions;
+/**
+ * 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 declare function buildExecutionConfig(mergedOptions: RunOptions, settings: SequantSettings, issueCount: number): ExecutionConfig;

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.d.ts

@@ -11,6 +11,7 @@ import { ShutdownManager } from "../shutdown.js";
 import { PhaseSpinner } from "../phase-spinner.js";
 import { Phase, ExecutionConfig, PhaseResult, QaVerdict } from "./types.js";
 import type { QaSummary } from "./run-log-schema.js";
+import type { AgentPhaseResult } from "./drivers/index.js";
 /**
  * Spec-specific retry configuration.
  * Spec failures have a higher failure rate (~8.6%) than other phases due to
@@ -40,6 +41,36 @@ export declare function parseQaSummary(output: string): QaSummary | null;
  * Format duration in human-readable format
  */
 export declare function formatDuration(seconds: number): string;
+/**
+ * Check whether the exec phase produced any changes in the worktree.
+ * Returns true if HEAD has commits unique to it relative to origin/main
+ * OR uncommitted work is present.
+ *
+ * Uses `git rev-list --count origin/main..HEAD` (commits reachable from HEAD
+ * but not origin/main) instead of `git diff origin/main..HEAD`, because the
+ * two-dot diff also fires in reverse when origin/main has advanced past HEAD
+ * — on stale branches that would falsely report "has commits" even when the
+ * exec phase produced nothing, reintroducing the bug #534 is fixing.
+ *
+ * Fails open (returns true) on git errors — a missing origin ref is better
+ * diagnosed as a real zero-diff run than as a false phase failure.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function hasExecChanges(cwd: string): boolean;
+/**
+ * Map a successful AgentPhaseResult to a PhaseResult, applying phase-specific
+ * guards that catch agent sessions which returned success without producing
+ * usable work (#534):
+ *
+ * - `qa`: fails when no parseable verdict is found (empty or malformed output).
+ * - `exec`: fails when no commits and no uncommitted changes exist.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function mapAgentSuccessToPhaseResult(phase: Phase, agentResult: AgentPhaseResult, durationSeconds: number, cwd: string): PhaseResult & {
+    sessionId?: string;
+};
 /**
  * Get the prompt for a phase with the issue number substituted.
  * Selects self-contained prompts for non-Claude agents.