sequant 2.1.1 → 2.2.0

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.
@@ -216,6 +218,131 @@ export function formatDuration(seconds) {
     const secs = seconds % 60;
     return `${mins}m ${secs.toFixed(0)}s`;
 }
+/**
+ * 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 function hasExecChanges(cwd) {
+    let commitsAhead;
+    try {
+        const count = execSync("git rev-list --count origin/main..HEAD", {
+            cwd,
+            stdio: "pipe",
+        })
+            .toString()
+            .trim();
+        commitsAhead = Number.parseInt(count, 10) > 0;
+    }
+    catch {
+        return true;
+    }
+    if (commitsAhead)
+        return true;
+    try {
+        const porcelain = execSync("git status --porcelain", { cwd, stdio: "pipe" })
+            .toString()
+            .trim();
+        return porcelain.length > 0;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * 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 function mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds, cwd) {
+    const tails = {
+        stderrTail: agentResult.stderrTail,
+        stdoutTail: agentResult.stdoutTail,
+        exitCode: agentResult.exitCode,
+    };
+    if (phase === "qa") {
+        const verdict = agentResult.output
+            ? parseQaVerdict(agentResult.output)
+            : null;
+        const summary = agentResult.output
+            ? (parseQaSummary(agentResult.output) ?? undefined)
+            : undefined;
+        if (verdict &&
+            verdict !== "READY_FOR_MERGE" &&
+            verdict !== "NEEDS_VERIFICATION") {
+            return {
+                phase,
+                success: false,
+                durationSeconds,
+                error: `QA verdict: ${verdict}`,
+                sessionId: agentResult.sessionId,
+                output: agentResult.output,
+                verdict,
+                summary,
+                ...tails,
+            };
+        }
+        if (!verdict) {
+            // #534: a null verdict (empty or unparseable output) is not success.
+            return {
+                phase,
+                success: false,
+                durationSeconds,
+                error: "QA completed without a parseable verdict",
+                sessionId: agentResult.sessionId,
+                output: agentResult.output,
+                summary,
+                ...tails,
+            };
+        }
+        return {
+            phase,
+            success: true,
+            durationSeconds,
+            sessionId: agentResult.sessionId,
+            output: agentResult.output,
+            verdict,
+            summary,
+            ...tails,
+        };
+    }
+    if (phase === "exec" && !hasExecChanges(cwd)) {
+        // #534: an exec phase that produced nothing is not success.
+        return {
+            phase,
+            success: false,
+            durationSeconds,
+            error: "exec produced no changes (no commits, no uncommitted work)",
+            sessionId: agentResult.sessionId,
+            output: agentResult.output,
+            ...tails,
+        };
+    }
+    return {
+        phase,
+        success: true,
+        durationSeconds,
+        sessionId: agentResult.sessionId,
+        output: agentResult.output,
+        ...tails,
+    };
+}
 /**
  * Get the prompt for a phase with the issue number substituted.
  * Selects self-contained prompts for non-Claude agents.
@@ -388,52 +515,8 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
         shutdownManager.removeAbortController(abortController);
     }
     const durationSeconds = (Date.now() - startTime) / 1000;
-    // Map AgentPhaseResult to PhaseResult
-    const tails = {
-        stderrTail: agentResult.stderrTail,
-        stdoutTail: agentResult.stdoutTail,
-        exitCode: agentResult.exitCode,
-    };
     if (agentResult.success) {
-        // For QA phase, check the verdict to determine actual success
-        // Agent "success" just means the execution completed — we need to parse the verdict
-        if (phase === "qa" && agentResult.output) {
-            const verdict = parseQaVerdict(agentResult.output);
-            const summary = parseQaSummary(agentResult.output) ?? undefined;
-            if (verdict &&
-                verdict !== "READY_FOR_MERGE" &&
-                verdict !== "NEEDS_VERIFICATION") {
-                return {
-                    phase,
-                    success: false,
-                    durationSeconds,
-                    error: `QA verdict: ${verdict}`,
-                    sessionId: agentResult.sessionId,
-                    output: agentResult.output,
-                    verdict,
-                    summary,
-                    ...tails,
-                };
-            }
-            return {
-                phase,
-                success: true,
-                durationSeconds,
-                sessionId: agentResult.sessionId,
-                output: agentResult.output,
-                verdict: verdict ?? undefined,
-                summary,
-                ...tails,
-            };
-        }
-        return {
-            phase,
-            success: true,
-            durationSeconds,
-            sessionId: agentResult.sessionId,
-            output: agentResult.output,
-            ...tails,
-        };
+        return mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds, cwd);
     }
     return {
         phase,
@@ -441,7 +524,9 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
         durationSeconds,
         error: agentResult.error,
         sessionId: agentResult.sessionId,
-        ...tails,
+        stderrTail: agentResult.stderrTail,
+        stdoutTail: agentResult.stdoutTail,
+        exitCode: agentResult.exitCode,
     };
 }
 /**
@@ -490,9 +575,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,161 @@
+/**
+ * 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;
+}
+/**
+ * Pure result of config resolution — no side effects, no services.
+ * Produced by `RunOrchestrator.resolveConfig()` and consumed by both
+ * `run()` (internally) and the CLI (for pre-run display).
+ */
+export interface ResolvedRun {
+    /** Post-merge run options (defaults < settings < env < explicit) */
+    mergedOptions: RunOptions;
+    /** Execution config derived from mergedOptions */
+    config: ExecutionConfig;
+    /** Parsed + dep-sorted issue numbers (pre-state-guard) */
+    issueNumbers: number[];
+    /** Resolved batches if --batch specified, else null */
+    batches: number[][] | null;
+    /** Resolved base branch (CLI → settings → auto-detect → "main") */
+    baseBranch: string;
+    /** Stack from manifest */
+    stack: string;
+    /** True when phases will be auto-detected from issue labels */
+    autoDetectPhases: boolean;
+    /** True when worktree isolation is enabled */
+    worktreeIsolationEnabled: boolean;
+    /** True when JSON logging will be initialized */
+    logEnabled: boolean;
+    /** True when state tracking will be enabled */
+    stateEnabled: boolean;
+}
+/**
+ * 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);
+    /**
+     * Pure config resolution — no side effects.
+     *
+     * Produces a `ResolvedRun` containing merged options, execution config,
+     * parsed/sorted issue numbers, base branch, and display-only flags. Safe
+     * to call for preview purposes (e.g. CLI config display before run).
+     *
+     * `run()` uses this internally to avoid duplicating resolution logic.
+     */
+    static resolveConfig(init: RunInit, issueArgs: string[], batches?: number[][] | null): ResolvedRun;
+    /**
+     * 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;