sequant 2.2.0 → 2.4.0

package/dist/src/lib/workflow/pr-status.js

@@ -31,22 +31,54 @@ export function checkPRMergeStatus(prNumber) {
 /**
  * Check if a branch has been merged into a base branch using git
  *
+ * "Merged" here means the branch was the source of an actual merge commit on
+ * the base branch — i.e., the branch tip appears as a non-first parent of some
+ * merge commit reachable from baseBranch. This deliberately excludes the case
+ * where the branch tip is just an ancestor of baseBranch with no commits ever
+ * added (e.g., a worktree branch created from main that was abandoned before
+ * any commits were made). Those branches are reachable from main but were
+ * never merged in any meaningful sense; the older `git branch --merged` check
+ * misclassified them as merged and caused subsequent runs to skip the still-
+ * open issue.
+ *
+ * Squash-merged branches do not satisfy this check (their tip is not on main
+ * after squash) — callers that need to detect squash merges should rely on
+ * commit-message detection (see {@link isIssueMergedIntoMain}'s `--grep` path)
+ * or a PR API check.
+ *
  * @param branchName - The branch name to check (e.g., "feature/33-some-title")
  * @param baseBranch - The base branch to check against (default: "main")
- * @returns true if the branch is merged into the base branch, false otherwise
+ * @returns true if a merge commit on baseBranch records branchName's tip as a
+ *   non-first parent, false otherwise
  */
 export function isBranchMergedIntoMain(branchName, baseBranch = "main") {
     try {
-        // Get branches merged into the base branch
-        const result = spawnSync("git", ["branch", "--merged", baseBranch], {
+        // Resolve the branch tip SHA. If the branch can't be resolved (deleted,
+        // typo'd, etc.), it can't be "merged" by any definition.
+        const tipResult = spawnSync("git", ["rev-parse", branchName], {
             stdio: "pipe",
             timeout: 10000,
         });
-        if (result.status === 0 && result.stdout) {
-            const mergedBranches = result.stdout.toString();
-            // Check if our branch is in the list (handle both local and remote refs)
-            return (mergedBranches.includes(branchName) ||
-                mergedBranches.includes(`remotes/origin/${branchName}`));
+        if (tipResult.status !== 0)
+            return false;
+        const branchTip = tipResult.stdout.toString().trim();
+        if (!branchTip)
+            return false;
+        // Walk recent merge commits on baseBranch and check whether any records
+        // the branch tip as a non-first parent. The first parent of a merge
+        // commit is the prior tip of baseBranch; non-first parents are the
+        // sources being merged in.
+        const mergesResult = spawnSync("git", ["rev-list", "--merges", "--parents", "-200", baseBranch], { stdio: "pipe", timeout: 10000 });
+        if (mergesResult.status === 0 && mergesResult.stdout) {
+            const lines = mergesResult.stdout.toString().trim().split("\n");
+            for (const line of lines) {
+                if (!line)
+                    continue;
+                const parts = line.split(" ");
+                if (parts.length > 2 && parts.slice(2).includes(branchTip)) {
+                    return true;
+                }
+            }
         }
     }
     catch {
@@ -58,7 +90,7 @@ export function isBranchMergedIntoMain(branchName, baseBranch = "main") {
  * Check if a feature branch for an issue is merged into a base branch
  *
  * Tries multiple detection methods:
- * 1. Check if branch exists and is merged via `git branch --merged <baseBranch>`
+ * 1. Find `feature/<N>-*` branches with `git branch -a` and check via {@link isBranchMergedIntoMain}
  * 2. Check for merge commits mentioning the issue
  *
  * @param issueNumber - The issue number to check

package/dist/src/lib/workflow/qa-stagnation.d.ts

@@ -0,0 +1,117 @@
+/**
+ * QA stagnation detection — early-exit guard for fullsolve's QA loop.
+ *
+ * Background (issue #581): when fullsolve's QA loop sees an `AC_NOT_MET`
+ * verdict it invokes `/loop` to apply fixes, then re-runs `/qa`. If `/loop`
+ * silently no-ops (no diff, no commit), the re-run produces the same verdict
+ * at the same SHA — wasting iterations without adding signal.
+ *
+ * This module exposes:
+ *
+ * - `detectStagnation()` — pure decision function. Given the latest qa marker,
+ *   the current HEAD SHA, and whether the worktree is dirty, returns whether
+ *   the next QA invocation would be wasted.
+ * - `recordStagnation()` — appends a stagnation entry to the per-issue
+ *   record in `.sequant/state.json` so successive fullsolve runs can see
+ *   the history.
+ *
+ * The fullsolve and loop SKILL.md files invoke a thin CLI shim that wraps
+ * these functions so the same code paths are exercised by tests and the
+ * orchestrated runtime.
+ */
+import { type StateManagerOptions } from "./state-manager.js";
+import type { PhaseMarker } from "./state-schema.js";
+/**
+ * Reason codes for halting the QA loop.
+ */
+export type StagnationReason = "SAME_SHA_NO_PROGRESS" | "LOOP_NO_DIFF";
+/**
+ * Decision returned by `detectStagnation`.
+ *
+ * `stagnant === true` means the orchestrator should NOT re-invoke `/qa` at
+ * the current state — either escalate or hand off to `/loop` for one more
+ * fix attempt.
+ */
+export interface StagnationDecision {
+    stagnant: boolean;
+    reason?: StagnationReason;
+    /** Human-readable explanation suitable for logs / GitHub comments. */
+    message: string;
+    /** SHA the prior QA was recorded at, if any. */
+    priorSha?: string;
+    /** Verdict from the prior QA, if any. */
+    priorVerdict?: string;
+}
+export interface DetectStagnationInput {
+    /** Current `git rev-parse HEAD` for the worktree. */
+    currentSha: string;
+    /** Whether `git status --porcelain` is non-empty. */
+    isDirty: boolean;
+    /**
+     * Most recent qa phase marker (any status). Pass `null` when no marker has
+     * been recorded yet — that always means "fresh, run qa".
+     */
+    lastMarker: PhaseMarker | null;
+}
+/**
+ * Pure detection function: would invoking `/qa` again be a wasted cycle?
+ *
+ * The contract from issue #581 AC-1: if the prior qa marker is `failed`,
+ * its `commitSHA` matches HEAD, AND the worktree is clean, the next `/qa`
+ * call will produce the same verdict — so the orchestrator should escalate
+ * (or run `/loop` once) instead.
+ */
+export declare function detectStagnation(input: DetectStagnationInput): StagnationDecision;
+/**
+ * Append a stagnation entry to the per-issue record. Schema-additive — older
+ * state files without the field will simply gain it on next write.
+ */
+export declare function recordStagnation(issueNumber: number, entry: {
+    sha: string;
+    verdict: string;
+    iteration: number;
+    reason: StagnationReason;
+}, options?: StateManagerOptions): Promise<void>;
+/**
+ * Inputs required for the CLI shim. Loaded from git + GitHub at the call site.
+ */
+export interface CLIDetectInput {
+    currentSha: string;
+    isDirty: boolean;
+    lastMarker: PhaseMarker | null;
+}
+/**
+ * Read the worktree's HEAD SHA. Pure wrapper around `git rev-parse HEAD`.
+ */
+export declare function readHeadSha(cwd?: string): string;
+/**
+ * Returns true when `git status --porcelain` reports any uncommitted change.
+ */
+export declare function readIsDirty(cwd?: string): boolean;
+/**
+ * Snapshot a worktree's HEAD SHA and dirty bit. Used by `/loop` to detect
+ * whether a fix attempt actually produced a diff. We deliberately exclude
+ * `.sequant/state.json` writes from the dirty check — the helper itself
+ * writes there, and per issue #581 those writes do NOT count as progress.
+ */
+export interface LoopProgressSnapshot {
+    sha: string;
+    /** Path-relative dirty entries, excluding `.sequant/` state writes. */
+    dirty: string[];
+}
+export declare function snapshotLoopProgress(cwd?: string): LoopProgressSnapshot;
+export interface LoopProgressDecision {
+    /** True when the snapshot pair shows a real diff (commit or working-tree change). */
+    progressed: boolean;
+    reason?: "LOOP_NO_DIFF";
+    message: string;
+}
+/**
+ * Compare two `LoopProgressSnapshot`s. Returns `progressed: false` ONLY when
+ * both the SHA and the (state-excluded) dirty set are unchanged.
+ *
+ * State-file / settings writes are excluded from the dirty comparison per
+ * issue #581's open question — `/loop` may legitimately touch
+ * `.sequant/state.json` without that counting as a fix.
+ */
+export declare function compareLoopProgress(before: LoopProgressSnapshot, after: LoopProgressSnapshot): LoopProgressDecision;

package/dist/src/lib/workflow/qa-stagnation.js

@@ -0,0 +1,179 @@
+/**
+ * QA stagnation detection — early-exit guard for fullsolve's QA loop.
+ *
+ * Background (issue #581): when fullsolve's QA loop sees an `AC_NOT_MET`
+ * verdict it invokes `/loop` to apply fixes, then re-runs `/qa`. If `/loop`
+ * silently no-ops (no diff, no commit), the re-run produces the same verdict
+ * at the same SHA — wasting iterations without adding signal.
+ *
+ * This module exposes:
+ *
+ * - `detectStagnation()` — pure decision function. Given the latest qa marker,
+ *   the current HEAD SHA, and whether the worktree is dirty, returns whether
+ *   the next QA invocation would be wasted.
+ * - `recordStagnation()` — appends a stagnation entry to the per-issue
+ *   record in `.sequant/state.json` so successive fullsolve runs can see
+ *   the history.
+ *
+ * The fullsolve and loop SKILL.md files invoke a thin CLI shim that wraps
+ * these functions so the same code paths are exercised by tests and the
+ * orchestrated runtime.
+ */
+import { execSync } from "child_process";
+import { StateManager, getStateManager, } from "./state-manager.js";
+/**
+ * Pure detection function: would invoking `/qa` again be a wasted cycle?
+ *
+ * The contract from issue #581 AC-1: if the prior qa marker is `failed`,
+ * its `commitSHA` matches HEAD, AND the worktree is clean, the next `/qa`
+ * call will produce the same verdict — so the orchestrator should escalate
+ * (or run `/loop` once) instead.
+ */
+export function detectStagnation(input) {
+    const { currentSha, isDirty, lastMarker } = input;
+    if (!lastMarker) {
+        return { stagnant: false, message: "No prior qa marker — fresh run." };
+    }
+    if (lastMarker.phase !== "qa") {
+        return {
+            stagnant: false,
+            message: `Latest marker is for phase '${lastMarker.phase}', not qa.`,
+        };
+    }
+    if (lastMarker.status !== "failed") {
+        return {
+            stagnant: false,
+            message: `Prior qa marker status is '${lastMarker.status}', not 'failed'.`,
+        };
+    }
+    if (!lastMarker.commitSHA) {
+        return {
+            stagnant: false,
+            message: "Prior qa marker has no commitSHA — cannot compare; fall through.",
+        };
+    }
+    if (lastMarker.commitSHA !== currentSha) {
+        return {
+            stagnant: false,
+            message: `Prior qa SHA ${lastMarker.commitSHA} ≠ HEAD ${currentSha}; new commits since last run.`,
+            priorSha: lastMarker.commitSHA,
+        };
+    }
+    if (isDirty) {
+        return {
+            stagnant: false,
+            message: "Worktree dirty since last qa — uncommitted changes will produce different output.",
+            priorSha: lastMarker.commitSHA,
+        };
+    }
+    return {
+        stagnant: true,
+        reason: "SAME_SHA_NO_PROGRESS",
+        message: `Prior qa failed at HEAD ${currentSha} and worktree is clean — ` +
+            `re-running /qa would produce the same verdict.`,
+        priorSha: lastMarker.commitSHA,
+        priorVerdict: lastMarker.error,
+    };
+}
+/**
+ * Append a stagnation entry to the per-issue record. Schema-additive — older
+ * state files without the field will simply gain it on next write.
+ */
+export async function recordStagnation(issueNumber, entry, options = {}) {
+    const manager = options.statePath !== undefined
+        ? new StateManager(options)
+        : getStateManager(options);
+    await manager.withLock(async () => {
+        const state = await manager.getState();
+        const issueState = state.issues[String(issueNumber)];
+        if (!issueState) {
+            throw new Error(`Cannot record stagnation: issue #${issueNumber} not found in state`);
+        }
+        const existing = issueState.qaStagnation ?? [];
+        existing.push({
+            sha: entry.sha,
+            verdict: entry.verdict,
+            iteration: entry.iteration,
+            reason: entry.reason,
+            detectedAt: new Date().toISOString(),
+        });
+        issueState.qaStagnation = existing;
+        issueState.lastActivity = new Date().toISOString();
+        await manager.saveState(state);
+    });
+}
+/**
+ * Read the worktree's HEAD SHA. Pure wrapper around `git rev-parse HEAD`.
+ */
+export function readHeadSha(cwd = process.cwd()) {
+    return execSync("git rev-parse HEAD", { cwd, encoding: "utf-8" }).trim();
+}
+/**
+ * Returns true when `git status --porcelain` reports any uncommitted change.
+ */
+export function readIsDirty(cwd = process.cwd()) {
+    return (execSync("git status --porcelain", { cwd, encoding: "utf-8" }).trim()
+        .length > 0);
+}
+const STATE_DIR_PREFIX = ".sequant/";
+function readDirtyExcludingState(cwd = process.cwd()) {
+    // `git status --porcelain` (v1) always prefixes each line with exactly
+    // `XY ` (two status bytes + a space) before the path. We must slice on the
+    // RAW line — trimming first strips the leading space of unstaged-only
+    // entries (` M file.ts`) and a subsequent `.{1,3}` regex would chop real
+    // path bytes. See issue #581 QA review.
+    const out = execSync("git status --porcelain", {
+        cwd,
+        encoding: "utf-8",
+    });
+    return out
+        .split("\n")
+        .filter((line) => line.length > 0)
+        .map((line) => {
+        // Renamed entries use `R  old -> new`; we only care about the new path.
+        const path = line.slice(3);
+        const arrow = path.indexOf(" -> ");
+        return arrow >= 0 ? path.slice(arrow + 4) : path;
+    })
+        .filter((path) => !path.startsWith(STATE_DIR_PREFIX));
+}
+export function snapshotLoopProgress(cwd = process.cwd()) {
+    return { sha: readHeadSha(cwd), dirty: readDirtyExcludingState(cwd) };
+}
+/**
+ * Compare two `LoopProgressSnapshot`s. Returns `progressed: false` ONLY when
+ * both the SHA and the (state-excluded) dirty set are unchanged.
+ *
+ * State-file / settings writes are excluded from the dirty comparison per
+ * issue #581's open question — `/loop` may legitimately touch
+ * `.sequant/state.json` without that counting as a fix.
+ */
+export function compareLoopProgress(before, after) {
+    if (before.sha !== after.sha) {
+        return {
+            progressed: true,
+            message: `HEAD advanced ${before.sha} → ${after.sha}.`,
+        };
+    }
+    const beforeSet = new Set(before.dirty);
+    const afterSet = new Set(after.dirty);
+    if (beforeSet.size !== afterSet.size) {
+        return {
+            progressed: true,
+            message: `Working-tree dirty count changed (${beforeSet.size} → ${afterSet.size}).`,
+        };
+    }
+    for (const path of afterSet) {
+        if (!beforeSet.has(path)) {
+            return {
+                progressed: true,
+                message: `New dirty path detected: ${path}.`,
+            };
+        }
+    }
+    return {
+        progressed: false,
+        reason: "LOOP_NO_DIFF",
+        message: "/loop made no commit and no working-tree changes (excluding .sequant/ state writes) — manual intervention required.",
+    };
+}

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

@@ -113,17 +113,7 @@ export type QaSummary = z.infer<typeof QaSummarySchema>;
  * Log entry for a single phase execution
  */
 export declare const PhaseLogSchema: z.ZodObject<{
-    phase: z.ZodEnum<{
-        qa: "qa";
-        loop: "loop";
-        verify: "verify";
-        spec: "spec";
-        "security-review": "security-review";
-        exec: "exec";
-        testgen: "testgen";
-        test: "test";
-        merger: "merger";
-    }>;
+    phase: z.ZodString;
     issueNumber: z.ZodNumber;
     startTime: z.ZodString;
     endTime: z.ZodString;
@@ -199,17 +189,7 @@ export declare const IssueLogSchema: z.ZodObject<{
         partial: "partial";
     }>;
     phases: z.ZodArray<z.ZodObject<{
-        phase: z.ZodEnum<{
-            qa: "qa";
-            loop: "loop";
-            verify: "verify";
-            spec: "spec";
-            "security-review": "security-review";
-            exec: "exec";
-            testgen: "testgen";
-            test: "test";
-            merger: "merger";
-        }>;
+        phase: z.ZodString;
         issueNumber: z.ZodNumber;
         startTime: z.ZodString;
         endTime: z.ZodString;
@@ -280,17 +260,7 @@ export type IssueLog = z.infer<typeof IssueLogSchema>;
  * Run configuration
  */
 export declare const RunConfigSchema: z.ZodObject<{
-    phases: z.ZodArray<z.ZodEnum<{
-        qa: "qa";
-        loop: "loop";
-        verify: "verify";
-        spec: "spec";
-        "security-review": "security-review";
-        exec: "exec";
-        testgen: "testgen";
-        test: "test";
-        merger: "merger";
-    }>>;
+    phases: z.ZodArray<z.ZodString>;
     sequential: z.ZodBoolean;
     qualityLoop: z.ZodBoolean;
     maxIterations: z.ZodNumber;
@@ -319,17 +289,7 @@ export declare const RunLogSchema: z.ZodObject<{
     startTime: z.ZodString;
     endTime: z.ZodString;
     config: z.ZodObject<{
-        phases: z.ZodArray<z.ZodEnum<{
-            qa: "qa";
-            loop: "loop";
-            verify: "verify";
-            spec: "spec";
-            "security-review": "security-review";
-            exec: "exec";
-            testgen: "testgen";
-            test: "test";
-            merger: "merger";
-        }>>;
+        phases: z.ZodArray<z.ZodString>;
         sequential: z.ZodBoolean;
         qualityLoop: z.ZodBoolean;
         maxIterations: z.ZodNumber;
@@ -346,17 +306,7 @@ export declare const RunLogSchema: z.ZodObject<{
             partial: "partial";
         }>;
         phases: z.ZodArray<z.ZodObject<{
-            phase: z.ZodEnum<{
-                qa: "qa";
-                loop: "loop";
-                verify: "verify";
-                spec: "spec";
-                "security-review": "security-review";
-                exec: "exec";
-                testgen: "testgen";
-                test: "test";
-                merger: "merger";
-            }>;
+            phase: z.ZodString;
             issueNumber: z.ZodNumber;
             startTime: z.ZodString;
             endTime: z.ZodString;

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

@@ -6,12 +6,24 @@
  *
  * @module
  */
-import type { ExecutionConfig, IssueResult, RunOptions, ProgressCallback } from "./types.js";
+import type { ExecutionConfig, IssueResult, RunOptions, ProgressCallback, PhasePlanCallback, PhasePauseHandle } from "./types.js";
+import type { RunSnapshot } from "./run-state.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 { LockFile } from "../locks/index.js";
+import { WorkflowEventEmitter } from "./event-emitter.js";
 import type { SequantSettings } from "../settings.js";
+/**
+ * Build the stack-manifest line emitted into PR bodies under --stacked.
+ *
+ * Example for issues `[100, 101, 102]` at `currentIndex=1`:
+ *   `Part of stack: #100 → #101 (this) → #102`
+ *
+ * @internal Exported for testing.
+ */
+export declare function buildStackManifest(issueNumbers: number[], currentIndex: number): string;
 /**
  * Injectable services for RunOrchestrator.
  * All optional — orchestrator degrades gracefully when services are absent.
@@ -45,6 +57,14 @@ export interface OrchestratorConfig {
     baseBranch?: string;
     /** Per-phase progress callback (parallel mode) */
     onProgress?: ProgressCallback;
+    /** #672 AC-2: phase-plan callback forwarded into per-issue contexts. */
+    onPhasePlan?: PhasePlanCallback;
+    /**
+     * Optional live-zone pause handle (#656). Forwarded to every issue's
+     * batch context so `executePhaseWithRetry` can quiesce the renderer
+     * around verbose Claude streaming.
+     */
+    phasePauseHandle?: PhasePauseHandle;
 }
 /**
  * High-level init config for full lifecycle execution.
@@ -64,6 +84,21 @@ export interface RunInit {
     baseBranch?: string;
     /** Per-phase progress callback */
     onProgress?: ProgressCallback;
+    /** #672 AC-2: phase-plan callback. Fired once per issue once the executor
+     * has resolved the final phase pipeline. */
+    onPhasePlan?: PhasePlanCallback;
+    /**
+     * Optional live-zone pause handle (#656). Threaded through to the
+     * `OrchestratorConfig` so verbose Claude streaming pauses the renderer's
+     * live zone instead of redrawing over it.
+     */
+    phasePauseHandle?: PhasePauseHandle;
+    /**
+     * Invoked once the orchestrator is constructed but before execution begins.
+     * Used by the experimental TUI to attach a snapshot poller to the active
+     * orchestrator instance created inside `run()`.
+     */
+    onOrchestratorReady?: (orchestrator: RunOrchestrator) => void;
 }
 /**
  * Pure result of config resolution — no side effects, no services.
@@ -127,7 +162,36 @@ export interface RunResult {
  */
 export declare class RunOrchestrator {
     private readonly cfg;
+    private readonly issueStates;
+    private readonly phaseStartTimes;
+    private readonly emitter;
+    private done;
     constructor(config: OrchestratorConfig);
+    /**
+     * Returns the workflow event emitter. External consumers (TUI, MCP server,
+     * future webhooks) call `getEmitter().on(...)` to subscribe to lifecycle
+     * events. Subscribing is opt-in — the orchestrator runs unaware of who is
+     * listening (#504, AC-3).
+     */
+    getEmitter(): WorkflowEventEmitter;
+    /**
+     * Point-in-time view of the entire run.
+     *
+     * Safe under concurrent reads: the returned object contains only freshly
+     * allocated arrays and plain records; no internal Map or mutable state
+     * reference is leaked. Callers may hold snapshots across awaits without
+     * observing torn writes.
+     */
+    getSnapshot(): RunSnapshot;
+    /**
+     * Mark the run as completed so the dashboard can unmount and drop event
+     * subscribers. Drains the emitter to prevent leaks across multiple
+     * `run()` invocations in the same process (e.g. the MCP server).
+     */
+    markDone(): void;
+    private initIssueStates;
+    private wrapProgress;
+    private applyProgressEvent;
     /**
      * Pure config resolution — no side effects.
      *
@@ -157,5 +221,10 @@ export declare class RunOrchestrator {
     private executeOneIssue;
     private static recordMetrics;
 }
+/**
+ * Build the synthetic `IssueResult` returned for an issue that was skipped
+ * because another sequant session holds its lock (#625).
+ */
+export declare function buildLockedResult(issueNumber: number, holder: LockFile): IssueResult;
 /** Log a non-fatal warning: one-line summary always, detail in verbose. */
 export declare function logNonFatalWarning(message: string, error: unknown, verbose: boolean): void;