sequant 2.2.0 → 2.3.0

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

@@ -12,11 +12,11 @@
  */
 export const UI_LABELS = ["ui", "frontend", "admin", "web", "browser"];
 /**
- * Bug-related labels that skip spec phase
+ * Bug-related labels (used by downstream metadata consumers)
  */
 export const BUG_LABELS = ["bug", "fix", "hotfix", "patch"];
 /**
- * Documentation labels that skip spec phase
+ * Documentation labels (used for issueType propagation and downstream metadata)
  */
 export const DOCS_LABELS = ["docs", "documentation", "readme"];
 /**
@@ -38,30 +38,19 @@ export const SECURITY_LABELS = [
  */
 export function detectPhasesFromLabels(labels) {
     const lowerLabels = labels.map((l) => l.toLowerCase());
-    // Check for bug/fix labels → exec → qa (skip spec)
-    const isBugFix = lowerLabels.some((label) => BUG_LABELS.some((bugLabel) => label === bugLabel));
-    // Check for docs labels → exec → qa (skip spec)
-    const isDocs = lowerLabels.some((label) => DOCS_LABELS.some((docsLabel) => label === docsLabel));
     // Check for UI labels → add test phase
     const isUI = lowerLabels.some((label) => UI_LABELS.some((uiLabel) => label === uiLabel));
     // Check for complex labels → enable quality loop
     const isComplex = lowerLabels.some((label) => COMPLEX_LABELS.some((complexLabel) => label === complexLabel));
     // Check for security labels → add security-review phase
     const isSecurity = lowerLabels.some((label) => SECURITY_LABELS.some((secLabel) => label === secLabel));
-    // Build phase list
-    let phases;
-    if (isBugFix || isDocs) {
-        // Simple workflow: exec → qa
-        phases = ["exec", "qa"];
-    }
-    else if (isUI) {
-        // UI workflow: spec → exec → test → qa
-        phases = ["spec", "exec", "test", "qa"];
-    }
-    else {
-        // Standard workflow: spec → exec → qa
-        phases = ["spec", "exec", "qa"];
-    }
+    // Build phase list — spec is always included by default (#533).
+    // Bug/docs labels no longer short-circuit spec; downstream consumers
+    // (e.g. `issueType: "docs"` propagation) still use DOCS_LABELS for
+    // metadata purposes, not for phase selection.
+    const phases = isUI
+        ? ["spec", "exec", "test", "qa"]
+        : ["spec", "exec", "qa"];
     // Add security-review phase after spec if security labels detected
     if (isSecurity && phases.includes("spec")) {
         const specIndex = phases.indexOf("spec");
@@ -132,6 +121,14 @@ export function determinePhasesForIssue(basePhases, labels, options) {
             phases.splice(specIndex + 1, 0, "testgen");
         }
     }
+    // Add security-review phase after spec if requested.
+    // Idempotent vs label-based auto-detection in detectPhasesFromLabels.
+    if (options.securityReview && phases.includes("spec")) {
+        const specIndex = phases.indexOf("spec");
+        if (!phases.includes("security-review")) {
+            phases.splice(specIndex + 1, 0, "security-review");
+        }
+    }
     // Auto-detect UI issues and add test phase
     if (hasUILabels(labels) && !phases.includes("test")) {
         // Add test phase before qa if present, otherwise at the end

package/dist/src/lib/workflow/platforms/github.d.ts

@@ -94,7 +94,7 @@ export declare class GitHubProvider implements PlatformProvider {
      * Create a PR via `gh pr create` CLI, returning raw result.
      * Used by worktree-manager.ts which needs access to stdout for URL extraction.
      */
-    createPRCliSync(title: string, body: string, head: string, cwd?: string): CreatePRCliResult;
+    createPRCliSync(title: string, body: string, head: string, cwd?: string, base?: string): CreatePRCliResult;
     /**
      * Batch fetch issue and PR status in a single GraphQL call.
      * Returns a map keyed by issue/PR number.

package/dist/src/lib/workflow/platforms/github.js

@@ -137,8 +137,25 @@ export class GitHubProvider {
      * Create a PR via `gh pr create` CLI, returning raw result.
      * Used by worktree-manager.ts which needs access to stdout for URL extraction.
      */
-    createPRCliSync(title, body, head, cwd) {
-        const result = spawnSync("gh", ["pr", "create", "--title", title, "--body", body, "--head", head], { stdio: "pipe", cwd, timeout: 30000 });
+    createPRCliSync(title, body, head, cwd, base) {
+        const args = [
+            "pr",
+            "create",
+            "--title",
+            title,
+            "--body",
+            body,
+            "--head",
+            head,
+        ];
+        if (base) {
+            args.push("--base", base);
+        }
+        const result = spawnSync("gh", args, {
+            stdio: "pipe",
+            cwd,
+            timeout: 30000,
+        });
         return {
             stdout: result.stdout?.toString() ?? "",
             stderr: result.stderr?.toString() ?? "",
@@ -415,7 +432,7 @@ export class GitHubProvider {
         });
     }
     async createPR(opts) {
-        const result = this.createPRCliSync(opts.title, opts.body, opts.head);
+        const result = this.createPRCliSync(opts.title, opts.body, opts.head, undefined, opts.base);
         if (result.exitCode !== 0) {
             const error = result.stderr.trim() || "Unknown error";
             throw new Error(`gh pr create failed: ${error}`);

package/dist/src/lib/workflow/pr-status.d.ts

@@ -28,16 +28,32 @@ export declare function checkPRMergeStatus(prNumber: number): PRMergeStatus;
 /**
  * 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 declare function isBranchMergedIntoMain(branchName: string, baseBranch?: string): boolean;
 /**
  * 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/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-orchestrator.d.ts

@@ -7,11 +7,22 @@
  * @module
  */
 import type { ExecutionConfig, IssueResult, RunOptions, ProgressCallback } 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 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.
@@ -64,6 +75,12 @@ export interface RunInit {
     baseBranch?: string;
     /** Per-phase progress callback */
     onProgress?: ProgressCallback;
+    /**
+     * 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 +144,24 @@ export interface RunResult {
  */
 export declare class RunOrchestrator {
     private readonly cfg;
+    private readonly issueStates;
+    private readonly phaseStartTimes;
+    private done;
     constructor(config: OrchestratorConfig);
+    /**
+     * 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. */
+    markDone(): void;
+    private initIssueStates;
+    private wrapProgress;
+    private applyProgressEvent;
     /**
      * Pure config resolution — no side effects.
      *
@@ -157,5 +191,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;