sequant 2.8.0 → 2.10.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";
@@ -27,20 +27,63 @@ function formatSignalLine(issue, pid, result) {
             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 "stale-pid-untrusted":
+            return `  Refused to signal PID ${pid} for #${issue} (lock is past the age ceiling; that PID has likely been recycled)`;
         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";
+/**
+ * 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, recordIssueCompletion, emitRunIdLine, } from "./batch-executor.js";
 import { reconcileStateAtStartup } from "./state-utils.js";
+import { runChainPreflight } from "./chain-preflight.js";
+import { runSkillsPreflight } from "./skills-preflight.js";
 import { getCommitHash } from "./git-diff-utils.js";
+import { planChainResumeFromState, } from "./chain-resume.js";
+import { isCompletedIssueStatus } from "./completed-status.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.
  *
@@ -92,6 +135,20 @@ export class RunOrchestrator {
     getEmitter() {
         return this.emitter;
     }
+    /**
+     * The wrapped progress sink handed to the batch executor — every phase
+     * lifecycle event enters the orchestrator through here.
+     *
+     * @internal Exported for testing only. `applyProgressEvent` is private and
+     * depends on `issueStates`/`phaseStartTimes`/`emitter`, so there is no way
+     * to exercise its branches short of a full `run()`. Without this seam the
+     * #804 `waiting` branch would be untestable — and an untested `waiting`
+     * branch is not cosmetic: falling through to the complete/failed handler
+     * marks a merely-paused phase `failed` and emits `phase_failed`.
+     */
+    getProgressCallback() {
+        return this.cfg.onProgress;
+    }
     /**
      * Point-in-time view of the entire run.
      *
@@ -158,6 +215,16 @@ export class RunOrchestrator {
             const wasStatus = state.status;
             if (!state.startedAt)
                 state.startedAt = new Date();
+            // #866: a phase starting means the issue is live again, so any
+            // `completedAt` from an earlier terminal verdict is stale and must not
+            // outlive it. The #766 quality-loop recovery path reaches here holding
+            // one: a non-loop failure pins `failed` and stamps `completedAt` below,
+            // then iteration 2 re-runs the phase through this branch. Leaving it set
+            // published a completion time for a running issue — which froze the TUI's
+            // header clock for the whole recovery window. `startedAt` is deliberately
+            // NOT reset: the header measures the issue's total wall clock, spanning
+            // every iteration.
+            state.completedAt = undefined;
             state.status = "running";
             const now = new Date();
             this.phaseStartTimes.set(`${issue}:${phase}`, now.getTime());
@@ -185,6 +252,25 @@ export class RunOrchestrator {
             }
             return;
         }
+        // #804 AC-7: an auto-wait is a *paused running* phase, not a terminal one.
+        // This branch must precede the complete/failed fall-through below, which
+        // would otherwise close out the phase the moment a wait began. Surfaces the
+        // wait through the same `nowLine` the TUI already renders.
+        if (event === "waiting") {
+            if (!state.currentPhase || state.currentPhase.name !== phase)
+                return;
+            const line = extra?.text;
+            if (!line)
+                return;
+            state.currentPhase.nowLine = line;
+            state.currentPhase.lastActivityAt = new Date();
+            void this.emitter.emit("progress", {
+                issueNumber: issue,
+                phase,
+                text: line,
+            });
+            return;
+        }
         if (event === "activity") {
             // Ignore activity for stale phases (race between completion and a
             // final flushed output chunk).
@@ -218,8 +304,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 +320,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 +339,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 +385,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 +398,7 @@ export class RunOrchestrator {
             mergedOptions,
             config,
             issueNumbers,
+            rawIssueOrder,
             batches: resolvedBatches,
             baseBranch,
             stack: manifest.stack,
@@ -319,6 +416,15 @@ export class RunOrchestrator {
      */
     static async run(init, issueArgs, batches) {
         const { manifest, onProgress, phasePauseHandle, settings } = init;
+        // #867: capture the run's start before any service/log setup, so wall clock
+        // is independent of whether the log writer exists (AC-3: correct under
+        // --no-log and when log init fails). This single origin is the source of
+        // truth for both the printed summary and the run log (AC-2).
+        const runStartedAt = Date.now();
+        // Every `return` below — the success path and all six early exits — closes
+        // the bracket the same way, so the subtraction lives in one place rather
+        // than being restated per exit and left to drift.
+        const wallClock = () => (Date.now() - runStartedAt) / 1000;
         // ── Config resolution ──────────────────────────────────────────────
         const resolved = RunOrchestrator.resolveConfig(init, issueArgs, batches);
         const { mergedOptions, config, baseBranch } = resolved;
@@ -334,6 +440,7 @@ export class RunOrchestrator {
                 config,
                 mergedOptions,
                 logWriter: null,
+                wallClockDurationSeconds: wallClock(),
             };
         }
         // ── Services setup ─────────────────────────────────────────────────
@@ -355,6 +462,10 @@ export class RunOrchestrator {
                     logPath: mergedOptions.logPath ?? settings.run.logPath,
                     verbose: config.verbose,
                     startCommit: getCommitHash(process.cwd()),
+                    // #867: share the orchestrator's run origin so the log's stored
+                    // wall clock (finalizeRunLog: (end-start)/1000) is derived from the
+                    // same start as the summary — AC-2/AC-7 (one producer, two consumers).
+                    startTime: new Date(runStartedAt),
                 });
                 await logWriter.initialize(runConfig);
                 const runId = logWriter.getRunId();
@@ -374,8 +485,12 @@ export class RunOrchestrator {
         const shutdown = new ShutdownManager();
         if (logWriter) {
             const writer = logWriter;
-            shutdown.registerCleanup("Finalize run logs", async () => {
-                await writer.finalize();
+            // #856: forward the abort cause into the log. This cleanup runs on the
+            // SIGINT/SIGTERM path, where no phase result will ever arrive for the
+            // in-flight issue — without the context, `finalize()` writes that issue
+            // out as if the run had simply ended.
+            shutdown.registerCleanup("Finalize run logs", async (abort) => {
+                await writer.finalize(abort ? { aborted: abort } : undefined);
             });
         }
         // ── Pre-flight state guard ─────────────────────────────────────────
@@ -392,29 +507,47 @@ 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,
+                        wallClockDurationSeconds: wallClock(),
+                    };
                 }
-            }
-            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: [],
@@ -425,8 +558,58 @@ export class RunOrchestrator {
                         config,
                         mergedOptions,
                         logWriter: null,
+                        wallClockDurationSeconds: wallClock(),
                     };
                 }
+                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 && isCompletedIssueStatus(issueState.status)) {
+                            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,
+                            wallClockDurationSeconds: wallClock(),
+                        };
+                    }
+                }
             }
         }
         // ── Concurrency lock (#625) ────────────────────────────────────────
@@ -483,14 +666,90 @@ export class RunOrchestrator {
                     config,
                     mergedOptions,
                     logWriter: null,
+                    wallClockDurationSeconds: wallClock(),
                 };
             }
         }
+        // ── 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,
+                        wallClockDurationSeconds: wallClock(),
+                    };
+                }
+            }
+        }
         // ── Issue info + worktree setup ────────────────────────────────────
         const issueInfoMap = new Map();
         for (const issueNumber of issueNumbers) {
             issueInfoMap.set(issueNumber, await getIssueInfo(issueNumber));
         }
+        // ── Skills pre-flight (#813) ───────────────────────────────────────
+        // Fail fast when the driver resolves phases via `.claude/skills/` and a
+        // required skill is missing — BEFORE any worktree is provisioned or
+        // per-issue state entry written. Without this, the phase agent hunts for
+        // a slash command that can never resolve and the run surfaces as a bogus
+        // "spec retry" failure. Skipped for non-skill drivers (aider) and for
+        // --dry-run (no agent executes).
+        if (!config.dryRun) {
+            const preflight = await runSkillsPreflight({
+                agent: config.agent,
+                aiderSettings: config.aiderSettings,
+                phases: config.phases,
+                autoDetectPhases: resolved.autoDetectPhases,
+                qualityLoop: config.qualityLoop,
+                testgen: mergedOptions.testgen,
+                securityReview: mergedOptions.securityReview,
+                issueNumbers,
+                issueInfoMap,
+            });
+            if (!preflight.ok) {
+                bracketedConsoleLog(phasePauseHandle, chalk.red(`\n  ✖ Skills pre-flight failed: ${preflight.cause}`));
+                bracketedConsoleLog(phasePauseHandle, chalk.red(`    ${preflight.remedy}`));
+                shutdown.dispose();
+                return {
+                    results: issueNumbers.map((issueNumber) => ({
+                        issueNumber,
+                        success: false,
+                        phaseResults: [],
+                        durationSeconds: 0,
+                        loopTriggered: false,
+                        abortReason: `skills pre-flight failed: ${preflight.cause}`,
+                    })),
+                    logPath: null,
+                    exitCode: 1,
+                    worktreeMap: new Map(),
+                    issueInfoMap,
+                    config,
+                    mergedOptions,
+                    logWriter: null,
+                    wallClockDurationSeconds: wallClock(),
+                };
+            }
+        }
         const useWorktreeIsolation = mergedOptions.worktreeIsolation !== false && issueNumbers.length > 0;
         let worktreeMap = new Map();
         if (useWorktreeIsolation && !config.dryRun) {
@@ -499,7 +758,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 +787,7 @@ export class RunOrchestrator {
             services: { logWriter, stateManager, shutdownManager: shutdown },
             packageManager: manifest.packageManager,
             baseBranch,
+            chainResume,
             onProgress,
             onPhasePlan: init.onPhasePlan,
             phasePauseHandle,
@@ -557,10 +821,15 @@ export class RunOrchestrator {
                     endCommit: getCommitHash(process.cwd()),
                 });
             }
+            // #867: the run's wall clock, computed once from the single origin. Both
+            // the metrics record and the RunResult below derive from this value — no
+            // consumer re-sums per-issue durations (which double-counts under
+            // --parallel). Same notion the log stores via finalizeRunLog above.
+            const wallClockDurationSeconds = wallClock();
             // ── Record metrics ─────────────────────────────────────────────
             if (!config.dryRun && results.length > 0) {
                 try {
-                    await RunOrchestrator.recordMetrics(config, mergedOptions, results, worktreeMap, issueNumbers);
+                    await RunOrchestrator.recordMetrics(config, mergedOptions, results, worktreeMap, issueNumbers, wallClockDurationSeconds);
                 }
                 catch (metricsError) {
                     logNonFatalWarning("  !  Metrics recording failed, continuing...", metricsError, config.verbose);
@@ -576,6 +845,7 @@ export class RunOrchestrator {
                 config,
                 mergedOptions,
                 logWriter,
+                wallClockDurationSeconds,
             };
         }
         finally {
@@ -639,6 +909,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.
@@ -670,14 +1042,13 @@ export class RunOrchestrator {
                     : undefined,
             });
             results.push(result);
-            if (!result.success) {
-                if (options.qaGate && options.chain) {
-                    const qaFailed = result.phaseResults.some((p) => p.phase === "qa" && !p.success);
-                    if (qaFailed)
-                        break;
-                }
+            // A chain halts on ANY failed link, QA or otherwise: every successor
+            // rebases onto its predecessor's committed work, so continuing past a
+            // failure would build on a broken or absent base. #795 removed a
+            // `--qa-gate` branch here that re-tested for a QA failure before this
+            // same unconditional break — it could never change the outcome.
+            if (!result.success)
                 break;
-            }
         }
         return results;
     }
@@ -762,11 +1133,12 @@ export class RunOrchestrator {
                     });
                 }
             }
-            if (logWriter && result.prNumber && result.prUrl) {
-                logWriter.setPRInfo(result.prNumber, result.prUrl, parallelIssueNumber);
-            }
+            // Record PR info, flip status on a PR-creation failure (#879), and
+            // finalize — via the shared helper so this live path stays in lockstep
+            // with executeBatch. Before #879 this block omitted the failure flip, so
+            // a real `sequant run` left the run-log status at `success` on PR failure.
             if (logWriter) {
-                logWriter.completeIssue(parallelIssueNumber);
+                recordIssueCompletion(logWriter, result, parallelIssueNumber);
             }
             return result;
         }
@@ -779,9 +1151,13 @@ export class RunOrchestrator {
             });
         }
     }
-    static async recordMetrics(config, mergedOptions, results, worktreeMap, issueNumbers) {
+    static async recordMetrics(config, mergedOptions, results, worktreeMap, issueNumbers, wallClockDurationSeconds) {
         const metricsWriter = new MetricsWriter({ verbose: config.verbose });
-        const totalDuration = results.reduce((sum, r) => sum + (r.durationSeconds ?? 0), 0);
+        // #867: run wall clock, not the sum of per-issue durations — under
+        // --parallel that sum double-counts overlapping issues (same defect the
+        // SUMMARY header had). The orchestrator owns the run's start/end and passes
+        // the single authoritative value in.
+        const totalDuration = wallClockDurationSeconds;
         const allPhases = new Set();
         for (const result of results) {
             for (const pr of result.phaseResults) {
@@ -826,6 +1202,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 +1214,7 @@ export class RunOrchestrator {
             duration: totalDuration,
             model: process.env.ANTHROPIC_MODEL ?? "opus",
             flags: cliFlags,
+            failureCategory,
             metrics: {
                 tokensUsed: tokenUsage.tokensUsed,
                 filesChanged: totalFilesChanged,