sequant 2.1.0 → 2.1.2

package/dist/src/lib/settings.js

@@ -12,10 +12,246 @@
  */
 import { readFile, writeFile, fileExists, ensureDir } from "./fs.js";
 import { dirname } from "path";
+import { z } from "zod";
 /** Path to project-level settings file */
 export const SETTINGS_PATH = ".sequant/settings.json";
 /** Current settings schema version */
 export const SETTINGS_VERSION = "1.0";
+// ─── Zod Schemas (AC-1, AC-5) ────────────────────────────────────────────────
+/** Zod schema for RotationSettings */
+export const RotationSettingsSchema = z.object({
+    enabled: z.boolean().default(true),
+    maxSizeMB: z.number().default(10),
+    maxFiles: z.number().default(100),
+});
+/** Zod schema for AiderSettings */
+export const AiderSettingsSchema = z.object({
+    model: z.string().optional(),
+    editFormat: z.string().optional(),
+    extraArgs: z.array(z.string()).optional(),
+});
+/** Zod schema for AgentSettings */
+export const AgentSettingsSchema = z.object({
+    parallel: z.boolean().default(false),
+    model: z.enum(["haiku", "sonnet", "opus"]).default("haiku"),
+    isolateParallel: z.boolean().default(false),
+});
+/** Zod schema for RunSettings */
+export const RunSettingsSchema = z.object({
+    logJson: z.boolean().default(true),
+    logPath: z.string().default(".sequant/logs"),
+    autoDetectPhases: z.boolean().default(true),
+    timeout: z.number().default(1800),
+    sequential: z.boolean().default(false),
+    concurrency: z.number().default(3),
+    qualityLoop: z.boolean().default(false),
+    maxIterations: z.number().default(3),
+    smartTests: z.boolean().default(true),
+    rotation: RotationSettingsSchema.default(() => RotationSettingsSchema.parse({})),
+    defaultBase: z.string().optional(),
+    mcp: z.boolean().default(true),
+    retry: z.boolean().default(true),
+    staleBranchThreshold: z.number().default(5),
+    resolvedIssueTTL: z.number().default(7),
+    pmRun: z.string().optional(),
+    devUrl: z.string().optional(),
+    agent: z.string().optional(),
+    aider: AiderSettingsSchema.optional(),
+});
+/** Zod schema for ScopeThreshold (base — fields required, no defaults) */
+export const ScopeThresholdSchema = z.object({
+    yellow: z.number(),
+    red: z.number(),
+});
+/**
+ * Create a threshold schema with specific defaults for partial input.
+ * Each threshold (featureCount, acItems, etc.) needs its own defaults
+ * so that `{ yellow: 10 }` fills `red` from that threshold's default.
+ */
+function thresholdWithDefaults(defaultYellow, defaultRed) {
+    return z.object({
+        yellow: z.number().default(defaultYellow),
+        red: z.number().default(defaultRed),
+    });
+}
+/** Zod schema for TrivialThresholds */
+export const TrivialThresholdsSchema = z.object({
+    maxACItems: z.number().default(3),
+    maxDirectories: z.number().default(1),
+});
+/** Zod schema for ScopeAssessmentSettings */
+export const ScopeAssessmentSettingsSchema = z.object({
+    enabled: z.boolean().default(true),
+    skipIfSimple: z.boolean().default(true),
+    trivialThresholds: TrivialThresholdsSchema.default(() => TrivialThresholdsSchema.parse({})),
+    thresholds: z
+        .object({
+        featureCount: thresholdWithDefaults(2, 3).default({ yellow: 2, red: 3 }),
+        acItems: thresholdWithDefaults(6, 9).default({ yellow: 6, red: 9 }),
+        fileEstimate: thresholdWithDefaults(8, 13).default({
+            yellow: 8,
+            red: 13,
+        }),
+        directorySpread: thresholdWithDefaults(3, 5).default({
+            yellow: 3,
+            red: 5,
+        }),
+    })
+        .default(() => z
+        .object({
+        featureCount: thresholdWithDefaults(2, 3).default({
+            yellow: 2,
+            red: 3,
+        }),
+        acItems: thresholdWithDefaults(6, 9).default({
+            yellow: 6,
+            red: 9,
+        }),
+        fileEstimate: thresholdWithDefaults(8, 13).default({
+            yellow: 8,
+            red: 13,
+        }),
+        directorySpread: thresholdWithDefaults(3, 5).default({
+            yellow: 3,
+            red: 5,
+        }),
+    })
+        .parse({})),
+});
+/** Zod schema for QASettings */
+export const QASettingsSchema = z.object({
+    smallDiffThreshold: z.number().default(100),
+});
+/**
+ * Zod schema for the full SequantSettings (AC-1, AC-5).
+ *
+ * Top-level uses `.passthrough()` to allow forward-compatible fields from
+ * newer Sequant versions. Unknown keys are preserved in parse output and
+ * reported as warnings via `validateSettings()`.
+ *
+ * Nested schemas don't use `.passthrough()` because unknown key detection
+ * is handled by `detectUnknownKeys()` at validation time.
+ */
+export const SettingsSchema = z
+    .object({
+    version: z.string().default("1.0"),
+    run: RunSettingsSchema.default(() => RunSettingsSchema.parse({})),
+    agents: AgentSettingsSchema.default(() => AgentSettingsSchema.parse({})),
+    scopeAssessment: ScopeAssessmentSettingsSchema.default(() => ScopeAssessmentSettingsSchema.parse({})),
+    qa: QASettingsSchema.default(() => QASettingsSchema.parse({})),
+})
+    .passthrough();
+/**
+ * Known keys at each level of the settings schema.
+ * Used to detect unknown/misspelled keys and produce warnings.
+ */
+const KNOWN_KEYS = {
+    "": new Set(["version", "run", "agents", "scopeAssessment", "qa"]),
+    run: new Set([
+        "logJson",
+        "logPath",
+        "autoDetectPhases",
+        "timeout",
+        "sequential",
+        "concurrency",
+        "qualityLoop",
+        "maxIterations",
+        "smartTests",
+        "rotation",
+        "defaultBase",
+        "mcp",
+        "retry",
+        "staleBranchThreshold",
+        "resolvedIssueTTL",
+        "pmRun",
+        "devUrl",
+        "agent",
+        "aider",
+    ]),
+    agents: new Set(["parallel", "model", "isolateParallel"]),
+    scopeAssessment: new Set([
+        "enabled",
+        "skipIfSimple",
+        "trivialThresholds",
+        "thresholds",
+    ]),
+    qa: new Set(["smallDiffThreshold"]),
+    "run.rotation": new Set(["enabled", "maxSizeMB", "maxFiles"]),
+    "run.aider": new Set(["model", "editFormat", "extraArgs"]),
+    "scopeAssessment.trivialThresholds": new Set([
+        "maxACItems",
+        "maxDirectories",
+    ]),
+    "scopeAssessment.thresholds": new Set([
+        "featureCount",
+        "acItems",
+        "fileEstimate",
+        "directorySpread",
+    ]),
+};
+/**
+ * Recursively detect unknown keys in a raw settings object.
+ */
+function detectUnknownKeys(obj, prefix) {
+    const warnings = [];
+    const knownSet = KNOWN_KEYS[prefix];
+    if (!knownSet)
+        return warnings; // no known-keys list → skip checking
+    for (const key of Object.keys(obj)) {
+        const fullPath = prefix ? `${prefix}.${key}` : key;
+        if (!knownSet.has(key)) {
+            warnings.push({
+                path: fullPath,
+                message: `Unknown key '${fullPath}' in settings.json (ignored)`,
+            });
+        }
+        // Recurse into nested objects
+        const val = obj[key];
+        if (val && typeof val === "object" && !Array.isArray(val)) {
+            warnings.push(...detectUnknownKeys(val, fullPath));
+        }
+    }
+    return warnings;
+}
+/**
+ * Format a Zod error into user-friendly messages (AC-2).
+ *
+ * Produces messages like:
+ *   settings.json: 'run.timeout' must be a number, got string 'fast'
+ */
+function formatZodErrors(error) {
+    return error.issues.map((issue) => {
+        const path = issue.path.join(".");
+        // Zod v4 uses issue.message which already includes type info
+        const message = `settings.json: '${path}' ${issue.message}`;
+        return { path, message };
+    });
+}
+/**
+ * Validate a raw settings object against the Zod schema (AC-2).
+ *
+ * Returns validated settings (with defaults filled in) and any warnings.
+ * On type errors, falls back to defaults for the invalid fields and
+ * reports warnings — never throws.
+ */
+export function validateSettings(raw) {
+    const warnings = [];
+    // Detect unknown keys before Zod parsing (passthrough preserves them but doesn't warn)
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        warnings.push(...detectUnknownKeys(raw, ""));
+    }
+    const result = SettingsSchema.safeParse(raw ?? {});
+    if (result.success) {
+        return { settings: result.data, warnings };
+    }
+    // Zod validation failed — report errors as warnings and fall back to defaults
+    warnings.push(...formatZodErrors(result.error));
+    // Try to salvage what we can: parse with defaults for the invalid parts
+    // by stripping invalid fields and re-parsing
+    const fallback = SettingsSchema.safeParse({});
+    const settings = (fallback.success ? fallback.data : DEFAULT_SETTINGS);
+    return { settings, warnings };
+}
 /**
  * Default rotation settings
  */
@@ -126,52 +362,46 @@ export function validateAiderSettings(aider) {
     return obj;
 }
 /**
- * Get the current project settings
+ * Get the current project settings with validation warnings (AC-2, AC-3).
  *
- * Returns default settings if no settings file exists.
+ * Returns settings merged with defaults and any validation warnings.
+ * Use this when you need to display warnings to the user (e.g., status command).
  */
-export async function getSettings() {
+export async function getSettingsWithWarnings() {
     if (!(await fileExists(SETTINGS_PATH))) {
-        return DEFAULT_SETTINGS;
+        return { settings: DEFAULT_SETTINGS, warnings: [] };
     }
     try {
         const content = await readFile(SETTINGS_PATH);
-        const parsed = JSON.parse(content);
-        // Validate aider settings if present
-        const aiderSettings = validateAiderSettings(parsed.run?.aider);
-        // Merge with defaults to ensure all fields exist
+        if (!content.trim()) {
+            return { settings: DEFAULT_SETTINGS, warnings: [] };
+        }
+        const parsed = JSON.parse(stripJsoncComments(content));
+        return validateSettings(parsed);
+    }
+    catch (err) {
+        const message = err instanceof SyntaxError
+            ? `settings.json: Invalid JSON — ${err.message}. Check syntax or delete the file to use defaults.`
+            : `settings.json: Failed to read — ${err instanceof Error ? err.message : String(err)}`;
         return {
-            version: parsed.version ?? DEFAULT_SETTINGS.version,
-            run: {
-                ...DEFAULT_SETTINGS.run,
-                ...parsed.run,
-                ...(aiderSettings !== undefined ? { aider: aiderSettings } : {}),
-            },
-            agents: {
-                ...DEFAULT_AGENT_SETTINGS,
-                ...parsed.agents,
-            },
-            scopeAssessment: {
-                ...DEFAULT_SCOPE_ASSESSMENT_SETTINGS,
-                ...parsed.scopeAssessment,
-                trivialThresholds: {
-                    ...DEFAULT_SCOPE_ASSESSMENT_SETTINGS.trivialThresholds,
-                    ...parsed.scopeAssessment?.trivialThresholds,
-                },
-                thresholds: {
-                    ...DEFAULT_SCOPE_ASSESSMENT_SETTINGS.thresholds,
-                    ...parsed.scopeAssessment?.thresholds,
-                },
-            },
-            qa: {
-                ...DEFAULT_QA_SETTINGS,
-                ...parsed.qa,
-            },
+            settings: DEFAULT_SETTINGS,
+            warnings: [{ path: "", message }],
         };
     }
-    catch {
-        return DEFAULT_SETTINGS;
+}
+/**
+ * Get the current project settings
+ *
+ * Returns default settings if no settings file exists.
+ * Validates against Zod schema (AC-2) — warnings are logged to stderr.
+ */
+export async function getSettings() {
+    const { settings, warnings } = await getSettingsWithWarnings();
+    // Log validation warnings to stderr so they're visible but don't pollute stdout
+    for (const w of warnings) {
+        console.error(`⚠ ${w.message}`);
     }
+    return settings;
 }
 /**
  * Save project settings
@@ -189,6 +419,221 @@ export async function settingsExist() {
 /**
  * Create default settings file
  */
+/**
+ * Create default settings file with JSONC inline comments (AC-4).
+ *
+ * Generates a JSONC file (.json with // comments) documenting each field
+ * and its default value. The loadSettings path strips comments before parsing.
+ */
 export async function createDefaultSettings() {
-    await saveSettings(DEFAULT_SETTINGS);
+    await ensureDir(dirname(SETTINGS_PATH));
+    const jsonc = generateSettingsJsonc(DEFAULT_SETTINGS);
+    await writeFile(SETTINGS_PATH, jsonc);
+}
+/**
+ * Generate JSONC content with inline comments for each settings field (AC-4).
+ */
+export function generateSettingsJsonc(settings) {
+    const lines = ["{"];
+    lines.push(`  // Schema version for migration support`);
+    lines.push(`  "version": ${JSON.stringify(settings.version)},`);
+    lines.push("");
+    lines.push(`  // Run command settings`);
+    lines.push(`  "run": {`);
+    lines.push(`    // Enable JSON logging`);
+    lines.push(`    "logJson": ${JSON.stringify(settings.run.logJson)},`);
+    lines.push(`    // Path to log directory`);
+    lines.push(`    "logPath": ${JSON.stringify(settings.run.logPath)},`);
+    lines.push(`    // Auto-detect phases from GitHub issue labels`);
+    lines.push(`    "autoDetectPhases": ${JSON.stringify(settings.run.autoDetectPhases)},`);
+    lines.push(`    // Default timeout per phase in seconds`);
+    lines.push(`    "timeout": ${JSON.stringify(settings.run.timeout)},`);
+    lines.push(`    // Run issues sequentially by default`);
+    lines.push(`    "sequential": ${JSON.stringify(settings.run.sequential)},`);
+    lines.push(`    // Max concurrent issues in parallel mode`);
+    lines.push(`    "concurrency": ${JSON.stringify(settings.run.concurrency)},`);
+    lines.push(`    // Enable quality loop by default`);
+    lines.push(`    "qualityLoop": ${JSON.stringify(settings.run.qualityLoop)},`);
+    lines.push(`    // Max iterations for quality loop`);
+    lines.push(`    "maxIterations": ${JSON.stringify(settings.run.maxIterations)},`);
+    lines.push(`    // Enable smart test detection`);
+    lines.push(`    "smartTests": ${JSON.stringify(settings.run.smartTests)},`);
+    lines.push(`    // Enable MCP servers in headless mode`);
+    lines.push(`    "mcp": ${JSON.stringify(settings.run.mcp)},`);
+    lines.push(`    // Enable automatic retry with MCP fallback`);
+    lines.push(`    "retry": ${JSON.stringify(settings.run.retry)},`);
+    lines.push(`    // Commits behind main before warning`);
+    lines.push(`    "staleBranchThreshold": ${JSON.stringify(settings.run.staleBranchThreshold)},`);
+    lines.push(`    // Days before resolved issues auto-prune (0=never, -1=immediate)`);
+    lines.push(`    "resolvedIssueTTL": ${JSON.stringify(settings.run.resolvedIssueTTL)},`);
+    lines.push("");
+    lines.push(`    // Log rotation settings`);
+    lines.push(`    "rotation": {`);
+    lines.push(`      // Enable automatic log rotation`);
+    lines.push(`      "enabled": ${JSON.stringify(settings.run.rotation.enabled)},`);
+    lines.push(`      // Maximum total size in MB before rotation`);
+    lines.push(`      "maxSizeMB": ${JSON.stringify(settings.run.rotation.maxSizeMB)},`);
+    lines.push(`      // Maximum number of rotated log files to keep`);
+    lines.push(`      "maxFiles": ${JSON.stringify(settings.run.rotation.maxFiles)}`);
+    lines.push(`    }`);
+    lines.push(`  },`);
+    lines.push("");
+    lines.push(`  // Agent settings`);
+    lines.push(`  "agents": {`);
+    lines.push(`    // Run agents in parallel (faster, higher token usage)`);
+    lines.push(`    "parallel": ${JSON.stringify(settings.agents.parallel)},`);
+    lines.push(`    // Default model for sub-agents ("haiku", "sonnet", "opus")`);
+    lines.push(`    "model": ${JSON.stringify(settings.agents.model)},`);
+    lines.push(`    // Isolate parallel agent groups in separate worktrees`);
+    lines.push(`    "isolateParallel": ${JSON.stringify(settings.agents.isolateParallel)}`);
+    lines.push(`  }`);
+    lines.push("}");
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Strip single-line // comments from JSONC content for JSON.parse compatibility.
+ * Handles comments on their own line and trailing comments after values.
+ * Preserves strings containing // (e.g., URLs).
+ */
+export function stripJsoncComments(content) {
+    const lines = content.split("\n");
+    const result = [];
+    for (const line of lines) {
+        // Find // outside of strings
+        let inString = false;
+        let escaped = false;
+        let commentStart = -1;
+        for (let i = 0; i < line.length; i++) {
+            const ch = line[i];
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (ch === "\\") {
+                escaped = true;
+                continue;
+            }
+            if (ch === '"') {
+                inString = !inString;
+                continue;
+            }
+            if (!inString &&
+                ch === "/" &&
+                i + 1 < line.length &&
+                line[i + 1] === "/") {
+                commentStart = i;
+                break;
+            }
+        }
+        if (commentStart === -1) {
+            result.push(line);
+        }
+        else {
+            const before = line.slice(0, commentStart).trimEnd();
+            if (before) {
+                result.push(before);
+            }
+            // Skip comment-only lines entirely
+        }
+    }
+    return result.join("\n");
+}
+/**
+ * Generate settings.reference.md companion document (AC-4).
+ *
+ * Supplements the inline JSONC comments with a structured Markdown reference.
+ */
+export function generateSettingsReference() {
+    return `# Sequant Settings Reference
+
+This file documents all settings available in \`.sequant/settings.json\`.
+Generated by \`sequant init\`. See defaults below.
+
+## Top-Level
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| \`version\` | string | \`"${SETTINGS_VERSION}"\` | Schema version for migration support |
+
+## \`run\` — Run Command Settings
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| \`logJson\` | boolean | \`true\` | Enable JSON logging |
+| \`logPath\` | string | \`".sequant/logs"\` | Path to log directory |
+| \`autoDetectPhases\` | boolean | \`true\` | Auto-detect phases from GitHub issue labels |
+| \`timeout\` | number | \`1800\` | Default timeout per phase in seconds |
+| \`sequential\` | boolean | \`false\` | Run issues sequentially by default |
+| \`concurrency\` | number | \`3\` | Max concurrent issues in parallel mode |
+| \`qualityLoop\` | boolean | \`false\` | Enable quality loop by default |
+| \`maxIterations\` | number | \`3\` | Max iterations for quality loop |
+| \`smartTests\` | boolean | \`true\` | Enable smart test detection |
+| \`defaultBase\` | string | — | Default base branch for worktree creation |
+| \`mcp\` | boolean | \`true\` | Enable MCP servers in headless mode |
+| \`retry\` | boolean | \`true\` | Enable automatic retry with MCP fallback |
+| \`staleBranchThreshold\` | number | \`5\` | Commits behind main before warning |
+| \`resolvedIssueTTL\` | number | \`7\` | Days before resolved issues auto-prune (0=never, -1=immediate) |
+| \`agent\` | string | — | Agent driver: \`"claude-code"\` (default) or \`"aider"\` |
+
+### \`run.rotation\` — Log Rotation
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| \`enabled\` | boolean | \`true\` | Enable automatic log rotation |
+| \`maxSizeMB\` | number | \`10\` | Maximum total size in MB before rotation |
+| \`maxFiles\` | number | \`100\` | Maximum file count before rotation |
+
+### \`run.aider\` — Aider Settings (when agent="aider")
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| \`model\` | string | — | Model to use (e.g., "claude-3-sonnet") |
+| \`editFormat\` | string | — | Edit format: "diff", "whole", "udiff" |
+| \`extraArgs\` | string[] | — | Extra CLI arguments passed to aider |
+
+## \`agents\` — Agent Execution Settings
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| \`parallel\` | boolean | \`false\` | Run agents in parallel (faster, higher token usage) |
+| \`model\` | enum | \`"haiku"\` | Default model: \`"haiku"\`, \`"sonnet"\`, or \`"opus"\` |
+| \`isolateParallel\` | boolean | \`false\` | Isolate parallel agents in separate worktrees |
+
+## \`scopeAssessment\` — Scope Assessment Settings
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| \`enabled\` | boolean | \`true\` | Whether scope assessment is enabled |
+| \`skipIfSimple\` | boolean | \`true\` | Skip assessment for trivial issues |
+
+### \`scopeAssessment.trivialThresholds\`
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| \`maxACItems\` | number | \`3\` | Max AC items for trivial classification |
+| \`maxDirectories\` | number | \`1\` | Max directories for trivial classification |
+
+### \`scopeAssessment.thresholds\`
+
+Each threshold has \`yellow\` (warning) and \`red\` (split recommended) values:
+
+| Metric | Yellow | Red |
+|--------|--------|-----|
+| \`featureCount\` | 2 | 3 |
+| \`acItems\` | 6 | 9 |
+| \`fileEstimate\` | 8 | 13 |
+| \`directorySpread\` | 3 | 5 |
+
+## \`qa\` — QA Skill Settings
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| \`smallDiffThreshold\` | number | \`100\` | Diff size threshold for small-diff fast path |
+
+---
+
+*Unknown keys are preserved but logged as warnings. This allows forward compatibility
+with newer Sequant versions.*
+`;
 }

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

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;