sequant 2.1.2 → 2.2.0

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

@@ -218,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.
@@ -390,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,
@@ -443,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,
     };
 }
 /**

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

@@ -65,6 +65,33 @@ export interface RunInit {
     /** 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.
  */
@@ -101,6 +128,16 @@ export interface RunResult {
 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.
      *

package/dist/src/lib/workflow/run-orchestrator.js

@@ -37,20 +37,21 @@ export class RunOrchestrator {
         this.cfg = config;
     }
     /**
-     * Full lifecycle execution — the primary entry point for programmatic use.
+     * Pure config resolution — no side effects.
      *
-     * Handles: config resolution → services setup → state guard →
-     * issue discovery → worktree creation → execution → metrics → cleanup.
+     * 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 async run(init, issueArgs, batches) {
-        const { options, settings, manifest, onProgress } = init;
-        // ── Config resolution ──────────────────────────────────────────────
+    static resolveConfig(init, issueArgs, batches) {
+        const { options, settings, manifest } = init;
         const mergedOptions = resolveRunOptions(options, settings);
         const baseBranch = init.baseBranch ??
             options.base ??
             settings.run.defaultBase ??
             detectDefaultBranch(mergedOptions.verbose ?? false);
-        // ── Parse issues ───────────────────────────────────────────────────
         let issueNumbers;
         let resolvedBatches = batches ?? null;
         if (mergedOptions.batch &&
@@ -67,6 +68,39 @@ export class RunOrchestrator {
                 .map((i) => parseInt(i, 10))
                 .filter((n) => !isNaN(n));
         }
+        if (issueNumbers.length > 1 && !resolvedBatches) {
+            issueNumbers = sortByDependencies(issueNumbers);
+        }
+        const config = buildExecutionConfig(mergedOptions, settings, issueNumbers.length);
+        const logEnabled = !mergedOptions.noLog &&
+            !config.dryRun &&
+            (mergedOptions.logJson ?? settings.run.logJson ?? false);
+        return {
+            mergedOptions,
+            config,
+            issueNumbers,
+            batches: resolvedBatches,
+            baseBranch,
+            stack: manifest.stack,
+            autoDetectPhases: mergedOptions.autoDetectPhases ?? false,
+            worktreeIsolationEnabled: mergedOptions.worktreeIsolation !== false && issueNumbers.length > 0,
+            logEnabled,
+            stateEnabled: !config.dryRun,
+        };
+    }
+    /**
+     * 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 async run(init, issueArgs, batches) {
+        const { manifest, onProgress, settings } = init;
+        // ── Config resolution ──────────────────────────────────────────────
+        const resolved = RunOrchestrator.resolveConfig(init, issueArgs, batches);
+        const { mergedOptions, config, baseBranch } = resolved;
+        let { issueNumbers } = resolved;
+        const resolvedBatches = resolved.batches;
         if (issueNumbers.length === 0) {
             return {
                 results: [],
@@ -74,17 +108,11 @@ export class RunOrchestrator {
                 exitCode: 0,
                 worktreeMap: new Map(),
                 issueInfoMap: new Map(),
-                config: buildExecutionConfig(mergedOptions, settings, 0),
+                config,
                 mergedOptions,
                 logWriter: null,
             };
         }
-        // Sort by dependencies
-        if (issueNumbers.length > 1 && !resolvedBatches) {
-            issueNumbers = sortByDependencies(issueNumbers);
-        }
-        // ── Build execution config ─────────────────────────────────────────
-        const config = buildExecutionConfig(mergedOptions, settings, issueNumbers.length);
         // ── Services setup ─────────────────────────────────────────────────
         let logWriter = null;
         const shouldLog = !mergedOptions.noLog &&

package/dist/src/lib/workflow/worktree-manager.d.ts

@@ -156,11 +156,12 @@ export declare function ensureWorktreesChain(issues: Array<{
     title: string;
 }>, verbose: boolean, packageManager?: string, baseBranch?: string): Promise<Map<number, WorktreeInfo>>;
 /**
- * Create a checkpoint commit in the worktree after QA passes
- * This allows recovery in case later issues in the chain fail
+ * Create a checkpoint commit in the worktree after QA passes.
+ * Only stages files that were touched by the issue's commits (diff vs baseBranch).
+ * If unrelated dirty files exist, emits a warning and skips the checkpoint.
  * @internal Exported for testing
  */
-export declare function createCheckpointCommit(worktreePath: string, issueNumber: number, verbose: boolean): boolean;
+export declare function createCheckpointCommit(worktreePath: string, issueNumber: number, verbose: boolean, baseBranch?: string): boolean;
 /**
  * Check if any lockfile changed during a rebase and re-run install if needed.
  * This prevents dependency drift when the lockfile was updated on main.

package/dist/src/lib/workflow/worktree-manager.js

@@ -612,30 +612,80 @@ export async function ensureWorktreesChain(issues, verbose, packageManager, base
     return worktrees;
 }
 /**
- * Create a checkpoint commit in the worktree after QA passes
- * This allows recovery in case later issues in the chain fail
+ * Create a checkpoint commit in the worktree after QA passes.
+ * Only stages files that were touched by the issue's commits (diff vs baseBranch).
+ * If unrelated dirty files exist, emits a warning and skips the checkpoint.
  * @internal Exported for testing
  */
-export function createCheckpointCommit(worktreePath, issueNumber, verbose) {
-    // Check if there are uncommitted changes
-    const statusResult = spawnSync("git", ["-C", worktreePath, "status", "--porcelain"], { stdio: "pipe" });
+export function createCheckpointCommit(worktreePath, issueNumber, verbose, baseBranch) {
+    // Check if there are uncommitted changes.
+    // Use -z (NUL-terminated) so paths with unicode or special chars aren't quoted/escaped.
+    const statusResult = spawnSync("git", ["-C", worktreePath, "status", "--porcelain", "-z"], { stdio: "pipe" });
     if (statusResult.status !== 0) {
         if (verbose) {
             console.log(chalk.yellow(`    !  Could not check git status for checkpoint`));
         }
         return false;
     }
-    const hasChanges = statusResult.stdout.toString().trim().length > 0;
-    if (!hasChanges) {
+    const statusRaw = statusResult.stdout.toString();
+    if (statusRaw.length === 0) {
         if (verbose) {
             console.log(chalk.gray(`    📌 No changes to checkpoint (already committed)`));
         }
         return true;
     }
-    // Stage all changes
-    const addResult = spawnSync("git", ["-C", worktreePath, "add", "-A"], {
-        stdio: "pipe",
-    });
+    // Parse NUL-separated porcelain entries. Each entry is "XY path".
+    // For renames/copies, the next entry is the old path and must be consumed.
+    const entries = statusRaw.split("\0").filter((e) => e.length > 0);
+    const dirtyFiles = [];
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        const xy = entry.slice(0, 2);
+        const path = entry.slice(3);
+        if (path)
+            dirtyFiles.push(path);
+        // Rename (R) and copy (C) entries are followed by the original path — skip it
+        if (xy[0] === "R" || xy[0] === "C") {
+            i++;
+        }
+    }
+    // Determine which files to stage.
+    // When baseBranch is provided (chain mode), scope to feature paths only.
+    // When baseBranch is absent (non-chain), treat all dirty files as in-scope.
+    let inScope;
+    if (baseBranch) {
+        const diffResult = spawnSync("git", ["-C", worktreePath, "diff", "--name-only", "-z", `${baseBranch}...HEAD`], { stdio: "pipe" });
+        const featurePaths = new Set();
+        if (diffResult.status === 0) {
+            diffResult.stdout
+                .toString()
+                .split("\0")
+                .filter((p) => p.length > 0)
+                .forEach((p) => featurePaths.add(p));
+        }
+        inScope = dirtyFiles.filter((f) => featurePaths.has(f));
+        const outOfScope = dirtyFiles.filter((f) => !featurePaths.has(f));
+        // AC-2: If unrelated dirty files exist, warn and skip checkpoint
+        if (outOfScope.length > 0) {
+            console.log(chalk.yellow(`    ⚠  Skipping checkpoint for #${issueNumber}: ${outOfScope.length} unrelated dirty file(s) in worktree:`));
+            for (const f of outOfScope) {
+                console.log(chalk.yellow(`       - ${f}`));
+            }
+            return false;
+        }
+    }
+    else {
+        // Non-chain mode: all dirty files are in-scope
+        inScope = dirtyFiles;
+    }
+    if (inScope.length === 0) {
+        if (verbose) {
+            console.log(chalk.gray(`    📌 No in-scope changes to checkpoint`));
+        }
+        return true;
+    }
+    // AC-1: Stage only in-scope feature paths
+    const addResult = spawnSync("git", ["-C", worktreePath, "add", "--", ...inScope], { stdio: "pipe" });
     if (addResult.status !== 0) {
         if (verbose) {
             console.log(chalk.yellow(`    !  Could not stage changes for checkpoint`));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sequant",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "Quantize your development workflow - Sequential AI phases with quality gates",
   "type": "module",
   "bin": {