sequant 2.1.2 → 2.3.0

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

@@ -9,17 +9,48 @@
 import chalk from "chalk";
 import { spawnSync } from "child_process";
 import pLimit from "p-limit";
+import { formatCoarseNowLine } from "./run-state.js";
 import { detectDefaultBranch, ensureWorktrees, ensureWorktreesChain, getWorktreeDiffStats, } from "./worktree-manager.js";
 import { LogWriter } from "./log-writer.js";
 import { StateManager } from "./state-manager.js";
 import { ShutdownManager } from "../shutdown.js";
-import { getIssueInfo, sortByDependencies, parseBatches, runIssueWithLogging, } from "./batch-executor.js";
+import { LockManager, formatLockedMessage } from "../locks/index.js";
+/** Human-readable line for the run-orchestrator's `--signal-other` log (#637). */
+function formatSignalLine(issue, pid, result) {
+    switch (result.reason) {
+        case "sent":
+            return `  Signaled PID ${pid} (SIGTERM) for #${issue}`;
+        case "cross-host":
+            return `  Could not signal PID ${pid} for #${issue} (cross-host holder)`;
+        case "self-or-parent":
+            return `  Refused to signal PID ${pid} for #${issue} (matches this process or its parent)`;
+        case "pid-dead":
+            return `  Could not signal PID ${pid} for #${issue} (already exited)`;
+        case "kill-failed":
+            return `  Could not signal PID ${pid} for #${issue} (kill syscall failed)`;
+        case "orchestrator":
+            return `  Skipped signal for #${issue} (orchestrator mode)`;
+    }
+}
+import { getIssueInfo, sortByDependencies, parseBatches, runIssueWithLogging, emitRunIdLine, } from "./batch-executor.js";
 import { reconcileStateAtStartup } from "./state-utils.js";
 import { getCommitHash } from "./git-diff-utils.js";
 import { MetricsWriter } from "./metrics-writer.js";
 import { determineOutcome } from "./metrics-schema.js";
 import { getTokenUsageForRun } from "./token-utils.js";
 import { resolveRunOptions, buildExecutionConfig } from "./config-resolver.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 function buildStackManifest(issueNumbers, currentIndex) {
+    const parts = issueNumbers.map((n, i) => i === currentIndex ? `#${n} (this)` : `#${n}`);
+    return `Part of stack: ${parts.join(" → ")}`;
+}
 // ── Orchestrator ────────────────────────────────────────────────────────────
 /**
  * CLI-free workflow execution engine.
@@ -32,25 +63,143 @@ import { resolveRunOptions, buildExecutionConfig } from "./config-resolver.js";
  */
 export class RunOrchestrator {
     cfg;
+    issueStates = new Map();
+    phaseStartTimes = new Map();
+    done = false;
     constructor(config) {
         this.validate(config);
-        this.cfg = config;
+        this.cfg = { ...config, onProgress: this.wrapProgress(config.onProgress) };
+        this.initIssueStates();
     }
     /**
-     * Full lifecycle execution — the primary entry point for programmatic use.
+     * Point-in-time view of the entire run.
      *
-     * Handles: config resolution → services setup → state guard →
-     * issue discovery → worktree creation → execution → metrics → cleanup.
+     * 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.
      */
-    static async run(init, issueArgs, batches) {
-        const { options, settings, manifest, onProgress } = init;
-        // ── Config resolution ──────────────────────────────────────────────
+    getSnapshot() {
+        const { config } = this.cfg;
+        const snapshotConfig = {
+            concurrency: config.concurrency,
+            baseBranch: this.cfg.baseBranch ?? "main",
+            qualityLoop: config.qualityLoop,
+        };
+        const issues = [];
+        for (const state of this.issueStates.values()) {
+            issues.push(cloneIssueState(state));
+        }
+        return {
+            config: snapshotConfig,
+            issues,
+            done: this.done,
+            capturedAt: new Date(),
+        };
+    }
+    /** Mark the run as completed so the dashboard can unmount. */
+    markDone() {
+        this.done = true;
+    }
+    initIssueStates() {
+        const { issueInfoMap, worktreeMap, config } = this.cfg;
+        for (const [num, info] of issueInfoMap.entries()) {
+            const branch = worktreeMap.get(num)?.branch ?? `#${num}`;
+            const phases = config.phases.map((name) => ({
+                name,
+                status: "pending",
+            }));
+            this.issueStates.set(num, {
+                number: num,
+                title: info.title,
+                branch,
+                status: "queued",
+                phases,
+            });
+        }
+    }
+    wrapProgress(external) {
+        return (issue, phase, event, extra) => {
+            this.applyProgressEvent(issue, phase, event, extra);
+            external?.(issue, phase, event, extra);
+        };
+    }
+    applyProgressEvent(issue, phase, event, extra) {
+        const state = this.issueStates.get(issue);
+        if (!state)
+            return;
+        if (event === "start") {
+            if (!state.startedAt)
+                state.startedAt = new Date();
+            state.status = "running";
+            const now = new Date();
+            this.phaseStartTimes.set(`${issue}:${phase}`, now.getTime());
+            state.currentPhase = {
+                name: phase,
+                startedAt: now,
+                lastActivityAt: now,
+                nowLine: formatCoarseNowLine(phase),
+            };
+            const p = findOrAppendPhase(state, phase);
+            p.status = "running";
+            p.startedAt = now;
+            return;
+        }
+        if (event === "activity") {
+            // Ignore activity for stale phases (race between completion and a
+            // final flushed output chunk).
+            if (!state.currentPhase || state.currentPhase.name !== phase)
+                return;
+            const line = extractActivityLine(extra?.text);
+            if (!line)
+                return;
+            state.currentPhase.nowLine = line;
+            state.currentPhase.lastActivityAt = new Date();
+            return;
+        }
+        // complete / failed
+        const key = `${issue}:${phase}`;
+        const startMs = this.phaseStartTimes.get(key);
+        this.phaseStartTimes.delete(key);
+        const elapsedMs = extra?.durationSeconds != null
+            ? extra.durationSeconds * 1000
+            : startMs != null
+                ? Date.now() - startMs
+                : undefined;
+        const p = findOrAppendPhase(state, phase);
+        p.status = event === "complete" ? "done" : "failed";
+        p.elapsedMs = elapsedMs;
+        state.currentPhase = undefined;
+        if (event === "failed") {
+            state.status = "failed";
+            state.completedAt = new Date();
+            return;
+        }
+        // Completed phase: if it's the last phase in the plan, mark issue passed.
+        const allDone = state.phases.every((ph) => ph.status === "done" || ph.status === "failed");
+        if (allDone) {
+            state.status = state.phases.some((ph) => ph.status === "failed")
+                ? "failed"
+                : "passed";
+            state.completedAt = new Date();
+        }
+    }
+    /**
+     * 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, 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 +216,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 +256,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 &&
@@ -106,6 +282,9 @@ export class RunOrchestrator {
                     startCommit: getCommitHash(process.cwd()),
                 });
                 await logWriter.initialize(runConfig);
+                const runId = logWriter.getRunId();
+                if (runId)
+                    emitRunIdLine(runId);
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
@@ -175,6 +354,63 @@ export class RunOrchestrator {
                 }
             }
         }
+        // ── Concurrency lock (#625) ────────────────────────────────────────
+        // Acquired here — after the state guard, before worktree creation — so
+        // that issues already filtered as ready_for_merge don't claim locks they
+        // wouldn't release. Locked issues are skipped from the run with a
+        // synthetic IssueResult so the batch continues.
+        const lockManager = new LockManager();
+        const lockedResults = [];
+        if (!lockManager.isNoop && !config.dryRun) {
+            const commandLabel = `npx sequant run ${issueNumbers.join(" ")}`;
+            const claimed = [];
+            for (const issueNumber of issueNumbers) {
+                const claim = mergedOptions.force
+                    ? (() => {
+                        const { previous } = lockManager.forceAcquire(issueNumber, commandLabel);
+                        if (previous && mergedOptions.signalOther) {
+                            const result = lockManager.signalOther(previous);
+                            console.log(chalk.gray(formatSignalLine(issueNumber, previous.pid, result)));
+                        }
+                        return { acquired: true };
+                    })()
+                    : lockManager.acquire(issueNumber, commandLabel);
+                if (claim.acquired) {
+                    claimed.push(issueNumber);
+                }
+                else {
+                    lockedResults.push(buildLockedResult(issueNumber, claim.holder));
+                    console.log(chalk.yellow(`  !  ${formatLockedMessage(issueNumber, claim.holder)}`));
+                }
+            }
+            issueNumbers = claimed;
+            if (claimed.length > 0) {
+                shutdown.registerCleanup("Release issue locks", async () => {
+                    lockManager.releaseAll();
+                });
+                // Sync cleanup for SIGKILL / uncaughtException paths. process.on('exit')
+                // only fires sync handlers; this is the best-effort safety net for
+                // events ShutdownManager doesn't catch.
+                const exitHandler = () => lockManager.releaseAll();
+                process.on("exit", exitHandler);
+                shutdown.registerCleanup("Detach exit-handler", async () => {
+                    process.off("exit", exitHandler);
+                });
+            }
+            if (issueNumbers.length === 0) {
+                shutdown.dispose();
+                return {
+                    results: lockedResults,
+                    logPath: null,
+                    exitCode: lockedResults.length > 0 ? 1 : 0,
+                    worktreeMap: new Map(),
+                    issueInfoMap: new Map(),
+                    config,
+                    mergedOptions,
+                    logWriter: null,
+                };
+            }
+        }
         // ── Issue info + worktree setup ────────────────────────────────────
         const issueInfoMap = new Map();
         for (const issueNumber of issueNumbers) {
@@ -205,17 +441,18 @@ export class RunOrchestrator {
         }
         // ── Execute ────────────────────────────────────────────────────────
         let results = [];
+        const orchestrator = new RunOrchestrator({
+            config,
+            options: mergedOptions,
+            issueInfoMap,
+            worktreeMap,
+            services: { logWriter, stateManager, shutdownManager: shutdown },
+            packageManager: manifest.packageManager,
+            baseBranch,
+            onProgress,
+        });
+        init.onOrchestratorReady?.(orchestrator);
         try {
-            const orchestrator = new RunOrchestrator({
-                config,
-                options: mergedOptions,
-                issueInfoMap,
-                worktreeMap,
-                services: { logWriter, stateManager, shutdownManager: shutdown },
-                packageManager: manifest.packageManager,
-                baseBranch,
-                onProgress,
-            });
             if (resolvedBatches) {
                 for (let batchIdx = 0; batchIdx < resolvedBatches.length; batchIdx++) {
                     const batch = resolvedBatches[batchIdx];
@@ -248,10 +485,11 @@ export class RunOrchestrator {
                     logNonFatalWarning("  !  Metrics recording failed, continuing...", metricsError, config.verbose);
                 }
             }
+            const allResults = [...lockedResults, ...results];
             return {
-                results,
+                results: allResults,
                 logPath,
-                exitCode: results.some((r) => !r.success) && !config.dryRun ? 1 : 0,
+                exitCode: allResults.some((r) => !r.success) && !config.dryRun ? 1 : 0,
                 worktreeMap,
                 issueInfoMap,
                 config,
@@ -260,6 +498,7 @@ export class RunOrchestrator {
             };
         }
         finally {
+            orchestrator.markDone();
             shutdown.dispose();
         }
     }
@@ -317,11 +556,34 @@ export class RunOrchestrator {
             if (shutdown?.shuttingDown) {
                 break;
             }
+            // #605: under --stacked, non-first PRs target the predecessor branch.
+            // The final PR still targets `main` (AC-3 open-question default) so the
+            // stack can land partially. Manifest renders for every PR in the stack.
+            let predecessorBranch;
+            let stackManifest;
+            if (options.chain && options.stacked) {
+                if (i > 0 && i < issueNumbers.length - 1) {
+                    // Invariant: chain breaks on prior failure (see `break` below), so the
+                    // predecessor's worktree is always in worktreeMap when we reach this
+                    // branch. The optional-chained fallback to undefined is unreachable.
+                    predecessorBranch = this.cfg.worktreeMap.get(issueNumbers[i - 1])?.branch;
+                }
+                else if (i > 0) {
+                    // Last PR: still emit manifest, but base stays main (no predecessor).
+                    // intentionally undefined predecessorBranch
+                }
+                stackManifest = buildStackManifest(issueNumbers, i);
+            }
             const result = await this.executeOneIssue({
                 issueNumber,
                 batchCtx,
                 chain: options.chain
-                    ? { enabled: true, isLast: i === issueNumbers.length - 1 }
+                    ? {
+                        enabled: true,
+                        isLast: i === issueNumbers.length - 1,
+                        predecessorBranch,
+                        stackManifest,
+                    }
                     : undefined,
             });
             results.push(result);
@@ -473,6 +735,97 @@ export class RunOrchestrator {
         }
     }
 }
+function findOrAppendPhase(state, name) {
+    let p = state.phases.find((ph) => ph.name === name);
+    if (!p) {
+        p = { name, status: "pending" };
+        state.phases.push(p);
+    }
+    return p;
+}
+/**
+ * Activity is considered stale (and `nowLine` falls back to the coarse
+ * `running <phase>` form) once it goes this long without an update (#543).
+ */
+const ACTIVITY_STALE_MS = 5_000;
+function cloneIssueState(s) {
+    return {
+        number: s.number,
+        title: s.title,
+        branch: s.branch,
+        status: s.status,
+        startedAt: s.startedAt,
+        completedAt: s.completedAt,
+        phases: s.phases.map((p) => ({
+            name: p.name,
+            status: p.status,
+            startedAt: p.startedAt,
+            elapsedMs: p.elapsedMs,
+        })),
+        currentPhase: s.currentPhase
+            ? {
+                name: s.currentPhase.name,
+                startedAt: s.currentPhase.startedAt,
+                lastActivityAt: s.currentPhase.lastActivityAt,
+                nowLine: nowLineWithStaleFallback(s.currentPhase),
+                logPath: s.currentPhase.logPath,
+            }
+            : undefined,
+    };
+}
+function nowLineWithStaleFallback(current) {
+    const ageMs = Date.now() - current.lastActivityAt.getTime();
+    if (ageMs >= ACTIVITY_STALE_MS) {
+        return formatCoarseNowLine(current.name);
+    }
+    return current.nowLine;
+}
+/**
+ * Reduce a chunk of streamed agent output to a single line suitable for the
+ * activity row. Strips ANSI sequences and trailing whitespace; returns the
+ * last non-empty line, truncated to keep the cell render cheap. Returns
+ * `undefined` when the chunk contains no usable content.
+ */
+function extractActivityLine(raw) {
+    if (!raw)
+        return undefined;
+    // Strip ANSI CSI escapes — covers SGR (colour/bold, `…m`), cursor-movement
+    // and line-clear codes (`\x1b[2K`, `\x1b[G`), and DEC private-mode toggles
+    // (`\x1b[?25l`), any of which can leak through chalk/ink in agent output.
+    // eslint-disable-next-line no-control-regex
+    const cleaned = raw.replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, "");
+    const lines = cleaned.split(/\r?\n/);
+    let last = "";
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const trimmed = lines[i].trim();
+        if (trimmed.length > 0) {
+            last = trimmed;
+            break;
+        }
+    }
+    if (!last)
+        return undefined;
+    // Bound at 200 chars; the TUI truncates further per row width.
+    return last.length > 200 ? last.slice(0, 200) : last;
+}
+/**
+ * Build the synthetic `IssueResult` returned for an issue that was skipped
+ * because another sequant session holds its lock (#625).
+ */
+export function buildLockedResult(issueNumber, holder) {
+    return {
+        issueNumber,
+        success: false,
+        phaseResults: [],
+        abortReason: `locked by PID ${holder.pid}`,
+        locked: {
+            pid: holder.pid,
+            hostname: holder.hostname,
+            startedAt: holder.startedAt,
+            command: holder.command,
+        },
+    };
+}
 /** Log a non-fatal warning: one-line summary always, detail in verbose. */
 export function logNonFatalWarning(message, error, verbose) {
     console.log(chalk.yellow(message));

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

@@ -33,7 +33,7 @@ function analyzeTimingPatterns(input, observations, suggestions) {
         // If spec times are similar (within 30%) despite different issues, flag it
         if (max > 0 && min / max > 0.7 && max - min < 120) {
             observations.push(`Spec times similar across issues (${formatSec(min)}–${formatSec(max)}) despite varying complexity`);
-            suggestions.push("Consider `--phases exec,qa` for simple fixes to skip spec");
+            suggestions.push("Consider `--phases exec,qa` for issues where spec is not adding value (the default includes spec, #533)");
         }
     }
     // Flag individual phases that took unusually long

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

@@ -0,0 +1,71 @@
+/**
+ * Runtime state snapshots for multi-issue dashboard rendering.
+ *
+ * Decouples the TUI from the orchestrator: `getSnapshot()` returns an
+ * immutable, plain-object view of current run state that can be safely
+ * read from a render loop without holding locks.
+ */
+import type { Phase } from "./types.js";
+/** Top-level lifecycle status of a single issue. */
+export type IssueStatus = "queued" | "running" | "passed" | "failed";
+/** Per-phase status within an issue. */
+export type PhaseStatus = "pending" | "running" | "done" | "failed";
+/**
+ * One phase's runtime state.
+ * `elapsedMs` is populated once a phase reaches `done` or `failed`.
+ */
+export interface PhaseRuntimeState {
+    name: string;
+    status: PhaseStatus;
+    startedAt?: Date;
+    elapsedMs?: number;
+}
+/**
+ * State of the currently running phase for an issue.
+ * Populated only while a phase is active. Dashboard consumers render
+ * `nowLine` as the activity row and tick `lastActivityAt` for the stamp.
+ */
+export interface CurrentPhaseState {
+    name: string;
+    startedAt: Date;
+    lastActivityAt: Date;
+    nowLine: string;
+    logPath?: string;
+}
+/** Complete runtime state for a single issue. */
+export interface IssueRuntimeState {
+    number: number;
+    title: string;
+    branch: string;
+    status: IssueStatus;
+    phases: PhaseRuntimeState[];
+    currentPhase?: CurrentPhaseState;
+    startedAt?: Date;
+    completedAt?: Date;
+}
+/** Run-level configuration captured at start for the header. */
+export interface RunSnapshotConfig {
+    concurrency: number;
+    baseBranch: string;
+    baseSha?: string;
+    baseFetchedAt?: Date;
+    qualityLoop: boolean;
+}
+/**
+ * A consistent point-in-time view of the entire run.
+ *
+ * Returned as a freshly-allocated plain object by `getSnapshot()`; callers
+ * may read fields concurrently without further synchronization because no
+ * internal mutable references are leaked.
+ */
+export interface RunSnapshot {
+    config: RunSnapshotConfig;
+    issues: IssueRuntimeState[];
+    done: boolean;
+    capturedAt: Date;
+}
+/**
+ * Format a coarse "now" line for a phase transition.
+ * Used as the M1 default when no finer activity signal exists.
+ */
+export declare function formatCoarseNowLine(phase: Phase | string): string;

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

@@ -0,0 +1,14 @@
+/**
+ * Runtime state snapshots for multi-issue dashboard rendering.
+ *
+ * Decouples the TUI from the orchestrator: `getSnapshot()` returns an
+ * immutable, plain-object view of current run state that can be safely
+ * read from a render loop without holding locks.
+ */
+/**
+ * Format a coarse "now" line for a phase transition.
+ * Used as the M1 default when no finer activity signal exists.
+ */
+export function formatCoarseNowLine(phase) {
+    return `running ${phase}`;
+}

package/dist/src/lib/workflow/state-cleanup.d.ts

@@ -58,9 +58,9 @@ export interface ReconcileOptions {
 export interface ReconcileResult {
     /** Whether reconciliation was successful */
     success: boolean;
-    /** Issues that were advanced from ready_for_merge to merged */
+    /** Issues advanced to `merged` (from `ready_for_merge`, `in_progress`, or `waiting_for_qa_gate`) */
     advanced: number[];
-    /** Issues checked but still ready_for_merge */
+    /** Issues checked but not yet merged (status unchanged) */
     stillPending: number[];
     /** Error message if failed */
     error?: string;
@@ -68,10 +68,18 @@ export interface ReconcileResult {
 /**
  * Lightweight state reconciliation at run start
  *
- * Checks issues in `ready_for_merge` state and advances them to `merged`
- * if their PRs are merged or their branches are in main.
+ * Checks issues in `ready_for_merge`, `in_progress`, or `waiting_for_qa_gate`
+ * state and advances them to `merged` if their PRs are merged or their branches
+ * are in main.
  *
- * This prevents re-running already completed issues.
+ * Including `in_progress` covers the case where a PR was merged outside
+ * this sequant session (separate process, `gh pr merge`, web UI) — without
+ * it, the run command would re-execute already-merged issues. See #592.
+ *
+ * Including `waiting_for_qa_gate` covers the symmetric case where a PR
+ * awaiting human QA-gate approval is merged externally before the next
+ * sequant session — without it, `sequant run <N>` re-executes the QA phase
+ * against already-merged work. See #606.
  *
  * @param options - Reconciliation options
  * @returns Result with lists of advanced and still-pending issues