sequant 2.8.0 → 2.9.0

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

@@ -10,7 +10,7 @@ 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 { detectDefaultBranch, ensureWorktrees, ensureWorktreesChain, getWorktreeDiffStats, rebaseOntoLocalBranch, } from "./worktree-manager.js";
 import { LogWriter } from "./log-writer.js";
 import { StateManager } from "./state-manager.js";
 import { ShutdownManager } from "../shutdown.js";
@@ -33,14 +33,53 @@ function formatSignalLine(issue, pid, result) {
             return `  Skipped signal for #${issue} (orchestrator mode)`;
     }
 }
+/**
+ * Resolve a git ref (branch name or base branch) to its tip commit SHA in the
+ * current repo, or undefined if the ref does not exist. Used by the chain
+ * resume planner (#760) to reconstruct — and validate the existence of — a
+ * completed link's committed tip.
+ */
+function revParseRef(ref) {
+    const result = spawnSync("git", ["rev-parse", "--verify", "--quiet", ref], {
+        stdio: "pipe",
+        encoding: "utf-8",
+    });
+    if (result.status !== 0) {
+        return undefined;
+    }
+    const sha = result.stdout.trim();
+    return sha.length > 0 ? sha : undefined;
+}
+/**
+ * True iff `worktreePath` has uncommitted changes (`git status --porcelain`,
+ * which already honours .gitignore). Used by the chain resume planner (#760) to
+ * reject a resume base whose checkpoint commit never landed.
+ *
+ * Returns false when the path is missing or not a worktree: an unreadable
+ * worktree can't be judged dirty, and the branch-tip check already covers the
+ * destroyed-link case.
+ */
+function isWorktreeDirty(worktreePath) {
+    const result = spawnSync("git", ["-C", worktreePath, "status", "--porcelain"], {
+        stdio: "pipe",
+        encoding: "utf-8",
+    });
+    if (result.status !== 0) {
+        return false;
+    }
+    return result.stdout.trim().length > 0;
+}
 import { getIssueInfo, sortByDependencies, parseBatches, runIssueWithLogging, emitRunIdLine, } from "./batch-executor.js";
 import { reconcileStateAtStartup } from "./state-utils.js";
+import { runChainPreflight } from "./chain-preflight.js";
 import { getCommitHash } from "./git-diff-utils.js";
+import { planChainResumeFromState, } from "./chain-resume.js";
 import { MetricsWriter } from "./metrics-writer.js";
 import { WorkflowEventEmitter } from "./event-emitter.js";
 import { determineOutcome } from "./metrics-schema.js";
 import { getTokenUsageForRun } from "./token-utils.js";
 import { resolveRunOptions, buildExecutionConfig } from "./config-resolver.js";
+import { pipelineHasFailed } from "./status-derivation.js";
 /**
  * Build the stack-manifest line emitted into PR bodies under --stacked.
  *
@@ -218,8 +257,15 @@ export class RunOrchestrator {
         const durationSec = elapsedMs !== undefined ? Math.round(elapsedMs / 1000) : undefined;
         if (event === "failed") {
             const prev = state.status;
-            state.status = "failed";
-            state.completedAt = new Date();
+            // #766: a loop-phase failure alone must not pin the issue `failed` — the
+            // outer quality loop may still recover on a later iteration. Derive from
+            // the phase slots (loop excluded) so only a genuine non-loop failure marks
+            // the issue failed; otherwise hold `running` until a later event reaches a
+            // terminal verdict (a subsequent iteration always follows a loop failure).
+            const nowFailed = pipelineHasFailed(state.phases);
+            state.status = nowFailed ? "failed" : "running";
+            if (nowFailed)
+                state.completedAt = new Date();
             void this.emitter.emit("phase_failed", {
                 issueNumber: issue,
                 phase,
@@ -227,11 +273,11 @@ export class RunOrchestrator {
                 error: extra?.error ?? "unknown",
                 iteration: extra?.iteration,
             });
-            if (prev !== "failed") {
+            if (prev !== state.status) {
                 void this.emitter.emit("issue_status_changed", {
                     issueNumber: issue,
                     from: prev,
-                    to: "failed",
+                    to: state.status,
                 });
             }
             return;
@@ -246,9 +292,10 @@ export class RunOrchestrator {
         const allDone = state.phases.every((ph) => ph.status === "done" || ph.status === "failed");
         if (allDone) {
             const prev = state.status;
-            state.status = state.phases.some((ph) => ph.status === "failed")
-                ? "failed"
-                : "passed";
+            // #766: exclude a stale failed `loop` slot so a run that failed the loop
+            // on an early iteration and then recovered finalizes as `passed`, not
+            // `failed`. An unrecovered failure still leaves a non-loop phase failed.
+            state.status = pipelineHasFailed(state.phases) ? "failed" : "passed";
             state.completedAt = new Date();
             if (prev !== state.status) {
                 void this.emitter.emit("issue_status_changed", {
@@ -291,6 +338,8 @@ export class RunOrchestrator {
                 .map((i) => parseInt(i, 10))
                 .filter((n) => !isNaN(n));
         }
+        // Capture the raw CLI order before dep-sorting (#762 pre-flight needs it).
+        const rawIssueOrder = [...issueNumbers];
         if (issueNumbers.length > 1 && !resolvedBatches) {
             issueNumbers = sortByDependencies(issueNumbers);
         }
@@ -302,6 +351,7 @@ export class RunOrchestrator {
             mergedOptions,
             config,
             issueNumbers,
+            rawIssueOrder,
             batches: resolvedBatches,
             baseBranch,
             stack: manifest.stack,
@@ -392,29 +442,46 @@ export class RunOrchestrator {
                 logNonFatalWarning("  !  State reconciliation failed, continuing...", error, config.verbose);
             }
         }
+        let chainResume;
         if (stateManager && !config.dryRun && !mergedOptions.force) {
-            const activeIssues = [];
-            for (const issueNumber of issueNumbers) {
-                try {
-                    const issueState = await stateManager.getIssueState(issueNumber);
-                    if (issueState &&
-                        (issueState.status === "ready_for_merge" ||
-                            issueState.status === "merged")) {
-                        console.log(chalk.yellow(`  !  #${issueNumber}: already ${issueState.status} — skipping (use --force to re-run)`));
-                    }
-                    else {
-                        activeIssues.push(issueNumber);
-                    }
-                }
-                catch (error) {
-                    logNonFatalWarning(`  !  State lookup failed for #${issueNumber}, including anyway...`, error, config.verbose);
-                    activeIssues.push(issueNumber);
+            if (mergedOptions.chain) {
+                // ── Chain-aware resume (#760) ──────────────────────────────────
+                // Don't just drop completed links (chain-unaware skip leaves the
+                // first incomplete link at index 0, where the #748 successor-rebase
+                // never fires → it silently builds on main). Instead compute a
+                // chain-correct plan that resumes at the first incomplete link,
+                // rebased onto the completed prefix's committed tip.
+                const resolver = {
+                    resolveBranchTip: (branch) => revParseRef(branch),
+                    resolveBaseTip: () => revParseRef(baseBranch),
+                    isWorktreeDirty,
+                };
+                const plan = await planChainResumeFromState(issueNumbers, baseBranch, (issueNumber) => stateManager.getIssueState(issueNumber), resolver, (issueNumber, error) => logNonFatalWarning(`  !  State lookup failed for #${issueNumber}, treating as incomplete...`, error, config.verbose));
+                if (plan.failFast) {
+                    console.log(chalk.red(`\n  ❌ Chain resume aborted: ${plan.failFast}`));
+                    shutdown.dispose();
+                    return {
+                        results: [
+                            {
+                                issueNumber: plan.resumeIssue ?? issueNumbers[0],
+                                success: false,
+                                phaseResults: [],
+                                durationSeconds: 0,
+                                loopTriggered: false,
+                                abortReason: `chain resume aborted: ${plan.failFast}`,
+                            },
+                        ],
+                        logPath: null,
+                        exitCode: 1,
+                        worktreeMap: new Map(),
+                        issueInfoMap: new Map(),
+                        config,
+                        mergedOptions,
+                        logWriter: null,
+                    };
                 }
-            }
-            if (activeIssues.length < issueNumbers.length) {
-                issueNumbers = activeIssues;
-                if (issueNumbers.length === 0) {
-                    console.log(chalk.yellow(`\n  All issues already completed. Use --force to re-run.`));
+                if (plan.allComplete) {
+                    console.log(chalk.yellow(`\n  All chain links already completed. Use --force to re-run.`));
                     shutdown.dispose();
                     return {
                         results: [],
@@ -427,6 +494,56 @@ export class RunOrchestrator {
                         logWriter: null,
                     };
                 }
+                if (plan.skipped.length > 0) {
+                    chainResume = plan;
+                    issueNumbers = plan.active;
+                    const resumeAt = plan.resumeBaseCommit
+                        ? plan.resumeBaseCommit.slice(0, 8)
+                        : (plan.resumeBase ?? "base");
+                    for (const s of plan.skipped) {
+                        console.log(chalk.yellow(`  !  #${s.issueNumber}: already ${s.status} — skipping (use --force to re-run)`));
+                    }
+                    console.log(chalk.cyan(`  ↻ Resuming chain at #${plan.resumeIssue} from ${resumeAt}` +
+                        ` (${plan.resumeBase})`));
+                }
+            }
+            else {
+                // ── Non-chain skip guard (unchanged) ───────────────────────────
+                const activeIssues = [];
+                for (const issueNumber of issueNumbers) {
+                    try {
+                        const issueState = await stateManager.getIssueState(issueNumber);
+                        if (issueState &&
+                            (issueState.status === "ready_for_merge" ||
+                                issueState.status === "merged")) {
+                            console.log(chalk.yellow(`  !  #${issueNumber}: already ${issueState.status} — skipping (use --force to re-run)`));
+                        }
+                        else {
+                            activeIssues.push(issueNumber);
+                        }
+                    }
+                    catch (error) {
+                        logNonFatalWarning(`  !  State lookup failed for #${issueNumber}, including anyway...`, error, config.verbose);
+                        activeIssues.push(issueNumber);
+                    }
+                }
+                if (activeIssues.length < issueNumbers.length) {
+                    issueNumbers = activeIssues;
+                    if (issueNumbers.length === 0) {
+                        console.log(chalk.yellow(`\n  All issues already completed. Use --force to re-run.`));
+                        shutdown.dispose();
+                        return {
+                            results: [],
+                            logPath: null,
+                            exitCode: 0,
+                            worktreeMap: new Map(),
+                            issueInfoMap: new Map(),
+                            config,
+                            mergedOptions,
+                            logWriter: null,
+                        };
+                    }
+                }
             }
         }
         // ── Concurrency lock (#625) ────────────────────────────────────────
@@ -486,6 +603,37 @@ export class RunOrchestrator {
                 };
             }
         }
+        // ── Chain content pre-flight (#762) ────────────────────────────────
+        // Warn-by-default; `--strict-preflight` turns warnings fatal. Runs BEFORE
+        // any worktree is provisioned. Uses the RAW CLI order (not the dep-sorted
+        // `issueNumbers`) so the dependency-order / file-overlap checks aren't
+        // masked by `sortByDependencies`, filtered to issues still active after the
+        // state guard / lock acquisition.
+        if (mergedOptions.chain && issueNumbers.length > 1) {
+            const activeSet = new Set(issueNumbers);
+            const preflightOrder = resolved.rawIssueOrder.filter((n) => activeSet.has(n));
+            const preflightWarnings = await runChainPreflight(preflightOrder);
+            if (preflightWarnings.length > 0) {
+                for (const w of preflightWarnings) {
+                    bracketedConsoleLog(phasePauseHandle, chalk.yellow(`  ⚠ ${w.message}`));
+                }
+                if (mergedOptions.strictPreflight) {
+                    bracketedConsoleLog(phasePauseHandle, chalk.red(`\n  ✖ --strict-preflight: ${preflightWarnings.length} pre-flight ` +
+                        `warning(s) — aborting before any worktree is provisioned.`));
+                    shutdown.dispose();
+                    return {
+                        results: [],
+                        logPath: null,
+                        exitCode: 1,
+                        worktreeMap: new Map(),
+                        issueInfoMap: new Map(),
+                        config,
+                        mergedOptions,
+                        logWriter: null,
+                    };
+                }
+            }
+        }
         // ── Issue info + worktree setup ────────────────────────────────────
         const issueInfoMap = new Map();
         for (const issueNumber of issueNumbers) {
@@ -499,7 +647,11 @@ export class RunOrchestrator {
                 title: issueInfoMap.get(num)?.title || `Issue #${num}`,
             }));
             if (mergedOptions.chain) {
-                worktreeMap = await ensureWorktreesChain(issueData, config.verbose, manifest.packageManager, baseBranch);
+                // On resume (#760), provision the first incomplete link from the
+                // completed prefix's committed tip (resumeBase) instead of the base
+                // branch, so the chain rebuilds onto the work already done.
+                const chainBase = chainResume?.resumeBase ?? baseBranch;
+                worktreeMap = await ensureWorktreesChain(issueData, config.verbose, manifest.packageManager, chainBase);
             }
             else {
                 worktreeMap = await ensureWorktrees(issueData, config.verbose, manifest.packageManager, baseBranch);
@@ -524,6 +676,7 @@ export class RunOrchestrator {
             services: { logWriter, stateManager, shutdownManager: shutdown },
             packageManager: manifest.packageManager,
             baseBranch,
+            chainResume,
             onProgress,
             onPhasePlan: init.onPhasePlan,
             phasePauseHandle,
@@ -639,6 +792,108 @@ export class RunOrchestrator {
             if (shutdown?.shuttingDown) {
                 break;
             }
+            // #760: On chain resume, the completed prefix was skipped, so the first
+            // active link (i === 0) is now the resume point. The #748 successor-rebase
+            // below only fires for i > 0, so explicitly rebase this first link onto
+            // the last completed link's committed tip (resumeBase). This is the
+            // authoritative correctness gate: provisioning may have created the
+            // worktree fresh (already on resumeBase → no-op) or rebased an existing
+            // one, but a provisioning-time rebase failure only warns and continues —
+            // here we fail fast so the link never silently executes on the wrong base.
+            const chainResume = this.cfg.chainResume;
+            if (options.chain && i === 0 && chainResume?.resumeBase) {
+                const activeWorktree = this.cfg.worktreeMap.get(issueNumber);
+                if (activeWorktree) {
+                    const rebase = rebaseOntoLocalBranch(activeWorktree.path, chainResume.resumeBase, this.cfg.config.verbose);
+                    if (!rebase.success) {
+                        console.log(chalk.yellow(`  ⚠️  Chain resume broken: could not rebase #${issueNumber} onto resume base ${chainResume.resumeBase}` +
+                            (rebase.conflict ? " — merge conflict" : "") +
+                            `. Stopping the chain; #${issueNumber} and any later issues were not run.`));
+                        results.push({
+                            issueNumber,
+                            success: false,
+                            phaseResults: [],
+                            durationSeconds: 0,
+                            loopTriggered: false,
+                            abortReason: rebase.conflict
+                                ? `chain resume rebase conflict onto ${chainResume.resumeBase}`
+                                : `chain resume rebase failed onto ${chainResume.resumeBase}: ${rebase.error ?? "unknown error"}`,
+                        });
+                        break;
+                    }
+                }
+                else {
+                    console.log(chalk.yellow(`  ⚠️  Chain resume broken: no worktree for #${issueNumber}. ` +
+                        `Stopping the chain; #${issueNumber} and any later issues were not run.`));
+                    results.push({
+                        issueNumber,
+                        success: false,
+                        phaseResults: [],
+                        durationSeconds: 0,
+                        loopTriggered: false,
+                        abortReason: `chain resume could not be established: missing worktree for #${issueNumber}`,
+                    });
+                    break;
+                }
+            }
+            // #748: Successors were provisioned up-front (ensureWorktreesChain) while
+            // the predecessor branch still pointed at the base, so on a fresh run each
+            // successor effectively branched from main. Now that the predecessor has
+            // executed and committed, re-rebase this successor's worktree onto the
+            // predecessor's *local* committed tip — independent of --stacked, and
+            // targeting the local feature branch (not origin/main). This is what makes
+            // the chain contract ("each branches from previous") actually hold.
+            if (options.chain && i > 0) {
+                const successorWorktree = this.cfg.worktreeMap.get(issueNumber);
+                const predecessorLocalBranch = this.cfg.worktreeMap.get(issueNumbers[i - 1])?.branch;
+                if (successorWorktree && predecessorLocalBranch) {
+                    const rebase = rebaseOntoLocalBranch(successorWorktree.path, predecessorLocalBranch, this.cfg.config.verbose);
+                    if (!rebase.success) {
+                        // A broken chain link must NOT silently produce a successor built on
+                        // the wrong base — that successor would miss the predecessor's work
+                        // (the original #748 bug) and the break would propagate to every
+                        // downstream successor. Treat it like a predecessor failure: warn
+                        // loudly, record the break, and stop the chain so a human can
+                        // resolve the conflict and re-run.
+                        console.log(chalk.yellow(`  ⚠️  Chain link broken: could not rebase #${issueNumber} onto #${issueNumbers[i - 1]} (${predecessorLocalBranch})` +
+                            (rebase.conflict ? " — merge conflict" : "") +
+                            `. Stopping the chain; #${issueNumber} and any later issues were not run.`));
+                        results.push({
+                            issueNumber,
+                            success: false,
+                            phaseResults: [],
+                            durationSeconds: 0,
+                            loopTriggered: false,
+                            abortReason: rebase.conflict
+                                ? `chain rebase conflict onto #${issueNumbers[i - 1]} (${predecessorLocalBranch})`
+                                : `chain rebase failed onto #${issueNumbers[i - 1]} (${predecessorLocalBranch}): ${rebase.error ?? "unknown error"}`,
+                        });
+                        break;
+                    }
+                }
+                else {
+                    // The worktree map is expected to be fully populated for a chain (the
+                    // --stacked block below treats a missing predecessor branch as
+                    // unreachable). If it isn't, the successor cannot be chained onto its
+                    // predecessor's work — the same end state as a rebase conflict — so we
+                    // break the chain identically rather than letting the successor
+                    // silently branch from its un-rebased base (the original #748 bug).
+                    const missing = !successorWorktree
+                        ? "successor worktree"
+                        : `predecessor branch for #${issueNumbers[i - 1]}`;
+                    console.log(chalk.yellow(`  ⚠️  Chain link could not be established for #${issueNumber}: missing ${missing} in worktree map. ` +
+                        `Stopping the chain; #${issueNumber} and any later issues were not run.`));
+                    results.push({
+                        issueNumber,
+                        success: false,
+                        phaseResults: [],
+                        durationSeconds: 0,
+                        loopTriggered: false,
+                        abortReason: `chain link could not be established onto #${issueNumbers[i - 1]}: missing ${missing} in worktree map`,
+                    });
+                    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.
@@ -826,6 +1081,11 @@ export class RunOrchestrator {
             cliFlags.push("--testgen");
         const tokenUsage = getTokenUsageForRun(undefined, true);
         const passed = results.filter((r) => r.success).length;
+        // #761 AC-7: record why the run failed, as a bounded enum. Sequential and
+        // chain runs halt at the first failure, so the first categorized failed
+        // issue is the halting one; in parallel runs it is the earliest-listed
+        // failure. Undefined on success — the field is omitted from the record.
+        const failureCategory = results.find((r) => !r.success && r.failureCategory)?.failureCategory;
         await metricsWriter.recordRun({
             issues: issueNumbers,
             phases: Array.from(allPhases),
@@ -833,6 +1093,7 @@ export class RunOrchestrator {
             duration: totalDuration,
             model: process.env.ANTHROPIC_MODEL ?? "opus",
             flags: cliFlags,
+            failureCategory,
             metrics: {
                 tokensUsed: tokenUsage.tokensUsed,
                 filesChanged: totalFilesChanged,

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

@@ -0,0 +1,30 @@
+/**
+ * Shared status derivation for the run's live state machines (#766).
+ *
+ * Both the orchestrator's `IssueRuntimeState` machine and the renderer's
+ * `IssueState` machine used to *pin* an issue `failed` on any phase failure and
+ * never de-escalate — so a phase that failed on an early quality-loop iteration
+ * left the card red even after a later iteration recovered and shipped the PR.
+ *
+ * The fix derives the failed verdict from the CURRENT phase slots instead.
+ * `findOrAppendPhase` (orchestrator) and the renderer both key phases by name,
+ * so a retried phase overwrites its slot with the latest attempt — the slot
+ * already holds "the last attempt". The one phase that is NOT overwritten on
+ * recovery is `loop`: it is an auxiliary recovery step that only runs after a
+ * failure, so a stale failed `loop` slot must not pin the issue. Excluding
+ * `loop` never hides a genuine failure — an unrecovered pipeline failure always
+ * leaves a non-loop phase's latest slot failed too (the qa/exec the loop was
+ * trying to fix).
+ */
+/** Auxiliary recovery phase — excluded from the failed verdict (see above). */
+export declare const LOOP_PHASE = "loop";
+/** Minimal phase shape both live state machines satisfy. */
+export interface DerivablePhase {
+    name: string;
+    status: string;
+}
+/**
+ * True iff a non-loop phase's latest slot is `failed`. The single source of
+ * truth for "is this issue failed" across both live state machines (#766 AC-2).
+ */
+export declare function pipelineHasFailed(phases: DerivablePhase[]): boolean;

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

@@ -0,0 +1,27 @@
+/**
+ * Shared status derivation for the run's live state machines (#766).
+ *
+ * Both the orchestrator's `IssueRuntimeState` machine and the renderer's
+ * `IssueState` machine used to *pin* an issue `failed` on any phase failure and
+ * never de-escalate — so a phase that failed on an early quality-loop iteration
+ * left the card red even after a later iteration recovered and shipped the PR.
+ *
+ * The fix derives the failed verdict from the CURRENT phase slots instead.
+ * `findOrAppendPhase` (orchestrator) and the renderer both key phases by name,
+ * so a retried phase overwrites its slot with the latest attempt — the slot
+ * already holds "the last attempt". The one phase that is NOT overwritten on
+ * recovery is `loop`: it is an auxiliary recovery step that only runs after a
+ * failure, so a stale failed `loop` slot must not pin the issue. Excluding
+ * `loop` never hides a genuine failure — an unrecovered pipeline failure always
+ * leaves a non-loop phase's latest slot failed too (the qa/exec the loop was
+ * trying to fix).
+ */
+/** Auxiliary recovery phase — excluded from the failed verdict (see above). */
+export const LOOP_PHASE = "loop";
+/**
+ * True iff a non-loop phase's latest slot is `failed`. The single source of
+ * truth for "is this issue failed" across both live state machines (#766 AC-2).
+ */
+export function pipelineHasFailed(phases) {
+    return phases.some((p) => p.name !== LOOP_PHASE && p.status === "failed");
+}

package/dist/src/lib/workflow/types.d.ts

@@ -8,6 +8,7 @@ import type { StateManager } from "./state-manager.js";
 import type { ShutdownManager } from "../shutdown.js";
 import type { WorktreeInfo } from "./worktree-manager.js";
 import type { SequantError } from "../errors.js";
+import type { ErrorCategory } from "./error-classifier.js";
 export type { WorkflowEventEmitter, WorkflowEvents, WorkflowEventListener, IssueEventStatus, BaseEventPayload, RunEventPayload, PhaseStartedPayload, PhaseCompletedPayload, PhaseFailedPayload, IssueStatusChangedPayload, QaVerdictPayload, ProgressPayload, } from "./event-emitter.js";
 /**
  * Canonical Zod schema for all workflow phases.
@@ -216,6 +217,21 @@ export interface IssueResult {
         startedAt: string;
         command: string;
     };
+    /**
+     * Set true when the chain-mode checkpoint commit could not be written after
+     * this link passed QA (#760). The link's own work is done, but the recovery
+     * point resume depends on is missing — surfaced prominently so a later resume
+     * failing fast (AC-3) is expected, not surprising.
+     */
+    checkpointFailed?: boolean;
+    /**
+     * Bounded-enum classification of the failure that halted this issue (#761
+     * AC-7), derived from the last non-loop failing phase's `structuredError`
+     * (preferred) or stderr-regex classification. Carried into
+     * `.sequant/metrics.json` — enum only, never a message string (metrics
+     * privacy contract). Absent on success.
+     */
+    failureCategory?: ErrorCategory;
 }
 /**
  * CLI options for the run command, merged with settings and env config.
@@ -265,6 +281,13 @@ export interface RunOptions {
      * from building on potentially broken code.
      */
     qaGate?: boolean;
+    /**
+     * Make `--chain` content pre-flight warnings fatal (#762).
+     * By default the pre-flight (missing AC section, dependency-order and
+     * file-overlap-order contradictions, closed issues) only warns. When true,
+     * any warning aborts the run BEFORE the first worktree is provisioned.
+     */
+    strictPreflight?: boolean;
     /**
      * Base branch for worktree creation.
      * Resolution priority: this CLI flag → settings.run.defaultBase → 'main'

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

@@ -43,6 +43,19 @@ export interface RebaseResult {
     /** Error message if rebase failed */
     error?: string;
 }
+/**
+ * Result of rebasing a worktree onto a local branch (chain successor → predecessor).
+ */
+export interface LocalRebaseResult {
+    /** Whether the rebase was attempted */
+    performed: boolean;
+    /** Whether the rebase succeeded (branch now contains `ontoBranch`'s commits) */
+    success: boolean;
+    /** Whether a merge conflict caused the rebase to be aborted */
+    conflict: boolean;
+    /** Error message if the rebase failed */
+    error?: string;
+}
 /**
  * Result of PR creation
  */
@@ -176,6 +189,17 @@ export declare function createCheckpointCommit(worktreePath: string, issueNumber
  * @internal Exported for testing
  */
 export declare function reinstallIfLockfileChanged(worktreePath: string, packageManager: string | undefined, verbose: boolean, preRebaseRef?: string): boolean;
+/**
+ * Rebase a worktree's branch onto a *local* branch ref (e.g. a chain
+ * predecessor's feature branch), NOT origin/main. Used to chain a successor
+ * onto its predecessor's committed work at execution time (#748), and to
+ * re-chain a pre-existing worktree onto its chain base.
+ *
+ * On conflict, aborts the rebase to restore the original branch state and
+ * returns `{ success: false, conflict: true }` so callers can warn rather than
+ * silently treat a broken link as healthy.
+ */
+export declare function rebaseOntoLocalBranch(worktreePath: string, ontoBranch: string, verbose?: boolean): LocalRebaseResult;
 /**
  * Rebase the worktree branch onto the base branch before PR creation.
  * This ensures the branch is up-to-date and prevents lockfile drift.
@@ -189,6 +213,24 @@ export declare function reinstallIfLockfileChanged(worktreePath: string, package
  * @internal Exported for testing
  */
 export declare function rebaseBeforePR(worktreePath: string, issueNumber: number, packageManager: string | undefined, verbose: boolean, baseBranch?: string): RebaseResult;
+/**
+ * Build the automated PR body for `sequant run`.
+ *
+ * Pure and I/O-free, kept separate from {@link createPR} (which shells out to
+ * `gh`) so the body — including the non-A+ QA note (#749) — is unit-testable
+ * directly.
+ *
+ * @param issueNumber Issue the PR closes
+ * @param opts.stackManifest Appended before the trailer under --stacked (#605)
+ * @param opts.qaVerdict QA verdict for the run; a non-A+ stopping state
+ *   (anything other than `READY_FOR_MERGE`) surfaces a note so a human reviewer
+ *   sees why the run broke to PR without reaching A+ (#749).
+ * @internal Exported for testing
+ */
+export declare function buildAutomatedPRBody(issueNumber: number, opts?: {
+    stackManifest?: string;
+    qaVerdict?: string;
+}): string;
 /**
  * Push branch and create a PR after successful QA.
  *
@@ -210,4 +252,4 @@ export declare function rebaseBeforePR(worktreePath: string, issueNumber: number
 export declare function createPR(worktreePath: string, issueNumber: number, issueTitle: string, branch: string, verbose: boolean, labels?: string[], stackOptions?: {
     prBase?: string;
     stackManifest?: string;
-}): PRCreationResult;
+}, qaVerdict?: string): PRCreationResult;